Skip to main content
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 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: 
{
  "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: 
{
  "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 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. 
curl "https://integration.getmateo.com/api/v1/import?select=id" \
 -X POST -H "Content-Type: application/json" \
 -d '[ ... the payload ... ]'

HTTP/1.1 201 Created

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
When the import is completed, you will find its result in the response of the Get Import API. 
{
  "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 page for more information. If you need to import more contacts, please contact our support team.