Manage contacts

Goal: build and maintain a contact base so campaigns can target audiences by tag, attribute or filter.
Prerequisites: an API key with the Recipients scope.

You only need contacts for audience-targeted campaigns. Transactional single sends address the number directly and need no stored contact.

Steps

1. (Optional) Define attributes

Attributes are the custom fields that power personalization ({{attribute.name}} in templates).

# See what attribute types are available
curl https://client.routeon.io/api/v1/recipient/attributes/types -H "X-API-Key: <API_KEY>"

# List existing attributes
curl https://client.routeon.io/api/v1/recipient/attributes -H "X-API-Key: <API_KEY>"

# Create one
curl -X POST https://client.routeon.io/api/v1/recipient/attributes 
  -H "X-API-Key: <API_KEY>" -H "Content-Type: application/json" 
  -d '{ "name": "city", "type": "string" }'

2. Import recipients

curl -X POST https://client.routeon.io/api/v1/recipient/recipients 
  -H "X-API-Key: <API_KEY>" -H "Content-Type: application/json" 
  -d '{
    "recipients": [
      { "name": "Alice", "phoneNumber": "48732231255", "tags": ["demo"], "attributes": { "name": "Alice", "city": "Warsaw" } }
    ],
    "tag": "demo",
    "type": "ENRICH"
  }'

Import mode (type):

Mode	Behaviour
ENRICH	Add new contacts, merge new data into existing ones.
OVERWRITE	Replace existing contact data with the imported values.
NOT_IMPORT	Skip numbers that already exist. New numbers are still created.

Phone numbers are digits only, no +.

3. List, update and delete

# List contacts
curl "https://client.routeon.io/api/v1/recipient/recipients" -H "X-API-Key: <API_KEY>"

# Update contacts
curl -X PUT https://client.routeon.io/api/v1/recipient/recipients 
  -H "X-API-Key: <API_KEY>" -H "Content-Type: application/json" 
  -d '{ "recipients": [ { "phoneNumber": "48732231255", "attributes": { "city": "Gdansk" } } ] }'

# Delete contacts
curl -X DELETE https://client.routeon.io/api/v1/recipient/recipients 
  -H "X-API-Key: <API_KEY>" -H "Content-Type: application/json" 
  -d '{ "recipients": [ { "phoneNumber": "48732231255" } ] }'

4. Work with tags and filters

curl https://client.routeon.io/api/v1/recipient/tags    -H "X-API-Key: <API_KEY>"
curl https://client.routeon.io/api/v1/recipient/filters -H "X-API-Key: <API_KEY>"

Use a tag or a saved filter as a campaign’s audience instead of an explicit recipientsList.

Verify

List recipients by tag and confirm the imported contacts and their attributes are present, then reference the tag/filter when you launch a campaign.

Common failures

Symptom	Cause	Fix
401	Key missing the Recipients scope	Use a key with Recipients
Attribute value ignored in a template	Attribute name mismatch	Ensure the {{attribute.name}} matches a defined attribute exactly
Existing numbers unchanged, new numbers missing	type: NOT_IMPORT only skips contacts that already exist	Use ENRICH or OVERWRITE to update existing rows
Numbers not matched	+ or spaces in phoneNumber	Send digits only, with country code