> ## 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 Import

> Learn how to efficiently import contacts into Hellomateo.

Let us assume you have 50.000 contacts in your ERP system, and you want to import them into Hellomateo. You can do this either via the CSV upload within the Hellomateo Web App, or via the API. This guide will show you how to import contacts using the API.

To not hit rate-limits, we we recommend using the [Import API](/api-reference/import/post-import) to import contacts in batches. An import is a simple entity that is defined by a `type` and a `payload`. The `type` defines what data you are importing, and the `payload` is the actual data you are importing.

To import contact data including custom fields and marketing subscriptions, you can use the following payload:

```json theme={null}
{
  "type": "contact_details",
  "payload": [
    {
      "external_id": "1",
      "email": "my@contact.com",
      "my_custom_field_key": "my_custom_field_value",
      "my_marketing_channel_key": "accepted"
    },
    {
      "external_id": "2",
      "email": "another@contact.com",
      "my_custom_field_key": "another_custom_field_value",
      "my_marketing_channel_key": "declined"
    }
  ]
}
```

If you are integrating with an external ERP or CRM system, you can use the `external_id` to store the ID of the contact from the external system directly within Hellomateo. This way, you do not need to keep track of the Hellomateo `id`.

Note that the `external_id`, and all handles (`whatsapp`, `email`, `sms`, etc) are unique identifiers for the contact. If you import a contact with the same value multiple times, the contact will be updated with the new data.

## Working with Datetime Data

When importing contacts with datetime fields, always send datetime values in **ISO 8601 format with timezone information** to ensure data accuracy.

### Required Format

Use the format: `YYYY-MM-DDTHH:mm:ss±HH:mm` or `YYYY-MM-DDTHH:mm:ssZ`

**Examples:**

```json theme={null}
{
  "type": "contact_details",
  "payload": [
    {
      "external_id": "1",
      "email": "my@contact.com",
      "birthday": "1990-05-15T00:00:00Z",
      "last_contacted_at": "2024-03-15T14:30:00+01:00"
    }
  ]
}
```

### Default Timezone

If no timezone is provided, **the system defaults to UTC**. However, always include timezone information explicitly to avoid ambiguity and potential data errors.

**Avoid:**

```
"last_contacted_at": "2024-03-15T14:30:00"  // ambiguous - will be interpreted as UTC
```

**Prefer:**

```
"last_contacted_at": "2024-03-15T14:30:00Z"  // explicit UTC
```

The request then imports a job that is processed **in the background**. We do not give any guarantee on the processing time, but you can check the status of the import job by calling the [Get Import API](/api-reference/get-import) with the `id` of the import job that was returned in the response of the `Post Import API`. Make sure to `select` the `id` of the import job when you create the import job.

```bash theme={null}
curl "https://integration.getmateo.com/api/v1/import?select=id" \
 -X POST -H "Content-Type: application/json" \
 -d '[ ... the payload ... ]'
```

```bash theme={null}
HTTP/1.1 201 Created
```

```json theme={null}
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
```

When the import is completed, you will find its result in the response of the [Get Import API](/api-reference/get-import).

```json theme={null}
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "total_count": 10,
  "success_count": 9,
  "failed_count": 1,
  "failed": [
    {
      "code": "23514",
      "message": "duplicate key value violates unique constraint \"unique_email\"",
      "input": {
        "external_id": "2",
        "email": "another@contact.com",
        "my_custom_field_key": "another_custom_field_value",
        "my_marketing_channel_key": "declined"
      }
    }
  ]
}
```

In this example, 10 contacts were imported, 9 were successful, and 1 failed due to a duplicate email address. The failed contacts are returned in the `failed` array with the reason why they failed.

There is a limit to the number of contacts you can import on a single day. Consult the [Limits](/limits) page for more information. If you need to import more contacts, please contact our support team.