Create or Update a Contact Using a Single Method

Use the POST /contacts/sign_up_form endpoint to add a new contact to an account or update an existing contact. Only use this method when a contact gives you their explicit permission to send them emails.

If the email address you provide is new, POST /contacts/sign_up_form creates a new contact. If the email address you provide already belongs to an existing contact, POST /contacts/sign_up_form updates that contact instead of returning a 409 Conflict error. This allows you to add contacts to an account without having to make a separate API call to check if the email address already exists for a contact in the user account.

The request body for this method does not use the permission_to_send or opt_in_source contact resource properties. This method modifies the permission_to_send and opt_in_source properties depending on the Confirmed Opt-In Constant Contact account setting:

If Confirmed Opt-in is enabled, this method automatically sets permission_to_send as pending_confirmation for new contacts.
If Confirmed Opt-in is disabled, this method automatically sets permission_to_send as explicit and opt_in_source as Contact for new contacts. Existing contacts have their permission_to_send property set as explicit.

This means that even if a contact is currently unsubscribed, POST /contacts/sign_up_form may set the contact's email permission policy as having given you explicit permission to send them emails.

This method only applies partial updates to contacts. Except for overwriting permission_to_send with explicit, this method only updates contacts using the properties you include in the request body.

Important

If specifying an email address

Only use this method when a contact gives you their explicit permission to send them an email. It is a violation of anti-spam and telemarketing laws, as well as a serious violation of the Constant Contact Terms of Service to use the Opt-in features of the API to opt a contact back in without his or her own action and consent.

If specifying an SMS number

Only use this method when a contact gives you their explicit permission to send them an SMS. It is a violation of anti-spam and telemarketing laws, as well as a serious violation of the Constant Contact Terms of Service to use the Opt-in features of the API to opt a contact back in without his or her own action and consent.

Method Request Body

The JSON request body must contain:

The email_address property. Use the email address to specify the contact you are creating or updating.
The list_memberships array. Use this array to add the contact lists using list_id values. You must include at least one contact list_id value and cannot exceed 50 list_id values. For more information on creating new contact lists, see the Contact Lists Overview.

All other request body properties are optional.

Request Body Schema

Schema Property	Data Type	Description
email_address required	string Max Length: 50	The email address for the contact. This method identifies each unique contact using their email address. If the email address exists in the account, this method updates the contact. If the email address is new, this method creates a new contact.
first_name	string Max Length: 50	The first name of the contact.
last_name	string Max Length: 50	The last name of the contact.
job_title	string Max Length: 50	The job title of the contact.
company_name	string Max Length: 50	The name of the company where the contact works.
phone_number	string Max Length: 50	A phone number for the contact.
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.
birthday_month	integer	The month value for the contact's birthday. Valid values are from 1 through 12. The `birthday_month` property is required if you use `birthday_day`.
birthday_day	integer	The day value for the contact's birthday. Valid values are from 1 through 31. The `birthday_day` property is required if you use `birthday_month`.
list_memberships required	array[string]	The contact lists you want to add the contact to as an array of up to 50 contact `list_id` values. You must include at least one `list_id`.
custom_fields	array[object]	The custom fields you want to add to the contact as an array of up to 50 objects. If you are adding custom fields to a contact, each custom field object must contain: `custom_field_id`—The unique id for the custom field. `value`—The value of the custom field you are adding for the contact.
street_address	object	The contact's street address as an object that can contain the following string properties: `kind`—The type of street address for the contact. Valid values are home, work, or other. `street`—The number and street of the contact's address. `city`—The name of the city for the contact's address. `state`—The name of the state or province for the contact's address. `postal_code`—The zip or postal code for the contact's address. `country`—The name of the country for the contact's address.

There are a few name and data types differences between the request body properties of POST /contacts/sign_up_form and POST /contacts.

POST /contacts/sign_up_form uses the string property phone_number to contain the contacts phone number. POST /contacts uses the array phone_numbers to contain an array of phone number objects.

POST /contacts/sign_up_form uses the object property street_address to contain a single street address for the contact. POST /contacts uses the array street_addresses to contain multiple street address objects.

Example POST Create or Update Contact Request

POST

https://api.cc.email/v3/contacts/sign_up_form

Endpoint Requirements

User privileges: contacts:writeAuthorization scopes: contact_data

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "\n{\n  \"email_address\": \"dlang@example.com\",\n  \"first_name\": \"Debora\",\n  \"last_name\": \"Lang\",\n  \"job_title\": \"Musician\",\n  \"company_name\": \"Acme Corp.\",\n  \"create_source\": \"Account\",\n  \"birthday_month\": 11,\n  \"birthday_day\": 24,\n  \"anniversary\": \"2006-11-15\",\n  \"custom_fields\": [\n    {\n      \"custom_field_id\": \"1618ae62-4752-11e9-9c8a-fa163e6b01c1\",\n      \"value\": \"Tesla S 2017\"\n    }\n  ],\n  \"phone_number\": \"555-555-1212\",\n  \"street_address\": \n    {\n      \"kind\": \"home\",\n      \"street\": \"124 Kashmir Valley Road\",\n      \"city\": \"Chicago\",\n      \"state\": \"Illinois\",\n      \"postal_code\": \"12345\",\n      \"country\": \"United States\"\n    },\n  \"list_memberships\": [\n    \"d13d60d0-f256-11e8-b47d-fa163e56c9b0\"\n  ]\n}\n");
Request request = new Request.Builder()
  .url("https://api.cc.email/v3/contacts/sign_up_form")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Bearer {access_token}")
  .build();
Response response = client.newCall(request).execute();

Response Body

This method returns a different status code depending on if the API created a new contact or updated an existing contact. When the API updates a contact, it returns a 200 response code and "action": "updated" in the response body. When the API creates a new contact, it returns a 201 response code and "action": "created" in the response body.

For example:

{
    "contact_id": "2f67f3f0-cf51-11e9-bbee-fa163e56c9b0",
    "action": "created"
}

Try it!

Tagscontacts code_samples