hellomateo API Docs

Compare the legacy API with the new public API and migrate observed legacy request patterns.

This guide helps you migrate from the legacy API at https://integration.getmateo.com/api/v1 to the new public API at https://api.getmateo.com/v1. It highlights the main behavioral differences between both APIs and provides request-specific migration guidance for successful legacy requests observed over the past 30 days.

Rollout expectations

We plan to phase out the legacy API gradually. During the rollout, we expect to reject legacy request patterns that have not been observed as successful requests in the past 30 days.

If your integration depends on a request pattern that is missing from this guide, reach out to us. This can happen when an integration was built earlier but has not launched yet, or has not sent successful production traffic recently. We can make exceptions for customers with valid migration constraints.

What changes in the new API

Base URL and versioning

The main URL change is that the legacy API used https://integration.getmateo.com/api/v1, while the new public API uses https://api.getmateo.com/v1. Endpoint paths in the API reference include the /v1 prefix. The new docs also include an OpenAPI schema for API tools and generated clients.

The new API also requires the current API version header on every request. This lets you choose when to opt in to newer API behavior. See Versioning for the current header name and supported version.

Authentication

Both APIs use bearer tokens in the Authorization header. In the new API, every authenticated request must also include the API version header.

Store API tokens securely and never expose them in frontend code, mobile apps, public repositories, logs, support screenshots, or other places where untrusted users can read them. See Authentication for token handling guidance.

Filtering and lookups

The legacy API allowed broad filter syntax on many resources. The new API exposes documented filters per endpoint. Check the API reference for the exact filters supported by the endpoint you are calling.

For exact lookups, prefer dedicated ID or locator routes when they exist, such as GET /v1/contacts/{id} or GET /v1/contacts/by?external_id=<external_id>. Some legacy filters do not have an exact public API equivalent yet; those request patterns are marked in the request-specific guide below.

Pagination

The legacy API used limit and offset, and some integrations used range-style pagination. The new API uses cursor pagination with page_token.

For list endpoints, start with the collection URL and follow the returned next_page_url or previous_page_url when present. Treat page tokens as opaque values. See Pagination for the full response shape and examples.

The legacy API used select to choose fields and embed related resources. The new API returns compact resources by default and uses documented include parameters for optional related data.

Use supported include values from the endpoint's API reference. Custom fields on contacts, deals, and appointments use named include_details=<custom_field> values. See Include-dependent responses.

Writes and deletes

The legacy API often used generic POST, PATCH, DELETE, or upsert-style requests with filters to decide which records changed. The new API uses purpose-built command endpoints.

For conditional updates or deletes, you may need to fetch the entity first, check the relevant fields client-side, and then call the documented command endpoint. Relationship updates use endpoint-specific request body fields; see Updating relationships when an endpoint supports relationship updates.

Errors and request IDs

The new API has a consistent JSON error shape with a stable code, an is_transient flag, a timestamp, and a request_id. Every response also includes a Request-Id header.

Use the request ID when debugging or contacting support. See Errors and Request IDs.

Request-specific migration guide

The entries below represent successful legacy API request patterns we recorded over the past 30 days.

Each entry is based on a request signature. A signature is a simplified request pattern where customer-specific values are replaced by placeholders.

For example:

GET /api/v1/contact filters=external_id.eq.? limit=?

This means the integration requested contacts by external_id with a limit, but the actual external_id value is not shown.

If a request your integration depends on is missing, reach out to us. This can happen if the integration was built earlier but has not launched yet, or has not sent successful production traffic during the past 30 days.

Appointments

GET/api/v1/appointment filters=contact_id.eq.?

Use case: listing appointments for one contact. Replace this request with GET /v1/appointments?contact=<contact_id>.

API reference:List Appointments

GET/api/v1/appointment filters=contact_id.eq.? limit=? offset=?

Use case: listing appointments for one contact. Replace this request with GET /v1/appointments?contact=<contact_id>&limit=<limit>; use page_token for additional pages instead of offset.

API references:List Appointments Pagination

GET/api/v1/appointment filters=external_id.eq.?

Use case: reading one appointment by external id. Because appointment external ids are unique, replace this request with GET /v1/appointments/by?external_id=<external_id>.

API reference:Get Appointment By Locator

GET/api/v1/appointment filters=start_time.gt.? limit=? offset=?

Use case: listing appointments after a start time. Replace this request with GET /v1/appointments?start_time[gt]=<timestamp>&limit=<limit>; use page_token for additional pages instead of offset.

API references:List Appointments Pagination

POST/api/v1/appointment_details

Use case: creating an appointment with detail fields. Replace this request with POST /v1/appointments and send those fields on the appointment body.

API reference:Create Appointment

PATCH/api/v1/appointment_details

Use case: updating an appointment with detail fields. Replace id-based updates with PATCH /v1/appointments/{id}; replace external-id based updates with PATCH /v1/appointments/by?external_id=<external_id>.

API references:Update Appointment Update Appointment By Locator

DELETE/api/v1/appointment filters=external_id.eq.?

Use case: deleting one appointment by external id. Replace this request with DELETE /v1/appointments/by?external_id=<external_id>.

API reference:Delete Appointment By Locator

Contact Lists

GET/api/v1/contact_list

Use case: listing contact lists. Replace this request with GET /v1/contact-lists.

API reference:List Contact Lists

GET/api/v1/contact_list filters=created_at.gte.?

Use case: finding contact lists changed since a timestamp. Replace this request with GET /v1/contact-lists?updated_at[gte]=<timestamp>; the new API exposes the contact-list update timestamp for this sync-style list filter.

API reference:List Contact Lists

GET/api/v1/contact_list filters=name.eq.?

Use case: finding contact lists by name. Replace this request with GET /v1/contact-lists?name=<name>.

API reference:List Contact Lists

GET/api/v1/contact_list_contact filters=contact_list_id.eq.?

Use case: listing contacts in one contact list. Replace this request with GET /v1/contact-lists/{id}/contacts; use page_token for additional pages instead of offset when paginating.

API references:List Contact List Contacts Pagination

POST/api/v1/contact_list

Use case: creating a contact list. Replace this request with POST /v1/contact-lists.

API reference:Create Contact List

POST/api/v1/contact_list/clear

Use case: clearing all contacts from one contact list. Replace id-based requests with POST /v1/contact-lists/{id}/contacts/clear; replace external-id based requests with POST /v1/contact-lists/by/contacts/clear?external_id=<external_id>.

API references:Clear Contact List Contacts Clear Contact List Contacts by Locator

DELETE/api/v1/contact_list filters=id.eq.?

Use case: deleting one contact list by id. Replace this request with DELETE /v1/contact-lists/{id}.

API reference:Delete Contact List

DELETE/api/v1/contact_list_contact filters=contact_id.in.?,contact_list_id.eq.?

We are working on public API support for this request pattern. If this request is important for your migration, contact us with your use case.

Contacts

GET/api/v1/contact

Use case: listing contacts. Replace this request with GET /v1/contacts.

API reference:List Contacts

GET/api/v1/contact filters=email.eq.?

Use case: reading one contact by email. Replace this request with GET /v1/contacts/by?email=<value>.

API reference:Get Contact by Locator

GET/api/v1/contact filters=external_id.eq.?

Use case: reading one contact by external_id. Replace this request with GET /v1/contacts/by?external_id=<value>.

API reference:Get Contact by Locator

GET/api/v1/contact filters=external_id.eq.? limit=?

Use case: reading one contact by external_id. Replace this request with GET /v1/contacts/by?external_id=<value>.

API reference:Get Contact by Locator

GET/api/v1/contact filters=external_id.eq.? limit=? offset=?

Use case: reading one contact by external_id. Replace this request with GET /v1/contacts/by?external_id=<value>.

API reference:Get Contact by Locator

GET/api/v1/contact filters=external_id.eq.?,organisation_id.eq.?

Use case: reading one contact by external_id. Replace this request with GET /v1/contacts/by?external_id=<value>.

API reference:Get Contact by Locator

GET/api/v1/contact filters=external_id.in.?

Use case: listing contacts by external ids. Replace this request with GET /v1/contacts?external_id[in]=<external_ids>.

API reference:List Contacts

GET/api/v1/contact filters=external_id.is.?

Use case: listing contacts without an external id. Replace this request with GET /v1/contacts?external_id[is_null]=true.

API reference:List Contacts

GET/api/v1/contact filters=external_id.like.?

Use case: finding a contact by external id pattern. If the pattern is actually a complete external id, replace this request with GET /v1/contacts/by?external_id=<external_id>. The new API does not support partial external_id matching yet; if your integration depends on partial matching, reach out to us with the concrete use case.

API reference:Get Contact by Locator

GET/api/v1/contact filters=external_id.not.is.?,updated_at.gt.? limit=? offset=?

Use case: syncing contacts with external ids that were updated after a timestamp. This history-style sync use case will be covered by the upcoming audit log endpoint rather than by a new API contact list filter.

GET/api/v1/contact filters=fts.fts.? limit=? order=display_name:desc.nullsLast

Use case: searching contacts. The new API does not support this full-text search request yet. Use direct contact filters such as email, phone number, or external_id when possible; if your integration depends on full-text search, reach out to us with the concrete use case.

API reference:List Contacts

GET/api/v1/contact filters=id.eq.?

Use case: reading one contact by id. Replace this request with GET /v1/contacts/{id}.

API reference:Get Contact

GET/api/v1/contact filters=or(created_at.gte.?,updated_by_import_id.eq.?) limit=? offset=?

Use case: finding contacts created after a timestamp or changed by an import. This history-style import/change lookup will be covered by the upcoming audit log endpoint rather than by a contact list filter; use page_token rather than offset when migrating adjacent list pagination.

API reference:Pagination

GET/api/v1/contact filters=or(email.eq.?,email.eq.?) limit=?

Use case: listing contacts matching one of several email addresses. Replace this request with GET /v1/contacts?email[in]=<emails>.

API reference:List Contacts

GET/api/v1/contact filters=or(sms.eq.?,sms.eq.?,whatsapp.eq.?,whatsapp.eq.?) limit=?

Use case: finding contacts by any of several phone-number locators. Replace the OR request with one GET /v1/contacts/by?sms=<sms> request per SMS value and one GET /v1/contacts/by?whatsapp=<whatsapp> request per WhatsApp value, then merge and deduplicate the returned contacts client-side.

API reference:Get Contact by Locator

GET/api/v1/contact filters=sms.eq.? limit=?

Use case: reading one contact by sms. Replace this request with GET /v1/contacts/by?sms=<value>.

API reference:Get Contact by Locator

GET/api/v1/contact filters=updated_at.gte.?

Use case: syncing contacts updated since a timestamp. This history-style sync use case will be covered by the upcoming audit log endpoint rather than by a contact list filter.

GET/api/v1/contact filters=whatsapp.eq.?

Use case: reading one contact by whatsapp. Replace this request with GET /v1/contacts/by?whatsapp=<value>.

API reference:Get Contact by Locator

GET/api/v1/contact filters=whatsapp.eq.? limit=?

Use case: reading one contact by whatsapp. Replace this request with GET /v1/contacts/by?whatsapp=<value>.

API reference:Get Contact by Locator

GET/api/v1/contact joins=conversation filters=external_id.eq.?

Use case: reading a contact and its conversations by external id. Replace this request with GET /v1/contacts/by?external_id=<external_id> for the contact and GET /v1/conversations?contact_external_id=<external_id> for its conversations.

API references:Get Contact by Locator List Conversations

GET/api/v1/contact limit=? offset=?

Use case: listing contacts. Replace this request with GET /v1/contacts?limit=<limit>; use page_token for additional pages instead of offset.

API references:List Contacts Pagination

GET/api/v1/contact limit=? offset=? order=created_at:desc.nullsLast

Use case: listing contacts. Replace this request with GET /v1/contacts?limit=<limit>; use page_token for additional pages instead of offset.

API references:List Contacts Pagination

GET/api/v1/contact limit=? order=display_name:desc.nullsLast

Use case: listing contacts. Replace this request with GET /v1/contacts?limit=<limit>.

API reference:List Contacts

GET/api/v1/contact offset=?

Use case: listing contacts. Replace this request with GET /v1/contacts; use page_token for additional pages instead of offset.

API references:List Contacts Pagination

GET/api/v1/contact_custom_field filters=contact_id.eq.?

Use case: reading detail fields for a contact. Replace this request with GET /v1/contacts/{contact_id}?include_details=<detail_field>; repeat include_details for each detail field your integration reads.

API reference:Get Contact

GET/api/v1/contact_custom_field filters=contact_id.eq.?,key.eq.?

Use case: reading one custom detail field for a contact. Replace this request with GET /v1/contacts/{contact_id}?include_details=<key>.

API reference:Get Contact

GET/api/v1/contact_custom_field joins=contact(conversation) filters=contact_id.eq.?,key.in.?

Use case: reading selected detail fields for one contact together with that contact’s conversations. Replace this request with GET /v1/contacts/{contact_id}?include_details=<key> for the contact and requested detail fields; repeat include_details for each key from the legacy key[in] filter. Fetch the conversations separately with GET /v1/conversations?contact=<contact_id>.

API references:Get Contact List Conversations

GET/api/v1/contact_details

Use case: listing contacts. Replace this request with GET /v1/contacts?include_details=<detail_field>; repeat include_details for each detail field your integration reads.

API reference:List Contacts

GET

/api/v1/contact_details filters=address_line1.not.is.?,city.not.is.?,external_id.is.?,kundennummer_hellomateo.is.?,zipcode.not.is.? limit=?

Use case: listing contacts without an external id whose address fields are present and whose kundennummer_hellomateo detail field is empty. Replace this request with GET /v1/contacts?external_id[is_null]=true&kundennummer_hellomateo[is_null]=true&limit=<limit>&include_details=kundennummer_hellomateo, then evaluate the address_line1, city, and zipcode checks client-side.

API reference:List Contacts

GET/api/v1/contact_details filters=convercus_account_id.eq.?

Use case: listing contacts by the convercus_account_id detail field. Replace this request with GET /v1/contacts?convercus_account_id=<value>&include_details=convercus_account_id.

API reference:List Contacts

GET/api/v1/contact_details filters=email.eq.?

Use case: reading one contact by email. Replace this request with GET /v1/contacts/by?email=<value>&include_details=<detail_field>; repeat include_details for each detail field your integration reads.

API reference:Get Contact by Locator

GET/api/v1/contact_details filters=external_id.eq.?

Use case: reading one contact by external_id. Replace this request with GET /v1/contacts/by?external_id=<value>&include_details=<detail_field>; repeat include_details for each detail field your integration reads.

API reference:Get Contact by Locator

GET/api/v1/contact_details filters=external_id.eq.? limit=?

API reference:Get Contact by Locator

GET/api/v1/contact_details filters=external_id.in.?

Use case: listing contacts by external ids. Replace this request with GET /v1/contacts?external_id[in]=<external_ids>&include_details=<detail_field>; repeat include_details for each detail field your integration reads.

API reference:List Contacts

GET/api/v1/contact_details filters=external_id.is.?

Use case: listing contacts without an external id. Replace this request with GET /v1/contacts?external_id[is_null]=true&include_details=<detail_field>; repeat include_details for each detail field your integration reads.

API reference:List Contacts

GET/api/v1/contact_details filters=external_id.is.?,kundennummer_hellomateo.not.is.?

Use case: listing contacts without an external id whose kundennummer_hellomateo detail field is present. Replace this request with GET /v1/contacts?external_id[is_null]=true&kundennummer_hellomateo[not_null]=true&include_details=kundennummer_hellomateo.

API reference:List Contacts

GET/api/v1/contact_details filters=external_id.is.?,kundennummer_hellomateo.not.is.?,zipcode.not.is.? limit=?

Use case: listing contacts without an external id whose kundennummer_hellomateo detail field is present and whose zipcode is present. Replace this request with GET /v1/contacts?external_id[is_null]=true&kundennummer_hellomateo[not_null]=true&limit=<limit>&include_details=kundennummer_hellomateo, then evaluate the zipcode check client-side.

API reference:List Contacts

GET/api/v1/contact_details filters=external_id.not.is.? limit=?

Use case: listing contacts with detail fields where external id is present. For a current snapshot, replace this request with GET /v1/contacts?external_id[not_null]=true&limit=<limit>&include_details=<detail_field>; repeat include_details for each detail field your integration reads. If this request is used to check for changes across all contacts, use the upcoming audit log endpoint instead.

API reference:List Contacts

GET/api/v1/contact_details filters=external_id.not.is.?,is_blocked.eq.?,updated_at.gt.? limit=? offset=?

Use case: syncing contacts whose blocked state changed after a timestamp. This history-style sync use case will be covered by the upcoming audit log endpoint rather than by a new API contact list filter.

GET/api/v1/contact_details filters=external_id.not.is.?,whatsapp_marketing_opt_in.eq.? limit=?

Use case: listing contacts with an external id that are opted in for WhatsApp marketing. When the legacy filter checks whatsapp_marketing_opt_in=true, replace this request with GET /v1/contacts?external_id[not_null]=true&channel_types[in]=whatsapp&require_marketing_opt_in=true&limit=<limit>&include_details=<detail_field>; repeat include_details for each detail field your integration reads.

API reference:List Contacts

GET/api/v1/contact_details filters=fts.fts.? limit=? order=display_name:desc.nullsLast

Use case: searching contacts with detail fields. The new API does not support this full-text search request yet. Use direct contact filters such as email, phone number, external_id, or named detail-field filters when possible; if your integration depends on full-text search, reach out to us with the concrete use case.

API reference:List Contacts

GET/api/v1/contact_details filters=id.eq.?

Use case: reading one contact by id. Replace this request with GET /v1/contacts/{id}?include_details=<detail_field>; repeat include_details for each detail field your integration reads.

API reference:Get Contact

GET/api/v1/contact_details filters=id.eq.?,tarif_status.eq.?

Use case: reading one contact only when its tarif_status detail field matches. Replace this request with GET /v1/contacts/{id}?include_details=tarif_status, then check the returned tarif_status value client-side.

API reference:Get Contact

GET/api/v1/contact_details filters=is_blocked.eq.? limit=? offset=? order=full_name:asc.nullsLast|id:asc.nullsLast

Use case: listing contacts by blocked state with detail fields. If the legacy request filters for is_blocked=false, replace it with GET /v1/contacts?limit=<limit>&include_details=<detail_field> and repeat include_details for each detail field your integration reads. The new API does not currently expose an exact list filter for only blocked contacts, and it controls contact ordering; use page_token for additional pages instead of offset.

API references:List Contacts Pagination

GET/api/v1/contact_details filters=last_delivery_date.lt.?,was_recalled.eq.?

Use case: listing contacts by last_delivery_date and was_recalled detail fields. Replace this request with GET /v1/contacts?last_delivery_date[lt]=<timestamp>&was_recalled=<value>&include_details=last_delivery_date&include_details=was_recalled.

API reference:List Contacts

GET

/api/v1/contact_details filters=or(email_marketing_opt_in.eq.?,sms_marketing_opt_in.eq.?,whatsapp_marketing_opt_in.eq.?) limit=? offset=? order=created_at:desc.nullsLast

Use case: listing contacts that match any of several channel-specific marketing opt-in clauses. Replace the OR request with one GET /v1/contacts?channel_types[in]=email&require_marketing_opt_in=true&limit=<limit>, one GET /v1/contacts?channel_types[in]=sms&require_marketing_opt_in=true&limit=<limit>, and one GET /v1/contacts?channel_types[in]=whatsapp&require_marketing_opt_in=true&limit=<limit>; merge and deduplicate the contacts client-side. The new API controls contact ordering, so do not rely on the legacy created_at sort; use page_token for additional pages instead of offset.

API references:List Contacts Pagination

GET

/api/v1/contact_details filters=or(google_calendar_id_01.eq.?,google_calendar_id_02.eq.?,google_calendar_id_03.eq.?,google_calendar_id_04.eq.?,google_calendar_id_05.eq.?,google_calendar_id_06.eq.?,google_calendar_id_07.eq.?,google_calendar_id_08.eq.?,google_calendar_id_09.eq.?,google_calendar_id_10.eq.?),tarif_status.eq.?

Use case: finding contacts by tarif_status and any one of several google_calendar_id detail fields. Replace the OR request with one GET /v1/contacts?tarif_status=<tarif_status>&google_calendar_id_01=<calendar_id>&include_details=tarif_status&include_details=google_calendar_id_01 per google_calendar_id detail field; repeat for google_calendar_id_02 through google_calendar_id_10 as needed, then merge and deduplicate the contacts client-side.

API reference:List Contacts

GET/api/v1/contact_details filters=tarif_status.eq.? limit=? offset=? order=display_name:asc.nullsLast

Use case: listing contacts by the tarif_status detail field. Replace this request with GET /v1/contacts?tarif_status=<value>&limit=<limit>&include_details=tarif_status. The new API controls contact ordering, so do not rely on the legacy display_name sort; use page_token for additional pages instead of offset.

API references:List Contacts Pagination

GET/api/v1/contact_details filters=timify_booking_id.eq.?

Use case: listing contacts by the timify_booking_id detail field. Replace this request with GET /v1/contacts?timify_booking_id=<value>&include_details=timify_booking_id.

API reference:List Contacts

GET/api/v1/contact_details filters=updated_at.gt.? limit=? offset=? order=updated_at:desc.nullsLast

Use case: syncing contacts updated after a timestamp. This history-style sync use case will be covered by the upcoming audit log endpoint rather than by a new API contact list filter.

GET

/api/v1/contact_details filters=whatsapp_marketing_opt_in.eq.? limit=? offset=? order=full_name:asc.nullsLast|id:asc.nullsLast

Use case: listing contacts opted in for WhatsApp marketing. When the legacy filter checks whatsapp_marketing_opt_in=true, replace this request with GET /v1/contacts?channel_types[in]=whatsapp&require_marketing_opt_in=true&limit=<limit>&include_details=<detail_field>; repeat include_details for each detail field your integration reads. The new API controls contact ordering, so do not rely on the legacy full_name sort; use page_token for additional pages instead of offset.

API references:List Contacts Pagination

GET/api/v1/contact_details filters=whatsapp.eq.?

Use case: reading one contact by whatsapp. Replace this request with GET /v1/contacts/by?whatsapp=<value>&include_details=<detail_field>; repeat include_details for each detail field your integration reads.

API reference:Get Contact by Locator

GET/api/v1/contact_details limit=?

Use case: listing contacts. Replace this request with GET /v1/contacts?limit=<limit>&include_details=<detail_field>; repeat include_details for each detail field your integration reads.

API reference:List Contacts

GET/api/v1/contact_details limit=? order=display_name:desc.nullsLast

Use case: listing contacts. Replace this request with GET /v1/contacts?limit=<limit>&include_details=<detail_field>; repeat include_details for each detail field your integration reads.

API reference:List Contacts

GET/api/v1/contact_details offset=?

Use case: listing contacts. Replace this request with GET /v1/contacts?include_details=<detail_field>; repeat include_details for each detail field your integration reads; use page_token for additional pages instead of offset.

API references:List Contacts Pagination

POST/api/v1/contact

Use case: creating a contact. Replace this request with POST /v1/contacts.

API reference:Create Contact

POST/api/v1/contact_custom_field

Use case: writing a custom detail field for one contact. Replace this request with PATCH /v1/contacts/{id} and send the detail key in the contact body.

API reference:Update Contact

POST/api/v1/contact_custom_field filters=contact_id.eq.?,custom_field_id.eq.?

Use case: writing a custom detail field for one contact. Replace this request with PATCH /v1/contacts/{id} and send the detail key in the contact body.

API reference:Update Contact

POST/api/v1/contact_details

Use case: creating a contact with detail fields. Replace this request with POST /v1/contacts and send detail fields on the contact body.

API reference:Create Contact

POST/api/v1/contact/merge

Use case: merging duplicate contacts. Replace this request with POST /v1/contacts/{id}/merge.

API reference:Merge Contacts

PATCH/api/v1/contact filters=id.eq.?

Use case: updating one contact by id. Replace this request with PATCH /v1/contacts/{id}.

API reference:Update Contact

PATCH/api/v1/contact_custom_field filters=contact_id.eq.?,custom_field_id.eq.?

Use case: writing a custom detail field for one contact. Replace this request with PATCH /v1/contacts/{id} and send the detail key in the contact body.

API reference:Update Contact

PATCH/api/v1/contact_details

Use case: updating one contact from a body-provided locator. Replace id-based updates with PATCH /v1/contacts/{id}; replace handle-based updates with PATCH /v1/contacts/by using email, sms, whatsapp, external_id, or secondary_external_id.

API references:Update Contact Update Contact by Locator

PATCH/api/v1/contact_details filters=id.eq.?

Use case: updating one contact by id. Replace this request with PATCH /v1/contacts/{id} and send detail fields on the contact body.

API reference:Update Contact

PATCH/api/v1/contact_details filters=whatsapp.eq.?

Use case: updating one contact by WhatsApp number. Replace this request with PATCH /v1/contacts/by?whatsapp=<whatsapp> and send detail fields on the contact body.

API reference:Update Contact by Locator

DELETE/api/v1/contact filters=external_id.eq.?

Use case: deleting one contact by external id. Replace this request with DELETE /v1/contacts/by?external_id=<external_id>.

API reference:Delete Contact by Locator

DELETE/api/v1/contact filters=id.eq.?

Use case: deleting one contact by id. Replace this request with DELETE /v1/contacts/{id}.

API reference:Delete Contact

DELETE/api/v1/contact_custom_field filters=contact_id.eq.?,custom_field_id.eq.?

Use case: clearing a custom detail field for one contact. Replace this request with PATCH /v1/contacts/{id} and set that detail key to null.

API reference:Update Contact

DELETE/api/v1/contact_custom_field filters=contact_id.eq.?,key.eq.?

Use case: clearing a custom detail field for one contact. Replace this request with PATCH /v1/contacts/{id} and set that detail key to null.

API reference:Update Contact

DELETE/api/v1/contact_details filters=external_id.eq.?

Use case: deleting one contact by external id. Replace this request with DELETE /v1/contacts/by?external_id=<external_id>.

API reference:Delete Contact by Locator

DELETE/api/v1/contact_details filters=id.eq.?

Use case: deleting one contact by id. Replace this request with DELETE /v1/contacts/{id}.

API reference:Delete Contact

Custom Fields

GET/api/v1/custom_field filters=entity.eq.?,key.eq.?

Use case: listing custom field definitions. Replace this request with GET /v1/custom-fields?entity=<entity>&key=<key>.

API reference:List Custom Fields

GET/api/v1/custom_field filters=key.eq.?

Use case: listing custom field definitions. Replace this request with GET /v1/custom-fields?key=<key>.

API reference:List Custom Fields

GET/api/v1/custom_field filters=or(key.eq.?,key.eq.?)

Use case: listing custom field definitions. Replace this request with GET /v1/custom-fields?key[in]=<keys>.

API reference:List Custom Fields

GET/api/v1/custom_field filters=organisation_id.eq.?

Use case: listing custom field definitions. Replace this request with GET /v1/custom-fields.

API reference:List Custom Fields

GET/api/v1/custom_field offset=?

Use case: listing custom field definitions. Replace this request with GET /v1/custom-fields; use page_token for additional pages instead of offset.

API references:List Custom Fields Pagination

Deals

GET/api/v1/deal limit=?

Use case: listing deals. Replace this request with GET /v1/deals?limit=<limit>.

API reference:List Deals

GET/api/v1/deal_custom_field limit=?

Use case: listing deal detail fields. Replace this request with GET /v1/deals?limit=<limit>&include_details=<detail_field>; repeat include_details for each deal detail field your integration reads.

API reference:List Deals

GET/api/v1/deal_details filters=contact_id.eq.? limit=? offset=?

Use case: listing deals for one contact with detail fields. Replace this request with GET /v1/deals?contact=<contact_id>&limit=<limit>&include_details=<detail_field>; repeat include_details for each detail field your integration reads; use page_token for additional pages instead of offset.

API references:List Deals Pagination

GET/api/v1/deal_details filters=external_id.eq.?,type_key.eq.?

Use case: reading one deal by external id and checking its type. Replace this request with GET /v1/deals/by?external_id=<external_id> and check type_key client-side.

API reference:Get Deal by Locator

POST/api/v1/deal_details

Use case: creating a deal with detail fields. Replace this request with POST /v1/deals and send detail fields on the deal body.

API reference:Create Deal

PATCH/api/v1/deal_details

Use case: updating a deal with detail fields. Replace id-based updates with PATCH /v1/deals/{id}; replace external-id based updates with PATCH /v1/deals/by?external_id=<external_id>.

API references:Update Deal Update Deal By Locator

DELETE/api/v1/deal filters=external_id.eq.?

Use case: deleting one deal by external id. Replace this request with DELETE /v1/deals/by?external_id=<external_id>.

API reference:Delete Deal By Locator

Employees

GET/api/v1/employee

Use case: listing team members. Replace this request with GET /v1/employees.

API reference:List Employees

GET/api/v1/employee filters=full_name.eq.?

Use case: finding employees by full name. Replace this request with GET /v1/employees?full_name=<full_name>.

API reference:List Employees

Files

POST/api/v1/storage/sign/:bucketName/*

Use case: creating a signed URL for a stored media library file. Replace this request with POST /v1/files/{id}/download_url for files managed by the public files API.

API reference:Create File Download URL

POST/api/v1/storage/upload/sign/:bucketName/*

Use case: creating a signed upload URL for a media library file. Replace this request by uploading the media_library file directly with POST /v1/files.

API reference:Create File

Formatting

POST/api/v1/format

Use case: formatting a phone number before sending it to another API request. In the new API this separate request is usually unnecessary because endpoints such as imports and message sending format phone numbers internally. POST /v1/format/phone-number remains available as an educational helper when you want to preview normalization behavior.

API reference:Format Phone Number

Identity

GET/api/v1/me

Use case: identifying the authenticated integration context. Replace this request with GET /v1/me.

API reference:Get Current Identity

Imports

GET/api/v1/import filters=id.eq.?

Use case: polling one asynchronous import by id. Replace this request with GET /v1/contacts/imports/{id}, GET /v1/deals/imports/{id}, or GET /v1/appointments/imports/{id} according to the imported entity type. Poll the returned status and result counts with backoff.

API references:Get Contact Import Get Deal Import Get Appointment Import

POST/api/v1/import

Use case: submitting an asynchronous contact, deal, or appointment import. Replace this request with POST /v1/contacts/imports/batch, POST /v1/deals/imports/batch, or POST /v1/appointments/imports/batch according to the legacy type. Send the record array in the payload field and omit type. Every successful POST creates a new import job.

API references:Create Contact Batch Import Create Deal Batch Import Create Appointment Batch Import

Journeys

GET

/api/v1/journey joins=latest_published_version_id(journey_node!inner) filters=latest_published_version_id.journey_node.event_type.eq.?,status.eq.?

We are working on public API support for this request pattern. If this request is important for your migration, contact us with your use case.

POST/api/v1/journey_execution

We are working on public API support for this request pattern. If this request is important for your migration, contact us with your use case.

Messaging

GET/api/v1/channel

Use case: listing communication channels. Replace this request with GET /v1/channels.

API reference:List Channels

GET/api/v1/channel filters=id.eq.?

Use case: reading one channel by id. Replace this request with GET /v1/channels/{id}.

API reference:Get Channel by ID

GET/api/v1/channel filters=status.eq.?,type.eq.?

Use case: listing communication channels. Replace this request with GET /v1/channels?status=<status>&type=<type>.

API reference:List Channels

GET/api/v1/channel filters=status.eq.?,type.eq.? limit=? offset=? order=name:desc.nullsLast

Use case: listing communication channels. Replace this request with GET /v1/channels?status=<status>&type=<type>&limit=<limit>; use page_token for additional pages instead of offset.

API references:List Channels Pagination

GET/api/v1/channel filters=type.eq.?

Use case: listing communication channels. Replace this request with GET /v1/channels?type=<type>.

API reference:List Channels

GET/api/v1/channel limit=? order=name:desc.nullsLast

Use case: listing communication channels. Replace this request with GET /v1/channels?limit=<limit>.

API reference:List Channels

GET/api/v1/comment filters=conversation_id.eq.?,created_at.gte.? limit=? order=created_at:desc.nullsLast

Use case: reading recent comments in one conversation. If you need the latest comments on that conversation, replace this request with GET /v1/conversations/{conversation_id}/comments?limit=<limit>. If you are polling for comments created after a timestamp, use GET /v1/conversation-events?conversation=<conversation_id>&type=comment.created&created_at[gte]=<timestamp>&limit=<limit>.

API references:List Conversation Comments List Conversation Events

GET/api/v1/conversation

Use case: listing conversations. Replace this request with GET /v1/conversations.

API reference:List Conversations

GET/api/v1/conversation filters=channel_id.eq.?,external_id.eq.?,organisation_id.eq.?

Use case: listing conversations. Replace this request with GET /v1/conversations?channel=<channel_id>&external_id=<external_id>.

API reference:List Conversations

GET/api/v1/conversation filters=channel_id.eq.?,unread.eq.?

Use case: listing conversations. Replace this request with GET /v1/conversations?channel=<channel_id>&unread=<unread>.

API reference:List Conversations

GET/api/v1/conversation filters=channel_type.eq.?,contact_id.eq.?

Use case: listing conversations. Replace this request with GET /v1/conversations?channel_type=<channel_type>&contact=<contact_id>.

API reference:List Conversations

GET

/api/v1/conversation filters=channel_type.eq.?,latest_message_created_at.gte.? limit=? offset=? order=latest_activity_created_at:desc.nullsLast

Use case: polling conversation activity after a message timestamp. Replace this with GET /v1/conversation-events?created_at[gte]=<timestamp>&limit=<limit> when the activity stream covers your use case; if you need channel-type-specific latest-message filtering, reach out to us. Use page_token for additional pages instead of offset.

API references:List Conversation Events Pagination

GET/api/v1/conversation filters=channel_type.eq.?,updated_at.gte.?

Use case: syncing conversation activity since a timestamp. Replace this with GET /v1/conversation-events?created_at[gte]=<timestamp> where possible; if you need channel-type-specific conversation updates, reach out to us.

API reference:List Conversation Events

GET/api/v1/conversation filters=channel_type.eq.?,updated_at.gte.? limit=? offset=?

Use case: syncing conversation activity since a timestamp. Replace this with GET /v1/conversation-events?created_at[gte]=<timestamp>&limit=<limit> where possible; if you need channel-type-specific conversation updates, reach out to us. Use page_token for additional pages instead of offset.

API references:List Conversation Events Pagination

GET/api/v1/conversation filters=contact_id.eq.?

Use case: listing conversations. Replace this request with GET /v1/conversations?contact=<contact_id>.

API reference:List Conversations

GET/api/v1/conversation filters=contact_id.eq.? limit=? offset=?

Use case: listing conversations. Replace this request with GET /v1/conversations?contact=<contact_id>&limit=<limit>; use page_token for additional pages instead of offset.

API references:List Conversations Pagination

GET/api/v1/conversation filters=contact_id.eq.? limit=? order=latest_activity_created_at:desc.nullsLast

Use case: reading recent activity for one contact. Replace this request with GET /v1/conversation-events?contact=<contact_id>&limit=<limit> when you need activity changes. If you only need the current conversations for that contact, use GET /v1/conversations?contact=<contact_id>&limit=<limit>.

API references:List Conversation Events List Conversations

GET/api/v1/conversation filters=contact_id.eq.? order=latest_activity_created_at:desc.nullsLast

Use case: reading recent activity for one contact. Replace this request with GET /v1/conversation-events?contact=<contact_id> when you need activity changes. If you only need the current conversations for that contact, use GET /v1/conversations?contact=<contact_id>.

API references:List Conversation Events List Conversations

GET/api/v1/conversation filters=created_at.gt.?,status.eq.?,unread.eq.? limit=?

Use case: finding recent conversation activity for conversations with a status/unread condition. Use GET /v1/conversation-events?created_at[gt]=<timestamp>&limit=<limit> for activity polling, then fetch or filter conversations by status and unread state as needed with GET /v1/conversations?status=<status>&unread=<unread>.

API references:List Conversation Events List Conversations

GET/api/v1/conversation filters=external_id.eq.?

Use case: listing conversations. Replace this request with GET /v1/conversations?external_id=<external_id>.

API reference:List Conversations

GET/api/v1/conversation filters=id.eq.?

Use case: reading one conversation by id. Replace this request with GET /v1/conversations/{conversation_id}.

API reference:Get Conversation

GET

/api/v1/conversation filters=latest_inbound_message_created_at.gte.?,latest_inbound_message_created_at.lte.? limit=? offset=?

Use case: polling inbound conversation activity within a time window. Replace this with GET /v1/conversation-events?type=message.received&created_at[gte]=<start>&created_at[lte]=<end>&limit=<limit> when inbound message events cover your use case; use page_token for additional pages instead of offset.

API references:List Conversation Events Pagination

GET/api/v1/conversation filters=latest_message_created_at.gt.?

Use case: polling conversation activity after a message timestamp. Replace this with GET /v1/conversation-events?created_at[gt]=<timestamp> when the activity stream covers your use case; if you specifically need latest-message filtering, reach out to us.

API reference:List Conversation Events

GET/api/v1/conversation filters=latest_message_created_at.gt.? limit=? offset=?

Use case: polling conversation activity after a message timestamp. Replace this with GET /v1/conversation-events?created_at[gt]=<timestamp>&limit=<limit> when the activity stream covers your use case; if you specifically need latest-message filtering, reach out to us. Use page_token for additional pages instead of offset.

API references:List Conversation Events Pagination

GET/api/v1/conversation filters=unread.eq.?

Use case: listing conversations by unread state. Replace this request with GET /v1/conversations?unread=<unread>.

API reference:List Conversations

GET/api/v1/conversation filters=unread.eq.? limit=?

Use case: listing conversations. Replace this request with GET /v1/conversations?unread=<unread>&limit=<limit>.

API reference:List Conversations

GET

/api/v1/conversation joins=contact_id!inner,message!message_conversation_id_fkey!inner filters=contact_id.whatsapp.eq.?,message.status.eq.?

We are working on public API support for this request pattern. If this request is important for your migration, contact us with your use case.

GET/api/v1/conversation joins=contact!conversation_contact_id_fkey!inner filters=contact.external_id.eq.?,unread.is.?

Use case: listing conversations for a contact external id and unread state, together with contact data. Replace this request with GET /v1/conversations?contact_external_id=<external_id>&unread=<unread>&include=contact.

API reference:List Conversations

GET/api/v1/conversation joins=contact!conversation_contact_id_fkey!inner filters=unread.is.?

Use case: listing conversations by unread state together with contact data. Replace this request with GET /v1/conversations?unread=<unread>&include=contact.

API reference:List Conversations

GET/api/v1/conversation joins=contact!inner filters=channel_id.eq.?,contact.id.eq.?

Use case: listing conversations for one channel and contact, together with contact data. Replace this request with GET /v1/conversations?channel=<channel_id>&contact=<contact_id>&include=contact.

API reference:List Conversations

GET/api/v1/conversation joins=contact!inner(contact_custom_field) filters=id.eq.?

We are working on public API support for this request pattern. If this request is important for your migration, contact us with your use case.

GET/api/v1/conversation limit=?

Use case: listing conversations. Replace this request with GET /v1/conversations?limit=<limit>.

API reference:List Conversations

GET/api/v1/conversation_tag filters=conversation_id.eq.?

Use case: reading tags for one conversation. Replace this request with GET /v1/conversations/{conversation_id}?include=tags.

API reference:Get Conversation

GET/api/v1/conversation_tag filters=tag_id.in.? limit=? offset=?

Use case: listing conversations with a tag. Replace this request with GET /v1/conversations?tag=<tag_id>&limit=<limit>; use page_token for additional pages instead of offset.

API references:List Conversations Pagination

GET/api/v1/conversation_tag filters=tag_id.in.?,updated_at.gt.? limit=? offset=?

Use case: syncing conversation tag changes after a timestamp. Replace this with GET /v1/conversation-events?type[in]=conversation.tag_added,conversation.tag_removed&created_at[gt]=<timestamp>&limit=<limit>, then filter the returned tag resources to the tag ids you care about. Use page_token for additional pages instead of offset.

API references:List Conversation Events Pagination

GET/api/v1/conversation_tag joins=tag_id filters=conversation_id.eq.?,tag_id.name.eq.?

Use case: checking whether one conversation has a named tag. Resolve the tag with GET /v1/tags, then fetch the conversation with GET /v1/conversations/{conversation_id}?include=tags and check the included tags client-side.

API references:List Tags Get Conversation

GET/api/v1/event filters=conversation_id.eq.?,created_at.lte.?,type.eq.? limit=? order=created_at:desc.nullsLast

Use case: listing conversation activity events. Replace this request with GET /v1/conversation-events?conversation=<conversation_id>&type=<new_event_type>&created_at[lte]=<timestamp>&limit=<limit>. Map old event types to new API event types before sending type: assign→conversation.assigned, unassign→conversation.unassigned, close→conversation.closed, reopen→conversation.reopened, inbox_change→conversation.inbox_changed, tag→conversation.tag_added, untag→conversation.tag_removed, inbound→message.received, outbound→message.sent, sending_error→message.sending_failed, message_bounce_error→message.delivery_failed, comment→comment.created, action_click→message_action.clicked.

API reference:List Conversation Events

GET/api/v1/event filters=conversation_id.eq.?,type.eq.? limit=? order=created_at:desc.nullsLast

Use case: listing conversation activity events. Replace this request with GET /v1/conversation-events?conversation=<conversation_id>&type=<new_event_type>&limit=<limit>. Map old event types to new API event types before sending type: assign→conversation.assigned, unassign→conversation.unassigned, close→conversation.closed, reopen→conversation.reopened, inbox_change→conversation.inbox_changed, tag→conversation.tag_added, untag→conversation.tag_removed, inbound→message.received, outbound→message.sent, sending_error→message.sending_failed, message_bounce_error→message.delivery_failed, comment→comment.created, action_click→message_action.clicked.

API reference:List Conversation Events

GET/api/v1/event filters=created_at.gt.?,type.eq.? offset=?

Use case: listing conversation activity events. Replace this request with GET /v1/conversation-events?type=<new_event_type>&created_at[gt]=<timestamp>; map old event types to new API event types before sending type: assign→conversation.assigned, unassign→conversation.unassigned, close→conversation.closed, reopen→conversation.reopened, inbox_change→conversation.inbox_changed, tag→conversation.tag_added, untag→conversation.tag_removed, inbound→message.received, outbound→message.sent, sending_error→message.sending_failed, message_bounce_error→message.delivery_failed, comment→comment.created, action_click→message_action.clicked. Use page_token for additional pages instead of offset.

API references:List Conversation Events Pagination

GET/api/v1/event joins=conversation filters=conversation_id.eq.?,type.eq.? limit=? order=created_at:desc.nullsLast

Use case: listing conversation activity events. Replace this request with GET /v1/conversation-events?conversation=<conversation_id>&type=<new_event_type>&limit=<limit>. Map old event types to new API event types: assign→conversation.assigned, unassign→conversation.unassigned, close→conversation.closed, reopen→conversation.reopened, inbox_change→conversation.inbox_changed, tag→conversation.tag_added, untag→conversation.tag_removed, inbound→message.received, outbound→message.sent, sending_error→message.sending_failed, message_bounce_error→message.delivery_failed, comment→comment.created, action_click→message_action.clicked.

API reference:List Conversation Events

GET/api/v1/message filters=author_type.eq.?,conversation_id.eq.? order=timestamp:desc.nullsLast

We are working on public API support for this request pattern. If this request is important for your migration, contact us with your use case.

GET/api/v1/message filters=contacts.neq.? limit=? offset=? order=timestamp:desc.nullsLast

We are working on public API support for this request pattern. If this request is important for your migration, contact us with your use case.

GET/api/v1/message filters=contacts.not.is.? limit=? offset=? order=timestamp:desc.nullsLast

We are working on public API support for this request pattern. If this request is important for your migration, contact us with your use case.

GET/api/v1/message filters=contacts.not.is.? order=timestamp:desc.nullsLast

We are working on public API support for this request pattern. If this request is important for your migration, contact us with your use case.

GET/api/v1/message filters=conversation_id.eq.? limit=? order=timestamp:desc.nullsLast

Use case: listing messages. Replace this request with GET /v1/messages?conversation=<conversation_id>&limit=<limit>.

API reference:List Messages

GET/api/v1/message filters=conversation_id.eq.?,created_at.gte.? order=timestamp:desc.nullsLast

Use case: listing messages in one conversation after a timestamp. Replace the legacy created_at filter with the message timestamp filter: GET /v1/messages?conversation=<conversation_id>&timestamp[gte]=<timestamp>.

API reference:List Messages

GET/api/v1/message filters=conversation_id.eq.?,created_at.lte.?

Use case: listing messages in one conversation before a timestamp. Replace the legacy created_at filter with the message timestamp filter: GET /v1/messages?conversation=<conversation_id>&timestamp[lte]=<timestamp>.

API reference:List Messages

GET/api/v1/message filters=conversation_id.eq.?,status.eq.?

Use case: listing messages. Replace this request with GET /v1/messages?conversation=<conversation_id>&status=<status>.

API reference:List Messages

GET/api/v1/message filters=conversation_id.eq.?,status.eq.?,template_id.eq.?

Use case: listing messages. Replace this request with GET /v1/messages?conversation=<conversation_id>&status=<status>&template=<template_id>.

API reference:List Messages

GET/api/v1/message filters=conversation_id.eq.?,timestamp.gte.? limit=? order=timestamp:desc.nullsLast

Use case: listing messages. Replace this request with GET /v1/messages?conversation=<conversation_id>&timestamp[gte]=<timestamp>&limit=<limit>.

API reference:List Messages

GET/api/v1/message filters=conversation_id.eq.?,timestamp.gte.? order=timestamp:asc.nullsLast

Use case: listing messages. Replace this request with GET /v1/messages?conversation=<conversation_id>&timestamp[gte]=<timestamp>.

API reference:List Messages

GET/api/v1/message filters=conversation_id.eq.?,updated_at.gte.?,updated_at.lte.?

Use case: listing messages in one conversation within a time window. Replace the legacy updated_at filters with message timestamp filters: GET /v1/messages?conversation=<conversation_id>&timestamp[gte]=<start>&timestamp[lte]=<end>.

API reference:List Messages

GET/api/v1/message filters=created_at.gte.?,is_inbound.eq.?,status.in.?

Use case: listing messages after a timestamp by direction and status. Replace the legacy created_at filter with the message timestamp filter: GET /v1/messages?timestamp[gte]=<timestamp>&is_inbound=<true_or_false>&status[in]=<statuses>.

API reference:List Messages

GET/api/v1/message filters=id.eq.?

Use case: reading one message by id. Replace this request with GET /v1/messages/{id}.

API reference:Get Message

GET/api/v1/message filters=id.in.?

Use case: listing messages. Replace this request with GET /v1/messages?id[in]=<message_ids>.

API reference:List Messages

GET/api/v1/message filters=timestamp.gte.? limit=? offset=? order=timestamp:desc.nullsLast

Use case: listing messages. Replace this request with GET /v1/messages?timestamp[gte]=<timestamp>&limit=<limit>; use page_token for additional pages instead of offset.

API references:List Messages Pagination

GET/api/v1/message joins=conversation limit=? offset=? order=timestamp:desc.nullsLast

Use case: listing messages. Replace this request with GET /v1/messages?limit=<limit>&include=conversation; use page_token for additional pages instead of offset.

API references:List Messages Pagination

GET/api/v1/message joins=conversation_id filters=template_id.eq.?,updated_at.gt.? limit=? offset=?

Use case: listing messages for a template after a timestamp. Replace the legacy updated_at filter with the message timestamp filter: GET /v1/messages?template=<template_id>&timestamp[gt]=<timestamp>&limit=<limit>&include=conversation; use page_token for additional pages instead of offset.

API references:List Messages Pagination

GET

/api/v1/message joins=conversation_id(contact_id) filters=author_type.eq.?,created_at.gt.?,is_inbound.eq.? limit=? offset=?

We are working on public API support for this request pattern. If this request is important for your migration, contact us with your use case.

GET/api/v1/message joins=conversation_id(contact_id) filters=campaign_id.eq.?

Use case: listing messages. Replace this request with GET /v1/messages?campaign=<campaign_id>&include=conversation.

API reference:List Messages

GET/api/v1/message joins=conversation_id(contact_id) filters=created_at.gt.?,is_inbound.eq.? limit=? offset=?

Use case: listing inbound or outbound messages after a timestamp. Replace the legacy created_at filter with the message timestamp filter: GET /v1/messages?timestamp[gt]=<timestamp>&is_inbound=<true_or_false>&limit=<limit>&include=conversation; use page_token for additional pages instead of offset.

API references:List Messages Pagination

GET

/api/v1/message joins=conversation_id(contact_id),employee filters=created_at.gt.?,created_at.lt.?,is_inbound.eq.? limit=? offset=? order=timestamp:asc.nullsLast

Use case: listing inbound or outbound messages in a time range with conversation details. Replace created_at filters with message timestamp filters and use GET /v1/messages?timestamp[gt]=<start>&timestamp[lt]=<end>&is_inbound=<true_or_false>&limit=<limit>&include=conversation; use page_token for additional pages instead of offset. Retrieve employee details separately when needed.

API references:List Messages Pagination

GET

/api/v1/message joins=conversation!message_conversation_id_fkey,message_action!message_action_message_id_fkey,recipient filters=channel_id.in.?,channel_type.eq.?,timestamp.gte.? limit=? offset=? order=timestamp:desc.nullsLast

We are working on public API support for this request pattern. If this request is important for your migration, contact us with your use case.

GET

/api/v1/message joins=message_action!message_action_message_id_fkey,recipient filters=channel_id.in.?,channel_type.eq.?,timestamp.gte.? limit=? offset=? order=timestamp:desc.nullsLast

We are working on public API support for this request pattern. If this request is important for your migration, contact us with your use case.

GET/api/v1/message limit=?

Use case: listing messages. Replace this request with GET /v1/messages?limit=<limit>.

API reference:List Messages

GET/api/v1/message limit=? offset=? order=timestamp:desc.nullsLast

Use case: listing messages. Replace this request with GET /v1/messages?limit=<limit>; use page_token for additional pages instead of offset.

API references:List Messages Pagination

GET/api/v1/message limit=? order=timestamp:desc.nullsLast

Use case: listing messages. Replace this request with GET /v1/messages?limit=<limit>.

API reference:List Messages

GET/api/v1/message order=timestamp:desc.nullsLast

Use case: listing messages. Replace this request with GET /v1/messages.

API reference:List Messages

GET/api/v1/message_action filters=clicked.eq.?,type.eq.?,updated_at.gte.? limit=? offset=? order=updated_at:asc.nullsLast

Use case: tracking recently clicked message actions. Replace this request with GET /v1/conversation-events?type=message_action.clicked&created_at[gte]=<last_seen_created_at>&limit=<limit>; use page_token and created_at for pagination instead of message_action.updated_at.

API references:List Conversation Events Pagination

GET/api/v1/provider

We are working on public API support for this request pattern. If this request is important for your migration, contact us with your use case.

GET/api/v1/provider_template_approval filters=template_id.in.?

We are working on public API support for this request pattern. If this request is important for your migration, contact us with your use case.

GET/api/v1/provider_template_approval joins=template!inner filters=provider_id.eq.?,template.type.eq.?

We are working on public API support for this request pattern. If this request is important for your migration, contact us with your use case.

GET/api/v1/recipient filters=handle.eq.?

We are working on public API support for this request pattern. If this request is important for your migration, contact us with your use case.

GET/api/v1/tag limit=? offset=? order=name:desc.nullsLast

Use case: listing tags. Replace this request with GET /v1/tags?limit=<limit>; use page_token for additional pages instead of offset.

API references:List Tags Pagination

GET/api/v1/template filters=id.eq.?

We are working on public API support for this request pattern. If this request is important for your migration, contact us with your use case.

GET/api/v1/template filters=id.eq.? limit=? offset=? order=name:desc.nullsLast

We are working on public API support for this request pattern. If this request is important for your migration, contact us with your use case.

GET/api/v1/template filters=whatsapp_status.eq.?

We are working on public API support for this request pattern. If this request is important for your migration, contact us with your use case.

GET/api/v1/template limit=? offset=? order=name:desc.nullsLast

We are working on public API support for this request pattern. If this request is important for your migration, contact us with your use case.

GET/api/v1/template limit=? order=name:desc.nullsLast

We are working on public API support for this request pattern. If this request is important for your migration, contact us with your use case.

POST/api/v1/comment

Use case: creating a comment in one conversation. Replace this request with POST /v1/conversations/{conversation_id}/comments.

API reference:Create Comment

POST/api/v1/conversation_tag

Use case: adding a tag to one conversation. Replace this request with PUT /v1/conversations/{conversation_id}/tags/{tag_id}.

API reference:Tag Conversation

POST/api/v1/send_message

Use case: sending a message. Replace this request with POST /v1/messages/send.

API reference:Send Message

POST/api/v1/template

We are working on public API support for this request pattern. If this request is important for your migration, contact us with your use case.

PATCH/api/v1/conversation filters=id.eq.?

Use case: changing one conversation state. Replace inbox_id with POST /v1/conversations/{conversation_id}/move, assignee_id with assign or unassign, and status with open or close.

API references:Move Conversation Assign Conversation Unassign Conversation Open Conversation Close Conversation

DELETE/api/v1/conversation_tag filters=conversation_id.eq.?,tag_id.eq.?

Use case: removing a tag from one conversation. Replace this request with DELETE /v1/conversations/{conversation_id}/tags/{tag_id}.

API reference:Untag Conversation

DELETE/api/v1/message filters=id.eq.?

Use case: deleting one message by id. Replace this request with DELETE /v1/messages/{message_id}.

API reference:Delete Message

DELETE/api/v1/message filters=id.eq.?,status.eq.?

Use case: deleting one message only when it has a specific status. Replace this request by first checking GET /v1/messages/{id}, then inspect the returned status client-side and call DELETE /v1/messages/{message_id} only if it matches.

API references:Get Message Delete Message

DELETE/api/v1/template filters=id.eq.?

We are working on public API support for this request pattern. If this request is important for your migration, contact us with your use case.

Scheduling

GET/api/v1/location

Use case: listing locations. Replace this request with GET /v1/locations.

API reference:List Locations

Sendouts

GET/api/v1/campaign filters=and.(last_sendout_date.gte.1969-12-31T23:00,or(status.eq.?

We are working on public API support for this request pattern. If this request is important for your migration, contact us with your use case.

Subscriptions

GET/api/v1/marketing_channel filters=organisation_id.eq.?

We are working on public API support for this request pattern. If this request is important for your migration, contact us with your use case.

GET/api/v1/marketing_subscription

Use case: listing subscription state. Replace this request with GET /v1/subscriptions.

API reference:List Subscriptions

GET/api/v1/marketing_subscription filters=created_at.gt.?

Use case: syncing subscription changes after a timestamp. This history-style subscription sync use case will be covered by the upcoming audit log endpoint rather than by a subscription list filter.

GET/api/v1/marketing_subscription filters=status.eq.?,updated_at.gte.?

Use case: syncing subscription changes after a timestamp. This history-style subscription sync use case will be covered by the upcoming audit log endpoint rather than by a subscription list filter.

GET/api/v1/marketing_subscription filters=updated_at.gt.? offset=?

Use case: syncing subscription changes after a timestamp. This history-style subscription sync use case will be covered by the upcoming audit log endpoint rather than by a subscription list filter. Use page_token rather than offset when migrating adjacent list pagination.

API reference:Pagination

GET/api/v1/marketing_subscription joins=contact

Use case: listing subscription state together with the related contact. Replace this request with GET /v1/subscriptions?include=contact.

API reference:List Subscriptions

GET/api/v1/marketing_subscription joins=contact filters=channel_type.eq.?,created_at.gt.?,status.eq.? limit=?

Use case: syncing subscription changes after a timestamp. This history-style subscription sync use case will be covered by the upcoming audit log endpoint rather than by a subscription list filter.

GET/api/v1/marketing_subscription joins=contact filters=status.in.?,updated_at.gt.?

Use case: syncing subscription changes after a timestamp. This history-style subscription sync use case will be covered by the upcoming audit log endpoint rather than by a subscription list filter.

GET/api/v1/marketing_subscription joins=contact filters=status.neq.?,updated_at.gt.? offset=?

API reference:Pagination

GET/api/v1/marketing_subscription joins=contact limit=?

Use case: listing subscription state together with the related contact. Replace this request with GET /v1/subscriptions?limit=<limit>&include=contact.

API reference:List Subscriptions

GET/api/v1/marketing_subscription joins=contact limit=? offset=?

Use case: listing subscription state together with the related contact. Replace this request with GET /v1/subscriptions?limit=<limit>&include=contact; use page_token for additional pages instead of offset.

API references:List Subscriptions Pagination

GET/api/v1/marketing_subscription joins=contact offset=?

Use case: listing subscription state together with the related contact. Replace this request with GET /v1/subscriptions?include=contact; use page_token for additional pages instead of offset.

API references:List Subscriptions Pagination

GET/api/v1/marketing_subscription joins=contact_id filters=updated_at.gt.?

Use case: syncing subscription changes after a timestamp. This history-style subscription sync use case will be covered by the upcoming audit log endpoint rather than by a subscription list filter.

GET

/api/v1/marketing_subscription joins=contact!inner filters=channel_type.eq.?,contact.external_id.not.is.?,status.in.?,updated_at.gt.?

Use case: syncing subscription changes after a timestamp. This history-style subscription sync use case will be covered by the upcoming audit log endpoint rather than by a subscription list filter.

GET/api/v1/marketing_subscription limit=?

Use case: listing subscription state. Replace this request with GET /v1/subscriptions?limit=<limit>.

API reference:List Subscriptions

GET/api/v1/marketing_subscription offset=?

Use case: listing subscription state. Replace this request with GET /v1/subscriptions; use page_token for additional pages instead of offset.

API references:List Subscriptions Pagination

Webhooks

GET/api/v1/webhook

Use case: listing webhooks. Replace this request with GET /v1/webhooks.

API reference:List Webhooks

POST/api/v1/webhook

Use case: creating a webhook. Replace this request with POST /v1/webhooks.

API reference:Create Webhook

DELETE/api/v1/webhook filters=id.eq.?

Use case: deleting one webhook by id. Replace this request with DELETE /v1/webhooks/{id}.

API reference:Delete Webhook

Legacy API migration guide

Rollout expectations

What changes in the new API

Base URL and versioning

Authentication

Filtering and lookups

Writes and deletes

Errors and request IDs

Request-specific migration guide

Appointments

Contact Lists

Contacts

Custom Fields

Deals

Employees

Files

Formatting

Identity

Imports

Journeys

Messaging

Scheduling

Sendouts

Subscriptions

Webhooks

On this page