Skip to main content

Create Contacts Import

POST 
/mailinglists/:mailingListId/contactimports
deprecated

This endpoint has been deprecated and may be replaced or removed in future versions of the API.

Deprecation Notice

This API is deprecated. As of June 30, 2026 it will no longer be actively supported and will be removed thereafter. Please migrate to a supported alternative. See the Research Core to XM Directory migration guide for migration steps.

Customers with an approved extension should follow their agreed migration timeline.

Imports contacts into a mailing list via JSON in the request body, a JSON file upload, or a JSON file at a reachable URL.

This API call is not supported for XM Directory users.
The JSON content (in a file or the request body) size is limited to 5MB or 8500 contacts

If the file is larger than 5 MB, or has more than 8500 contacts, the import will fail. If more contacts need to be imported, they should be imported with subsequent calls.

You can import contacts three different ways using this endpoint:

  1. Using the application/json content type, add your contacts object to the raw data of the request
  2. Using the application/json content type, add your binary file with your contacts object to the data of the request
  3. Using the multipart/form-data content type supply the URL location of the file
    • NOTE: Unlike the first content type, when uploading from a URL, your file should have a single array of contact objects (shown below).

This API request requires a JSON array of JSON objects - where each object represents one mailing list contact. If you are including the contacts in the request body (1 and 2 above), then your JSON array must be contained within a contacts JSON object. As mentioned above, this JSON array can be provided in a JSON file. If this file is hosted at a URL, then the JSON array of contacts should be within an unwrapped JSON array.

Each contact object accepts the following optional fields: id, firstName, lastName, email, unsubscribed, externalReference, and embeddedData. The embeddedData field consists of keys and values defined by you, for your purposes.

Example JSON array:

In the request body
 
/* Remove all comments before testing*/
{
  "contacts":
  [
    {
      "id": "MLRP_ABC1234567", /* If included, the contact with this id will be updated. */
      "firstName": "First",
      "lastName": "Last",
      "email": "firstlast@example.com",
      "unsubscribed": 0,
      "externalReference": "Example",
      "embeddedData": {
        "ExampleField1": "example_field_val_1",
        "ExampleField2": "example_field_val_2"
      }
    },
    {
      ... # add more contacts within this JSON
    }
  ]
}
Hosted at a URL
 
/* Remove all comments before testing*/
[
  {
    "id": "MLRP_ABC1234567", /* If included, the contact with this id will be updated. */
    "firstName": "First",
    "lastName": "Last",
    "email": "firstlast@example.com",
    "unsubscribed": 0,
    "externalReference": "Example",
    "embeddedData": {
      "ExampleField1": "example_field_val_1",
      "ExampleField2": "example_field_val_2"
    }
  },
  {
    ... # add more contacts within this JSON
  }
]

This call will return an importId that can be used to check on the status of the import via Get Contacts Import Progress.

Only explicit mode is supported for FTPS

To illustrate the differences between the three ways of calling this endpoint, simple cURL examples of each type of call are below:

  • NOTE: If you provide a contact's ID, as in the examples below, then that contact will receive an update with the information you send. To create a contact, leave the "id" off the contact object.
In the request body as raw data of content type application/json

curl 'https://co1.qualtrics.com/API/v3/mailinglists/CG_er1pwJbK9BZuxo1/contactimports' \
-X 'POST'  \
-H 'X-API-TOKEN: <API Token>' \
-H 'Content-Type: application/json' \
-d '{
  "contacts": [
    {
      "id": "MLRP_ABC1234567", 
      "firstName": "First",
      "lastName": "Last",
      "email": "firstlast@example.com",
      "unsubscribed": 0,
      "externalReference": "Example",
      "embeddedData": {
        "ExampleField1": "example_field_val_1",
        "ExampleField2": "example_field_val_2"
      }
    },
    {
      ... # add more contacts within this JSON
    }
  ]
}'
In the request body as raw data of content type application/json

curl -X POST -H 'X-API-TOKEN: <API Token>' \
-H "Content-Type: application/json" \
--data @/docs/public-api/contacts/contacts/ \ 'https://co1.qualtrics.com/API/v3/mailinglists/CG_6F1gRt186CZOVoh/contactimports'
Provided by a URL and sending request with content type multipart/form-data

curl 'https://yourdatacenterid.qualtrics.com/API/v3/mailinglists/ML_123456789/contactimports' \
-X POST \
-H 'X-API-TOKEN: <API Token>' \
-F 'contentType=application/json' \
-F 'fileUrl=https://www.example.com/example.json'

Request​

Responses​

A successful Create Contacts Import response