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