Developer docs: Agents

Agents

AI receptionist configuration.

List agentsLink to List agents

GET/agents

Scope: agents:read

curl "https://bookifycall.com/api/v1/external/agents" \
  -H "X-API-Key: $BOOKIFYCALL_API_KEY"

Example response · 200

{
  "success": true,
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000002",
      "organizationId": "00000000-0000-4000-8000-000000000100",
      "name": "Riley",
      "slug": "riley",
      "description": "Front desk for Example Dental",
      "status": "active",
      "personality": {
        "name": "Riley",
        "tone": "friendly"
      },
      "voiceConfig": {
        "provider": "elevenlabs",
        "voiceId": "example-voice"
      },
      "companyInfo": {
        "name": "Example Dental",
        "hours": "Mon-Fri 9-5"
      },
      "language": "en-US",
      "transferConfig": {
        "enabled": true,
        "contacts": [
          {
            "name": "Front desk",
            "phone": "+15551230003",
            "priority": 1
          }
        ]
      },
      "conversationConfig": {
        "knowledgeBase": {
          "entries": [
            {
              "fact": "We are open 9-5 Monday to Friday"
            }
          ]
        }
      },
      "enabledTools": [
        "book_appointment",
        "transfer_call"
      ],
      "customTools": [],
      "kind": "tenant",
      "conversationEngine": "platform",
      "stats": {},
      "isDefault": true,
      "createdAt": "2026-01-02T10:00:00.000Z",
      "updatedAt": "2026-01-15T16:34:10.000Z",
      "deletedAt": null,
      "phoneNumber": {
        "id": "00000000-0000-4000-8000-000000000006",
        "phoneNumber": "+15551230002"
      }
    }
  ]
}

Create an agentLink to Create an agent

POST/agents

Scope: agents:write
Idempotency-Key: supported

Body (JSON)

namestringrequired
descriptionstring
personalityobject
languagestring: Language the agent speaks and understands on calls. Anything but English needs the multiLanguage plan feature (403 PLAN_001).One of: en-US, en-GB, es-US, es-ES, fr-FR, de-DE, pt-BR, it-IT · Default: en-US
voiceConfigobject
companyInfoobject
transferConfigobject: { enabled, contacts: [{ name, phone, role?, priority?, whisper? (<=200 chars), ringTimeoutSec? (10-60, default 20) }] }. Rung in priority/list order; nobody answering returns the caller to the agent. Malformed contact: 400 AGENT_020; more than maxTransferContacts: 403 PLAN_002.
conversationConfigobject
enabledToolsstring[]
customToolsobject[]: HTTP tools the agent may call mid-conversationUp to 10 items
aiPersonalityobject: Live alias of personality
voiceSettingsobject: Live alias of voiceConfig
transferContactsobject: Live alias of transferConfig
conversationSettingsobject: Live alias of conversationConfig
statusstring: One of: active, inactive, testing

curl -X POST "https://bookifycall.com/api/v1/external/agents" \
  -H "X-API-Key: $BOOKIFYCALL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"Riley","description":"Front desk for Example Dental","language":"en-US","personality":{"name":"Riley","tone":"friendly"},"companyInfo":{"name":"Example Dental","hours":"Mon-Fri 9-5"},"status":"active"}'

Example response · 201

{
  "success": true,
  "data": {
    "id": "00000000-0000-4000-8000-000000000002",
    "organizationId": "00000000-0000-4000-8000-000000000100",
    "name": "Riley",
    "slug": "riley",
    "description": "Front desk for Example Dental",
    "status": "active",
    "personality": {
      "name": "Riley",
      "tone": "friendly"
    },
    "voiceConfig": {
      "provider": "elevenlabs",
      "voiceId": "example-voice"
    },
    "companyInfo": {
      "name": "Example Dental",
      "hours": "Mon-Fri 9-5"
    },
    "language": "en-US",
    "transferConfig": {
      "enabled": true,
      "contacts": [
        {
          "name": "Front desk",
          "phone": "+15551230003",
          "priority": 1
        }
      ]
    },
    "conversationConfig": {
      "knowledgeBase": {
        "entries": [
          {
            "fact": "We are open 9-5 Monday to Friday"
          }
        ]
      }
    },
    "enabledTools": [
      "book_appointment",
      "transfer_call"
    ],
    "customTools": [],
    "kind": "tenant",
    "conversationEngine": "platform",
    "stats": {},
    "isDefault": true,
    "createdAt": "2026-01-02T10:00:00.000Z",
    "updatedAt": "2026-01-15T16:34:10.000Z",
    "deletedAt": null
  }
}

Get an agentLink to Get an agent

GET/agents/{id}

Scope: agents:read
Not found: 404 AGENT_001

Path parameters

idstringrequired

curl "https://bookifycall.com/api/v1/external/agents/00000000-0000-4000-8000-000000000002" \
  -H "X-API-Key: $BOOKIFYCALL_API_KEY"

Example response · 200

{
  "success": true,
  "data": {
    "id": "00000000-0000-4000-8000-000000000002",
    "organizationId": "00000000-0000-4000-8000-000000000100",
    "name": "Riley",
    "slug": "riley",
    "description": "Front desk for Example Dental",
    "status": "active",
    "personality": {
      "name": "Riley",
      "tone": "friendly"
    },
    "voiceConfig": {
      "provider": "elevenlabs",
      "voiceId": "example-voice"
    },
    "companyInfo": {
      "name": "Example Dental",
      "hours": "Mon-Fri 9-5"
    },
    "language": "en-US",
    "transferConfig": {
      "enabled": true,
      "contacts": [
        {
          "name": "Front desk",
          "phone": "+15551230003",
          "priority": 1
        }
      ]
    },
    "conversationConfig": {
      "knowledgeBase": {
        "entries": [
          {
            "fact": "We are open 9-5 Monday to Friday"
          }
        ]
      }
    },
    "enabledTools": [
      "book_appointment",
      "transfer_call"
    ],
    "customTools": [],
    "kind": "tenant",
    "conversationEngine": "platform",
    "stats": {},
    "isDefault": true,
    "createdAt": "2026-01-02T10:00:00.000Z",
    "updatedAt": "2026-01-15T16:34:10.000Z",
    "deletedAt": null,
    "phoneNumber": {
      "id": "00000000-0000-4000-8000-000000000006",
      "phoneNumber": "+15551230002"
    }
  }
}

Partially update an agent (only sent fields change)Link to Partially update an agent (only sent fields change)

PATCH/agents/{id}

Scope: agents:write
Not found: 404 AGENT_001

Path parameters

idstringrequired

Body (JSON)

namestring
descriptionstring
personalityobject
languagestring: Language the agent speaks and understands on calls. Anything but English needs the multiLanguage plan feature (403 PLAN_001).One of: en-US, en-GB, es-US, es-ES, fr-FR, de-DE, pt-BR, it-IT · Default: en-US
voiceConfigobject
companyInfoobject
transferConfigobject: { enabled, contacts: [{ name, phone, role?, priority?, whisper? (<=200 chars), ringTimeoutSec? (10-60, default 20) }] }. Rung in priority/list order; nobody answering returns the caller to the agent. Malformed contact: 400 AGENT_020; more than maxTransferContacts: 403 PLAN_002.
conversationConfigobject
enabledToolsstring[]
customToolsobject[]: HTTP tools the agent may call mid-conversationUp to 10 items
aiPersonalityobject: Live alias of personality
voiceSettingsobject: Live alias of voiceConfig
transferContactsobject: Live alias of transferConfig
conversationSettingsobject: Live alias of conversationConfig
statusstring: One of: active, inactive, testing

curl -X PATCH "https://bookifycall.com/api/v1/external/agents/00000000-0000-4000-8000-000000000002" \
  -H "X-API-Key: $BOOKIFYCALL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description":"After-hours line","status":"inactive"}'

Example response · 200

{
  "success": true,
  "data": {
    "id": "00000000-0000-4000-8000-000000000002",
    "organizationId": "00000000-0000-4000-8000-000000000100",
    "name": "Riley",
    "slug": "riley",
    "description": "Front desk for Example Dental",
    "status": "active",
    "personality": {
      "name": "Riley",
      "tone": "friendly"
    },
    "voiceConfig": {
      "provider": "elevenlabs",
      "voiceId": "example-voice"
    },
    "companyInfo": {
      "name": "Example Dental",
      "hours": "Mon-Fri 9-5"
    },
    "language": "en-US",
    "transferConfig": {
      "enabled": true,
      "contacts": [
        {
          "name": "Front desk",
          "phone": "+15551230003",
          "priority": 1
        }
      ]
    },
    "conversationConfig": {
      "knowledgeBase": {
        "entries": [
          {
            "fact": "We are open 9-5 Monday to Friday"
          }
        ]
      }
    },
    "enabledTools": [
      "book_appointment",
      "transfer_call"
    ],
    "customTools": [],
    "kind": "tenant",
    "conversationEngine": "platform",
    "stats": {},
    "isDefault": true,
    "createdAt": "2026-01-02T10:00:00.000Z",
    "updatedAt": "2026-01-15T16:34:10.000Z",
    "deletedAt": null
  }
}

Delete an agentLink to Delete an agent

DELETE/agents/{id}

Scope: agents:write
Not found: 404 AGENT_001

Path parameters

idstringrequired

curl -X DELETE "https://bookifycall.com/api/v1/external/agents/00000000-0000-4000-8000-000000000001" \
  -H "X-API-Key: $BOOKIFYCALL_API_KEY"

Example response · 200

{
  "success": true,
  "message": "Agent deleted"
}

Replace knowledge-base entriesLink to Replace knowledge-base entries

PATCH/agents/{id}/knowledge-base

Scope: agents:write
Not found: 404 AGENT_001

Path parameters

idstringrequired

Body (JSON)

entriesobject[]required

curl -X PATCH "https://bookifycall.com/api/v1/external/agents/00000000-0000-4000-8000-000000000002/knowledge-base" \
  -H "X-API-Key: $BOOKIFYCALL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entries":[{"fact":"We are open 9-5 Monday to Friday","excludeFromBot":false}]}'

Example response · 200

{
  "success": true,
  "data": {
    "id": "00000000-0000-4000-8000-000000000002",
    "organizationId": "00000000-0000-4000-8000-000000000100",
    "name": "Riley",
    "slug": "riley",
    "description": "Front desk for Example Dental",
    "status": "active",
    "personality": {
      "name": "Riley",
      "tone": "friendly"
    },
    "voiceConfig": {
      "provider": "elevenlabs",
      "voiceId": "example-voice"
    },
    "companyInfo": {
      "name": "Example Dental",
      "hours": "Mon-Fri 9-5"
    },
    "language": "en-US",
    "transferConfig": {
      "enabled": true,
      "contacts": [
        {
          "name": "Front desk",
          "phone": "+15551230003",
          "priority": 1
        }
      ]
    },
    "conversationConfig": {
      "knowledgeBase": {
        "entries": [
          {
            "fact": "We are open 9-5 Monday to Friday"
          }
        ]
      }
    },
    "enabledTools": [
      "book_appointment",
      "transfer_call"
    ],
    "customTools": [],
    "kind": "tenant",
    "conversationEngine": "platform",
    "stats": {},
    "isDefault": true,
    "createdAt": "2026-01-02T10:00:00.000Z",
    "updatedAt": "2026-01-15T16:34:10.000Z",
    "deletedAt": null
  }
}

Replace the agent's server tools (e.g. who_is_available)Link to Replace the agent's server tools (e.g. who_is_available)

PATCH/agents/{id}/custom-apis

Each url must be public https. `{{param}}` placeholders are filled at call time.

Scope: agents:write
Not found: 404 AGENT_001

Path parameters

idstringrequired

Body (JSON)

customApisobject[]required

curl -X PATCH "https://bookifycall.com/api/v1/external/agents/00000000-0000-4000-8000-000000000002/custom-apis" \
  -H "X-API-Key: $BOOKIFYCALL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customApis":[{"name":"who_is_available","description":"Check whether a named person can take a call right now","url":"https://app.example.com/api/voice/availability?agent={{agentName}}","method":"GET","headers":[{"key":"Authorization","value":"Bearer <your token>"}],"parameters":[{"name":"agentName","description":"The person asked for","required":true}],"enabled":true}]}'

Example response · 200

{
  "success": true,
  "data": {
    "id": "00000000-0000-4000-8000-000000000002",
    "organizationId": "00000000-0000-4000-8000-000000000100",
    "name": "Riley",
    "slug": "riley",
    "description": "Front desk for Example Dental",
    "status": "active",
    "personality": {
      "name": "Riley",
      "tone": "friendly"
    },
    "voiceConfig": {
      "provider": "elevenlabs",
      "voiceId": "example-voice"
    },
    "companyInfo": {
      "name": "Example Dental",
      "hours": "Mon-Fri 9-5"
    },
    "language": "en-US",
    "transferConfig": {
      "enabled": true,
      "contacts": [
        {
          "name": "Front desk",
          "phone": "+15551230003",
          "priority": 1
        }
      ]
    },
    "conversationConfig": {
      "knowledgeBase": {
        "entries": [
          {
            "fact": "We are open 9-5 Monday to Friday"
          }
        ]
      }
    },
    "enabledTools": [
      "book_appointment",
      "transfer_call"
    ],
    "customTools": [
      {
        "name": "who_is_available",
        "description": "Check whether a named person can take a call right now",
        "url": "https://app.example.com/api/voice/availability?agent={{agentName}}",
        "method": "GET",
        "parameters": [
          {
            "name": "agentName",
            "description": "The person asked for",
            "required": true
          }
        ],
        "enabled": true
      }
    ],
    "kind": "tenant",
    "conversationEngine": "platform",
    "stats": {},
    "isDefault": true,
    "createdAt": "2026-01-02T10:00:00.000Z",
    "updatedAt": "2026-01-15T16:34:10.000Z",
    "deletedAt": null
  }
}

Replace transfer contactsLink to Replace transfer contacts

PATCH/agents/{id}/transfer-contacts

Scope: agents:write
Not found: 404 AGENT_001

Path parameters

idstringrequired

Body (JSON)

transferContactsobjectrequired

curl -X PATCH "https://bookifycall.com/api/v1/external/agents/00000000-0000-4000-8000-000000000002/transfer-contacts" \
  -H "X-API-Key: $BOOKIFYCALL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transferContacts":{"enabled":true,"contacts":[{"name":"Front desk","role":"reception","phone":"+15551230003","priority":1,"ringTimeoutSec":20}]}}'

Example response · 200

{
  "success": true,
  "data": {
    "id": "00000000-0000-4000-8000-000000000002",
    "organizationId": "00000000-0000-4000-8000-000000000100",
    "name": "Riley",
    "slug": "riley",
    "description": "Front desk for Example Dental",
    "status": "active",
    "personality": {
      "name": "Riley",
      "tone": "friendly"
    },
    "voiceConfig": {
      "provider": "elevenlabs",
      "voiceId": "example-voice"
    },
    "companyInfo": {
      "name": "Example Dental",
      "hours": "Mon-Fri 9-5"
    },
    "language": "en-US",
    "transferConfig": {
      "enabled": true,
      "contacts": [
        {
          "name": "Front desk",
          "phone": "+15551230003",
          "priority": 1
        }
      ]
    },
    "conversationConfig": {
      "knowledgeBase": {
        "entries": [
          {
            "fact": "We are open 9-5 Monday to Friday"
          }
        ]
      }
    },
    "enabledTools": [
      "book_appointment",
      "transfer_call"
    ],
    "customTools": [],
    "kind": "tenant",
    "conversationEngine": "platform",
    "stats": {},
    "isDefault": true,
    "createdAt": "2026-01-02T10:00:00.000Z",
    "updatedAt": "2026-01-15T16:34:10.000Z",
    "deletedAt": null
  }
}

Next: Numbers