Common Models

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 and lastName (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

type

Either INDIVIDUAL or ORGANIZATION. Required.

prefix

String (INDIVIDUAL type only, and must match one of your available prefixes Mr., Mrs., Miss, Ms. )

firstName

String (INDIVIDUAL type only)

middleName

String (INDIVIDUAL type only)

lastName

String (INDIVIDUAL type only)

nickName

String (INDIVIDUAL type only)

suffix

String (INDIVIDUAL type only)

salutation

String (INDIVIDUAL type only)

mailName

String (INDIVIDUAL type only)

spouseName

String (INDIVIDUAL type only)

commonName

String (ORGANIZATION type only)

officialName

String (ORGANIZATION type only)

primaryContactFirstName

String (ORGANIZATION type only)

primaryContactLastName

String (ORGANIZATION type only)

emails

A collection of objects with the following structure:
address | String; the email address
type | One of: HOME, OTHER, OTHER_2, PERSONAL, WORK, ALTERNATIVE, BILLING, MAIN, ASSISTANT
doNotEmail | Boolean
isPrimary | Boolean
appliedEmailLists | Integer. Must be a valid email list Id that already exists in the system. See the emailLists API call for retrieval of valid values.

It’s not possible to have two emails with the same type.

addresses

A collection of objects with the following structure:
line1 | String; address line 1
line2 | String; address line 2; optional
city | String
stateProvince | String
postalCode | String
isDisclosure | Boolean; The address that is reported on a disclosure report. Only one address on a contact may be marked isDisclosure=true.
isPrimary | Boolean
type | One of: ABROAD, HOME, MILITARY, SCHOOL, TEMPORARY, VACATION, WORK, ALTERNATIVE, BILLING, MAIN, ASSISTANT, OTHER, OTHER_2, VOTING

It’s not possible to have two addresses with the same type.

phones

A collection of objects with the following structure:
number | String; the phone number, digits only (no spaces, dashes, etc.)
isDisclosure | Boolean; The phone that is reported on a disclosure report. Only one phone on a contact may be marked isDisclosure=true.
isPrimary | Boolean
type | One of: HOME, HOME_FAX, OTHER_2, VACATION, WORK, WORK_FAX, BILLING, MAIN, MAIN_FAX, OTHER_FAX, ASSISTANT, MOBILE, OTHER, TTY_TDD

It’s not possible to have two phones with the same type.

communicationPreferences

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.

doNotContact | Boolean; if doNotContact=true, will also override doNotCall, doNotTelemarket, doNotEmail, doNotMail to true
doNotCall | Boolean; if doNotCall=true, will set prefersPhone to false
doNotTelemarket | Boolean
doNotEmail | Boolean; if doNotEmail=true, will set prefersEmail to false
doNotMail | Boolean; if doNotMail=true, will set prefersMail to false
doNotExchangeInfo | Boolean; if doNotExchangeInfo=true, this indicates the contact has requested not to have their information shared with others.
prefersEmail | Boolean
prefersFax | Boolean
prefersPhone | Boolean
prefersMail | Boolean
prefersSms | Boolean

contactCodes

A collection of objects with the following structure:
contactCodeId | Integer. Must be a valid contact code Id that already exists in the system. See the contactCodes API call for retrieval of valid values.

employer

String

occupation

String

facebookProfileUrl

String; the fully qualified URL for the contact’s Facebook profile.

disclosureFields

A collection of objects with the following structure:
disclosureFieldId | Integer; the id of a disclosure field (see the designations/{id}/contactDisclosureFields call for a list of valid values for this and also the designationId).

externalLinks

A collection of objects with the following structure:
externalSourceTypeId | Integer. Must be a valid external source type Id that already exists in the system. See the externalSource API call for retrieval of valid values.
externalId | String. The Id from the third-party database.

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).