Some Contacts endpoints share a common data model for requests; these are described below.
Contact
Required data: type
is a required field. In addition, one of the following identification criteria must be satisfied:
firstName
andlastName
(required for INDIVIDUAL type)commonName
(required for ORGANIZATION type)- at least one
emails
- at least one
phones
contactId
should not be specified in the request body. If you do, the response will be a 301 redirect to the correct /contacts/{contactId} resource for making that call.
All other fields are optional. Note that deduping logic is always in effect, so if you make a POST with a set of data that closely matches a contact already in the system (e.g. same name and email address), then the data you are POSTing will be merged into the existing data.
Example POST data (note that this is submitted with content-type application/json
):
{
"type": "INDIVIDUAL",
"firstName": "Lefty",
"lastName": "McDonkey",
"emails": [
{
"address": "[email protected]",
"type": "MAIN",
"doNotEmail": false,
"appliedEmailLists": [{
"emailListId": 12,
},
{
"emailListId": 14
}]
}
],
"addresses" : [
{
"line1": "1203 12th St",
"line2": "Suite 525",
"city": "Washington",
"stateProvince": "DC",
"postalCode": "20005",
"type": "WORK"
}
],
"phones" : [
{
"number": "2025557979",
"type": "MOBILE"
},
{
"number": "3014884002",
"type": "HOME"
}
],
"externalLinks" : [
{
"externalSourceTypeId": "13",
"externalId": "12345"
},
{
"externalSourceTypeId": "15",
"externalId": "6789"
}
],
"contactCodes": [
{
"contactCodeId": 37653
},
{
"contactCodeId": 1022
},
{
"contactCodeId": 27
}
],
"employer": "NGP VAN",
"occupation": "Mascot",
"facebookProfileUrl": "http://facebook.com/shia_labeouf",
"disclosureFields": [
{
"disclosureFieldId": 1,
"designationId": 8,
"value": 702
},
{
"disclosureFieldId": 2114,
"designationId": 8,
"value": 2013
}
]
}
Key | Value |
---|---|
| Either |
| String (INDIVIDUAL type only, and must match one of your available prefixes |
| String (INDIVIDUAL type only) |
| String (INDIVIDUAL type only) |
| String (INDIVIDUAL type only) |
| String (INDIVIDUAL type only) |
| String (INDIVIDUAL type only) |
| String (INDIVIDUAL type only) |
| String (INDIVIDUAL type only) |
| String (INDIVIDUAL type only) |
| String (ORGANIZATION type only) |
| String (ORGANIZATION type only) |
| String (ORGANIZATION type only) |
| String (ORGANIZATION type only) |
| A collection of objects with the following structure: It’s not possible to have two emails with the same type. |
| A collection of objects with the following structure: It’s not possible to have two addresses with the same type. |
| A collection of objects with the following structure: It’s not possible to have two phones with the same type. |
| A single object containing the below properties(not all required). ndicates the best way to communicate with this contact. Setting values on this object does not override the properties of any phones, emails, or addresses.
|
| A collection of objects with the following structure: |
| String |
| String |
| String; the fully qualified URL for the contact’s Facebook profile. |
| A collection of objects with the following structure: |
| A collection of objects with the following structure: |
Contact Response
Successful contact creation or merging returns the contactId
of the newly created contact. Example:
{
"contactId": "VN93A9H7CW7"
}
The status code of the response indicates whether a new contact was created (201
) or if an existing one was updated (200
).