---
title: "Import Contacts using a JSON Payload"
method: POST
path: "/activities/contacts_json_import"
tags: ["Bulk Activities"]
---

# Import Contacts using a JSON Payload

`POST /activities/contacts_json_import`

Use this method to create an asynchronous background job that adds new contacts or updates existing contacts by importing a JSON payload. This method requires a request body that contains the contact data you are importing and the contact lists to which you want to add the imported contacts. A contact's data must include an `email` address and/or `sms_number`. The `sms_number` must be a US phone number to associate with the contact's SMS-enabled phone. Valid formats are <code>1231231234</code> or <code>123-123-1234</code> (the country code must be valid).

Importing a new contact using this method automatically sets the contact's email `permission_to_send` property to `implicit` and the `opt_in_source` property as `Account`. Importing an existing contact only updates the contact properties you include in the request. For each contact, you can import up to three addresses and three phone numbers. International phone numbers are currently not supported.      

To import custom fields, prefix the custom field name with `cf:` and add it as a contact property. For example, use the property name `cf:first_name` if you have a custom field named `first_name`. The custom field must already exist in the Constant Contact account you are using. Each contact can contain up to 25 custom fields.

To include a contact's `sms_number`, if the contact provided explicit permission to receive SMS messages, you must set the `sms_permission_to_send` property to `explicit` and specify the date of consent using the `sms_consent_date` column header. If explicit permission was not provided, set `sms_permission_to_send` to `not_set` (the `sms_consent_date` is not required). If the `sms_consent_date` is not set, SMS messages cannot be sent to contacts and `sms_permission_to_send` defaults to `not_set`. Valid value formats for `sms_consent_date` include MM/DD/YYYY, M/D/YYYY, YYYY/MM/DD, YYYY/M/D, YYYY-MM-DD, YYYY-M-D,M-D-YYYY, or M-DD-YYYY. 

The request body payload has a maximum size of 4 megabytes (MB). If the request body exceeds 4 MB, this method only imports the first 4 MB and drops the remaining data. Use the activity URL to check the status of the import activity request.

## Request body

- ContactsJsonImport
  - `import_data` JsonImportContact[], required — An array containing the contacts to import.
    - `email` string — The email address of the contact. This method identifies each unique contact using their email address. Required if `sms_number` is not specified.
    - `first_name` string — The first name of the contact.
    - `last_name` string — The last name of the contact.
    - `job_title` string — The job title of the contact.
    - `company_name` string — The name of the company where the contact works.
    - `birthday_month` integer — The month value for the contact's birthday. Valid values are from 1 through 12. The <code>birthday_month</code> property is required if you use <code>birthday_day</code>.
    - `birthday_day` integer — The day value for the contact's birthday. Valid values are from 1 through 31. The <code>birthday_day</code> property is required if you use <code>birthday_month</code>.
    - `anniversary` string — The anniversary date for the contact. For example, this value could be the date when the contact first became a customer of an organization in Constant Contact. Valid date formats are MM/DD/YYYY, M/D/YYYY, YYYY/MM/DD, YYYY/M/D, YYYY-MM-DD, YYYY-M-D,M-D-YYYY, or M-DD-YYYY.
    - `phone` string — The primary phone number for the contact. Use this field to add the default kind of phone number to the imported contact's phone number. Default <code>kind</code> is <code>other</code>.
    - `home_phone` string — The home phone number for the contact.
    - `work_phone` string — The work phone number for the contact.
    - `mobile_phone` string — The mobile phone number for the contact.
    - `other_phone` string — A phone number for the contact.
    - `street` string — Line one of the primary street address for the contact. Use this field to add the default kind of street to the imported contact's street address. The default <code>kind</code> is <code>home</code>. which maps to the <code>street_addresses</code> array` in the response.
    - `street2` string — Line two of the primary street address for the contact. This value is automatically appended to the <code>street</code> value. Use this field to add the default kind for line two of the street address to the imported contact's address. The default <code>kind</code> is <code>other</code>.
    - `city` string — The name of the primary city for the contact. Use this field to add the default kind of city to the imported contact's home address. The default <code>kind</code> is <code>home</code>.
    - `state` string — The name of the primary state or province for the contact. Use this field to add the default kind of state to the imported contact's home address. The default <code>kind</code> is <code>home</code>.
    - `zip` string — The zip or postal code associated with the contact's primary address. Use this field to add the default kind of zip to the imported contact's street address. The default <code>kind</code> is <code>home</code>.
    - `country` string — The name of the primary country where the contact is located. Use this field to add the default kind of country to the imported contact's street address. The default <code>kind</code> is <code>home</code>.
    - `home_street` string — Line one of the home street address for the contact.
    - `home_street2` string — Line two of the home street address for the contact. This value is automatically appended to the <code>home_street</code> value.
    - `home_city` string — The name of the city where the contact lives.
    - `home_state` string — The name of the home state or province where the contact lives.
    - `home_zip` string — The zip or postal code associated with the contact's home address.
    - `home country` string — The name of the country where the contact lives.
    - `work_street` string — Line one of the work street address for the contact.
    - `work_street2` string — Line two of the work street address for the contact. This value is automatically appended to the <code>work_street</code> value.
    - `work_city` string — The name of the city where the contact works.
    - `work_state` string — The name of the state or province where the contact works.
    - `work_zip` string — The zip or postal code associated with the contact's work address.
    - `work_country` string — The name of the country where the contact works.
    - `other_street` string — Line one of the other street address for the contact.
    - `other_street2` string — Line two of the other street address for the contact. This value is automatically appended to the <code>other_street</code> value.
    - `other_city` string — The name of another city where the contact is located.
    - `other_state` string — The name of another state or province where the contact is located.
    - `other_zip` string — The zip or postal code associated with the contact's other address.
    - `other_country` string — The name of another country where the contact is located.
    - `cf:custom_field_name` string — The name of this property is dynamic based on the custom fields you want to import. Use a key-value pair where the key is an existing custom field name prefixed with <code>cf:</code>, and the value is a custom field string value. For example, if you have a custom field named <code>first_name</code> you can use <code>"cf:first_name":"Joe"</code>. Each contact can contain up to 25 different custom fields.
    - `sms_number` string — The US phone number to associate with the contact's SMS-enabled phone. The country code must be valid. Valid formats are <code>1231231234</code> or <code>123-123-1234</code>. Required if `email` is not specified.
    - `sms_consent_date` string — Required if the SMS permission is set to `explicit`. The date that the contact consented to receiving SMS messages. Valid date formats are MM/DD/YYYY, M/D/YYYY, YYYY/MM/DD, YYYY/M/D, YYYY-MM-DD, YYYY-M-D,M-D-YYYY, or M-DD-YYYY.
  - `list_ids` string[], required — Specify which contact lists you are adding all imported contacts to as an array of up to 50 contact <code>list_id</code> string values.
  - `sms_permission_to_send` string — Specifies if the contact gave <code>explicit</code> SMS permission or if the SMS permission was not set (<code>not_set</code>). If `explicit, the <code>sms_consent_date</code> must be provided.

## Response `201`

Request successful. Activity queued for processing.

- ActivityImport — Activity status for contacts_json_import and contacts_file_import activities
  - `activity_id` string, uuid — Unique ID for the activity.
  - `state` string — 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_at` string, date-time — Timestamp showing when we began processing the activity request, in ISO-8601 format.
  - `completed_at` string, date-time — Timestamp showing when we completed processing the activity, in ISO-8601 format.
  - `created_at` string, date-time — Timestamp showing when we created the activity, in ISO-8601 format.
  - `updated_at` string, date-time — Timestamp showing when we last updated the activity, in ISO-8601 format.
  - `source_file_name` string — Name of the file used for an file_import activity.
  - `percent_done` integer — Shows the percent done for an activity that we are still processing.
  - `activity_errors` string[] — Array of messages describing the errors that occurred.
  - `status` object
    - `items_total_count` integer — The total number of rows, including the header row, in the import file.
    - `person_count` integer — The total number of contacts in the import file.
    - `error_count` integer — The number of non-correctable errors encountered during the file import.
    - `correctable_count` integer — The number of correctable errors. Correctable errors are: invalid email address format, birthday or anniversary format error, or does not have minimal contact information (no name or email address). Correctable errors are available in the product UI to correct.
    - `cannot_add_to_list_count` integer — The number of previously unsubscribed contacts in the import - they cannot be added to a list.
  - `_links` ActivityStatusLink
    - `self` object — HATEOS-style link to the activity status (this object).
      - `href` string

## Other responses

- `400` — Bad request. Either the JSON was malformed or there was a data validation error.
- `401` — The Access Token used is invalid.
- `403` — Forbidden request. You lack the necessary scopes, you lack the necessary user privileges, or the application is deactivated.
- `429` — Too many requests. You exceeded 1,000 queued activities for this user account.
- `500` — There was a problem with our internal service.
- `503` — Our internal service is temporarily unavailable.

---

[API](https://skmtc.net/cc/apis/appconnect-v3.md) · [All operations](https://skmtc.net/cc/apis/appconnect-v3/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/cc/appconnect-v3/revisions/4b4a534c818d/schema)