Contacts
Keep your WhatsApp audience in sync with your own database. Contacts are identified by phone number within the workspace.
Base address: https://app.ezreach.in/api/v1
Query parameters
qstring
Search by name, email or phone digits.
pageinteger
Page number, starting at 1 (default 1).
pageSizeinteger
Results per page, 1–100 (default 25).
Request
curl "https://app.ezreach.in/api/v1/contacts?q=ananya&page=1&pageSize=25" \
-H "Authorization: Bearer $EZREACH_API_KEY"Response
{
"data": [
{
"id": "cm4c0nt4ct0001x7k2p9q3r8s",
"phone": "+919876543210",
"name": "Ananya Iyer",
"email": "ananya@example.com",
"countryCode": "IN",
"attributes": {
"plan": "gold",
"city": "Bengaluru"
},
"subscriptionStatus": "SUBSCRIBED",
"optedInAt": "2026-09-16T10:30:00.000Z",
"optedOutAt": null,
"optInSource": "REST API",
"isBlocked": false,
"source": "API",
"lastMessageAt": null,
"lastInboundAt": null,
"tags": [
{
"id": "cm4t4g000001a2b3c4d5e6f7g",
"name": "Customers",
"color": "#22c55e"
}
],
"createdAt": "2026-09-16T10:30:00.000Z",
"updatedAt": "2026-09-16T10:30:00.000Z"
}
],
"pagination": {
"page": 1,
"pageSize": 25,
"total": 1,
"totalPages": 1
}
}Create or update a contact
contacts:writeIdempotency-KeyCreates the contact, or updates it when the phone number already exists. Non-empty name and email overwrite stored values, attributes are merged, tags are added (missing tags are created) and subscribed changes the subscription. Omitted fields keep their stored values.
Body
phonerequiredstring
Phone number, international format recommended.
namestring
Full name.
emailstring
Email address (stored lowercase).
tagsstring[]
Up to 20 tag names to add. Matched case-insensitively; missing tags are created.
attributesRecord<string, string | number | boolean>
Custom fields merged into the contact's attributes (stored as strings).
subscribedboolean
true opts the contact in, false opts them out of marketing messages. New contacts default to subscribed.
defaultCountrystring
ISO country code (e.g. IN) used for numbers without a country code.
Request
curl -X POST "https://app.ezreach.in/api/v1/contacts" \
-H "Authorization: Bearer $EZREACH_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone": "+919876543210",
"name": "Ananya Iyer",
"email": "ananya@example.com",
"tags": [
"Customers"
],
"attributes": {
"plan": "gold",
"city": "Bengaluru"
},
"subscribed": true
}'Response
{
"data": {
"id": "cm4c0nt4ct0001x7k2p9q3r8s",
"phone": "+919876543210",
"name": "Ananya Iyer",
"email": "ananya@example.com",
"countryCode": "IN",
"attributes": {
"plan": "gold",
"city": "Bengaluru"
},
"subscriptionStatus": "SUBSCRIBED",
"optedInAt": "2026-09-16T10:30:00.000Z",
"optedOutAt": null,
"optInSource": "REST API",
"isBlocked": false,
"source": "API",
"lastMessageAt": null,
"lastInboundAt": null,
"tags": [
{
"id": "cm4t4g000001a2b3c4d5e6f7g",
"name": "Customers",
"color": "#22c55e"
}
],
"createdAt": "2026-09-16T10:30:00.000Z",
"updatedAt": "2026-09-16T10:30:00.000Z"
}
}Errors
- 422
INVALID_PHONEThe phone number couldn't be parsed.
- 422
VALIDATION_ERRORA field has the wrong type or is too long.
- Responds 201 when the contact was created and 200 when an existing contact was updated.
Path parameters
phonerequiredstring
E.164 number, URL-encoded (%2B919876543210) or as digits only (919876543210).
Request
curl "https://app.ezreach.in/api/v1/contacts/919876543210" \
-H "Authorization: Bearer $EZREACH_API_KEY"Response
{
"data": {
"id": "cm4c0nt4ct0001x7k2p9q3r8s",
"phone": "+919876543210",
"name": "Ananya Iyer",
"email": "ananya@example.com",
"countryCode": "IN",
"attributes": {
"plan": "gold",
"city": "Bengaluru"
},
"subscriptionStatus": "SUBSCRIBED",
"optedInAt": "2026-09-16T10:30:00.000Z",
"optedOutAt": null,
"optInSource": "REST API",
"isBlocked": false,
"source": "API",
"lastMessageAt": null,
"lastInboundAt": null,
"tags": [
{
"id": "cm4t4g000001a2b3c4d5e6f7g",
"name": "Customers",
"color": "#22c55e"
}
],
"createdAt": "2026-09-16T10:30:00.000Z",
"updatedAt": "2026-09-16T10:30:00.000Z"
}
}Errors
- 404
NOT_FOUNDNo contact with this phone number.
- 422
INVALID_PHONEThe phone number couldn't be parsed.
Update a contact
contacts:writePartially updates an existing contact. Only the fields you send change.
Path parameters
phonerequiredstring
E.164 number (URL-encoded) or digits only.
Body
phonestring
Optional. When sent it must be the same number as in the URL — a contact's phone can't be changed.
namestring | null
New name; null clears it.
emailstring | null
New email; null clears it.
tagsstring[]
Up to 20 tag names to add (missing tags are created).
removeTagsstring[]
Up to 20 tag names to remove.
attributesRecord<string, string | number | boolean | null>
Merged into stored attributes; null removes a key.
subscribedboolean
Alias: true = consent "subscribed", false = "no_marketing".
consent"subscribed" | "no_marketing" | "no_messages"
Offers and updates / updates about their bookings only / nothing at all. Stronger choices always apply.
optInEvidencestring
Required to subscribe somebody who opted out (≤ 200 characters): how they asked to hear from you again.
Request
curl -X PATCH "https://app.ezreach.in/api/v1/contacts/919876543210" \
-H "Authorization: Bearer $EZREACH_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"tags": [
"VIP"
],
"removeTags": [
"Leads"
],
"attributes": {
"plan": "platinum",
"city": null
},
"consent": "subscribed",
"optInEvidence": "Ticked '\''WhatsApp updates'\'' at checkout, 2 Oct"
}'Response
{
"data": {
"id": "cm4c0nt4ct0001x7k2p9q3r8s",
"phone": "+919876543210",
"name": "Ananya Iyer",
"email": "ananya@example.com",
"countryCode": "IN",
"attributes": {
"plan": "platinum"
},
"subscriptionStatus": "SUBSCRIBED",
"optedInAt": "2026-09-16T10:30:00.000Z",
"optedOutAt": null,
"optInSource": "REST API",
"isBlocked": false,
"source": "API",
"lastMessageAt": null,
"lastInboundAt": null,
"tags": [
{
"id": "cm4t4g000001a2b3c4d5e6f7g",
"name": "Customers",
"color": "#22c55e"
},
{
"id": "cm4t4g000002h8j9k0l1m2n3o",
"name": "VIP",
"color": "#f59e0b"
}
],
"createdAt": "2026-09-16T10:30:00.000Z",
"updatedAt": "2026-09-16T10:30:00.000Z"
}
}Errors
- 404
NOT_FOUNDNo contact with this phone number.
- 422
PHONE_MISMATCHphonein the body differs from the phone in the URL. - 422
VALIDATION_ERRORUnknown field, wrong type or an empty body.
Delete a contact
contacts:writePermanently deletes the contact with its conversations, notes and the messages they sent you. Messages you sent them stay only as a record without their content (no text, no name, no conversation; GET /messages/{id} then answers with contactId and conversationId null), so a delivery confirmed later is still billed.
Path parameters
phonerequiredstring
E.164 number (URL-encoded) or digits only.
Request
curl -X DELETE "https://app.ezreach.in/api/v1/contacts/919876543210" \
-H "Authorization: Bearer $EZREACH_API_KEY"Response
{
"data": {
"id": "cm4c0nt4ct0001x7k2p9q3r8s",
"phone": "+919876543210",
"deleted": true
}
}Errors
- 404
NOT_FOUNDNo contact with this phone number.
Bulk upsert contacts
contacts:writeIdempotency-KeyCreates or updates up to 1,000 contacts in one request — built for syncing users from your backend. Each row follows the same rules as “Create or update a contact”; invalid rows are reported without failing the batch.
Body
contactsrequiredobject[]
1–1,000 rows of { phone, name?, email?, tags?, attributes?, subscribed? } (up to 20 tags per row).
updateExistingboolean
Update contacts that already exist (default true). When false they are counted as skipped.
defaultCountrystring
ISO country code for numbers without a country code.
Request
curl -X POST "https://app.ezreach.in/api/v1/contacts/bulk" \
-H "Authorization: Bearer $EZREACH_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contacts": [
{
"phone": "+919876543210",
"name": "Ananya Iyer",
"tags": [
"Customers"
],
"attributes": {
"plan": "gold"
}
},
{
"phone": "+14155550123",
"name": "Jordan Lee",
"email": "jordan@example.com",
"subscribed": true
},
{
"phone": "98765 43211",
"name": "Rohit Mehta"
}
],
"updateExisting": true,
"defaultCountry": "IN"
}'Response
{
"data": {
"created": 2,
"updated": 1,
"skipped": 0,
"invalid": []
}
}Errors
- 413
PAYLOAD_TOO_LARGEThe request body is larger than 10 MB.
- 422
TOO_MANY_TAGSThe rows reference more than 200 different tag names.
- 422
VALIDATION_ERRORcontacts is missing, empty or has more than 1,000 rows.
- invalid lists rejected rows as { index, phone, reason }, where index is the row's position in contacts.
- When the same phone appears several times in one request, the last row wins and the earlier ones count as skipped.
- To sync more than 1,000 contacts, send consecutive batches; each batch counts as one request towards the rate limit.
- A batch may reference at most 200 different tag names and its body can be up to 10 MB.

