Sign in

v1

latestSwagger 2.0Private2026-08-04128286690.5 KB
Bulk Activities

Import Contacts using a CSV File

This multipart method creates an asynchronous background job that adds or updates contacts by importing a CSV file containing contact information. Do not use a Content-Type header value with this method.

Importing a new contact email address automatically sets the contact's permission_to_send property as implicit and the opt_in_source property as Account. Importing an existing contact only updates the contact properties you include in the request. Importing contacts with sms_numbers requires using the sms_permission_to_send parameter to specify permissions for all contacts being imported. Set to explicit to specify that all contacts either provided explicit permission. Set to not_set if permission was not provided. If explicit, you must also include the sms_consent_date as a column header to include the date the contact consented to receiving SMS messages. Contacts must have either an email address or an SMS number defined.

The CSV file has a maximum of 40,000 lines including the header row (39,999 contacts) and a maximum file size of 4 megabytes (MB). Lines above the 40,000 line maximum are not processed. If the request body exceeds 4 MB, only the contacts contained in the first 4 MB are imported and the remaining data is dropped.

post/activities/contacts_file_import

Response

Request successful. Activity queued for processing.

activity_idstring uuid

Unique ID for the activity.

statestring

The state of the request:

<p><ul> <li>initialized - request has been received</li> <li>processing - request is being processed</li> <li>completed - job completed</li> <li>cancelled - request was cancelled</li> <li>failed - job failed to complete</li> <li>timed_out - the request timed out before completing"</li> </ul> </p>
started_atstring date-time

Timestamp showing when we began processing the activity request, in ISO-8601 format.

completed_atstring date-time

Timestamp showing when we completed processing the activity, in ISO-8601 format.

created_atstring date-time

Timestamp showing when we created the activity, in ISO-8601 format.

updated_atstring date-time

Timestamp showing when we last updated the activity, in ISO-8601 format.

source_file_namestring

Name of the file used for an file_import activity.

percent_doneinteger

Shows the percent done for an activity that we are still processing.

activity_errorsstring[]

Array of messages describing the errors that occurred.

Example response

{
  "activity_id": "86b90820-cc52-11ea-9dad-fa163e3d9194",
  "state": "initialized",
  "started_at": "2016-01-23T13:48:40.108Z",
  "completed_at": "2016-01-23T13:48:44.108Z",
  "created_at": "2016-01-23T13:48:44.108Z",
  "updated_at": "2016-01-23T13:48:44.108Z",
  "source_file_name": "2016-21-04-contact_import.xls",
  "percent_done": 75,
  "activity_errors": [
    "Message describing the error condition."
  ],
  "status": {
    "items_total_count": 87,
    "person_count": 20,
    "error_count": 1,
    "correctable_count": 1,
    "cannot_add_to_list_count": 1
  },
  "_links": {
    "self": {
      "href": "/v3/activities/04fe9a97-a579-43c5-bb1a-58ed29bf0a6a"
    }
  }
}