Copy page

Guides

Getting started

The Ringtime API lets your system start a conversation with a person. You send a trigger. Ringtime calls the person or sends a WhatsApp message.

The base URL is https://api.ringtime.ai.

Before you start

You need an API key. Request one by email at success@ringtime.ai. Read Authentication.

Send your first trigger

POST /api/v2/triggers starts one conversation. Give it a campaign routing key and the contact data.

Keep test_mode on true while you try the API. Ringtime then calls the phone number in contact, not a real candidate. Use your own number.

Code
curl -X POST https://api.ringtime.ai/api/v2/triggers \
  -H "Authorization: Bearer $RINGTIME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: my-request-1" \
  -d '{
    "campaign": "warehouse-nl",
    "contact": {
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": "+15555550100",
      "email": "example@example.com",
      "language": "nl"
    },
    "test_mode": true
  }'

What you get back

A successful request gives HTTP 201 and the standard envelope.

Code
{
  "data": {
    "id": "trg_01HZX9Q2K8",
    "task_id": "task_01HZX9Q2K9",
    "status": "accepted",
    "created_at": "2026-09-15T09:30:00Z"
  },
  "metadata": {
    "request_id": "my-request-1"
  }
}

status is always accepted. It means Ringtime recorded the trigger and made a task. The conversation starts later, when the campaign schedule allows it.

The fields

Field	Required	What it is
campaign	Yes	Routing key of the target campaign.
ids	Recommended	Up to 20 external ids for the contact. Rules depend on the source.
contact	Usually	The person to enrol. Whether it can be omitted depends on the source.
channel	No	voice or whatsapp. Send it when one routing key maps to campaigns on more than one channel.
context	Depends on source	Key and value data merged into the task context. See Sources for required keys.
test_mode	No	Send the outreach to the phone number in contact instead of the real person.

contact.language is a BCP 47 code, for example nl or fr-BE.

Send your own ids

ids is optional, but send it whenever the contact exists in a system of your own. Ringtime returns the same ids on every webhook, so they are how you match a result back to your record without storing our task_id.

Each entry is a source, a type and a value. Ringtime lowercases source and type and returns value unchanged. The task.completed webhook always carries them. An interaction.finalized webhook carries them too, unless the attempt has no parent task.

Phone number formats

contact.phone must carry the country calling code. Ringtime stores one canonical E.164 value.

Accepted:

• A number already in E.164, such as +15555550100. Stored as sent.
• A number with a calling code plus spaces, dots, slashes or brackets. Ringtime strips them.
• A number with a calling code plus the national trunk prefix, usually a leading 0 after the country code. Ringtime strips that too.

The number must also be assigned and dialable in its own country. Ringtime checks that, so a typo fails on this request instead of hours later, when the call cannot connect and the reason is much harder to see.

Refused:

• A national number with no calling code, such as 5555550100. Ringtime does not guess a country. Nothing in the request says which one to pick, and a wrong guess calls a stranger.
• A number that writes the international prefix as 00 instead of +.
• A number that is impossible or unassigned for its country.

A refused number is a schema error. You get HTTP 422 with the detail shape and one entry for the phone field.

Code
{
  "detail": [
    {
      "type": "value_error",
      "loc": ["body", "contact", "phone"],
      "msg": "Value error, phone must include a country calling code and be a valid number (e.g. '+15555550100')"
    }
  ]
}

See Errors for both error shapes.

Read Sources before sending source-specific ids or context. The API reference has the full schema.

Next

• Authentication
• Errors
• Sources
• Versioning