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 Validate the payload without persisting — a dry run.

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.