API Reference · Workflows

Send contacts to call

Sends one contact, or up to 1,000, to a live workflow that starts with an API Trigger. They're called right away (within the workflow's calling hours), and the workflow's follow-ups and results delivery run as usual. Use it to call new leads from your CRM, a website form or Zapier.

POST/workflows/{workflow_id}/trigger

https://calling.ubiqproject.com/api/v1/workflows/{workflow_id}/trigger · Auth: API key (full access)

Before you start

Build a workflow in the dashboard whose source is an API Trigger block (see Workflows).
Open the API Trigger block: it shows this endpoint with your workflow's ID already filled in. Copy it.
Press Start calling. The workflow then stays live, waiting for contacts, until you stop it — even when it has nothing left to call.

Request

Path parameters

workflow_idstring (UUID)required

The workflow's ID, from its API Trigger block.

Body

contactobject

One contact.

contactsobject[]

A list of contacts. You can send both; contact is counted first.

Send at least one contact, and at most 1,000 per request. Each contact is an object:

Contact fields

phonestringrequired

International format: + or 00, then 8–15 digits. Spaces and dashes are removed, so +91 98765-43210 is fine. A number without + or 00, such as 9876543210, is rejected. phone_number works too.

any other fieldstring

Becomes a {{placeholder}} the AI employee can use, and a column your workflow's filter can check — name, amount_due, lead_source… Fields starting with _ are dropped.

Request

curl -X POST https://calling.ubiqproject.com/api/v1/workflows/e2d7c4b9-5f1a-4b8e-9c63-0a4d6e8f1b25/trigger \
  -H "Authorization: Bearer vk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "phone": "+919876543210", "name": "Rahul Verma", "lead_source": "website" },
      { "phone": "+919812345678", "name": "Anita Desai", "lead_source": "website" },
      { "phone": "98989 12345", "name": "Imran Khan", "lead_source": "walk-in" }
    ]
  }'

Response

Response · 200

{
  "queued": 2,
  "skipped_by_filter": 0,
  "duplicates": 0,
  "invalid": [2],
  "detail": "Invalid rows need an international phone number, e.g. +919876543210."
}

Response fields

queuedinteger

Contacts added to the queue to be called.

skipped_by_filterinteger

Contacts that didn't pass the workflow's filter. They're recorded but never called.

duplicatesinteger

Contacts not queued because the same phone number was in this request or is already waiting in this run.

invalidinteger[]

Positions (from 0) of contacts rejected for a bad phone number, counting contact first and then contacts. The others are still queued.

detailstring | null

Explains invalid; null when every phone was valid.

Errors

Responses

The workflow isn't calling — press Start calling on it first409

The workflow isn't live, or it has been stopped.

This workflow doesn't start from an API Trigger409

Only workflows with an API Trigger block accept contacts this way.

At most 1000 contacts per request413

Split the list into batches of 1,000.

Send a contact ({"contact": {...}}) or a list ({"contacts": [...]})422

The body had no contacts.

Workflow not found404

No workflow with this ID in your company, or the ID isn't a UUID.

Duplicates are sent once

If the same phone number appears twice in one request, or is already waiting or on a call in this run, it isn't queued again — it's counted in duplicates. A number whose call has already finished can be queued again.

Follow the results

Each workflow runs as a campaign, so you can read its results with the Campaigns endpoints, or add a results step to the workflow so each result is sent to your CRM, a Google Sheet or your own URL (see Workflows).