# Calls and texts API

Tell us of each call and text from a system of your own.

`POST /v1/business/activity`

If your calls or texts go out through a system of your own, tell us of each one as the call starts or the text is sent. If the person you’re contacting is on Check Twice, their phone shows it’s really you.

## Keys

Make a key on your organisation’s [Keys page](https://www.check-twice.com/workspace/keys), named for the system that holds it. You can limit the lines it may name, and the IP addresses or CIDR blocks it may be used from. It starts with `ctb_` and you see it once. Keep it on your server, never in a browser or an app. Every admin is told when a key is made or revoked.

## Request

```bash
curl https://api.check-twice.com/v1/business/activity \
  -H "Authorization: Bearer $CHECK_TWICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+447700900123",
    "channel": "call",
    "from": "+448081570412",
    "staff": "Sarah",
    "reference": "call-8812"
  }'
```

- `phone_number`: who you’re contacting, with its country code.
- `channel`: `call` or `text`.
- `from`: the line it’s from. See [From](#from).
- `staff`: optional, up to 40 characters. The notification says “You’re speaking to Sarah”.
- `reference`: optional, up to 100 characters, your own ID for it, shown in your organisation’s Activity.

## From

One of the lines on your [Lines page](https://www.check-twice.com/workspace/lines):

- a phone number, with its country code, for a call or a text
- a sender ID, in any case, for a text
- `withheld`, for a call with your phone number withheld

Leave it out only if just one of your lines fits the call or text and the key may name it.

## Response

The answer is always `202` with nothing in it, whether or not the person is on Check Twice, so nothing tells you who is. The notification follows. Another call or text from the same line to the same phone number within a minute isn’t told twice.

## Errors

An error comes back with its code, such as `{"error": "unknown_from"}`.

- `400 invalid_phone`: the phone number isn’t one, or has no country code.
- `400 phone_unsupported`: the phone number is from a country Check Twice isn’t in.
- `400 invalid_channel`, `invalid_staff` or `invalid_reference`: that field needs fixing.
- `400 unknown_from`: not one of your live lines, or not one this key may name.
- `400 from_needed`: several of your lines fit, so say which.
- `401 unauthorised`: the key is wrong or revoked.
- `403 organisation_not_live`: your organisation isn’t live.
- `403 key_paused`: the key is paused. Resume it on the Keys page.
- `403 address_not_allowed`: the request came from an address the key doesn’t allow.
- `429 too_many_requests` or `daily_cap_reached`: past one of the limits below. `Retry-After` says how many seconds until the key can send again.

## Limits

- 1,200 requests a minute on one key.
- 50,000 a day on one key, unless we’ve set your organisation another.

A key that sends over 1,000 in a day and over five times its usual day is paused, and every admin is told.