Browse the docs

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

GET/api/v1/contacts

List contacts

Permission:contacts:read

Pages through contacts, newest first.

Query parameters

  • q

    string

    Search by name, email or phone digits.

  • page

    integer

    Page number, starting at 1 (default 1).

  • pageSize

    integer

    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

200 OK
{
  "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
  }
}
POST/api/v1/contacts

Create or update a contact

Permission:contacts:writeIdempotency-Key

Creates 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

  • phonerequired

    string

    Phone number, international format recommended.

  • name

    string

    Full name.

  • email

    string

    Email address (stored lowercase).

  • tags

    string[]

    Up to 20 tag names to add. Matched case-insensitively; missing tags are created.

  • attributes

    Record<string, string | number | boolean>

    Custom fields merged into the contact's attributes (stored as strings).

  • subscribed

    boolean

    true opts the contact in, false opts them out of marketing messages. New contacts default to subscribed.

  • defaultCountry

    string

    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

201 Created
{
  "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

  • 422INVALID_PHONE

    The phone number couldn't be parsed.

  • 422VALIDATION_ERROR

    A field has the wrong type or is too long.

  • Responds 201 when the contact was created and 200 when an existing contact was updated.
GET/api/v1/contacts/{phone}

Get a contact

Permission:contacts:read

Looks up a contact by phone number.

Path parameters

  • phonerequired

    string

    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

200 OK
{
  "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

  • 404NOT_FOUND

    No contact with this phone number.

  • 422INVALID_PHONE

    The phone number couldn't be parsed.

PATCH/api/v1/contacts/{phone}

Update a contact

Permission:contacts:write

Partially updates an existing contact. Only the fields you send change.

Path parameters

  • phonerequired

    string

    E.164 number (URL-encoded) or digits only.

Body

  • phone

    string

    Optional. When sent it must be the same number as in the URL — a contact's phone can't be changed.

  • name

    string | null

    New name; null clears it.

  • email

    string | null

    New email; null clears it.

  • tags

    string[]

    Up to 20 tag names to add (missing tags are created).

  • removeTags

    string[]

    Up to 20 tag names to remove.

  • attributes

    Record<string, string | number | boolean | null>

    Merged into stored attributes; null removes a key.

  • subscribed

    boolean

    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.

  • optInEvidence

    string

    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

200 OK
{
  "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

  • 404NOT_FOUND

    No contact with this phone number.

  • 422PHONE_MISMATCH

    phone in the body differs from the phone in the URL.

  • 422VALIDATION_ERROR

    Unknown field, wrong type or an empty body.

DELETE/api/v1/contacts/{phone}

Delete a contact

Permission:contacts:write

Permanently 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

  • phonerequired

    string

    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

200 OK
{
  "data": {
    "id": "cm4c0nt4ct0001x7k2p9q3r8s",
    "phone": "+919876543210",
    "deleted": true
  }
}

Errors

  • 404NOT_FOUND

    No contact with this phone number.

POST/api/v1/contacts/bulk

Bulk upsert contacts

Permission:contacts:writeIdempotency-Key

Creates 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

  • contactsrequired

    object[]

    1–1,000 rows of { phone, name?, email?, tags?, attributes?, subscribed? } (up to 20 tags per row).

  • updateExisting

    boolean

    Update contacts that already exist (default true). When false they are counted as skipped.

  • defaultCountry

    string

    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

200 OK
{
  "data": {
    "created": 2,
    "updated": 1,
    "skipped": 0,
    "invalid": []
  }
}

Errors

  • 413PAYLOAD_TOO_LARGE

    The request body is larger than 10 MB.

  • 422TOO_MANY_TAGS

    The rows reference more than 200 different tag names.

  • 422VALIDATION_ERROR

    contacts 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.