Runs

One shopper to call with one flow. A run places up to maxAttempts calls within calling hours and ends with the shopper’s answers and an outcome.

Start a run

POST/runs

Calls one shopper with a flow. Every check a call needs happens first: the shopper’s consent (send it with the run, or record it on the contact), opt-outs, the flow’s required inputs and calling hours. Outside calling hours the run waits for them to open, unless whenClosed is refuse. A test key’s run calls no one.

Needs the runs scope.

Headers

Idempotency-Keystring
Retry safely: the same key and request get the same response for 24 hours.

Body

flowIdstring
The flow to call with; its published version runs.
flowKeystring
Instead of flowId: a library flow installed for this org (POST /v1/flows/library/{libraryKey}/install), by its key, e.g. order_verification.
contactIdstring
A contact to call, instead of a phone number.
phonestring
Who to call, if not a contact id.
namestring
Saves the number as a contact with this name.
inputsmap of string
The flow’s inputs, as its inputSchema describes.
Default {}
languagestring
The language to start in, when the flow allows it; else the flow’s default.
One ofhi-INen-INta-INte-INmr-INgu-INbn-INkn-INml-INpa-INod-IN
consentobject
The shopper’s consent, recorded on their contact before the call.
Show 4 fields insideHide the fields inside
- scopestringrequired
  One ofservicepromotional
- givenAtstringrequired
- notestringrequired
- sourcestringrequired
  One offormcheckoutimportverbalother
transactionAtstring
When the shopper’s own purchase happened: allows a transactional call within 30 minutes.
whenClosedstring
Outside calling hours: wait for them to open (default), or refuse.
One ofschedulerefuse
Default "schedule"
metadatamap of string
Your own references (order id, merchant id): sent back with every event.
Default {}
testAnswersmap of string
Test keys only: the answer each question gets, by its key ("yes"/"no", a choice, a number, text). Questions left out get a sample.

Returns 201

Done.

okbooleanrequired
One oftrue
runRunrequired
Show 20 fields insideHide the fields inside
- idstringrequired
- flowIdstringrequired
- flowVersionIdstringrequired
  The exact published version the run follows.
- contactIdstring or nullrequired
- phonestringrequired
- inputsmap of stringrequired
- languagestringrequired
- statusstringrequired
  One ofscheduleddialingdonegave_upcanceled
- attemptsintegerrequired
- maxAttemptsintegerrequired
- nextAttemptAtstring or nullrequired
  ISO 8601 time.
- lastErrorstring or nullrequired
  Why it’s waiting or stopped without reaching the shopper.
- outcomestring or nullrequired
  The run’s outcome once it ends (its last attempt’s).
- answersmap of string or number or boolean or nullrequired
  The last attempt’s answers, by question key.
- metadatamap of stringrequired
- isTestbooleanrequired
- createdAtstringrequired
  ISO 8601 time.
- updatedAtstringrequired
  ISO 8601 time.
- callslist of RunAttemptrequired
  Show 6 fields insideHide the fields inside
  callIdstringrequired
  attemptintegerrequired
  statusstringrequired
  answeredAtstring or nullrequired
  ISO 8601 time.
  endedAtstring or nullrequired
  ISO 8601 time.
  outcomestring or nullrequired
- actionslist of ActionCallrequired
  Every action its calls asked for, oldest first.
  Show 13 fields insideHide the fields inside
  idstringrequired
  callIdstringrequired
  runIdstring or nullrequired
  namestringrequired
  argsmap of stringrequired
  statusstringrequired
  sample: not registered, so the catalogue’s sample reply was used.
  One ofsentsuccessrefusedpendingtimeoutsample
  resultmap of any or nullrequired
  saystring or nullrequired
  errorCodestring or nullrequired
  httpStatusinteger or nullrequired
  durationMsinteger or nullrequired
  createdAtstringrequired
  ISO 8601 time.
  finishedAtstring or nullrequired
  ISO 8601 time.

Request

curl -X POST https://app.rowcall.ai/v1/runs \
  -H "Authorization: Bearer $ROWCALL_API_KEY" \
  -H "Idempotency-Key: verify-4821" \
  -H "Content-Type: application/json" \
  -d '{
    "flowKey": "order_verification",
    "phone": "+919812345678",
    "name": "Asha Rao",
    "inputs": {
      "customer_name": "Asha",
      "phone": "+919812345678",
      "order_id": "4821",
      "items": "a pair of running shoes",
      "order_total": "2499",
      "address": "12 MG Road, Pune"
    },
    "consent": {
      "scope": "service",
      "source": "checkout",
      "givenAt": "2026-10-13T09:20:00+05:30",
      "note": "Ticked \"Call me about this order\" at checkout."
    },
    "transactionAt": "2026-10-13T09:20:00+05:30",
    "metadata": {
      "shopify_order_id": "5523981"
    }
  }'

Response

{
  "ok": true,
  "run": {
    "id": "run_8hq2x2m4q8w1z7p5n6b0",
    "flowId": "flw_k3j9x2m4q8w1z7p5n6b0",
    "flowVersionId": "flv_z2x4c6v8b0n2m4l6k8j0",
    "contactId": "con_m5n7b9v1c3x5z7l9k1j3",
    "phone": "+919812345678",
    "inputs": {
      "customer_name": "Asha",
      "phone": "+919812345678",
      "order_id": "4821",
      "items": "a pair of running shoes",
      "order_total": "2499",
      "address": "12 MG Road, Pune"
    },
    "language": "hi-IN",
    "status": "scheduled",
    "attempts": 0,
    "maxAttempts": 3,
    "nextAttemptAt": "2026-10-13T09:31:02.000Z",
    "lastError": null,
    "outcome": null,
    "answers": {},
    "metadata": {
      "shopify_order_id": "5523981"
    },
    "isTest": false,
    "createdAt": "2026-10-13T09:31:02.000Z",
    "updatedAt": "2026-10-13T09:31:02.000Z",
    "calls": [],
    "actions": []
  }
}

List runs

GET/runs

Your runs, newest first, 50 a page (up to 100). A test key lists test runs only.

Needs the runs scope.

Query

cursorstring
limitinteger
Default 50
flowIdstring
statusstring
One ofscheduleddialingdonegave_upcanceled

Returns 200

Done.

okbooleanrequired
One oftrue
runslist of Runrequired
Show 20 fields insideHide the fields inside
- idstringrequired
- flowIdstringrequired
- flowVersionIdstringrequired
  The exact published version the run follows.
- contactIdstring or nullrequired
- phonestringrequired
- inputsmap of stringrequired
- languagestringrequired
- statusstringrequired
  One ofscheduleddialingdonegave_upcanceled
- attemptsintegerrequired
- maxAttemptsintegerrequired
- nextAttemptAtstring or nullrequired
  ISO 8601 time.
- lastErrorstring or nullrequired
  Why it’s waiting or stopped without reaching the shopper.
- outcomestring or nullrequired
  The run’s outcome once it ends (its last attempt’s).
- answersmap of string or number or boolean or nullrequired
  The last attempt’s answers, by question key.
- metadatamap of stringrequired
- isTestbooleanrequired
- createdAtstringrequired
  ISO 8601 time.
- updatedAtstringrequired
  ISO 8601 time.
- callslist of RunAttemptrequired
  Show 6 fields insideHide the fields inside
  callIdstringrequired
  attemptintegerrequired
  statusstringrequired
  answeredAtstring or nullrequired
  ISO 8601 time.
  endedAtstring or nullrequired
  ISO 8601 time.
  outcomestring or nullrequired
- actionslist of ActionCallrequired
  Every action its calls asked for, oldest first.
  Show 13 fields insideHide the fields inside
  idstringrequired
  callIdstringrequired
  runIdstring or nullrequired
  namestringrequired
  argsmap of stringrequired
  statusstringrequired
  sample: not registered, so the catalogue’s sample reply was used.
  One ofsentsuccessrefusedpendingtimeoutsample
  resultmap of any or nullrequired
  saystring or nullrequired
  errorCodestring or nullrequired
  httpStatusinteger or nullrequired
  durationMsinteger or nullrequired
  createdAtstringrequired
  ISO 8601 time.
  finishedAtstring or nullrequired
  ISO 8601 time.
nextCursorstring or nullrequired

Request

curl https://app.rowcall.ai/v1/runs \
  -H "Authorization: Bearer $ROWCALL_API_KEY"

Response

{
  "ok": true,
  "runs": [
    {
      "id": "run_8hq2x2m4q8w1z7p5n6b0",
      "flowId": "flw_k3j9x2m4q8w1z7p5n6b0",
      "flowVersionId": "flv_z2x4c6v8b0n2m4l6k8j0",
      "contactId": "con_m5n7b9v1c3x5z7l9k1j3",
      "phone": "+919812345678",
      "inputs": {
        "customer_name": "Asha",
        "phone": "+919812345678",
        "order_id": "4821",
        "items": "a pair of running shoes",
        "order_total": "2499",
        "address": "12 MG Road, Pune"
      },
      "language": "hi-IN",
      "status": "done",
      "attempts": 1,
      "maxAttempts": 3,
      "nextAttemptAt": null,
      "lastError": null,
      "outcome": "confirmed",
      "answers": {
        "placed_order": true,
        "address_correct": true
      },
      "metadata": {
        "shopify_order_id": "5523981"
      },
      "isTest": false,
      "createdAt": "2026-10-13T09:31:02.000Z",
      "updatedAt": "2026-10-13T09:32:20.000Z",
      "calls": [
        {
          "callId": "cal_r4t6y8u0i2o4p6a8s0d2",
          "attempt": 1,
          "status": "completed",
          "answeredAt": "2026-10-13T09:31:12.000Z",
          "endedAt": "2026-10-13T09:32:20.000Z",
          "outcome": "confirmed"
        }
      ],
      "actions": [
        {
          "id": "act_q1w3e5r7t9y1u3i5o7p9",
          "callId": "cal_r4t6y8u0i2o4p6a8s0d2",
          "runId": "run_8hq2x2m4q8w1z7p5n6b0",
          "name": "confirm_order",
          "args": {
            "order_id": "4821"
          },
          "status": "success",
          "result": {
            "confirmed": true
          },
          "say": null,
          "errorCode": null,
          "httpStatus": 200,
          "durationMs": 412,
          "createdAt": "2026-10-13T09:31:48.000Z",
          "finishedAt": "2026-10-13T09:31:48.412Z"
        }
      ]
    }
  ],
  "nextCursor": null
}

Get a run

GET/runs/{runId}

Where the run is, each attempt, and once the shopper answered, their answers and the outcome.

Needs the runs scope.

Path

runIdstringrequired

Returns 200

Done.

okbooleanrequired
One oftrue
runRunrequired
Show 20 fields insideHide the fields inside
- idstringrequired
- flowIdstringrequired
- flowVersionIdstringrequired
  The exact published version the run follows.
- contactIdstring or nullrequired
- phonestringrequired
- inputsmap of stringrequired
- languagestringrequired
- statusstringrequired
  One ofscheduleddialingdonegave_upcanceled
- attemptsintegerrequired
- maxAttemptsintegerrequired
- nextAttemptAtstring or nullrequired
  ISO 8601 time.
- lastErrorstring or nullrequired
  Why it’s waiting or stopped without reaching the shopper.
- outcomestring or nullrequired
  The run’s outcome once it ends (its last attempt’s).
- answersmap of string or number or boolean or nullrequired
  The last attempt’s answers, by question key.
- metadatamap of stringrequired
- isTestbooleanrequired
- createdAtstringrequired
  ISO 8601 time.
- updatedAtstringrequired
  ISO 8601 time.
- callslist of RunAttemptrequired
  Show 6 fields insideHide the fields inside
  callIdstringrequired
  attemptintegerrequired
  statusstringrequired
  answeredAtstring or nullrequired
  ISO 8601 time.
  endedAtstring or nullrequired
  ISO 8601 time.
  outcomestring or nullrequired
- actionslist of ActionCallrequired
  Every action its calls asked for, oldest first.
  Show 13 fields insideHide the fields inside
  idstringrequired
  callIdstringrequired
  runIdstring or nullrequired
  namestringrequired
  argsmap of stringrequired
  statusstringrequired
  sample: not registered, so the catalogue’s sample reply was used.
  One ofsentsuccessrefusedpendingtimeoutsample
  resultmap of any or nullrequired
  saystring or nullrequired
  errorCodestring or nullrequired
  httpStatusinteger or nullrequired
  durationMsinteger or nullrequired
  createdAtstringrequired
  ISO 8601 time.
  finishedAtstring or nullrequired
  ISO 8601 time.

Request

curl https://app.rowcall.ai/v1/runs/run_8hq2x2m4q8w1z7p5n6b0 \
  -H "Authorization: Bearer $ROWCALL_API_KEY"

Response

{
  "ok": true,
  "run": {
    "id": "run_8hq2x2m4q8w1z7p5n6b0",
    "flowId": "flw_k3j9x2m4q8w1z7p5n6b0",
    "flowVersionId": "flv_z2x4c6v8b0n2m4l6k8j0",
    "contactId": "con_m5n7b9v1c3x5z7l9k1j3",
    "phone": "+919812345678",
    "inputs": {
      "customer_name": "Asha",
      "phone": "+919812345678",
      "order_id": "4821",
      "items": "a pair of running shoes",
      "order_total": "2499",
      "address": "12 MG Road, Pune"
    },
    "language": "hi-IN",
    "status": "done",
    "attempts": 1,
    "maxAttempts": 3,
    "nextAttemptAt": null,
    "lastError": null,
    "outcome": "confirmed",
    "answers": {
      "placed_order": true,
      "address_correct": true
    },
    "metadata": {
      "shopify_order_id": "5523981"
    },
    "isTest": false,
    "createdAt": "2026-10-13T09:31:02.000Z",
    "updatedAt": "2026-10-13T09:32:20.000Z",
    "calls": [
      {
        "callId": "cal_r4t6y8u0i2o4p6a8s0d2",
        "attempt": 1,
        "status": "completed",
        "answeredAt": "2026-10-13T09:31:12.000Z",
        "endedAt": "2026-10-13T09:32:20.000Z",
        "outcome": "confirmed"
      }
    ],
    "actions": [
      {
        "id": "act_q1w3e5r7t9y1u3i5o7p9",
        "callId": "cal_r4t6y8u0i2o4p6a8s0d2",
        "runId": "run_8hq2x2m4q8w1z7p5n6b0",
        "name": "confirm_order",
        "args": {
          "order_id": "4821"
        },
        "status": "success",
        "result": {
          "confirmed": true
        },
        "say": null,
        "errorCode": null,
        "httpStatus": 200,
        "durationMs": 412,
        "createdAt": "2026-10-13T09:31:48.000Z",
        "finishedAt": "2026-10-13T09:31:48.412Z"
      }
    ]
  }
}

Cancel a run

POST/runs/{runId}/cancel

No more attempts. A call already on carries on to its end. A finished run stays as it is.

Needs the runs scope.

Path

runIdstringrequired

Headers

Idempotency-Keystring
Retry safely: the same key and request get the same response for 24 hours.

Returns 200

Done.

okbooleanrequired
One oftrue
runRunrequired
Show 20 fields insideHide the fields inside
- idstringrequired
- flowIdstringrequired
- flowVersionIdstringrequired
  The exact published version the run follows.
- contactIdstring or nullrequired
- phonestringrequired
- inputsmap of stringrequired
- languagestringrequired
- statusstringrequired
  One ofscheduleddialingdonegave_upcanceled
- attemptsintegerrequired
- maxAttemptsintegerrequired
- nextAttemptAtstring or nullrequired
  ISO 8601 time.
- lastErrorstring or nullrequired
  Why it’s waiting or stopped without reaching the shopper.
- outcomestring or nullrequired
  The run’s outcome once it ends (its last attempt’s).
- answersmap of string or number or boolean or nullrequired
  The last attempt’s answers, by question key.
- metadatamap of stringrequired
- isTestbooleanrequired
- createdAtstringrequired
  ISO 8601 time.
- updatedAtstringrequired
  ISO 8601 time.
- callslist of RunAttemptrequired
  Show 6 fields insideHide the fields inside
  callIdstringrequired
  attemptintegerrequired
  statusstringrequired
  answeredAtstring or nullrequired
  ISO 8601 time.
  endedAtstring or nullrequired
  ISO 8601 time.
  outcomestring or nullrequired
- actionslist of ActionCallrequired
  Every action its calls asked for, oldest first.
  Show 13 fields insideHide the fields inside
  idstringrequired
  callIdstringrequired
  runIdstring or nullrequired
  namestringrequired
  argsmap of stringrequired
  statusstringrequired
  sample: not registered, so the catalogue’s sample reply was used.
  One ofsentsuccessrefusedpendingtimeoutsample
  resultmap of any or nullrequired
  saystring or nullrequired
  errorCodestring or nullrequired
  httpStatusinteger or nullrequired
  durationMsinteger or nullrequired
  createdAtstringrequired
  ISO 8601 time.
  finishedAtstring or nullrequired
  ISO 8601 time.

Request

curl -X POST https://app.rowcall.ai/v1/runs/run_8hq2x2m4q8w1z7p5n6b0/cancel \
  -H "Authorization: Bearer $ROWCALL_API_KEY" \
  -H "Idempotency-Key: verify-4821"

Response

{
  "ok": true,
  "run": {
    "id": "run_8hq2x2m4q8w1z7p5n6b0",
    "flowId": "flw_k3j9x2m4q8w1z7p5n6b0",
    "flowVersionId": "flv_z2x4c6v8b0n2m4l6k8j0",
    "contactId": "con_m5n7b9v1c3x5z7l9k1j3",
    "phone": "+919812345678",
    "inputs": {
      "customer_name": "Asha",
      "phone": "+919812345678",
      "order_id": "4821",
      "items": "a pair of running shoes",
      "order_total": "2499",
      "address": "12 MG Road, Pune"
    },
    "language": "hi-IN",
    "status": "canceled",
    "attempts": 0,
    "maxAttempts": 3,
    "nextAttemptAt": null,
    "lastError": null,
    "outcome": null,
    "answers": {},
    "metadata": {
      "shopify_order_id": "5523981"
    },
    "isTest": false,
    "createdAt": "2026-10-13T09:31:02.000Z",
    "updatedAt": "2026-10-13T09:31:02.000Z",
    "calls": [],
    "actions": []
  }
}