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.

❗️

Important

Before sending specific contact data to Yespo 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.

👍

Recommendation

Import your contacts via 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 Yespo 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.yespo.io/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.

📘

Note

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 Yespo to find those changes.

📘

Note

A one-off bulk import of tens of thousands of contacts (for example, around 60,000) doesn't need special timing or off-hours scheduling — processing is asynchronous, so it just takes correspondingly longer at that scale rather than requiring any different handling.

🚧

Don't fire a dependent send at the same time

Because v1/contacts is asynchronous, don't trigger a dependent Send prepared message (smartsend) call simultaneously with the import — wait for it or verify the result first, for example through asyncSessionId and the import status method.

A stable externalCustomerId is the most reliable identifier for matching the contact afterwards.

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"
}