Contacts

The Recipients surface is an optional address book. You need it only when you want to target a campaign by audience (tags, attributes, filters) instead of passing an explicit list of phone numbers. Transactional single sends via POST /messages do not require stored contacts.

Working with contacts requires an API key with the Recipients scope. See API keys & scopes.

Recipients

A recipient is one person in your contact base.

POST https://client.routeon.io/api/v1/recipient/recipients
X-API-Key: <API_KEY>

{
  "recipients": [
    {
      "name": "Alice",
      "phoneNumber": "48732231255",
      "tags": ["demo"],
      "attributes": { "Age": 30 }
    }
  ],
  "tag": "demo",
  "type": "ENRICH"
}
Field Meaning
recipients[] The contacts to import. Each has phoneNumber (digits, no +), optional name, tags, and attributes.
tag A tag applied to the whole imported batch.
type Import mode — see below.

Recipients are managed with GET /recipient/recipients (list), POST (create/import), PUT (update), DELETE.

Import modes

Mode Behaviour
ENRICH Add new contacts and merge new data into existing ones; existing values are kept.
OVERWRITE Replace existing contact data with the imported values.
NOT_IMPORT Skip numbers that already exist. New numbers are still created. This is not a dry run.

These three values are the API type enum. They are not the four Excel merge modes in the Alaris portal (Ignore duplicates, Update number tags only, Update tags and contact data, Add duplicates).

Attributes

Attributes are custom per-contact fields (for example name, Age, city). They are what powers template personalization: a {{attribute.name}} placeholder in a template is filled from the contact’s attribute of that name.

  • GET /recipient/attributes — list defined attributes.
  • GET /recipient/attributes/types — list the available attribute value types.
  • POST /recipient/attributes, PUT/DELETE /recipient/attributes/{id} — manage attribute definitions.

Tags

Tags are labels you attach to contacts to group them into audiences. A campaign can target everyone carrying a given tag instead of an explicit number list.

  • GET /recipient/tags — list the tags in your contact base.
  • Tags are assigned at import time (tags[] per recipient, or the batch-level tag).

Filters

Filters are saved audience queries — combinations of tags and attribute conditions — that a campaign can target as its filterList.

  • GET /recipient/filters — list the filters available to your account.