# 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](/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.

```bash
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.

```json
{
  "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](/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](/webhooks), 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.

```json
{
  "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](/errors) for both error shapes.

Read [Sources](/sources) before sending source-specific ids or context. The
[API reference](/api) has the full schema.

## Next

- [Authentication](/authentication)
- [Errors](/errors)
- [Sources](/sources)
- [Versioning](/versioning)