Endpoint
POST /v1/calls is the public route for a call request. The application handler is /api/calls. Send a Bearer API key created in the authenticated workspace Settings page. Keys belong to an organization and are shown once at creation.
Approved request
curl https://app.topdoer.ai/v1/calls \
-H "Authorization: Bearer $TOPDOER_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"to": "+12025550123",
"goal": "Ask about available appointment times. Do not book without approval.",
"language": "en",
"approved": true,
"request_id": "123e4567-e89b-42d3-a456-426614174000"
}'
The number above is an example, not a destination you are authorized to call. Use a number you control for testing. The approval flag must represent an actual human approval of the destination and goal. It is not a blanket authorization for future calls.
Fields
to: an eligible destination in E.164 format.goal: a specific description of the approved task.language:enores.approved: must betrueafter human approval.request_id: a new UUID for this intended operation. Reuse it only when retrying that same request.
The organization must have a configured agent and number, a verified owner phone, sufficient credit, and applicable limits. Recipient eligibility, suppression policy, permitted countries, and calling hours are also checked. A rejected prerequisite is not an invitation to bypass the control.
Retries and outcomes
The server reserves an operation before dispatch. Do not issue a new request identifier merely because a request is still processing. Check the call result instead. A provider accepting a request is not the same as a completed conversation or a successful real-world outcome.
Errors
Unauthenticated requests fail with 401. Invalid input fails validation. Missing provider configuration returns 503. A workflow or policy prerequisite can return 409 with a message describing the category to review. Store the request identifier in your own application so support can trace the intended operation without exposing the API key.