API reference
RowCall API
Start calls to shoppers with your flows, read what they said, and keep your contacts in step. Use an API key (Authorization: Bearer rc_…) for your own org, or OAuth 2 when your app acts for merchants. Test credentials never call anyone.
New to RowCall? Start with the developer guides: what a flow, a run and an action are, and how they fit together.
Base URL
https://app.rowcall.ai/v1
Requests and responses are JSON. Every response has ok; times are ISO 8601 and ids carry a prefix (run_…, flw_…).
Authentication
Send a credential as a bearer token. Use an API key for your own org (Developers → API keys in the dashboard), or OAuth 2 when your app acts for merchants. Test credentials (rc_test_…) walk flows without calling anyone.
Authorization: Bearer rc_live_…
OAuth 2
Authorization code with PKCE. Send the merchant to https://app.rowcall.ai/oauth/authorize, then trade the code at https://app.rowcall.ai/v1/oauth/token. Access tokens last an hour; refresh tokens rotate.
Scopes
| Scope | Allows |
|---|---|
runs | Start, read and cancel calls to shoppers |
flows | Read, make and publish flows |
contacts | Add and update contacts and their consent |
calls | Read calls, transcripts and recordings |
actions | Define, change and delete actions, and finish pending ones |
Errors
A refused or failed request has ok: false, a sentence you can log or show (error) and a stable code to branch on (errorCode). Codes never change meaning; treat one you don’t know as a generic failure.
{ "ok": false, "error": "Fill in Order.", "errorCode": "INVALID_INPUT" }| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | INVALID_INPUT | A field is missing or wrong (error names it), or a required flow input is missing. | Fix the request. Don’t retry it as it is. |
| 401 | UNAUTHENTICATED | No credential, or the key or token is revoked or expired. | Check the Authorization header; refresh an OAuth token. |
| 402 | NO_CREDIT | The org’s balance can’t cover a minute of calling. Test runs are never refused for credit. | Top up in Settings → Billing. |
| 403 | FORBIDDEN | The credential lacks the route’s scope. | Use a key, or ask for a connection, with the right scope. |
| 403 | NOT_VERIFIED | RowCall hasn’t approved the business yet, so live calls can’t start. Test runs aren’t affected. | Send the business details for approval. |
| 403 | ORG_SUSPENDED | The org is suspended. | Contact RowCall support. |
| 403 | NO_CONSENT | No standing consent for the flow’s call type: service consent from the last 7 days, or for a transactional flow, a purchase within 30 minutes (transactionAt). | Send consent with the run, or record it on the contact first. |
| 403 | OPTED_OUT | The shopper asked not to be called. | Don’t call them. The opt-out stays until they ask to be called again. |
| 404 | NOT_FOUND | No such flow, run, call, contact or action, or it belongs to the other mode (live or test). | Check the id and the credential’s mode. |
| 409 | CONFLICT | The change clashes with what’s there, such as finishing an action that already has its result. | Read the current state first. |
| 409 | NOT_PUBLISHED | The flow has no published version. | Publish it, or start the run with a published flow. |
| 409 | OUTSIDE_CALLING_HOURS | It’s outside calling hours and the run asked to be refused then (whenClosed: "refuse"). | Try again when calling hours open, or let the run wait (the default). |
| 409 | NO_NUMBER | The org has no phone number for this kind of call yet. RowCall assigns one when it approves the business. | Wait for approval. Promotional flows never get a number. |
| 409 | IDEMPOTENCY_IN_PROGRESS | A request with this Idempotency-Key is still running. | Wait a moment, then retry. |
| 422 | IDEMPOTENCY_MISMATCH | The same Idempotency-Key came with a different request. | Use a new key for a new request. |
| 422 | FLOW_INVALID | The draft still has problems, so it can’t be published. | Fix each problem the draft lists, then publish. |
| 413 | PAYLOAD_TOO_LARGE | The body is over 64 KB. | Send less. |
| 429 | RATE_LIMITED | Too many requests for this credential. | Wait, then retry with backoff. |
| 501 | NOT_CONFIGURED | The first attempt couldn’t be placed: nothing is set up to place it. The run ends as gave_up. | Contact RowCall support. |
| 503 | PHONE_UNAVAILABLE | The first attempt couldn’t be placed: no phone line was free. The run ends as gave_up. | Retry with backoff. |
| 500 | INTERNAL | Something failed on RowCall’s side. | Retry with backoff; contact support if it persists. |
Sections
- ConnectionCheck a credential: the org it acts for, its mode and what it may do.
- FlowsThe calls RowCall can make for you. Install a ready-made flow from the library, or make your own, publish it, and start runs with it.
- RunsOne shopper to call with one flow. A run places up to
maxAttemptscalls within calling hours and ends with the shopper’s answers and an outcome. - CallsEach attempt of a run: how it went, its transcript and its recording.
- ContactsThe shoppers you call, with their consent and opt-outs.
- ActionsWhat the agent may do for a shopper during a call (look up an order, confirm it, change the address), and how your system answers.
- EventsWhat RowCall posts to your webhook URL as things happen.
- Action requestsWhat RowCall posts to your action URL when the agent uses an action.