Create a new contact or update an existing contact

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:write

Authorization scopes: contact_data

JAVA cURL PHP 
<?php

$request = new HttpRequest();
$request->setUrl('https://api.cc.email/v3/contacts/sign_up_form');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders(array(
  'Authorization' => 'Bearer {access_token}',
  'Content-Type' => 'application/json'
));

$request->setBody('
{
  "email_address": "dlang@example.com",
  "first_name": "Debora",
  "last_name": "Lang",
  "job_title": "Musician",
  "company_name": "Acme Corp.",
  "create_source": "Account",
  "birthday_month": 11,
  "birthday_day": 24,
  "anniversary": "2006-11-15",
  "custom_fields": [
    {
      "custom_field_id": "1618ae62-4752-11e9-9c8a-fa163e6b01c1",
      "value": "Tesla S 2017"
    }
  ],
  "phone_number": "555-555-1212",
  "street_address": 
    {
      "kind": "home",
      "street": "124 Kashmir Valley Road",
      "city": "Chicago",
      "state": "Illinois",
      "postal_code": "12345",
      "country": "United States"
    },
  "list_memberships": [
    "d13d60d0-f256-11e8-b47d-fa163e56c9b0"
  ]
}
');

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

curl --location --request POST 'https://api.cc.email/v3/contacts/sign_up_form' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '
{
  "email_address": "dlang@example.com",
  "first_name": "Debora",
  "last_name": "Lang",
  "job_title": "Musician",
  "company_name": "Acme Corp.",
  "create_source": "Account",
  "birthday_month": 11,
  "birthday_day": 24,
  "anniversary": "2006-11-15",
  "custom_fields": [
    {
      "custom_field_id": "1618ae62-4752-11e9-9c8a-fa163e6b01c1",
      "value": "Tesla S 2017"
    }
  ],
  "phone_number": "555-555-1212",
  "street_address": 
    {
      "kind": "home",
      "street": "124 Kashmir Valley Road",
      "city": "Chicago",
      "state": "Illinois",
      "postal_code": "12345",
      "country": "United States"
    },
  "list_memberships": [
    "d13d60d0-f256-11e8-b47d-fa163e56c9b0"
  ]
}
'

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!

[]:

Tags: contacts code_samples