API Reference
Welcome to the GetRaze API. Use our REST API to integrate GetRaze functionality into your applications.
Using an AI agent?
Claude Code, Cursor, the OpenAI Agents SDK and n8n can drive GetRaze through the MCP server with the same API keys.
Base URL
https://app.getraze.com/external/v1Authentication
All API requests require authentication using an API key. Include your API key in the request header:
X-API-Key: your_api_key_hereOr using Bearer token format:
Authorization: Bearer your_api_key_hereQuick Start
1. Get your API Key
Navigate to Config > API Keys in your GetRaze dashboard to create a new API key.
2. Make your first request
curl --request GET \
--url "https://app.getraze.com/external/v1/contacts" \
--header "X-API-Key: YOUR_API_KEY"3. Response
{
"success": true,
"data": [...],
"pagination": {
"page": 1,
"per_page": 50,
"total": 150,
"total_pages": 3,
"has_next": true,
"has_prev": false
}
}Available Endpoints
Contacts
| Method | Endpoint | Description |
|---|---|---|
| GET | /contacts | List all contacts |
| GET | /contacts/:id | Retrieve a contact |
| POST | /contacts | Create a contact |
| PUT | /contacts/:id | Update a contact |
| DELETE | /contacts/:id | Delete a contact |
Opportunities
| Method | Endpoint | Description |
|---|---|---|
| GET | /opportunities | List all opportunities |
| GET | /opportunities/:id | Retrieve an opportunity |
| GET | /opportunities/:id/history | Retrieve stage/value history |
| POST | /opportunities | Create an opportunity |
| PUT | /opportunities/:id | Update an opportunity |
| PATCH | /opportunities/:id/stage | Update opportunity stage |
| DELETE | /opportunities/:id | Delete an opportunity |
Pipelines
pipeline_id and stage_id used by the opportunities endpoints come from here.
| Method | Endpoint | Description |
|---|---|---|
| GET | /pipelines | List pipelines and their stages |
| GET | /pipelines/:id | Retrieve a pipeline with its stages |
| GET | /pipelines/:id/stages | Stages of a pipeline with card count and value |
| GET | /pipelines/:id/stages/:stageId | Retrieve one stage |
Tasks
| Method | Endpoint | Description |
|---|---|---|
| GET | /tasks | List tasks |
| GET | /tasks/:id | Retrieve a task with its subtasks |
| POST | /tasks | Create a task |
| PUT | /tasks/:id | Update a task |
| PATCH | /tasks/:id/status | Move to pending / in progress / completed |
| PATCH | /tasks/:id/complete | Complete a task |
| DELETE | /tasks/:id | Delete a task |
| GET | /tasks/:id/comments | List the comments of a task |
| POST | /tasks/:id/comments | Comment on a task |
| GET | /task-pipelines | List task pipelines (boards) |
| GET | /task-labels | List task labels |
Playbooks
| Method | Endpoint | Description |
|---|---|---|
| GET | /playbooks | List playbooks |
| GET | /playbooks/:id | Retrieve a playbook with its steps |
| POST | /playbooks/:id/runs | Start a playbook run |
| GET | /playbook-runs | List playbook runs |
| GET | /playbook-runs/:id | Retrieve a run with its steps |
| POST | /playbook-runs/:id/cancel | Cancel a run |
| POST | /playbook-runs/:id/reschedule | Reschedule a late run from now |
Campaigns
| Method | Endpoint | Description |
|---|---|---|
| GET | /campaigns | List all campaigns |
| POST | /campaigns/:id/contacts | Add a contact to a campaign |
Conversations
| Method | Endpoint | Description |
|---|---|---|
| GET | /conversations | List conversations (incl. AI qualification) |
| GET | /conversations/:id | Retrieve a conversation with its messages |
Reports
| Method | Endpoint | Description |
|---|---|---|
| GET | /reports/funnel | Per-stage funnel (count + value) per pipeline |
| GET | /reports/sales-summary | Open / won / lost counts and values |
| GET | /reports/sellers | Per-seller KPIs (revenue, ticket, conversion) |
| GET | /reports/sla | Avg durations (response time, qualification, sales cycle) |
Reference Data
| Method | Endpoint | Description |
|---|---|---|
| GET | /sectors | List sectors/teams |
| GET | /tags | List tags |
| GET | /discard-reasons | List loss/discard reasons |
| GET | /products | List the product/service catalog |
| GET | /users | List team members (sellers) |
| GET | /custom-fields | List custom field definitions (keys, types, options) |
| GET | /projects | List CRM projects (the groups pipelines belong to) |
Instagram Agents
| Method | Endpoint | Description |
|---|---|---|
| GET | /instagram-agents | List all Instagram agents |
| POST | /instagram-agents/:id/profiles | Add a profile to an agent |
Agency Inbound
For whitelabel agencies only. Uses a different base URL and authentication — see Agency Inbound API.
| Method | Endpoint | Description |
|---|---|---|
| POST | /sub-accounts | Create a sub-account |
| PUT | /sub-accounts/:ref/channels | Update channel quotas |
| DELETE | /sub-accounts/:ref | Delete a sub-account |
| GET | /events/:event_id | Retrieve the outcome of a call |
Rate Limits
Each API key has configurable rate limits. Default is 1000 requests per hour.
Rate limit information is included in response headers:
X-RateLimit-Limit: Maximum requests per hourX-RateLimit-Remaining: Remaining requestsX-RateLimit-Reset: Unix timestamp when limit resets
Permissions
API keys use granular permissions:
| Permission | Description |
|---|---|
contacts:read | Read contact data |
contacts:write | Create and update contacts |
contacts:delete | Delete contacts |
opportunities:read | Read opportunity data |
opportunities:write | Create and update opportunities |
opportunities:delete | Delete opportunities |
campaigns:read | Read campaign data |
campaigns:write | Add contacts to campaigns |
conversations:read | Read conversations and messages (incl. AI qualification) |
reports:read | Read aggregated commercial reports (funnel, sales summary, sellers) |
pipelines:read | Read pipelines and stages |
sectors:read | Read sectors/teams |
tags:read | Read tags |
discard_reasons:read | Read loss/discard reasons |
products:read | Read the product/service catalog |
users:read | Read team members (sellers) |
custom_fields:read | Read custom field definitions |
projects:read | Read CRM projects |
instagram_agents:read | Read Instagram agent data |
instagram_agents:write | Add profiles to agents |
tasks:read | Read tasks, task comments, task pipelines and labels |
tasks:write | Create, update, complete and comment on tasks |
tasks:delete | Delete tasks |
playbooks:read | Read playbooks, their steps and runs |
playbooks:run | Start, cancel and reschedule playbook runs |
Wildcard permissions are supported (e.g., contacts:* grants all contact permissions).