Assistants

Assistants are the AI agents that handle calls. ErzyCall has two types:

Inbound — handle incoming calls to your phone numbers
Outbound — used for outgoing calls initiated via the API or dashboard

List Inbound Assistants

GET /api/v1/assistants/inbound

Required scope: assistants:read

Example Request

curl -X GET "https://app.erzycall.com/api/v1/assistants/inbound" \
  -H "X-API-Key: ek_live_abc123"

Example Response

{
  "data": [
    {
      "id": "asst_001",
      "name": "Customer Support Agent",
      "systemPromptId": "prompt_abc",
      "createdAt": "2025-01-05T12:00:00Z"
    }
  ]
}

Get Inbound Assistant

GET /api/v1/assistants/inbound/{id}

Required scope: assistants:read

Example Request

curl -X GET "https://app.erzycall.com/api/v1/assistants/inbound/asst_001" \
  -H "X-API-Key: ek_live_abc123"

Example Response

{
  "data": {
    "id": "asst_001",
    "name": "Customer Support Agent",
    "systemPromptId": "prompt_abc",
    "createdAt": "2025-01-05T12:00:00Z"
  }
}

Update Inbound Assistant

Update the name or system prompt of an inbound assistant.

PATCH /api/v1/assistants/inbound/{id}

Required scope: assistants:write

Request Body

Field	Type	Required	Description
`name`	`string`	No	Assistant name (1–200 chars)
`systemPromptId`	`string`	No	ID of the system prompt to use

Example Request

curl -X PATCH "https://app.erzycall.com/api/v1/assistants/inbound/asst_001" \
  -H "X-API-Key: ek_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Support Agent"}'

Example Response

{
  "data": {
    "id": "asst_001",
    "name": "Updated Support Agent",
    "systemPromptId": "prompt_abc",
    "createdAt": "2025-01-05T12:00:00Z"
  }
}

The Outbound Assistant Object

An outbound assistant is a reusable voice configuration: which voice speaks, which LLM thinks, which transcriber listens. Pass its id as assistantConfigId when you create a call.

Field	Type	Description
`id`	`string`	Use it as `assistantConfigId` on `POST /calls`
`name`	`string`	Display name
`description`	`string \| null`	Free-text note
`isDefault`	`boolean`	Marks the dashboard's preferred assistant. Only one per organization. Note this is not consulted by `POST /calls` — a call without `assistantConfigId` uses the platform defaults.
`voice`	`object`	`provider`, `voiceId`, and optional `model`, `language`, `stability`, `similarityBoost`, `speed`
`model`	`object`	`provider`, `model`, `temperature`
`transcriber`	`object`	`provider`, `model`, `language`
`firstMessage`	`string \| null`	Opening line, used only when neither the request nor the case supplies one
`systemPrompt`	`string \| null`	Instructions, used only when neither the request nor the case supplies one
`dialKeypadFunctionEnabled`	`boolean`	Lets the assistant press DTMF keys
`backchannelingEnabled`	`boolean`	Emits "mm-hmm"-style acknowledgements
`backgroundDenoisingEnabled`	`boolean`	Filters background noise
`createdAt`, `updatedAt`	`string`	ISO 8601 timestamps

The list endpoint returns a summary — id, name, description, isDefault, voice.provider/voice.voiceId, model.provider/model.model, and timestamps. Fetch a single assistant for the full object.

List Outbound Assistants

GET /api/v1/assistants/outbound

Required scope: assistants:read

Example Request

curl -X GET "https://app.erzycall.com/api/v1/assistants/outbound" \
  -H "X-API-Key: ek_live_abc123"

Example Response

{
  "data": [
    {
      "id": "asst_002",
      "name": "Sales Outreach Agent",
      "description": null,
      "isDefault": true,
      "voice": { "provider": "cartesia", "voiceId": "694f9389-aac1-45b6-b726-9d9369183238" },
      "model": { "provider": "openai", "model": "gpt-5.1-chat-latest" },
      "createdAt": "2025-01-08T14:00:00.000Z",
      "updatedAt": "2025-01-08T14:00:00.000Z"
    }
  ]
}

Get Outbound Assistant

GET /api/v1/assistants/outbound/{id}

Required scope: assistants:read

Example Request

curl -X GET "https://app.erzycall.com/api/v1/assistants/outbound/asst_002" \
  -H "X-API-Key: ek_live_abc123"

Example Response

{
  "data": {
    "id": "asst_002",
    "name": "Sales Outreach Agent",
    "description": null,
    "isDefault": true,
    "voice": {
      "provider": "cartesia",
      "voiceId": "694f9389-aac1-45b6-b726-9d9369183238",
      "model": "sonic-3"
    },
    "model": { "provider": "openai", "model": "gpt-5.1-chat-latest", "temperature": 0.7 },
    "transcriber": { "provider": "openai", "model": "gpt-4o-transcribe", "language": "en" },
    "firstMessage": "Hi, this is Aisyah from TechCorp.",
    "systemPrompt": "You are a friendly sales assistant...",
    "dialKeypadFunctionEnabled": false,
    "backchannelingEnabled": true,
    "backgroundDenoisingEnabled": true,
    "createdAt": "2025-01-08T14:00:00.000Z",
    "updatedAt": "2025-01-08T14:00:00.000Z"
  }
}

Errors

Status	Code	Description
404	`NOT_FOUND`	Outbound assistant not found

Create Outbound Assistant

POST /api/v1/assistants/outbound

Required scope: assistants:write

Request Body

Field	Type	Required	Description
`name`	`string`	Yes	Display name (1–200 chars)
`voice`	`object`	Yes	`provider` and `voiceId` required; `model`, `language`, `stability`, `similarityBoost`, `speed` optional
`model`	`object`	Yes	`provider` and `model` required; `temperature` (0–2) defaults to `0.7`
`transcriber`	`object`	No	Defaults to `{"provider": "openai", "model": "gpt-4o-transcribe", "language": "en"}`
`description`	`string`	No	Free-text note (max 1,000 chars)
`isDefault`	`boolean`	No	Marks this as the dashboard's preferred assistant, unsetting the previous one
`firstMessage`	`string`	No	Opening line (max 1,000 chars)
`systemPrompt`	`string`	No	Instructions for the assistant
`dialKeypadFunctionEnabled`	`boolean`	No	Defaults to `false`
`backchannelingEnabled`	`boolean`	No	Defaults to `true`
`backgroundDenoisingEnabled`	`boolean`	No	Defaults to `true`

Example Request

curl -X POST "https://app.erzycall.com/api/v1/assistants/outbound" \
  -H "X-API-Key: ek_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Outreach Agent",
    "voice": {
      "provider": "cartesia",
      "voiceId": "694f9389-aac1-45b6-b726-9d9369183238"
    },
    "model": {
      "provider": "openai",
      "model": "gpt-5.1-chat-latest"
    }
  }'

Returns 201 Created with the full assistant object.

Update Outbound Assistant

PATCH /api/v1/assistants/outbound/{id}

Required scope: assistants:write

Accepts the same fields as create, all optional. Omitted fields are left alone.

voice, model, and transcriber are stored as whole objects — sending one replaces it rather than merging field by field. To change just the voice speed, send the complete voice object with the new speed.

Example Request

curl -X PATCH "https://app.erzycall.com/api/v1/assistants/outbound/asst_002" \
  -H "X-API-Key: ek_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Outreach Agent v2",
    "firstMessage": "Hi, this is Aisyah calling from TechCorp."
  }'

Returns 200 OK with the updated assistant object.

Errors

Status	Code	Description
404	`NOT_FOUND`	Outbound assistant not found

Delete Outbound Assistant

DELETE /api/v1/assistants/outbound/{id}

Required scope: assistants:write

Example Request

curl -X DELETE "https://app.erzycall.com/api/v1/assistants/outbound/asst_002" \
  -H "X-API-Key: ek_live_abc123"

Response

Returns 204 No Content on success.

An assistant that is still in use cannot be deleted — the request returns 409 and the assistant is left untouched. "In use" means any of:

a call not yet dispatched (new, scheduled, or lock-processing)
a recurring schedule pointing at it, active or paused
an AutoFollow campaign pointing at it

Cancel those calls with DELETE /calls/{id}, or re-point the schedules and campaigns, then retry. The error message names what is blocking.

This is deliberate: a recurring schedule stores its assistant as a required reference that cannot be cleared, both generators stamp their stored assistant onto every call they create, and a queued call whose assistant vanishes either falls back to unrelated platform defaults or fails to dial outright. Refusing is safer than silently changing how a call sounds.

Errors

Status	Code	Description
404	`NOT_FOUND`	Outbound assistant not found
409	`CONFLICT`	Assistant is still referenced by queued calls, recurring schedules, or AutoFollow campaigns

Assistants are the AI agents that handle calls. ErzyCall has two types:

Inbound — handle incoming calls to your phone numbers
Outbound — used for outgoing calls initiated via the API or dashboard

List Inbound Assistants

GET /api/v1/assistants/inbound

Required scope: assistants:read

Example Request

curl -X GET "https://app.erzycall.com/api/v1/assistants/inbound" \
  -H "X-API-Key: ek_live_abc123"

Example Response

{
  "data": [
    {
      "id": "asst_001",
      "name": "Customer Support Agent",
      "systemPromptId": "prompt_abc",
      "createdAt": "2025-01-05T12:00:00Z"
    }
  ]
}

Get Inbound Assistant

GET /api/v1/assistants/inbound/{id}

Required scope: assistants:read

Example Request

curl -X GET "https://app.erzycall.com/api/v1/assistants/inbound/asst_001" \
  -H "X-API-Key: ek_live_abc123"

Example Response

{
  "data": {
    "id": "asst_001",
    "name": "Customer Support Agent",
    "systemPromptId": "prompt_abc",
    "createdAt": "2025-01-05T12:00:00Z"
  }
}

Update Inbound Assistant

Update the name or system prompt of an inbound assistant.

PATCH /api/v1/assistants/inbound/{id}

Required scope: assistants:write

Request Body

Field	Type	Required	Description
`name`	`string`	No	Assistant name (1–200 chars)
`systemPromptId`	`string`	No	ID of the system prompt to use

Example Request

curl -X PATCH "https://app.erzycall.com/api/v1/assistants/inbound/asst_001" \
  -H "X-API-Key: ek_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Support Agent"}'

Example Response

{
  "data": {
    "id": "asst_001",
    "name": "Updated Support Agent",
    "systemPromptId": "prompt_abc",
    "createdAt": "2025-01-05T12:00:00Z"
  }
}

The Outbound Assistant Object

An outbound assistant is a reusable voice configuration: which voice speaks, which LLM thinks, which transcriber listens. Pass its id as assistantConfigId when you create a call.

Field	Type	Description
`id`	`string`	Use it as `assistantConfigId` on `POST /calls`
`name`	`string`	Display name
`description`	`string \| null`	Free-text note
`isDefault`	`boolean`	Marks the dashboard's preferred assistant. Only one per organization. Note this is not consulted by `POST /calls` — a call without `assistantConfigId` uses the platform defaults.
`voice`	`object`	`provider`, `voiceId`, and optional `model`, `language`, `stability`, `similarityBoost`, `speed`
`model`	`object`	`provider`, `model`, `temperature`
`transcriber`	`object`	`provider`, `model`, `language`
`firstMessage`	`string \| null`	Opening line, used only when neither the request nor the case supplies one
`systemPrompt`	`string \| null`	Instructions, used only when neither the request nor the case supplies one
`dialKeypadFunctionEnabled`	`boolean`	Lets the assistant press DTMF keys
`backchannelingEnabled`	`boolean`	Emits "mm-hmm"-style acknowledgements
`backgroundDenoisingEnabled`	`boolean`	Filters background noise
`createdAt`, `updatedAt`	`string`	ISO 8601 timestamps

List Outbound Assistants

GET /api/v1/assistants/outbound

Required scope: assistants:read

Example Request

curl -X GET "https://app.erzycall.com/api/v1/assistants/outbound" \
  -H "X-API-Key: ek_live_abc123"

Example Response

{
  "data": [
    {
      "id": "asst_002",
      "name": "Sales Outreach Agent",
      "description": null,
      "isDefault": true,
      "voice": { "provider": "cartesia", "voiceId": "694f9389-aac1-45b6-b726-9d9369183238" },
      "model": { "provider": "openai", "model": "gpt-5.1-chat-latest" },
      "createdAt": "2025-01-08T14:00:00.000Z",
      "updatedAt": "2025-01-08T14:00:00.000Z"
    }
  ]
}

Get Outbound Assistant

GET /api/v1/assistants/outbound/{id}

Required scope: assistants:read

Example Request

curl -X GET "https://app.erzycall.com/api/v1/assistants/outbound/asst_002" \
  -H "X-API-Key: ek_live_abc123"

Example Response

{
  "data": {
    "id": "asst_002",
    "name": "Sales Outreach Agent",
    "description": null,
    "isDefault": true,
    "voice": {
      "provider": "cartesia",
      "voiceId": "694f9389-aac1-45b6-b726-9d9369183238",
      "model": "sonic-3"
    },
    "model": { "provider": "openai", "model": "gpt-5.1-chat-latest", "temperature": 0.7 },
    "transcriber": { "provider": "openai", "model": "gpt-4o-transcribe", "language": "en" },
    "firstMessage": "Hi, this is Aisyah from TechCorp.",
    "systemPrompt": "You are a friendly sales assistant...",
    "dialKeypadFunctionEnabled": false,
    "backchannelingEnabled": true,
    "backgroundDenoisingEnabled": true,
    "createdAt": "2025-01-08T14:00:00.000Z",
    "updatedAt": "2025-01-08T14:00:00.000Z"
  }
}

Errors

Status	Code	Description
404	`NOT_FOUND`	Outbound assistant not found

Create Outbound Assistant

POST /api/v1/assistants/outbound

Required scope: assistants:write

Request Body

Field	Type	Required	Description
`name`	`string`	Yes	Display name (1–200 chars)
`voice`	`object`	Yes	`provider` and `voiceId` required; `model`, `language`, `stability`, `similarityBoost`, `speed` optional
`model`	`object`	Yes	`provider` and `model` required; `temperature` (0–2) defaults to `0.7`
`transcriber`	`object`	No	Defaults to `{"provider": "openai", "model": "gpt-4o-transcribe", "language": "en"}`
`description`	`string`	No	Free-text note (max 1,000 chars)
`isDefault`	`boolean`	No	Marks this as the dashboard's preferred assistant, unsetting the previous one
`firstMessage`	`string`	No	Opening line (max 1,000 chars)
`systemPrompt`	`string`	No	Instructions for the assistant
`dialKeypadFunctionEnabled`	`boolean`	No	Defaults to `false`
`backchannelingEnabled`	`boolean`	No	Defaults to `true`
`backgroundDenoisingEnabled`	`boolean`	No	Defaults to `true`

Example Request

curl -X POST "https://app.erzycall.com/api/v1/assistants/outbound" \
  -H "X-API-Key: ek_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Outreach Agent",
    "voice": {
      "provider": "cartesia",
      "voiceId": "694f9389-aac1-45b6-b726-9d9369183238"
    },
    "model": {
      "provider": "openai",
      "model": "gpt-5.1-chat-latest"
    }
  }'

Returns 201 Created with the full assistant object.

Update Outbound Assistant

PATCH /api/v1/assistants/outbound/{id}

Required scope: assistants:write

Accepts the same fields as create, all optional. Omitted fields are left alone.

Example Request

curl -X PATCH "https://app.erzycall.com/api/v1/assistants/outbound/asst_002" \
  -H "X-API-Key: ek_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Outreach Agent v2",
    "firstMessage": "Hi, this is Aisyah calling from TechCorp."
  }'

Returns 200 OK with the updated assistant object.

Errors

Status	Code	Description
404	`NOT_FOUND`	Outbound assistant not found

Delete Outbound Assistant

DELETE /api/v1/assistants/outbound/{id}

Required scope: assistants:write

Example Request

curl -X DELETE "https://app.erzycall.com/api/v1/assistants/outbound/asst_002" \
  -H "X-API-Key: ek_live_abc123"

Response

Returns 204 No Content on success.

An assistant that is still in use cannot be deleted — the request returns 409 and the assistant is left untouched. "In use" means any of:

a call not yet dispatched (new, scheduled, or lock-processing)
a recurring schedule pointing at it, active or paused
an AutoFollow campaign pointing at it

Cancel those calls with DELETE /calls/{id}, or re-point the schedules and campaigns, then retry. The error message names what is blocking.

Errors

Status	Code	Description
404	`NOT_FOUND`	Outbound assistant not found
409	`CONFLICT`	Assistant is still referenced by queued calls, recurring schedules, or AutoFollow campaigns

On this page

Assistants

On this page