The calls API is an alternative for applications that need a direct integration. A server uses a scoped workspace API key to submit a reviewed call request, then reads the result using the returned identifier. topdoer.ai checks the account and destination before a call can proceed. Keep the human approval step in your application.
Start with a clear request
Create an API key in your workspace settings and grant only the scopes your application needs. Store the key on your server or in a supported secret manager. A browser bundle, mobile package, public repository, or URL query string is not a safe place for a private API credential. Use separate keys when you need different access boundaries.
Construct a request from an approved intent. The destination should use E.164 format, the goal should be specific, and the language should be en or es. Include approved true only after a person has reviewed the action. A unique request_id lets your application retry the same intent without deliberately creating a second call. Generate a fresh identifier for a different approved task.
Connect the client you use
Use the documented POST /v1/calls endpoint on app.topdoer.ai. The server also exposes the matching authenticated read routes. The example below illustrates the body, not an instruction to run an unattended campaign. Begin with a permitted destination and a test goal you have explicitly approved. See the developer documentation for the full authentication and webhook contract.
Review the result
Treat API responses as states in a workflow. Accepted means the request passed the initial checks, not that the recipient answered. Save the call identifier, poll the authenticated result route or process verified webhooks, and surface the actual status to your user. A failed request should remain a failure in your UI rather than becoming an optimistic success message.
Keep the boundaries clear
The API applies the same plan limits as other clients. A valid key alone is not enough: the owner may need verified phone access, a number, an active plan or credits, and recipient consent. Your application should handle validation failures, limit responses, and service-unavailable states. Do not retry an uncertain outbound request with a new identifier until you have checked the first result.
Set up the connection in three steps
- Choose your AI in the Phone setup dialog. Check that the client supports the remote connection and that your workspace permits it.
- Connect the MCP endpoint with supported authentication. Use a read-only request first, then review a specific call or message before approving it.
- Review the plan at checkout. Choosing a client does not charge you, and a connection does not activate an unconfigured number or subscription.
Read the plan before you start
The first month is $9, then $19 per month, or $190 a year with two months free. Fair use applies: 200 call minutes and 300 text segments a month, one call at a time, 30 calls a day, and up to 15 minutes per call, to US, Puerto Rico and Canada numbers. Over the cap, add a $10 top-up (about 60 minutes) or wait for the next cycle. See the full fair-use list.
Keep a record of what you approved and what actually happened. If a request fails, read the error and check its state before trying again. Review the billing terms shown by Stripe, including renewal and taxes. Your workspace Billing page opens the supported customer portal for subscription changes. You can also contact our team when a plan or client requirement needs clarification.
Frequently asked questions
Do I approve the call or text?
Yes. Review the destination, goal, and information to be shared before approving an outbound action. Keep your client's approval controls enabled.
Can I use English or Spanish?
English and Spanish are supported choices. Specify the language before the action and check the result for important names, dates, and numbers.
Where do I see the price and limits?
It costs $9 for the first month, then $19 a month or $190 a year. Fair-use limits apply, and checkout shows the final terms before you pay.
Request shape
The request below is an example body. Generate a request identifier for one approved intent, and send it from your authenticated server. It does not place a call until your account, consent, billing, and destination checks pass.
{
"to": "+1YOUR_ALLOWED_NUMBER",
"goal": "Ask about available appointment times. Do not book.",
"language": "en",
"approved": true,
"request_id": "YOUR_UNIQUE_REQUEST_ID"
}
Read the calls API documentation before implementing the request. Never use an example value as a real destination or credential.