Overview

Base URL

All routes start from this address. Paths in this reference start at /v1.

https://backend.synthesys.app/api

Authentication

Send your key in the SYNTH_API_KEY header on every /v1 request. Each endpoint shows the minimum permission it needs. See Authentication.

curl https://backend.synthesys.app/api/v1/agents \
  -H "SYNTH_API_KEY: YOUR_API_KEY"

API info

GET /api needs no key. It returns the API's name, its version of v1, a documentation link, and an endpoints object listing the path of each resource.

Response format

A successful response has "success": true and its result in data. List routes usually add pagination.

{
  "success": true,
  "data": [],
  "pagination": { "total": 0, "limit": 50, "offset": 0 }
}

A delete returns a message instead of data.

{ "success": true, "message": "Contact deleted successfully" }

An error has "success": false, a string error, a stable code and a requestId. Every route uses this one format. See Errors.

{
  "success": false,
  "error": "This API key does not have permission to do this.",
  "code": "FORBIDDEN",
  "requestId": "6f1a2b3c-4d5e-4f60-8a7b-9c0d1e2f3a4b",
  "timestamp": "2026-10-31T09:30:00.000Z"
}

Conventions

• JSON: send request bodies as JSON with Content-Type: application/json. The maximum body size is 256 KB, or 2 MB when saving custom functions.
• IDs: most resource IDs are UUIDs. A path ID that isn't a valid UUID returns 400.
• Timestamps: responses use ISO 8601 strings.
• Date filters: send YYYY-MM-DD or a full ISO 8601 time with a timezone, such as 2026-10-31T12:00:00Z. Anything else, including an impossible date such as 2026-02-31, returns 400.
• Whole numbers: paging values must be digits only, so 1e3 and 0x10 return 400.
• Search: a search value can be up to 200 characters. A value made only of * returns 400, so leave search out to list everything.
• Phone numbers: use international format, such as +12025550123. The number must be valid and dialable.
• Field casing: casing varies by resource. Agents, phone numbers and POST /v1/calls use camelCase. Contacts and query parameters use snake_case. Call logs mostly use snake_case, with a few camelCase fields. Use the names on each page exactly as shown.
• Fixed fields: each response holds only the fields listed on that resource's page. A field with no value can be left out.
• Pagination: most lists use limit and offset, up to 100 results per request. See Pagination.
• Rate limits: each key has its own allowance. See Rate limits.
• Tracing: every response has an X-Request-ID header. Include it when you contact support.
• Unknown routes: anything else under /v1 returns 404, after the key check.

Resources

Agents

Calling

Outreach

Account