> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getmateo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Contact Sync

> Learn how to setup a (bi-directional) contact sync between Hellomateo and an external system.

Lets assume you have just imported 50.000 contacts into hellomateo using the [Contact Import](/recipes/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](/webhooks/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](/api-reference/contact/patch-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](/api-reference/contact-custom-field/get-contact_custom_field) to retrieve all values that have been updated since a certain timestamp for a specific custom field:

```bash theme={null}
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`:

```bash theme={null}
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](/concepts/resource-embedding) to filter on the `external_id` of the contact:

```bash theme={null}
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](/concepts/read) to only retrieve the data you need.

Similarly, you can query marketing subscriptions and contacts using the [Get Contact API](/api-reference/contact/get-contact) and the [Get Marketing Subscription API](/api-reference/marketing-subscription/get-marketing_subscription). For example, to get all whatsapp marketing subscriptions that have been updated:

```bash theme={null}
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](/concepts/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.