# Triggering calls

To call one customer, send a `POST` request to the automation's trigger URL. Copy the URL from the
automation's **Trigger and credentials** tab in the console, which admins and engineers can see. It
has the form `https://api.signals.pressone.africa/automations/{automation_id}/calls`, where
the automation id starts with `sig_`. Both operations on this page are listed in the
[Automations API reference](/api/signals/automations).

## Authentication

Authenticate with an organization API key sent as a Bearer token in the `Authorization` header. The
key must hold the `service_configuration:write` scope and cannot be restricted to a subaccount. The
request runs in the automation's own project, so it does not need an `X-Project-ID` header. A key
that has been revoked or has expired may continue to work for up to 60 seconds. See
[Authentication](/getting-started/authentication) to create a key.

## The request

The body is a JSON object of at most 16 KiB.

| Field | Required | Description |
| --- | --- | --- |
| `phone_number` | Yes | The number to call, in E.164 format: a `+` followed by 8 to 15 digits, the first of which is not `0`. |
| `name` | No | The customer's name, used for the `{{name}}` variable. At most 120 characters. |
| `event_id` | No | Your identifier for this trigger, used for [idempotency](#idempotency). At most 120 characters and not blank. |
| `parameters` | No | Values for the message's other variables, such as `time`. At most 40 keys. Each key starts with a letter and contains only letters, digits and underscores, up to 64 characters. Each value is a string of at most 500 characters, a number or a boolean. |
| `metadata` | No | Any JSON object of at most 4096 bytes. Signals stores it with the run and returns it in every webhook event. |

```bash title="Request"
curl -X POST "https://api.signals.pressone.africa/automations/sig_0199c4e2-5a10-7000-8000-000000000017/calls" \
  -H "Signals-Version: 2026-10-27" \
  -H "Authorization: Bearer $SIGNALS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+2348035550142",
    "name": "Adebayo Ogundimu",
    "event_id": "appt-77120-2026-10-30",
    "parameters": { "time": "10:30" },
    "metadata": { "booking": "APPT-77120" }
  }'
```

```json title="Response: 202 Accepted"
{
  "id": "run_0199c4e2-7b1a-7000-8000-000000000042",
  "signalId": "sig_0199c4e2-5a10-7000-8000-000000000017",
  "runId": "run_0199c4e2-7b1a-7000-8000-000000000042",
  "recipientNumber": "+2348035550142",
  "status": "queued",
  "outcome": null,
  "suppressionReason": null,
  "createdAt": "2026-10-29T09:00:00Z"
}
```

Signals applies the [suppression rules](#suppression-rules) before it answers, then responds with the
run as it stands, using camelCase field names. `id` and `runId` carry the same run id and `signalId`
is the automation id. A run that passed the rules is `queued` with `outcome` and `suppressionReason`
still `null`; a run stopped by a rule already shows `status` `finished`, `outcome` `suppressed` and
the reason; a run that arrived outside calling hours on an automation set to wait shows
`waiting_hours`. A `202 Accepted` therefore means Signals accepted the request, not that the call
has been placed. Follow the run through its [webhook events](/automations/webhook-events) or the
console.

## Idempotency

Use `event_id` to make triggers safe to retry. Signals keeps one run per `event_id` for each
automation. If you send the same `event_id` again, Signals returns `200 OK` with the original run as
it is now and does not call the customer a second time.

Derive the `event_id` from the business event rather than generating it at send time. For an
appointment reminder, `appt-77120-2026-10-30` identifies one booking on one day, so every retry of
that reminder carries the same value. A new UUID per attempt defeats the purpose, because two ids
for the same event produce two calls. If you omit `event_id`, Signals generates one in the form
`auto_<uuid>`, and retrying such a request calls the customer again.

## Responses and errors

Error responses use the problem format described in
[Requests and errors](/getting-started/requests-and-errors). The `code` member identifies the
reason, and on a `422` response the `field` member names the invalid field.

| Status | `code` | Meaning | What to do |
| --- | --- | --- | --- |
| `202` | | Signals created a new run. | No action is required. |
| `200` | | The `event_id` matches an earlier trigger, and the body is the original run. | No action is required. The customer is not called again. |
| `401` | `unauthenticated` | The API key is missing or not recognised. | Check the `Authorization` header and the key. |
| `403` | `api_key_scope_missing` | The key does not hold `service_configuration:write`. | Use a key that has the scope. |
| `403` | `api_key_subaccount` | The key is restricted to a subaccount. | Use an organization API key. |
| `404` | `automation_not_found` | Your organization has no automation with this id. | Check the automation id in the trigger URL. |
| `413` | | The body is larger than 16 KiB. | Reduce the size of the request body. |
| `422` | `invalid_phone_number`, `invalid_name`, `invalid_event_id`, `event_id_too_long`, `invalid_parameters`, `invalid_metadata`, `metadata_too_large`, `invalid_body` | A field is invalid. `invalid_body` means the body was not a JSON object. | Correct the field named in `field` and send the request again. |
| `429` | `rate_limited` | The automation received more than 20 requests in one second. The response carries `Retry-After: 1`. | Wait one second, then retry with the same `event_id`. |
| `503` | `try_again`, `identity_unavailable` | Signals could not store the request or verify the key. A `try_again` response carries `Retry-After: 1`. | Retry with the same `event_id`. |

Retry `429` and `503` responses, and requests that time out, with the same `event_id`. Correct the
cause of a `401`, `403` or `422` before you send the request again.

## Suppression rules

Before dialling, Signals checks the automation's rules in the order below and stops at the first
one that applies. A run stopped by a rule finishes with outcome `suppressed` and
`suppressionReason` records the rule. A suppressed run is a deliberate decision not to call, not a
failed call. You can switch off the do-not-call, daily-limit and calling-hours rules in step 6 of
the builder.

| Rule | `suppressionReason` |
| --- | --- |
| The automation is switched off. | `automation_off` |
| The number is on the do-not-call list. | `do_not_call` |
| The automation has already called this number today, counted in the calling-hours time zone. | `already_called_today` |
| The trigger arrives outside calling hours and the automation is set not to call outside them. If it is set to wait instead, the run takes the status `waiting_hours` and is called when calling hours open. | `outside_hours` |

## Run status

| Field | Values |
| --- | --- |
| `status` | `staged`, `queued`, `waiting_hours`, `scheduled`, `dialing`, `placed`, `ringing`, `answered`, `finishing`, `finished` |
| `outcome` | `null` until the run finishes, then one of `completed`, `no_answer`, `busy`, `suppressed`, `failed`, `rejected`, `expired`, `duplicate` |
| `suppressionReason` | `null`, or one of `automation_off`, `do_not_call`, `already_called_today`, `outside_hours`, `no_longer_owed` |

## Cancel a run

If a call is no longer needed, for example because the customer rescheduled, cancel the run before
Signals dials it. Send a `POST` request to the trigger URL with `/cancel` appended, using the same
API key, and identify the run by the `event_id` you triggered it with. Unlike on a trigger,
`event_id` is required here.

```bash title="Request"
curl -X POST "https://api.signals.pressone.africa/automations/sig_0199c4e2-5a10-7000-8000-000000000017/calls/cancel" \
  -H "Signals-Version: 2026-10-27" \
  -H "Authorization: Bearer $SIGNALS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "event_id": "appt-77120-2026-10-30" }'
```

```json title="Response: 200 OK"
{
  "id": "run_0199c4e2-7b1a-7000-8000-000000000042",
  "signalId": "sig_0199c4e2-5a10-7000-8000-000000000017",
  "runId": "run_0199c4e2-7b1a-7000-8000-000000000042",
  "recipientNumber": "+2348035550142",
  "status": "finished",
  "outcome": "suppressed",
  "suppressionReason": "no_longer_owed",
  "createdAt": "2026-10-29T09:00:00Z"
}
```

If the run has not been dialled yet, Signals suppresses it and returns it with `200 OK`. If it has
already been dialled or has finished, Signals returns the run unchanged with `200 OK` and does not
end a call in progress. If no run of the automation has that `event_id`, the response is `404` with
code `event_id_unknown`. A missing or invalid `event_id` returns `422`, and the authentication,
rate-limit and storage errors match those of a trigger.
