Bulk Contact Uploading

You can carry out bulk contact uploading in two ways:

• Upload a CSV file — initial import of contacts and segments from other systems.
• Backend API request (server-to-server) — an alternative way to import volume and complicated contact lists, when your database contains more than several million contacts or includes more than several dozen fields.

Let’s consider the process of bulk contact uploading.

Contact Card and Additional Fields

Understanding contact cards and additional fields before uploading a contact list is crucial because these elements form the backbone of user data management.

A contact card is a user profile that contains user identifiers (external ID, email, phone number, mobile, and push tokens), activity data, and attributes stored in additional fields.

Attributes represent extended information about your users: the number of completed lessons, viewed product category, used promo code, plan type, and so on.

File Uploading

You can upload a file in the CSV format in the Contacts → Import section.

The process of import is divided into three stages:

• File Preparation
• Field Mapping
• Import Parameters Settings

📘

Note

If contacts in your file are in the Deleted status, a plain re-import won't bring them back. In Import Parameters Settings, enable the Restore and update previously deleted contacts switcher before starting the import.

The same applies over the API. Sending an event that carries only an external ID is not a reliable way to restore a deleted contact. For deterministic restoration, call Add/update contacts with the same externalCustomerId and "restoreDeleted": true, including the channels and fields you need.

If a workflow has to send an email before the contact card is restored, pass the email address in the event and set ${emailAddress} explicitly as the recipient. Creation, restoration, and enrichment can be asynchronous, so add a delay and a Get contact block before checking contactId or field values.

Backend API

The Add/update contacts API method is used for bulk asynchronous contact creation and updating. One request allows you to add or update up to 3000 contacts, which are added or updated in Reteno within a few minutes.

Use the Add/update contacts method for initial imports and scheduled high-volume updates when changes can be processed asynchronously. For a single contact that must be updated immediately, use the Add/update a contact method.

Features:

• The response includes an asyncSessionId, which you can use to get the import status and contact IDs using the v1/import status/ method.

Method type: POST. The description of the method, fields, and request body format are available here.

URL to send request: https://api.reteno.com/api/v1/contacts

Batch Import vs. Individual Requests

When a scheduled sync updates many contacts every day, batch the changed contacts instead of sending one real-time request per contact. For example, a daily sync of 25,000 changed contacts would require 25,000 calls to the Add/update a contact method, but it can be sent as one CSV import job or split into bulk API batches of up to 3000 contacts per request.

To reduce API volume during a recurring contact sync:

1. Export only contacts whose data changed since the previous sync.
2. Include a stable identifier, such as an external ID, so existing contact cards are updated instead of duplicated.
3. Add only the fields, groups, and subscription data that need to be created or updated.
4. Upload the changes as a file import or send them through the Add/update contacts bulk API method.
5. Store the returned asyncSessionId and check the import status before treating the sync as completed.

An example of a request body:

{
  "contacts": [
    {
      "channels": [
        {
          "type": "email",
          "value": "[email protected]"
        },
        {
          "type": "sms",
          "value": "380942583691"
        }
      ],
      "firstName": "John",
      "lastName": "Smith",
      "address": {
        "town": "London",
        "region": "West",
        "address": "First str. 1",
        "postcode": "12345"
      },
      "fields": [
        {
          "id": 12345,
          "value": "..."
        }
      ]
    }
  ],
  "dedupeOn": "email",
  "customFieldsIDs": [
    12345
  ],
  "groupNames": [
    "Customers"
  ],
  "groupNamesExclude": [
    "Subscribers"
  ],
  "restoreDeleted": false,
  "eventKeyForNewContacts": "newContact"
}

To retrieve the IDs, keys, types, and allowed values of additional fields, use the Get additional fields method.