API reference

Contacts

A lightweight CRM layer on top of your messaging. Attach metadata (name, tags, custom fields) to phone numbers so workflows can branch on it.

Create a contact

POST/v1/contacts

Field	Type	Description
`phoneNumber`required	string	E.164 format.
`firstName`	string
`lastName`	string
`email`	string
`tags`	string[]	Free-form tags for filtering, e.g. `["lead", "vip"]`.
`metadata`	object	Arbitrary JSON.

curl -X POST 'https://api.bluereplies.com/v1/contacts' \
  -H "x-api-key: $BLUEREPLIES_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "phoneNumber": "+15551234567",
    "firstName": "Sarah",
    "tags": ["lead", "warm"],
    "metadata": { "source": "ads-campaign-2026Q2" }
  }'

Bulk upsert

POST/v1/contacts/bulk

Upserts up to 500 contacts in one request. Existing matches are updated, not duplicated.

{
  "contacts": [
    { "phoneNumber": "+15551111111", "firstName": "Sarah" },
    { "phoneNumber": "+15552222222", "firstName": "Mike", "tags": ["customer"] }
  ]
}

List + filter

GET/v1/contacts

Query

Field	Type	Description
`limit`	integer	Max 100. Default 25.
`cursor`	string
`tags`	string	Comma-separated. Returns contacts that have ALL listed tags.
`search`	string	Searches across name, email, phone, metadata.

Bulk-tag contacts

POST/v1/contacts/bulk-tag

Merge a set of tags into many contacts at once. Existing tags on each contact are preserved.

{
  "contactIds": ["ctc_a", "ctc_b", "ctc_c"],
  "tags": ["q2-campaign", "warm"]
}

Export

GET/v1/contacts/export

?format=json|csv. Returns the full list, no pagination.

Large exports stream the response. For accounts with 100k+ contacts, use the dashboard export which background-renders to a downloadable file.

Delete

DELETE/v1/contacts/:id