Quickstart

This walkthrough uses the Voice API to place an outbound call with one of your voice agents and read the transcript afterwards. You need an organization API key and a voice agent that has been published in the Clarity app, with an outbound phone number configured for your project.

Store your key

export CLARITY_API_KEY="anek_org_..."

Find your project

curl https://voice-api.onclarity.com/v1/projects \
  -H "Authorization: Bearer $CLARITY_API_KEY"

Note the id of the project your agent belongs to.

export PROJECT_ID="..."

Find your agent

curl https://voice-api.onclarity.com/v1/projects/$PROJECT_ID/agents \
  -H "Authorization: Bearer $CLARITY_API_KEY"

Pick the agent and note its id.

export AGENT_ID="..."

Place a call

curl -X POST https://voice-api.onclarity.com/v1/projects/$PROJECT_ID/agents/$AGENT_ID/dispatch-call \
  -H "Authorization: Bearer $CLARITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+15551234567" }'

The call starts ringing straight away. The response carries the conversation’s id:

{
  "callId": "…",
  "roomName": "…",
  "status": "dialing",
  "conversationId": "…"
}

export CONVERSATION_ID="..."

Add "on_call_ended_url": "https://your-server.example.com/clarity/call-ended" to have the full call record posted to you when the call ends. See Call-ended webhook.

Read the transcript

After the call ends:

curl -G https://voice-api.onclarity.com/v1/projects/$PROJECT_ID/conversations/$CONVERSATION_ID/artifacts \
  -H "Authorization: Bearer $CLARITY_API_KEY" \
  --data-urlencode "include_recording=true"

merged.transcript holds the whole call as text, and each session’s recording_signed_url is a download link for its audio, valid for one hour. Until the call’s files are stored the request answers 404 with ARTIFACTS_NOT_READY; retry after a minute. See Conversations.

Next steps

Outbound calls

Caller ids, errors, and following a call to the end.

Campaigns

Call a list of numbers on a schedule.

Support API

Tickets, customers, messages, and webhooks.

API reference

Every endpoint, with a live playground.

Get started

Voice AI

Support and chat

SDKs

Next steps

Outbound calls

Campaigns

Support API

API reference

​Next steps

Outbound calls

Campaigns

Support API

API reference

Next steps