API reference

Contacts

Keep the people you message, with their consent, tags and custom attributes, and group them in lists and segments.

Create a contact#

POST/v1/contactsScopecontacts:write

Creates a contact. At least one of phone, email or a channel identifier is required. The phone number is validated and stored in E.164; a number without a country prefix is read as a national number of the account country.

A phone number can belong to one contact only: creating a second contact with it fails with 409 contact_exists. Use the upsert endpoint when you do not know whether the contact exists.

Headers

Idempotency-KeystringOptional
Unique string of up to 255 characters, such as a UUID. Repeating a request with the same key and body within 24 hours returns the stored response instead of performing the operation again.

Request body

first_namestring or nullOptional
Given name, up to 100 characters.
Up to 100 characters
last_namestring or nullOptional
Family name, up to 100 characters.
Up to 100 characters
phonestring or nullOptional
Phone number. International format (+971501234567) or a national number of the account country; it is stored in E.164.
Up to 40 characters
emailstring or nullOptional
Email address.
Up to 254 characters
channel_identifiersobjectOptional
Identifiers for Telegram, Messenger, Instagram and TikTok. null removes one.
Show child attributesHide child attributes
- telegramstring or nullOptional
  Identifier on telegram.
  Up to 255 characters
- messengerstring or nullOptional
  Identifier on messenger.
  Up to 255 characters
- instagramstring or nullOptional
  Identifier on instagram.
  Up to 255 characters
- tiktokstring or nullOptional
  Identifier on tiktok.
  Up to 255 characters
localestring or nullOptional
Language tag such as en or pt-BR.
timezonestring or nullOptional
IANA time zone such as Asia/Dubai. Campaigns can apply their send window in it.
attributesobjectOptional
Custom attributes by key. Keys must be defined in the console first; a value is checked against the type of its definition. null removes an attribute.
tagsarray of stringsOptional
Up to 50 tags. Replaces the current tags on update.
consentobjectOptional
Consent per channel type. opted_out is an unsubscribe: campaigns skip the contact on that channel type. unknown clears the entry.
blockedbooleanOptional
A blocked contact is never messaged by a campaign, on any channel.
blocked_reasonstring or nullOptional
Why the contact is blocked.
Up to 255 characters

Responses

201
The contact was created.
400
Bad request.
parameter_missing parameter_invalid invalid_json contact_limit_reached
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
409
Conflict.
contact_exists idempotency_key_in_use idempotency_key_reused
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

POST/v1/contacts

curl https://api.omnimessage.co/v1/contacts \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Layla",
    "last_name": "Haddad",
    "phone": "+971501234567",
    "email": "layla@example.com",
    "locale": "ar",
    "timezone": "Asia/Dubai",
    "tags": [
      "vip",
      "newsletter"
    ],
    "consent": {
      "whatsapp": "opted_in"
    }
  }'

Response · 201

{
  "id": "ct_8Jk3mP6qR9sT2vW5xY1z",
  "object": "contact",
  "first_name": "Layla",
  "last_name": "Haddad",
  "phone": "+971501234567",
  "email": "layla@example.com",
  "channel_identifiers": {
    "telegram": "482910375"
  },
  "locale": "ar",
  "timezone": "Asia/Dubai",
  "attributes": {
    "city": "Dubai",
    "orders": 12
  },
  "tags": [
    "vip",
    "newsletter"
  ],
  "consent": {
    "whatsapp": {
      "state": "opted_in",
      "source": "api",
      "updated_at": "2026-10-01T08:00:00.000Z"
    }
  },
  "blocked": false,
  "blocked_reason": null,
  "last_messaged_at": "2026-10-05T09:30:00.000Z",
  "created_at": "2026-10-01T08:00:00.000Z",
  "updated_at": "2026-10-05T09:30:00.000Z"
}

List contacts#

GET/v1/contactsScopecontacts:read

Returns the contacts of the account, newest first. Filters can be combined. Contacts belong to the account, so live and test keys return the same contacts.

Query parameters

qstringOptional
Search in names and email addresses; a value made of digits searches phone numbers.
phonestringOptional
Only the contact with this phone number.
emailstringOptional
Only contacts with this email address.
tagstringOptional
Only contacts carrying this tag.
list_idstringOptional
Only contacts on this list.
segment_idstringOptional
Only contacts matching this segment.
consentstringOptional
Only contacts with this consent state on a channel type, written <channel type>:<state>.
blockedstringOptional
Only blocked (true) or only unblocked (false) contacts.
Possible valuestruefalse
limitintegerOptional
Number of objects to return, 1 to 100. Default 20.
starting_afterstringOptional
Cursor for the next page: the next_cursor of the previous response (the ID of its last object).

Responses

200
A page of contacts.
400
Bad request.
parameter_invalid
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
404
The segment named by segment_id does not exist.
resource_missing
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

GET/v1/contacts

curl "https://api.omnimessage.co/v1/contacts?phone=%2B971501234567&consent=whatsapp%3Aopted_in" \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "object": "list",
  "data": [
    {
      "id": "ct_8Jk3mP6qR9sT2vW5xY1z",
      "object": "contact",
      "first_name": "Layla",
      "last_name": "Haddad",
      "phone": "+971501234567",
      "email": "layla@example.com",
      "channel_identifiers": {
        "telegram": "482910375"
      },
      "locale": "ar",
      "timezone": "Asia/Dubai",
      "attributes": {
        "city": "Dubai",
        "orders": 12
      },
      "tags": [
        "vip",
        "newsletter"
      ],
      "consent": {
        "whatsapp": {
          "state": "opted_in",
          "source": "api",
          "updated_at": "2026-10-01T08:00:00.000Z"
        }
      },
      "blocked": false,
      "blocked_reason": null,
      "last_messaged_at": "2026-10-05T09:30:00.000Z",
      "created_at": "2026-10-01T08:00:00.000Z",
      "updated_at": "2026-10-05T09:30:00.000Z"
    }
  ],
  "has_more": true,
  "next_cursor": "ct_8Jk3mP6qR9sT2vW5xY1z"
}

Create or update a contact by phone number#

POST/v1/contacts/upsertScopecontacts:write

Creates the contact, or updates the one that already has this phone number. On update only the fields you send change and tags are added to the existing tags. An existing opted_out consent is only changed when you send consent for that channel type explicitly.

Headers

Idempotency-KeystringOptional
Unique string of up to 255 characters, such as a UUID. Repeating a request with the same key and body within 24 hours returns the stored response instead of performing the operation again.

Request body

first_namestring or nullOptional
Given name, up to 100 characters.
Up to 100 characters
last_namestring or nullOptional
Family name, up to 100 characters.
Up to 100 characters
phonestringRequired
Phone number that identifies the contact.
Up to 40 characters
emailstring or nullOptional
Email address.
Up to 254 characters
channel_identifiersobjectOptional
Identifiers for Telegram, Messenger, Instagram and TikTok. null removes one.
Show child attributesHide child attributes
- telegramstring or nullOptional
  Identifier on telegram.
  Up to 255 characters
- messengerstring or nullOptional
  Identifier on messenger.
  Up to 255 characters
- instagramstring or nullOptional
  Identifier on instagram.
  Up to 255 characters
- tiktokstring or nullOptional
  Identifier on tiktok.
  Up to 255 characters
localestring or nullOptional
Language tag such as en or pt-BR.
timezonestring or nullOptional
IANA time zone such as Asia/Dubai. Campaigns can apply their send window in it.
attributesobjectOptional
Custom attributes by key. Keys must be defined in the console first; a value is checked against the type of its definition. null removes an attribute.
tagsarray of stringsOptional
Up to 50 tags. Replaces the current tags on update.
consentobjectOptional
Consent per channel type. opted_out is an unsubscribe: campaigns skip the contact on that channel type. unknown clears the entry.
blockedbooleanOptional
A blocked contact is never messaged by a campaign, on any channel.
blocked_reasonstring or nullOptional
Why the contact is blocked.
Up to 255 characters

Responses

200
The contact as it is after the request.
400
Bad request.
parameter_missing parameter_invalid invalid_json contact_limit_reached
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
409
Conflict.
idempotency_key_in_use idempotency_key_reused
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

POST/v1/contacts/upsert

curl https://api.omnimessage.co/v1/contacts/upsert \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Layla",
    "last_name": "Haddad",
    "phone": "+971501234567",
    "email": "layla@example.com",
    "locale": "ar",
    "timezone": "Asia/Dubai",
    "tags": [
      "vip",
      "newsletter"
    ],
    "consent": {
      "whatsapp": "opted_in"
    }
  }'

Response · 200

{
  "id": "ct_8Jk3mP6qR9sT2vW5xY1z",
  "object": "contact",
  "first_name": "Layla",
  "last_name": "Haddad",
  "phone": "+971501234567",
  "email": "layla@example.com",
  "channel_identifiers": {
    "telegram": "482910375"
  },
  "locale": "ar",
  "timezone": "Asia/Dubai",
  "attributes": {
    "city": "Dubai",
    "orders": 12
  },
  "tags": [
    "vip",
    "newsletter"
  ],
  "consent": {
    "whatsapp": {
      "state": "opted_in",
      "source": "api",
      "updated_at": "2026-10-01T08:00:00.000Z"
    }
  },
  "blocked": false,
  "blocked_reason": null,
  "last_messaged_at": "2026-10-05T09:30:00.000Z",
  "created_at": "2026-10-01T08:00:00.000Z",
  "updated_at": "2026-10-05T09:30:00.000Z"
}

Add and remove tags in bulk#

POST/v1/contacts/tagsScopecontacts:write

Adds and removes tags on up to 1,000 contacts with one request. A contact that would end up with more than 50 tags is left unchanged.

Headers

Idempotency-KeystringOptional
Unique string of up to 255 characters, such as a UUID. Repeating a request with the same key and body within 24 hours returns the stored response instead of performing the operation again.

Request body

contact_idsarray of stringsRequired
Contacts to change, up to 1,000. Unknown IDs are ignored.
1 to 1000 items
addarray of stringsOptional
Tags to add.
removearray of stringsOptional
Tags to remove.

Responses

200
How many contacts were changed.
400
Bad request.
parameter_missing parameter_invalid invalid_json
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
409
Conflict.
idempotency_key_in_use idempotency_key_reused
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

POST/v1/contacts/tags

curl https://api.omnimessage.co/v1/contacts/tags \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_ids": [
      "ct_8Jk3mP6qR9sT2vW5xY1z"
    ],
    "add": [
      "october-launch"
    ],
    "remove": [
      "prospect"
    ]
  }'

Response · 200

{
  "object": "bulk_result",
  "affected": 2
}

Retrieve a contact#

GET/v1/contacts/{id}Scopecontacts:read

Returns one contact.

Path parameters

idstringRequired
Contact ID.

Responses

200
The contact.
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
404
The resource does not exist in this account and mode.
resource_missing
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

GET/v1/contacts/{id}

curl https://api.omnimessage.co/v1/contacts/ct_8Jk3mP6qR9sT2vW5xY1z \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "id": "ct_8Jk3mP6qR9sT2vW5xY1z",
  "object": "contact",
  "first_name": "Layla",
  "last_name": "Haddad",
  "phone": "+971501234567",
  "email": "layla@example.com",
  "channel_identifiers": {
    "telegram": "482910375"
  },
  "locale": "ar",
  "timezone": "Asia/Dubai",
  "attributes": {
    "city": "Dubai",
    "orders": 12
  },
  "tags": [
    "vip",
    "newsletter"
  ],
  "consent": {
    "whatsapp": {
      "state": "opted_in",
      "source": "api",
      "updated_at": "2026-10-01T08:00:00.000Z"
    }
  },
  "blocked": false,
  "blocked_reason": null,
  "last_messaged_at": "2026-10-05T09:30:00.000Z",
  "created_at": "2026-10-01T08:00:00.000Z",
  "updated_at": "2026-10-05T09:30:00.000Z"
}

Update a contact#

PATCH/v1/contacts/{id}Scopecontacts:write

Changes the fields you send. tags replaces the current tags; attributes and channel identifiers are merged key by key, and null removes a key. Setting consent for a channel type to opted_out unsubscribes the contact there.

Path parameters

idstringRequired
Contact ID.

Request body

first_namestring or nullOptional
Given name, up to 100 characters.
Up to 100 characters
last_namestring or nullOptional
Family name, up to 100 characters.
Up to 100 characters
phonestring or nullOptional
Phone number. International format (+971501234567) or a national number of the account country; it is stored in E.164.
Up to 40 characters
emailstring or nullOptional
Email address.
Up to 254 characters
channel_identifiersobjectOptional
Identifiers for Telegram, Messenger, Instagram and TikTok. null removes one.
Show child attributesHide child attributes
- telegramstring or nullOptional
  Identifier on telegram.
  Up to 255 characters
- messengerstring or nullOptional
  Identifier on messenger.
  Up to 255 characters
- instagramstring or nullOptional
  Identifier on instagram.
  Up to 255 characters
- tiktokstring or nullOptional
  Identifier on tiktok.
  Up to 255 characters
localestring or nullOptional
Language tag such as en or pt-BR.
timezonestring or nullOptional
IANA time zone such as Asia/Dubai. Campaigns can apply their send window in it.
attributesobjectOptional
Custom attributes by key. Keys must be defined in the console first; a value is checked against the type of its definition. null removes an attribute.
tagsarray of stringsOptional
Up to 50 tags. Replaces the current tags on update.
consentobjectOptional
Consent per channel type. opted_out is an unsubscribe: campaigns skip the contact on that channel type. unknown clears the entry.
blockedbooleanOptional
A blocked contact is never messaged by a campaign, on any channel.
blocked_reasonstring or nullOptional
Why the contact is blocked.
Up to 255 characters

Responses

200
The updated contact.
400
Bad request.
parameter_missing parameter_invalid invalid_json
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
404
The resource does not exist in this account and mode.
resource_missing
409
Another contact already has the new phone number.
contact_exists
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

PATCH/v1/contacts/{id}

curl -X PATCH https://api.omnimessage.co/v1/contacts/ct_8Jk3mP6qR9sT2vW5xY1z \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": [
      "vip"
    ],
    "consent": {
      "whatsapp": "opted_out"
    }
  }'

Response · 200

{
  "id": "ct_8Jk3mP6qR9sT2vW5xY1z",
  "object": "contact",
  "first_name": "Layla",
  "last_name": "Haddad",
  "phone": "+971501234567",
  "email": "layla@example.com",
  "channel_identifiers": {
    "telegram": "482910375"
  },
  "locale": "ar",
  "timezone": "Asia/Dubai",
  "attributes": {
    "city": "Dubai",
    "orders": 12
  },
  "tags": [
    "vip",
    "newsletter"
  ],
  "consent": {
    "whatsapp": {
      "state": "opted_in",
      "source": "api",
      "updated_at": "2026-10-01T08:00:00.000Z"
    }
  },
  "blocked": false,
  "blocked_reason": null,
  "last_messaged_at": "2026-10-05T09:30:00.000Z",
  "created_at": "2026-10-01T08:00:00.000Z",
  "updated_at": "2026-10-05T09:30:00.000Z"
}

Delete a contact#

DELETE/v1/contacts/{id}Scopecontacts:write

Removes the contact and its list memberships. Messages and campaign results that mention the contact are kept. The phone number becomes free for a new contact.

Path parameters

idstringRequired
Contact ID.

Responses

200
The contact was deleted.
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
404
The resource does not exist in this account and mode.
resource_missing
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

DELETE/v1/contacts/{id}

curl -X DELETE https://api.omnimessage.co/v1/contacts/ct_8Jk3mP6qR9sT2vW5xY1z \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "id": "ct_8Jk3mP6qR9sT2vW5xY1z",
  "object": "contact",
  "deleted": true
}

List tags#

GET/v1/contact_tagsScopecontacts:read

Returns every tag in use with the number of contacts carrying it, most used first. The list is not paginated.

Responses

200
Tags in use.
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

GET/v1/contact_tags

curl https://api.omnimessage.co/v1/contact_tags \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "object": "list",
  "data": [
    {
      "object": "contact_tag",
      "name": "vip",
      "contact_count": 412
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Create a contact list#

POST/v1/contact_listsScopecontacts:write

Creates an empty list. Add contacts with the members endpoint.

Headers

Idempotency-KeystringOptional
Unique string of up to 255 characters, such as a UUID. Repeating a request with the same key and body within 24 hours returns the stored response instead of performing the operation again.

Request body

namestringRequired
Name of the list.
1 to 100 characters
descriptionstring or nullOptional
Optional note, up to 500 characters.
Up to 500 characters

Responses

201
The list was created.
400
Bad request.
parameter_missing parameter_invalid invalid_json
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
409
Conflict.
idempotency_key_in_use idempotency_key_reused
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

POST/v1/contact_lists

curl https://api.omnimessage.co/v1/contact_lists \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "October launch",
    "description": "Customers invited to the launch"
  }'

Response · 201

{
  "id": "lst_4Bd7fH0jL3nQ6sU9wZ2c",
  "object": "contact_list",
  "name": "October launch",
  "description": "Customers invited to the launch",
  "contact_count": 0,
  "created_at": "2026-10-01T08:00:00.000Z",
  "updated_at": "2026-10-04T16:20:00.000Z"
}

List contact lists#

GET/v1/contact_listsScopecontacts:read

Returns the static contact lists of the account, newest first.

Query parameters

limitintegerOptional
Number of objects to return, 1 to 100. Default 20.
starting_afterstringOptional
Cursor for the next page: the next_cursor of the previous response (the ID of its last object).

Responses

200
A page of contact lists.
400
Bad request.
parameter_invalid
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

GET/v1/contact_lists

curl https://api.omnimessage.co/v1/contact_lists \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "object": "list",
  "data": [
    {
      "id": "lst_4Bd7fH0jL3nQ6sU9wZ2c",
      "object": "contact_list",
      "name": "October launch",
      "description": "Customers invited to the launch",
      "contact_count": 1280,
      "created_at": "2026-10-01T08:00:00.000Z",
      "updated_at": "2026-10-04T16:20:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Retrieve a contact list#

GET/v1/contact_lists/{id}Scopecontacts:read

Returns one list with its current number of contacts.

Path parameters

idstringRequired
Contact list ID.

Responses

200
The list.
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
404
The resource does not exist in this account and mode.
resource_missing
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

GET/v1/contact_lists/{id}

curl https://api.omnimessage.co/v1/contact_lists/lst_4Bd7fH0jL3nQ6sU9wZ2c \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "id": "lst_4Bd7fH0jL3nQ6sU9wZ2c",
  "object": "contact_list",
  "name": "October launch",
  "description": "Customers invited to the launch",
  "contact_count": 1280,
  "created_at": "2026-10-01T08:00:00.000Z",
  "updated_at": "2026-10-04T16:20:00.000Z"
}

Update a contact list#

PATCH/v1/contact_lists/{id}Scopecontacts:write

Renames a list or changes its note.

Path parameters

idstringRequired
Contact list ID.

Request body

namestringOptional
New name.
1 to 100 characters
descriptionstring or nullOptional
New note; null clears it.
Up to 500 characters

Responses

200
The updated list.
400
Bad request.
parameter_missing parameter_invalid invalid_json
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
404
The resource does not exist in this account and mode.
resource_missing
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

PATCH/v1/contact_lists/{id}

curl -X PATCH https://api.omnimessage.co/v1/contact_lists/lst_4Bd7fH0jL3nQ6sU9wZ2c \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "October launch (wave 2)"
  }'

Response · 200

{
  "id": "lst_4Bd7fH0jL3nQ6sU9wZ2c",
  "object": "contact_list",
  "name": "October launch (wave 2)",
  "description": "Customers invited to the launch",
  "contact_count": 1280,
  "created_at": "2026-10-01T08:00:00.000Z",
  "updated_at": "2026-10-04T16:20:00.000Z"
}

Delete a contact list#

DELETE/v1/contact_lists/{id}Scopecontacts:write

Removes the list. The contacts on it are kept.

Path parameters

idstringRequired
Contact list ID.

Responses

200
The list was deleted.
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
404
The resource does not exist in this account and mode.
resource_missing
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

DELETE/v1/contact_lists/{id}

curl -X DELETE https://api.omnimessage.co/v1/contact_lists/lst_4Bd7fH0jL3nQ6sU9wZ2c \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "id": "lst_4Bd7fH0jL3nQ6sU9wZ2c",
  "object": "contact_list",
  "deleted": true
}

Add contacts to a list#

POST/v1/contact_lists/{id}/membersScopecontacts:write

Adds up to 1,000 contacts to the list. Contacts that are already on it, and IDs that do not exist, are ignored. Answers with the list and its new count.

Path parameters

idstringRequired
Contact list ID.

Headers

Idempotency-KeystringOptional
Unique string of up to 255 characters, such as a UUID. Repeating a request with the same key and body within 24 hours returns the stored response instead of performing the operation again.

Request body

contact_idsarray of stringsRequired
Contact IDs, up to 1,000 per request. Unknown IDs are ignored.
1 to 1000 items

Responses

200
The list after the change.
400
Bad request.
parameter_missing parameter_invalid invalid_json
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
404
The resource does not exist in this account and mode.
resource_missing
409
Conflict.
idempotency_key_in_use idempotency_key_reused
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

POST/v1/contact_lists/{id}/members

curl https://api.omnimessage.co/v1/contact_lists/lst_4Bd7fH0jL3nQ6sU9wZ2c/members \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_ids": [
      "ct_8Jk3mP6qR9sT2vW5xY1z"
    ]
  }'

Response · 200

{
  "id": "lst_4Bd7fH0jL3nQ6sU9wZ2c",
  "object": "contact_list",
  "name": "October launch",
  "description": "Customers invited to the launch",
  "contact_count": 1280,
  "created_at": "2026-10-01T08:00:00.000Z",
  "updated_at": "2026-10-04T16:20:00.000Z"
}

Remove contacts from a list#

POST/v1/contact_lists/{id}/members/removeScopecontacts:write

Takes up to 1,000 contacts off the list. The contacts themselves are kept. Answers with the list and its new count.

Path parameters

idstringRequired
Contact list ID.

Headers

Idempotency-KeystringOptional
Unique string of up to 255 characters, such as a UUID. Repeating a request with the same key and body within 24 hours returns the stored response instead of performing the operation again.

Request body

contact_idsarray of stringsRequired
Contact IDs, up to 1,000 per request. Unknown IDs are ignored.
1 to 1000 items

Responses

200
The list after the change.
400
Bad request.
parameter_missing parameter_invalid invalid_json
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
404
The resource does not exist in this account and mode.
resource_missing
409
Conflict.
idempotency_key_in_use idempotency_key_reused
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

POST/v1/contact_lists/{id}/members/remove

curl https://api.omnimessage.co/v1/contact_lists/lst_4Bd7fH0jL3nQ6sU9wZ2c/members/remove \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_ids": [
      "ct_8Jk3mP6qR9sT2vW5xY1z"
    ]
  }'

Response · 200

{
  "id": "lst_4Bd7fH0jL3nQ6sU9wZ2c",
  "object": "contact_list",
  "name": "October launch",
  "description": "Customers invited to the launch",
  "contact_count": 1279,
  "created_at": "2026-10-01T08:00:00.000Z",
  "updated_at": "2026-10-04T16:20:00.000Z"
}

List segments#

GET/v1/segmentsScopecontacts:read

Returns the saved segments of the account, newest first. Segments are created and edited in the console.

Query parameters

limitintegerOptional
Number of objects to return, 1 to 100. Default 20.
starting_afterstringOptional
Cursor for the next page: the next_cursor of the previous response (the ID of its last object).

Responses

200
A page of segments.
400
Bad request.
parameter_invalid
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

GET/v1/segments

curl https://api.omnimessage.co/v1/segments \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "object": "list",
  "data": [
    {
      "id": "seg_1Ae4gI7kM0oR3tV6xB9d",
      "object": "segment",
      "name": "VIP customers not messaged this month",
      "description": null,
      "rules": {
        "op": "and",
        "rules": [
          {
            "field": "tags",
            "operator": "has_any",
            "value": [
              "vip"
            ]
          },
          {
            "field": "consent.whatsapp",
            "operator": "is",
            "value": "opted_in"
          },
          {
            "field": "last_messaged_at",
            "operator": "not_in_last_days",
            "value": 30
          }
        ]
      },
      "created_at": "2026-10-01T08:00:00.000Z",
      "updated_at": "2026-10-01T08:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Retrieve a segment#

GET/v1/segments/{id}Scopecontacts:read

Returns one segment with its rules.

Path parameters

idstringRequired
Segment ID.

Responses

200
The segment.
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
404
The resource does not exist in this account and mode.
resource_missing
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

GET/v1/segments/{id}

curl https://api.omnimessage.co/v1/segments/seg_1Ae4gI7kM0oR3tV6xB9d \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "id": "seg_1Ae4gI7kM0oR3tV6xB9d",
  "object": "segment",
  "name": "VIP customers not messaged this month",
  "description": null,
  "rules": {
    "op": "and",
    "rules": [
      {
        "field": "tags",
        "operator": "has_any",
        "value": [
          "vip"
        ]
      },
      {
        "field": "consent.whatsapp",
        "operator": "is",
        "value": "opted_in"
      },
      {
        "field": "last_messaged_at",
        "operator": "not_in_last_days",
        "value": 30
      }
    ]
  },
  "created_at": "2026-10-01T08:00:00.000Z",
  "updated_at": "2026-10-01T08:00:00.000Z"
}

Count the contacts of a segment#

GET/v1/segments/{id}/previewScopecontacts:read

Evaluates the segment now and returns how many contacts match, with up to five of them as a sample.

Path parameters

idstringRequired
Segment ID.

Responses

200
Current size of the segment.
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
404
The resource does not exist in this account and mode.
resource_missing
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

GET/v1/segments/{id}/preview

curl https://api.omnimessage.co/v1/segments/seg_1Ae4gI7kM0oR3tV6xB9d/preview \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "object": "segment_preview",
  "segment_id": "seg_1Ae4gI7kM0oR3tV6xB9d",
  "count": 412,
  "sample": [
    {
      "id": "ct_8Jk3mP6qR9sT2vW5xY1z",
      "object": "contact",
      "first_name": "Layla",
      "last_name": "Haddad",
      "phone": "+971501234567",
      "email": "layla@example.com",
      "channel_identifiers": {
        "telegram": "482910375"
      },
      "locale": "ar",
      "timezone": "Asia/Dubai",
      "attributes": {
        "city": "Dubai",
        "orders": 12
      },
      "tags": [
        "vip",
        "newsletter"
      ],
      "consent": {
        "whatsapp": {
          "state": "opted_in",
          "source": "api",
          "updated_at": "2026-10-01T08:00:00.000Z"
        }
      },
      "blocked": false,
      "blocked_reason": null,
      "last_messaged_at": "2026-10-05T09:30:00.000Z",
      "created_at": "2026-10-01T08:00:00.000Z",
      "updated_at": "2026-10-05T09:30:00.000Z"
    }
  ]
}