REST endpoints

Contacts

Find, create, update and delete contacts, and set custom attributes the AI and actions can use.

Send your API key in the Authorization: Bearer af_live_… header. See Authentication.

Contacts added through the API count as verified: the AI may use their details and attributes, and actions can use {contact.…} placeholders. See Contacts.

Contact object

idstring

The contact's ID in AnytimeReply.

external_idstring | null

Your own user ID.

emailstring | null

Lower-cased.

phonestring | null

Digits only, with country code (e.g. 8801711111111).

namestring | null

attributesobject

Custom attributes: keys start with a letter (letters, digits, _, up to 41 characters); values are strings (up to 300 characters), numbers or booleans. Up to 40.

tagsarray

Lower-case tags.

verifiedboolean

Details come from a trusted source (API, import, identity token, WhatsApp).

opted_outboolean

The contact replied STOP to broadcasts.

sourcestring

Where the contact came from, e.g. api, website, whatsapp, lead.

created_at, last_seen_at string

List or find contacts

GET/api/v1/agents/{id}/contacts

Query parameters

emailstring

Exact email (case-insensitive).

external_idstring

Exact user ID.

phonestring

Phone number; non-digits are ignored.

pagenumber

100 contacts per page. Default 1.

Shell

curl "https://anytimereply.com/api/v1/agents/AGENT_ID/[email protected]" -H "Authorization: Bearer af_live_YOUR_KEY"

200 OK

{
  "data": [
    {
      "id": "k1…",
      "external_id": "u_42",
      "email": "[email protected]",
      "phone": "8801711111111",
      "name": "Nadia",
      "attributes": { "plan": "Pro", "orders": 7 },
      "tags": ["vip"],
      "verified": true,
      "opted_out": false,
      "source": "api",
      "created_at": "2026-09-01T10:00:00.000Z",
      "last_seen_at": "2026-10-19T08:00:00.000Z"
    }
  ],
  "page": 1
}

Create or update a contact

POST/api/v1/agents/{id}/contacts

Matched by external_id, then email, then phone. An existing contact is updated (new attributes are merged in, tags are added); otherwise a new one is created.

Body

external_idstring

Your user ID (max 120). Give at least one of external_id, email or phone.

emailstring

phonestring

With country code.

namestring

attributesobject

Custom attributes to set.

tagsarray

Up to 10 tags (max 30 characters each) to add.

Shell

curl https://anytimereply.com/api/v1/agents/AGENT_ID/contacts \
  -H "Authorization: Bearer af_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "u_42", "email": "[email protected]", "name": "Nadia", "attributes": {"plan": "Pro", "orders": 7}, "tags": ["vip"]}'

Returns { "data": <contact> }. 400 Invalid email or phone when none of the identifiers is usable.

Get a contact

GET/api/v1/agents/{id}/contacts/{contact_id}

Returns the contact plus its 50 most recent conversations:

200 OK

{
  "data": {
    "id": "k1…",
    "external_id": "u_42",
    "email": "[email protected]",
    "name": "Nadia",
    "attributes": { "plan": "Pro" },
    "tags": ["vip"],
    "verified": true,
    "conversations": [
      { "id": "8b1d…", "channel": "WIDGET", "status": "CLOSED", "created_at": "2026-10-18T10:02:11.000Z", "last_message_at": "2026-10-18T10:09:45.000Z" }
    ]
  }
}

Update a contact

PATCH/api/v1/agents/{id}/contacts/{contact_id}

Body

namestring

attributesobject

Merged into the existing attributes. Send null for a key to remove it.

tagsarray

Replaces all tags.

opted_outboolean

Opt the contact out of (or back into) broadcasts.

JSON

{ "attributes": { "plan": "Business", "trial_ends": null }, "tags": ["vip", "renewed"] }

Returns { "data": <contact> }.

Delete a contact

DELETE/api/v1/agents/{id}/contacts/{contact_id}

Returns { "ok": true }. Conversations stay; they're just no longer linked to the contact.

Errors

Status	Error
`400`	`input: give external_id, email or phone` · `Invalid email or phone`
`404`	`Agent not found` · `Contact not found`

Was this page helpful?

Still stuck? Contact us