Skip to Content
HallolaraDocs
Public API

Quickstart

Choose a voice, create an assistant, add knowledge, and place your first outbound call.

From a fresh API key to a live outbound call. All examples use https://api.hallolara.ai/api/v1.

1. Create an API key

In the dashboard, go to Settings → API Keys and create a key. Each key is scoped to your organization and to a single Role, which determines the endpoints it may call. Newly generated keys are ~43-character base64url strings with no prefix; older keys that start with a prefix remain valid. Export it for the examples below:

export API_KEY="<your_api_key>"

2. Check connectivity

curl https://api.hallolara.ai/api/v1/ping \
  -H "Authorization: Bearer $API_KEY"
{ "data": { "ok": true, "now": "2026-07-01T12:00:00.000Z" } }

A 401 with error.code = "unauthorized" means the key is missing or invalid - see Errors.

3. Choose a voice

Fetch the voices currently selectable for new assistants and voice changes:

curl https://api.hallolara.ai/api/v1/voices \
  -H "Authorization: Bearer $API_KEY"

Use an id from the response as voice_id below. See listVoices for the response schema.

4. Create an assistant

name, language, voice_id, company_name, company_industry, and introduction are required. The platform assigns the phone number; to use one of your organization's purchased numbers instead, send its id from listPhoneNumbers as phone_number_id. Organizations that route calls through their own assigned carrier must send phone_number_id.

curl -X POST https://api.hallolara.ai/api/v1/assistants \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sarah",
    "language": "en",
    "voice_id": "<voice_id>",
    "company_name": "Example GmbH",
    "company_industry": "Retail",
    "introduction": "Hello, you have reached Example GmbH. How can I help you?"
  }'

The 201 response contains the assistant under data, including its generated id (needed below) and assigned phone_number. See createAssistant for all optional fields.

5. Add knowledge

Knowledge items live in groups: create a knowledges group, add an item, attach the group to your assistant.

curl -X POST https://api.hallolara.ai/api/v1/groups \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "knowledges", "name": "FAQ" }'

Take data.id from the response and create the item:

curl -X POST https://api.hallolara.ai/api/v1/knowledge-items \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "<group_id>",
    "name": "Opening hours",
    "text": "We are open Monday to Friday, 9:00 to 18:00."
  }'

Attach the group to the assistant:

curl -X PATCH https://api.hallolara.ai/api/v1/assistants/<assistant_id> \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "knowledge_group_ids": ["<group_id>"] }'

Embedding is asynchronous: sync_status.state moves pending → syncing → synced (or failed). There are no event webhooks - poll getKnowledgeItem until the item is synced or failed, and apply a client-side timeout so a persistent pending state does not create an endless poll loop.

6. Place an outbound call

Provide exactly one of assistant_id or assistant_phone, and exactly one of to or target_phone. Numbers are E.164 (+ followed by 6–20 digits).

curl -X POST https://api.hallolara.ai/api/v1/calls \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "<assistant_id>",
    "to": "+491701234999",
    "details": "Follow-up on order 4711."
  }'
{
  "data": {
    "call_id": "65f8fa6f1a9d8e0012ab34cd",
    "assistant_id": "<assistant_id>",
    "assistant_phone": "+491701234567",
    "to": "+491701234999",
    "status": "queued",
    "created_at": "2026-07-01T12:00:00.000Z"
  }
}

POST /calls defaults to a 60 requests/hour bucket per API key and also permits only one outbound call per assistant in any 60-second window. On 429, use Retry-After when present; otherwise wait at least 60 seconds and retry with exponential backoff.

Once the call completes, poll getCall for the transcript and analyses, and getCallRecording for the audio. On a call that was transferred, an analysis that uses didTryForwarding or didForwardingSucceed appears later: about 10 to 15 seconds after the call is done, or up to 43 minutes while the transfer is still connected. Other analyses of the call are not delayed.

For bounded machine-answer retries, see the mailbox detection guide.

7. Where next

  • The full endpoint reference in the sidebar - every page has an interactive playground.
  • Errors - error envelope, codes, and retry guidance.
  • Authentication - key handling and role scoping.

On this page