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.

Import duration is not fixed. Import jobs share processing capacity across accounts, so completion time depends on the current load and on how many additional fields must be created or updated. Contact imports run independently from campaign sending and message template editing, so you can continue these activities while an import is being processed.

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.

❗️

Important

Before sending specific contact data to eSputnik in any way, you must create corresponding additional fields in your account.

📘

Note

Use an external ID as the primary contact identifier to prevent data duplication when creating and updating contacts.

File Uploading

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

📘

Note

The file can also be downloaded in XLS, XLSX, and TXT formats.

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.

You can also import contacts via the Get Started section.

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 eSputnik 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 Get contact import status.
• When updating the mobilepush channel, pass the device object with at least the os field. Without it, the token may fail sending after the update.
• If the request doesn't specify contactFields, all contact fields are updated — including the ones you didn't send, which are written with null. To update only some fields, list them in contactFields.
• To remove the email channel using Add/update contacts, include email in contactFields and omit the email channel from the contact's channels array.

📘

Note

The API returns no explicit flag telling you that a contact is deleted — the response of the bulk method contains only the session identifier. The indirect signal is the mapping field of the import status: it lists only the contacts that were created or updated. If restoreDeleted is false and a contact from the request is missing from mapping, that contact exists in the account in the deleted state and was skipped. Send the same request with "restoreDeleted": true to restore and update it.

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

URL to send request: https://api.esputnik.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.

For a one-off import of around 60,000 contacts via the bulk API, no special timing or throttling is needed — processing is asynchronous, so a larger batch simply takes longer to complete rather than requiring a different approach.

If your integration already knows which contacts changed in an external segment, update a contact field or group membership during the import instead of querying every segment back from eSputnik to find those changes.

An example of a request body:

{
  "contacts": [
    {
      "channels": [
        {
          "type": "email",
          "value": "[email protected]"
        },
        {
          "type": "sms",
          "value": "380942583691"
        },
        {
          "type": "mobilepush",
          "value": "8900-7654-6456-9876-0011",
          "device": {
            "appId": "83b77a49-fc28-409b-aeaa-68c9d544ab9d",
            "deviceModel": "iPhone 13",
            "os": "iOS",
            "appVersion": "4.1.6"
          }
        }
      ],
      "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"
}