--- schema_version: "1" id: 7cc0e24718151b22221a331fd8518e93938f2029bd6cb9804e5d63ef7685e705 title: Contacts (REST API) collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/marketing-cloud/mc-core/references/generated-api-specs/mc-rest-contacts.md canonical_url: https://developer.salesforce.com/docs/marketing/marketing-cloud-growth/references/mc-rest-contacts source_site: developer.salesforce.com content_type: documentation content_hash: dc6ab17ebb4e18fd0f271f02d08ef1d7c7d3e4fff438e5c9feab9ae00881318f products: - Marketing Cloud Next - Marketing Cloud --- Contacts (REST API) # Contacts (REST API) Manage and modify Marketing Cloud Next contacts synchronously by using REST API. This table lists the contact-related use cases that REST API supports. | Supported Use Case | HTTP Verb | URI | | --- | --- | --- | | Create a contact | [POST](/docs/marketing/marketing-cloud-core/references/mc-rest-contacts?meta=createContact) | /services/data/{apiVersion}/sobjects/contact | | Get a contact | [GET](/docs/marketing/marketing-cloud-core/references/mc-rest-contacts?meta=getContact) | /services/data/{apiVersion}/sobjects/contact/{contactId} | | Delete a contact | [DELETE](/docs/marketing/marketing-cloud-core/references/mc-rest-contacts?meta=deleteContact) | /services/data/{apiVersion}/sobjects/contact/{contactId} | | Update a contact | [PATCH](/docs/marketing/marketing-cloud-core/references/mc-rest-contacts?meta=updateContact) | /services/data/{apiVersion}/sobjects/contact/{contactId} | | Get updated contacts | [GET](/docs/marketing/marketing-cloud-core/references/mc-rest-contacts?meta=getUpdatedContacts) | /services/data/{apiVersion}/sobjects/contact/updated/ | | Get deleted contacts | [GET](/docs/marketing/marketing-cloud-core/references/mc-rest-contacts?meta=getDeletedContacts) | /services/data/{apiVersion}/sobjects/contact/deleted/ | **Version:** v68.0 ## Servers * `https://{subdomain}.my.salesforce.com` * `subdomain (default (no default)) The unique API subdomain for your Salesforce org.` ## Operations ### POST Create a contact record. This operation can create contacts that contain standard and custom fields. `POST /services/data/{apiVersion}/sobjects/contact` Operation ID: `createContact`. The Body section lists all of the standard contact fields. Some orgs contain different fields. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to Bulk API 2.0. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` #### Request body (required) Media type: `application/json`. Schema: `contactUpdateRequestBody`. #### Responses * **201** This response indicates that the API accepted your request to create a contact. Media type: `application/json`. Schema: `contactResponseBody`. _Example_ ``` { "id": "003SB000002UaPtYAK", "success": true, "errors": [] } ``` * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that your authorization token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` [ { "message": "Session expired or invalid", "errorCode": "INVALID_SESSION_ID" } ] ``` ### GET Get a contact record. `GET /services/data/{apiVersion}/sobjects/contact/{contactId}` Operation ID: `getContact`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to Bulk API 2.0. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `contactId` (query, string, required) The record ID of the contact. #### Responses * **200** This response indicates that the API accepted your request to retrieve information about a contact. Media type: `application/json`. Schema: `getContactResponseBody`. * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that your authorization token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` [ { "message": "Session expired or invalid", "errorCode": "INVALID_SESSION_ID" } ] ``` * **404** This response indicates that the URI in your request couldn’t be reached. When you receive a 404 response, verify that your request included the correct record ID for the contact. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` [ { "errorCode": "NOT_FOUND", "message": "Provided external ID field does not exist or is not accessible: 003SB000002MCarYAGG" } ] ``` ### DELETE Delete a contact record. `DELETE /services/data/{apiVersion}/sobjects/contact/{contactId}` Operation ID: `deleteContact`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to Bulk API 2.0. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `contactId` (query, string, required) The record ID of the contact. #### Responses * **204** Indicates that the API accepted your request to delete the contact. The response contains no content. * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that your authorization token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` [ { "message": "Session expired or invalid", "errorCode": "INVALID_SESSION_ID" } ] ``` * **404** This response indicates that the URI in your request couldn’t be reached. When you receive a 404 response, verify that your request included the correct record ID for the contact. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` [ { "errorCode": "NOT_FOUND", "message": "Provided external ID field does not exist or is not accessible: 003SB000002MCarYAGG" } ] ``` ### PATCH Update one or more fields in a contact record. `PATCH /services/data/{apiVersion}/sobjects/contact/{contactId}` Operation ID: `updateContact`. This operation can update standard and custom fields. Your org can contain custom fields not listed here. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to Bulk API 2.0. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `contactId` (query, string, required) The record ID of the contact. #### Request body (required) Media type: `application/json`. Schema: `contactUpdateRequestBody`. #### Responses * **204** Indicates that the API accepted your request to update the contact. The response contains no content. * **400** This response indicates that the API wasn’t able to process your request. This error can occur if you specify an incorrect field name or parameter. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` [ { "message": "No such column 'JobTitle' on sobject of type Contact", "errorCode": "INVALID_FIELD" } ] ``` * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that your authorization token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` [ { "message": "Session expired or invalid", "errorCode": "INVALID_SESSION_ID" } ] ``` * **404** This response indicates that the URI in your request couldn’t be reached. When you receive a 404 response, verify that your request included the correct record ID for the contact. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` [ { "errorCode": "NOT_FOUND", "message": "Provided external ID field does not exist or is not accessible: 003SB000002MCarYAGG" } ] ``` ### GET Get a list of contacts that were modified within a specified range of dates. `GET /services/data/{apiVersion}/sobjects/contact/updated/` Operation ID: `getUpdatedContacts`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to Bulk API 2.0. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `start` (query, string (date-time), required) The start date for the query. Express the date as an ISO 8601 timestamp string, such as `2023-08-05T00:00:00.000Z`. * `end` (query, string (date-time), required) The end date for the query. Express the date as an ISO 8601 timestamp string, such as `2023-08-05T00:00:00.000Z`. #### Responses * **200** This response indicates that the API accepted your request to retrieve information about contacts that were modified or deleted in the specified date range. Media type: `application/json`. Schema: `getUpdatedContactsResponseBody`. _Example_ ``` { "ids": [ "003Hs00004ollVTivd", "003Hs00004ollrMBVp", "003Hs00004olluzkbW" ], "latestDateCovered": "2023-11-17T00:00:00.000+0000" } ``` * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that your authorization token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` [ { "message": "Session expired or invalid", "errorCode": "INVALID_SESSION_ID" } ] ``` ### GET Get a list of contacts that were deleted within a specified range of dates. `GET /services/data/{apiVersion}/sobjects/contact/deleted/` Operation ID: `getDeletedContacts`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to Bulk API 2.0. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `start` (query, string (date-time), required) The start date for the query. Express the date as an ISO 8601 timestamp string, such as `2023-08-05T00:00:00.000Z`. * `end` (query, string (date-time), required) The end date for the query. Express the date as an ISO 8601 timestamp string, such as `2023-08-05T00:00:00.000Z`. #### Responses * **200** This response indicates that the API accepted your request to retrieve information about contacts that were modified or deleted in the specified date range. Media type: `application/json`. Schema: `getUpdatedContactsResponseBody`. _Example_ ``` { "ids": [ "003Hs00004ollVTivd", "003Hs00004ollrMBVp", "003Hs00004olluzkbW" ], "latestDateCovered": "2023-11-17T00:00:00.000+0000" } ``` * **401** This response indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that your authorization token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` [ { "message": "Session expired or invalid", "errorCode": "INVALID_SESSION_ID" } ] ``` ## Schemas ### contactUpdateRequestBody * `AccountId` (_string_) The ID of the account that’s the parent of this contact. * `AssistantName` (_string_) The name of the contact’s assistant. * `AssistantPhone` (_string_) The phone number of the contact’s assistant. * `Birthdate` (_string_) The contact’s birthdate. * `CanAllowPortalSelfReg` (_boolean_) Indicates whether this contact can self-register for your customer portal. A value of `true` indicates that the contact can self-register. * `CleanStatus` (_string_) Indicates the record’s clean status as compared with Data.com. Allowed values: `Acknowledged`, `Different`, `Inactive`, `Matched`, `NotFound`, `Pending`, `SelectMatch`, `Skipped`. * `Department` (_string_) The contact’s department. * `Description` (_string_) A description of the contact. This field can contain up to 32 KB of data. * `DoNotCall` (_boolean_) Indicates that the contact doesn’t want to receive calls. * `Email` (_string_) The contact’s email address. * `EmailBouncedDate` (_string (date-time)_) If bounce management is activated and an email sent to the contact bounces, this field contains the date and time that the bounce occurred. * `EmailBouncedReason` (_string_) If bounce management is activated and an email sent to the contact bounces, this field contains the reason for the bounce. * `Fax` (_string_) The contact’s fax number. * `FirstName` (_string_) The contact’s first name. This field can contain up to 40 characters. * `GenderIdentity` (_string_) The contact’s gender identity. * `HomePhone` (_string_) The contact’s home phone number. * `LastName` (_string_) The last name of the contact. This field can contain up to 80 characters. * `LeadSource` (_string_) The source of the lead that was converted to this contact. * `MailingCity` (_string_) The city of the mailing address. * `MailingCountry` (_string_) The country of the mailing address. * `MailingLatitude` (_number (double)_) Used with MailingLongitude to specify the precise geolocation of a mailing address. Acceptable values are numbers between –90 and 90 up to 15 decimal places. For details on geolocation compound fields, see [Compound Field Considerations and Limitations](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/compound_fields_limitations.htm). * `MailingLongitude` (_number (double)_) Used with MailingLatitude to specify the precise geolocation of a mailing address. Acceptable values are numbers between –180 and 180 up to 15 decimal places. For details on geolocation compound fields, see [Compound Field Considerations and Limitations](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/compound_fields_limitations.htm). * `MailingPostalCode` (_string_) The postal code of the mailing address. * `MailingState` (_string_) The state or other subnational division of the mailing address. * `MailingStreet` (_string_) The street address of the mailing address. * `MiddleName` (_string_) The contact’s middle name. This field can contain up to 40 characters. To enable this field, contact Salesforce Customer Support. * `MobilePhone` (_string_) The contact’s mobile phone number. * `OtherCity` (_string_) The city of the contact’s alternative address. * `OtherCountry` (_string_) The country of the contact’s alternative address. * `OtherLatitude` (_number (double)_) Used with OtherLongitude to specify the precise geolocation of an alternative address. Acceptable values are numbers between –90 and 90 up to 15 decimal places. * `OtherLongitude` (_number (double)_) Used with OtherLatitude to specify the precise geolocation of an alternative address. Acceptable values are numbers between –180 and 180 up to 15 decimal places. * `OtherPhone` (_string_) An alternative phone number for the contact. * `OtherPostalCode` (_string_) The postal code of the contact’s alternative address. * `OtherState` (_string_) The state or other subnational division of the contact’s alternative address. * `OtherStreet` (_string_) The street address of the contact’s alternative address. * `OwnerId` (_string_) The ID of the owner of the account associated with this contact. * `Phone` (_string_) The phone number for the contact. * `Pronouns` (_string_) The contact’s personal pronouns, reflecting their gender identity. Others can use these pronouns to refer to the contact in the third person. The entry is selected from a picklist of available values, which the administrator sets. This field can contain up to 40 characters. * `Salutation` (_string_) Honorific abbreviation, word, or phrase to be used in front of the contact's name in greetings, such as Dr. or Mrs. * `Suffix` (_string_) The name suffix of the contact, such as Jr. or Sr. This field can contain up to 40 characters. To enable this field, contact Salesforce Customer Support. * `Title` (_string_) Title of the contact, such as CEO or Vice President. _Example_ ``` { "Salutation": "Mr.", "FirstName": "D’Angelo", "LastName": "Cunningham", "Title": "Salesforce Admin", "Email": "dangelo.cunningham@example.com", "MobilePhone": "+18575550142" } ``` ### contactResponseBody * `id` (_string_) The Salesforce ID of the contact. * `success` (_boolean_) Indicates whether the operation succeeded. * `errors` (_array of string_) Each item: An error message, if an error occurred. If no errors occurred, the array is empty. ### httpErrorResponseBody Array of `object`. * `errorcode` (_string_) The error message. * `message` (_string_) A detailed error message. ### getContactResponseBody * `attributes` (_object_) * `type` (_string_) The type of the Salesforce object. For contacts, this value is always `Contact`. * `url` (_string_) The API URL endpoint for the Contact object. * `Id` (_string_) The unique Salesforce record ID for the contact. * `IsDeleted` (_boolean_) Indicates whether the object has been deleted. * `MasterRecordId` (_string_) The ID of the master record that the contact is associated with. * `AccountId` (_string_) The ID of the account associated with the contact. * `LastName` (_string_) Last name of the contact. Can contain up to 80 characters. * `FirstName` (_string_) The contact’s first name up to 40 characters. * `Salutation` (_string_) Honorific abbreviation, word, or phrase to be used in front of name in greetings, such as Dr. or Mrs. * `Name` (_string_) The full name of the contact. This field combines the values in the FirstName, MiddleName, LastName, and Suffix fields. * `OtherCity` (_string_) Alternative address details. * `OtherCountry` (_string_) Alternative address details. * `OtherGeocodeAccuracy` (_string_) Accuracy level of the geocode for the other address. * `OtherLatitude` (_number (double)_) Used with OtherLongitude to specify the precise geolocation of an alternative address. Acceptable values are numbers between –90 and 90 up to 15 decimal places. * `OtherLongitude` (_number (double)_) Used with OtherLatitude to specify the precise geolocation of an alternative address. Acceptable values are numbers between –180 and 180 up to 15 decimal places. * `OtherPostalCode` (_string_) Alternative address details. * `OtherState` (_string_) Alternative address details. * `OtherStreet` (_string_) Street for alternative address. * `MailingCity` (_string_) The city of the mailing address. * `MailingCountry` (_string_) The country of the mailing address. * `MailingGeocodeAccuracy` (_string_) The accuracy level of the geocode for the mailing address. * `MailingLatitude` (_number (double)_) Used with MailingLongitude to specify the precise geolocation of a mailing address. Acceptable values are numbers between –90 and 90 up to 15 decimal places. * `MailingLongitude` (_number (double)_) Used with MailingLatitude to specify the precise geolocation of a mailing address. Acceptable values are numbers between –180 and 180 up to 15 decimal places. * `MailingPostalCode` (_string_) The postal code of the mailing address. * `MailingState` (_string_) The state or other subnational division of the mailing address. * `MailingStreet` (_string_) The street address of the mailing address. * `MailingAddress` (_object_) An object that combines all of the mailing address fields. * `street` (_string_) The street address of the mailing address. * `city` (_string_) The city of the mailing address. * `state` (_string_) The state or other subnational division of the mailing address. * `country` (_string_) The country of the mailing address. * `postalCode` (_string_) The postal code of the mailing address. * `latitude` (_number (double)_) The latitude of the mailing address. * `longitude` (_number (double)_) The longitude of the mailing address. * `geocodeAccuracy` (_string_) The accuracy level of the geocode for the mailing address. * `Phone` (_string_) The primary phone number of the contact. * `Fax` (_string_) The contact’s fax number. * `HomePhone` (_string_) The home phone number of the contact. * `OtherPhone` (_string_) An alternative phone number for the contact. * `AssistantPhone` (_string_) The phone number of the contact's assistant. * `ReportsToId` (_string_) The Salesforce ID of the contact's manager or supervisor. * `Email` (_string_) The email address of the contact. * `Title` (_string_) The job title of the contact. * `Department` (_string_) The contact's department or organization. * `AssistantName` (_string_) The name of the contact's assistant. * `LeadSource` (_string_) The source of the lead that was converted to this contact. * `Birthdate` (_string_) The contact's date of birth. * `Description` (_string_) A description of the contact. * `OwnerId` (_string_) The ID of the owner of the account associated with this contact. * `CreatedDate` (_string (date-time)_) A timestamp that indicates when the contact was created. * `CreatedById` (_string_) The ID of the user that created the contact record. * `LastModifiedDate` (_string (date-time)_) A timestamp that indicates when the contact was last modified. * `LastModifiedById` (_string_) The ID of the user that last modified the contact record. * `SystemModstamp` (_string (date-time)_) A timestamp that indicates when the contact was last modified. * `LastActivityDate` (_string_) Contains either the due date of the most recent event logged against the record or the due date of the most recently closed task associated with the record, whichever is most recent. * `LastCURequestDate` (_string_) The last stay-in-touch request date for the contact. * `LastCUUpdateDate` (_string_) The last stay-in-touch save date for the contact. * `LastViewedDate` (_string (date-time)_) The timestamp when the current user last viewed this record or list view. If this value is null, it typically indicates that the user only accessed the record or list view but didn't view it. * `LastReferencedDate` (_string (date-time)_) The timestamp when the current user last accessed this record, a record related to this record, or a list view. * `EmailBouncedReason` (_string_) If bounce management is activated and an email sent to the contact bounces, this field contains the reason for the bounce. * `EmailBouncedDate` (_string (date-time)_) If bounce management is activated and an email sent to the contact bounces, this field contains the date and time when the bounce occurred. * `IsEmailBounced` (_boolean_) If bounce management is activated and an email is sent to a contact, this field indicates whether the email bounced. If the value of the field is `true`, the email bounced. * `PhotoUrl` (_string_) The path to add to the end of the Salesforce instance URL to view the profile image for the contact. * `Jigsaw` (_string_) References the company’s ID in Data.com. If an account has a value in this field, it means that the account was imported from Data.com. If the field value is null, the account wasn’t imported from Data.com. * `JigsawContactId` (_string_) The contact ID from Data.com. * `CleanStatus` (_string_) Indicates the record’s clean status as compared with Data.com. Allowed values: `Acknowledged`, `Different`, `Inactive`, `Matched`, `NotFound`, `Pending`, `SelectMatch`, `Skipped`. * `IndividualId` (_string_) The ID of the data-privacy record associated with this contact. _Example_ ``` { "attributes": { "type": "Contact", "url": "/services/data/{apiVersion}/sobjects/Contact/003Hs00004llr2oIAA" }, "Id": "003Hs00004llr2oIAA", "IsDeleted": false, "MasterRecordId": null, "AccountId": null, "LastName": "Cunningham", "FirstName": "D’Angelo", "Salutation": "Mr.", "Name": "D’Angelo Cunningham", "OtherStreet": null, "OtherCity": null, "OtherState": null, "OtherPostalCode": null, "OtherCountry": null, "OtherLatitude": null, "OtherLongitude": null, "OtherGeocodeAccuracy": null, "OtherAddress": null, "MailingStreet": "500 Boylston Street", "MailingCity": "Boston", "MailingState": "MA", "MailingPostalCode": "02116", "MailingCountry": null, "MailingLatitude": null, "MailingLongitude": null, "MailingGeocodeAccuracy": null, "MailingAddress": { "city": "Boston", "country": null, "geocodeAccuracy": null, "latitude": null, "longitude": null, "postalCode": "02116", "state": "MA", "street": "500 Boylston Street" }, "Phone": null, "Fax": null, "MobilePhone": "+18575550142", "HomePhone": null, "OtherPhone": null, "AssistantPhone": null, "ReportsToId": null, "Email": "dangelo.cunningham@example.com", "Title": "Salesforce Admin", "Department": null, "AssistantName": null, "LeadSource": null, "Birthdate": null, "Description": null, "OwnerId": "005Hs00000BpyybIAB", "CreatedDate": "2023-11-16T23:07:59.000+0000", "CreatedById": "005Hs00000BpyybIAB", "LastModifiedDate": "2023-11-16T23:07:59.000+0000", "LastModifiedById": "005Hs00000BpyybIAB", "SystemModstamp": "2023-11-16T23:07:59.000+0000", "LastActivityDate": null, "LastCURequestDate": null, "LastCUUpdateDate": null, "LastViewedDate": "2023-11-16T23:08:22.000+0000", "LastReferencedDate": "2023-11-16T23:08:22.000+0000", "EmailBouncedReason": null, "EmailBouncedDate": null, "IsEmailBounced": false, "PhotoUrl": "/services/images/photo/003Hs00004llr2oIAA", "Jigsaw": null, "JigsawContactId": null, "CleanStatus": "Pending", "IndividualId": null } ``` ### getUpdatedContactsResponseBody * `ids` (_array of string_) Each item: Contact IDs that were modified between the start date and the end date. * `latestDateCovered` (_string (date-time)_) The end date for the query.