Lets assume you have just imported 50.000 contacts into hellomateo using the Contact Import recipe. You sent out your first campaigns and collected a lot of Marketing Opt-Ins - great! But you need these opt-ins to be reflected in your ERP or CRM system as well. This is where the Contact Sync comes into play.

In essence, there are two ways to sync contacts between Hellomateo and an external system:

  1. Push Sync: Hellomateo pushes contact updates to the external system via a webhook.
  2. Pull Sync: The external system pulls contact updates from Hellomateo via the API.

We recommend using the Push Sync, as it is more efficient and real-time. However, if you are not able to set up a webhook on your external system, you can use the Pull Sync.

To set up a Push Sync, you need to create a webhook in Hellomateo that sends contact updates to your external system. Learn how to set up and consume webhooks in the Setting up Webhooks guide. Upon receiving a webhook, you can use the external_id of the contact that is also part of the webhook payload to find and update the contact in your system. If the contact does not exist yet within the external system, the external_id will be null and you can create it instead. Make sure to update the contact in Hellomateo with the external_id of the contact in your system after it has been created.

The Pull Sync is a bit more complex, as you need to periodically poll the Hellomateo API for changes. We recommend setting up a cron job that runs at least every night to fetch all contacts, marketing subscriptions, and custom fields from Hellomateo that were updated since the last run. You can then update the contacts in your system accordingly.

For example, you can use the Get Contact Custom Field API to retrieve all values that have been updated since a certain timestamp for a specific custom field:

curl "https://integration.getmateo.com/api/v1/contact_custom_field?select=key,value&updated_at=gte.2021-01-01T00:00:00Z&key=eq.my_custom_field_key"

If you are interested in just a single contact, you can filter on the contact_id:

curl "https://integration.getmateo.com/api/v1/contact_custom_field?select=key,value&contact_id=eq.1&updated_at=gte.2021-01-01T00:00:00Z&key=eq.my_custom_field_key"

If you just know the external_id of the contact, you can use Resource Embeddings to filter on the external_id of the contact:

curl "https://integration.getmateo.com/api/v1/contact_custom_field?select=key,value,contact!inner(external_id)&contact.external_id=eq.1&updated_at=gte.2021-01-01T00:00:00Z&key=eq.my_custom_field_key"

You can leverage all of the available filtering options to only retrieve the data you need.

Similarly, you can query marketing subscriptions and contacts using the Get Contact API and the Get Marketing Subscription API. For example, to get all whatsapp marketing subscriptions that have been updated:

curl "https://integration.getmateo.com/api/v1/marketing_subscription?select=key,value&updated_at=gte.2021-01-01T00:00:00Z&channel=eq.whatsapp"

Use pagination to retrieve the data in chunks. If you have a lot of contacts that are updated frequently, you might hit our rate limits. In this case, migrate to the Push Sync.