Use the POST /contacts/sign_up_form
endpoint to add a new contact to an account or update an existing contact based on their email address. 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 andopt_in_source
as Contact for new contacts. Existing contacts have theirpermission_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.
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 usinglist_id
values. You must include at least one contactlist_id
value and cannot exceed 50list_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:
|
street_address | object | The contact's street address as an object that can contain the following string properties:
|
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
<?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"
}