Transfer reasons

A transfer reason is a single rule: this situation goes to that number. An assistant carries as many as you give it (billing to one line, complaints to another, "just let me talk to someone" to the front desk), and when the conversation matches one, the assistant says the line you wrote and hands the call over.

Transfers covers how a hand-off is performed: cold, warm, or warm-return. This page covers when it happens and where it goes. The two compose (a reason picks the destination, the mode governs the hand-off), but they are configured in different places: the mode is a setting on the assistant, and none of the fields below set one. The generated field-by-field reference lives at Transfer Reasons API.

The shape of a rule#

Every transfer reason answers three questions: what triggers it, what the caller hears, and where the call goes.

phoneNumber is E.164 like every number in the API: +15555550123, no spaces or punctuation. See API conventions.

Write reason as the caller's situation rather than as an instruction to yourself: "the caller asks about a charge they do not recognise" is a trigger, "billing stuff" is not.

A stored record carries the same fields plus id, createdAt and updatedAt. Timestamps are ISO 8601 in UTC, again per convention.

Create a transfer reason#

POST /transfer-reasons

Reach for a new reason when a caller wants a person for a specific case (an escalation, a special request) or when you want the assistant to have somewhere to send queries it cannot handle itself.

curl -X POST https://core-api.heysadie.ai/transfer-reasons \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistantId": "0195f1e2-0000-0000-0000-000000000000",
    "name": "Billing escalation",
    "reason": "The caller asks to speak to a person about an invoice, a refund, or a charge they do not recognise.",
    "message": "Let me put you through to our billing team.",
    "phoneNumber": "+15555550123",
    "extension": "204",
    "isActive": true,
    "waitForResponse": true
  }'

A successful create returns 200 with the new record under data, in the standard envelope:

{
  "success": true,
  "data": {
    "id": "0195f1e2-2222-0000-0000-000000000000",
    "name": "Billing escalation",
    "reason": "The caller asks to speak to a person about an invoice, a refund, or a charge they do not recognise.",
    "message": "Let me put you through to our billing team.",
    "assistantId": "0195f1e2-0000-0000-0000-000000000000",
    "phoneNumber": "+15555550123",
    "extension": "204",
    "isActive": true,
    "waitForResponse": true,
    "createdAt": "2026-07-30T12:00:00.000Z",
    "updatedAt": "2026-07-30T12:00:00.000Z"
  },
  "metadata": {
    "timestamp": "2026-07-30T12:00:00.000Z",
    "version": "1.0",
    "path": "/transfer-reasons"
  }
}

properties is present on every record too. It is left out of the samples on this page because the spec does not define its shape. See the callout above.

Keep the returned id. It is what the end-of-call report sends back in transfer_reason_id when this rule fires. That webhook names its fields in snake_case, unlike the camelCase of the REST API.

List transfer reasons#

GET /transfer-reasons

curl "https://core-api.heysadie.ai/transfer-reasons?assistantId=0195f1e2-0000-0000-0000-000000000000" \
  -H "Authorization: ApiKey YOUR_API_KEY"

data.transferReasons holds the page, data.total the size of the whole collection. Advance offset until you have seen total items.

{
  "success": true,
  "data": {
    "transferReasons": [
      {
        "id": "0195f1e2-2222-0000-0000-000000000000",
        "name": "Billing escalation",
        "reason": "The caller asks to speak to a person about an invoice, a refund, or a charge they do not recognise.",
        "message": "Let me put you through to our billing team.",
        "assistantId": "0195f1e2-0000-0000-0000-000000000000",
        "phoneNumber": "+15555550123",
        "extension": "204",
        "isActive": true,
        "waitForResponse": true,
        "createdAt": "2026-07-30T12:00:00.000Z",
        "updatedAt": "2026-07-30T12:00:00.000Z"
      }
    ],
    "total": 3
  },
  "metadata": {
    "timestamp": "2026-07-30T12:00:00.000Z",
    "version": "1.0",
    "path": "/transfer-reasons"
  }
}

Filtering by assistantId is the call worth building a habit around: it answers "what can this assistant currently escalate, and to where?" in one request.

Get one transfer reason#

GET /transfer-reasons/{id}

curl https://core-api.heysadie.ai/transfer-reasons/0195f1e2-2222-0000-0000-000000000000 \
  -H "Authorization: ApiKey YOUR_API_KEY"

The response is 200 with a single record under data: the same object shown for create, not wrapped in an array. An id that does not exist returns 404; see Errors.

Update a transfer reason#

The spec gives both verbs an identical body, the same fields as create: name, reason, message, assistantId, phoneNumber, extension, isActive, waitForResponse, properties. Both return 200 with the updated record under data, in the same shape as create. What differs is how each treats the fields you leave out.

PATCH /transfer-reasons/{id}

A partial update: only the fields you include in the request are changed, and everything else is left alone. It is the right verb for a quick edit: a new number, a reworded message, taking a rule out of service.

curl -X PATCH https://core-api.heysadie.ai/transfer-reasons/0195f1e2-2222-0000-0000-000000000000 \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phoneNumber": "+15555550124", "isActive": false }'

isActive is how you retire a rule without losing it: set it to false and the record (its wording, its destination, its history in your own logs) stays exactly where it is.

PUT /transfer-reasons/{id}

Same body, same response. What it does with an omitted field is the open question:

Delete a transfer reason#

DELETE /transfer-reasons/{id}

curl -X DELETE https://core-api.heysadie.ai/transfer-reasons/0195f1e2-2222-0000-0000-000000000000 \
  -H "Authorization: ApiKey YOUR_API_KEY"

Delete returns 200 with the deleted record under data (the full object, not just its id), so you can log exactly what was removed:

{
  "success": true,
  "data": {
    "id": "0195f1e2-2222-0000-0000-000000000000",
    "name": "Billing escalation",
    "reason": "The caller asks to speak to a person about an invoice, a refund, or a charge they do not recognise.",
    "message": "Let me put you through to our billing team.",
    "assistantId": "0195f1e2-0000-0000-0000-000000000000",
    "phoneNumber": "+15555550124",
    "extension": "204",
    "isActive": false,
    "waitForResponse": true,
    "createdAt": "2026-07-30T12:00:00.000Z",
    "updatedAt": "2026-07-30T12:05:00.000Z"
  },
  "metadata": {
    "timestamp": "2026-07-30T12:06:00.000Z",
    "version": "1.0",
    "path": "/transfer-reasons/0195f1e2-2222-0000-0000-000000000000"
  }
}

If you might want the rule back later, PATCH it to "isActive": false instead of deleting it.

Errors#

Every endpoint on this page uses the standard error envelope. These are the statuses the spec documents for the transfer-reason routes; the API-wide statuses apply too, including throttling (see Rate limits).

If a create or update comes back 400, check the destination number first: it has to be E.164, like +15555550123 rather than (555) 555-0123.

Next steps#

• Transfers: the three hand-off modes; a reason picks the destination, the mode decides how the hand-off sounds.
• Dynamic transfer: resolve the destination from your own directory at call time instead of maintaining a fixed list of reasons.
• End-of-call report: transfer_reason_id tells you which rule fired, supervisor_answered whether anyone picked up.
• IVR router mode: let a short router transfer on these same reasons before the assistant takes the call.
• Transfer Reasons API: the generated reference, regenerated from the spec on every build.