--- schema_version: "1" id: a39f19d10ec6a0d0cee123489c1b8f5706075b346ab5afb5727f5a354b836efb title: Leads (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-leads.md canonical_url: https://developer.salesforce.com/docs/marketing/marketing-cloud-growth/references/mc-rest-leads source_site: developer.salesforce.com content_type: documentation content_hash: f63a5c2141ceb1d00c56e5363843d4bcf10d72090dfe1619f2799d9c6fafcae8 products: - Marketing Cloud Next - Marketing Cloud --- Leads (REST API) # Leads (REST API) Manage and modify Marketing Cloud Next leads synchronously by using REST API. This table lists the lead-related use cases that REST API supports. | Supported Use Case | HTTP Verb | URI | | --- | --- | --- | | Create a lead | [POST](/docs/marketing/marketing-cloud-core/references/mc-rest-leads?meta=createLead) | /services/data/{apiVersion}/sobjects/lead | | Get a lead | [GET](/docs/marketing/marketing-cloud-core/references/mc-rest-leads?meta=getLead) | /services/data/{apiVersion}/sobjects/lead/{leadId} | | Delete a lead | [DELETE](/docs/marketing/marketing-cloud-core/references/mc-rest-leads?meta=deleteLead) | /services/data/{apiVersion}/sobjects/lead/{leadId} | | Update a lead | [PATCH](/docs/marketing/marketing-cloud-core/references/mc-rest-leads?meta=updateLead) | /services/data/{apiVersion}/sobjects/lead/{leadId} | | Get updated leads | [GET](/docs/marketing/marketing-cloud-core/references/mc-rest-leads?meta=getUpdatedLeads) | /services/data/{apiVersion}/sobjects/lead/updated/ | | Get deleted leads | [GET](/docs/marketing/marketing-cloud-core/references/mc-rest-leads?meta=getDeletedLeads) | /services/data/{apiVersion}/sobjects/lead/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 lead record. This operation can create leads that contain standard and custom fields. `POST /services/data/{apiVersion}/sobjects/lead` Operation ID: `createLead`. The Body section lists all of the standard lead fields. Your org can contain different fields. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to REST API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` #### Request body (required) Media type: `application/json`. Schema: `leadUpdateRequestBody`. #### Responses * **201** This response indicates that the API accepted your request to create a lead. Media type: `application/json`. Schema: `leadResponseBody`. _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 lead record. `GET /services/data/{apiVersion}/sobjects/lead/{leadId}` Operation ID: `getLead`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to REST API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `leadId` (query, string, required) The record ID of the lead. #### Responses * **200** This response indicates that the API accepted your request to retrieve information about a lead. Media type: `application/json`. Schema: `getLeadResponseBody`. * **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 lead. 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 lead record. `DELETE /services/data/{apiVersion}/sobjects/lead/{leadId}` Operation ID: `deleteLead`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to REST API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `leadId` (query, string, required) The record ID of the lead. #### Responses * **204** Indicates that the API accepted your request to delete the lead. 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 lead. 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 fields in a lead record. `PATCH /services/data/{apiVersion}/sobjects/lead/{leadId}` Operation ID: `updateLead`. 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 REST API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `leadId` (query, string, required) The record ID of the lead. #### Request body (required) Media type: `application/json`. Schema: `leadUpdateRequestBody`. #### Responses * **204** Indicates that the API accepted your request to update the lead. 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 Lead", "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 lead. 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 leads that were modified within a specified range of dates. `GET /services/data/{apiVersion}/sobjects/Lead/updated/` Operation ID: `getUpdatedLeads`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to REST API. 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 leads that were modified or deleted in the specified date range. Media type: `application/json`. Schema: `getUpdatedLeadsResponseBody`. _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 leads that were deleted within a specified range of dates. `GET /services/data/{apiVersion}/sobjects/Lead/deleted/` Operation ID: `getDeletedLeads`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to REST API. 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 leads that were modified or deleted in the specified date range. Media type: `application/json`. Schema: `getUpdatedLeadsResponseBody`. _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 ### leadUpdateRequestBody * `AnnualRevenue` (_string_) The annual revenue of the lead’s company or organization. * `City` (_string_) The city of the mailing address. * `CleanStatus` (_string_) Indicates the record’s clean status as compared with Data.com. Allowed values: `Acknowledged`, `Different`, `Inactive`, `Matched`, `NotFound`, `Pending`, `SelectMatch`, `Skipped`. * `Company` (_string_) The lead's company. * `CompanyDunsNumber` (_string_) The Data Universal Numbering System (DUNS) number, which is a unique, nine-digit number assigned to every business location in the Dun & Bradstreet database that has a unique, separate, and distinct operation. This field is available only to organizations that use Data.com Prospector or Data.com Clean. * `Country` (_string_) The lead's country. * `CountryCode` (_string_) The ISO country code for the lead's country. * `Description` (_string_) A description of the lead. This field can contain up to 32 KB of data. * `Division` (_string_) A logical segment of your organization's data. For example, if your company is organized into different business units, you could create a division for each business unit, such as “North America,” “Healthcare,” or “Consulting.” Available only when the organization has the Division permission enabled. * `Email` (_string_) The lead’s email address. * `EmailBouncedDate` (_string (date-time)_) If bounce management is activated and an email sent to the lead 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 lead bounces, this field contains the reason for the bounce. * `Fax` (_string_) The lead’s fax number. * `FirstName` (_string_) The lead’s first name. This field can contain up to 40 characters. * `GenderIdentity` (_string_) The gender identity of the lead. * `HasOptedOutOfEmail` (_boolean_) Indicates whether the lead has opted out of email. If this value is `true`, the lead has opted out. * `HasOptedOutOfFax` (_boolean_) Indicates whether the lead has opted out of receiving faxes. If this value is `true`, the lead has opted out. * `GeocodeAccuracy` (_string_) Accuracy level of the geocode for the address. * `IndividualId` (_string_) ID of the data-privacy record associated with this lead. This field is available if you enabled Data Protection and Privacy in Setup. * `Industry` (_string_) The lead's industry. * `IsUnreadByOwner` (_boolean_) Indicates whether the lead owner has viewed the record. If the value is `true`, the owner has viewed the record. * `Jigsaw` (_string_) References the ID of a contact in Data.com. If a lead has a value in this field, it means that a contact was imported as a lead from Data.com. If the converted contact wasn’t imported from Data.com, the value of the field is null. Maximum length: 20. * `LastName` (_string_) The last name of the lead. This field can contain up to 80 characters. * `Latitude` (_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). * `Longitude` (_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). * `LeadSource` (_string_) The source of the lead that was converted to this lead. * `MiddleName` (_string_) The lead’s middle name. This field can contain up to 40 characters. To enable this field, contact Salesforce Customer Support. * `MobilePhone` (_string_) The lead’s mobile phone number. * `NumberOfEmployees` (_number_) The number of employees in the lead’s company or organization. * `OwnerId` (_string_) The ID of the owner of the account associated with this lead. * `Phone` (_string_) The lead’s phone number. * `PostalCode` (_string_) The postal code of the mailing address. * `Pronouns` (_string_) The lead’s personal pronouns. The value must align with a picklist of available values, which the administrator sets. This field can contain up to 40 characters. * `Rating` (_string_) A score that indicates the quality of the lead. * `RecordTypeId` (_string_) The ID of the record type assigned to this object. * `Salutation` (_string_) Honorific abbreviation, word, or phrase to be used in front of the lead's name in greetings, such as Dr. or Mrs. * `State` (_string_) The state or other subnational division of the lead's address. * `StateCode` (_string_) The code for the state or other subnational division of the lead's address. * `Status` (_string_) Status code for this converted lead. Status codes are defined in Status and represented in the API by the LeadStatus object. * `Street` (_string_) The street name and number for the lead's address. * `Suffix` (_string_) The name suffix of the lead, such as Jr. or Sr. This field can contain up to 40 characters. To enable this field, contact Salesforce Customer Support. * `Title` (_string_) The lead's job title, such as CEO or Vice President. * `Website` (_string_) The website for the lead’s company or organization. _Example_ ``` { "Salutation": "Mr.", "FirstName": "D’Angelo", "LastName": "Cunningham", "Title": "Salesforce Admin", "Email": "dangelo.cunningham@example.com", "MobilePhone": "+18575550142" } ``` ### leadResponseBody * `id` (_string_) The Salesforce ID of the lead. * `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. ### getLeadResponseBody * `attributes` (_object_) * `type` (_string_) The type of the Salesforce object. For leads, this value is always "Lead". * `url` (_string_) The API URL endpoint for the Lead object. * `Id` (_string_) The unique Salesforce record ID for the lead. * `IsDeleted` (_boolean_) Indicates whether the object has been deleted. If this value is `true`, the object has been deleted. * `MasterRecordId` (_string_) The ID of the master record that the lead is associated with. * `AccountId` (_string_) The ID of the account associated with the lead. * `LastName` (_string_) Last name of the lead. Can contain up to 80 characters. * `FirstName` (_string_) The lead’s first name up to 40 characters. * `Salutation` (_string_) Honorific abbreviation, word, or phrase to be used in front of the lead's name in greetings, such as Dr. or Mrs. * `Name` (_string_) The full name of the lead. This field combines the values in the FirstName, MiddleName, LastName, and Suffix fields. * `Title` (_string_) The job title of the lead. * `Company` (_string_) The name of the lead’s company. * `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. * `PostalCode` (_string_) The postal code of the mailing address. * `Country` (_string_) The country of the mailing address. * `Latitude` (_number (double)_) Used with Longitude to specify the precise geolocation of a mailing address. Acceptable values are numbers from -90 through 90 up to 15 decimal places. * `Longitude` (_number (double)_) Used with Latitude to specify the precise geolocation of a mailing address. Acceptable values are numbers from -180 through 180 up to 15 decimal places. * `GeocodeAccuracy` (_string_) The accuracy level of the geocode for the mailing address. * `Address` (_object_) An object that combines all of the 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 lead. * `Email` (_string_) The email address of the lead. * `Website` (_string_) The website for the lead’s company or organization. * `PhotoUrl` (_string_) The path to add to the end of the Salesforce instance URL to view the profile image for the lead. * `Description` (_string_) A description of the lead. * `LeadSource` (_string_) The source of the lead. * `Status` (_string_) A status code for the lead. * `Industry` (_string_) The lead’s industry. * `Rating` (_string_) A score that indicates the quality of the lead. * `AnnualRevenue` (_number_) The annual revenue of the lead’s company or organization. * `NumberOfEmployees` (_number_) The number of employees in the lead’s company or organization. * `OwnerId` (_string_) The ID of the owner of the account associated with this lead. * `IsConverted` (_boolean_) Indicates whether the lead has been converted. If the value is `true`, the lead has been converted. * `ConvertedDate` (_string_) Date when the lead was converted. * `ConvertedAccountId` (_string_) The ID of the account that the lead was converted into. * `ConvertedContactId` (_string_) The ID of the contact record that the lead was converted into. * `ConvertedOpportunityId` (_string_) The ID of the opportunity that the lead was converted into. * `IsUnreadByOwner` (_boolean_) Indicates whether the lead owner has viewed the record. If the value is `true`, the owner has viewed the record. * `CreatedDate` (_string (date-time)_) A timestamp that indicates when the lead was created. * `CreatedById` (_string_) The ID of the user that created the lead record. * `LastModifiedDate` (_string (date-time)_) A timestamp that indicates when the lead was last modified. * `LastModifiedById` (_string_) The ID of the user that last modified the lead record. * `SystemModstamp` (_string (date-time)_) A timestamp that indicates when the lead 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. * `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 accessed this 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. * `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 lead ID from Data.com. * `EmailBouncedReason` (_string_) If bounce management is activated and an email sent to the lead bounces, this field contains the reason for the bounce. * `EmailBouncedDate` (_string (date-time)_) If bounce management is activated and an email sent to the lead bounces, this field contains the date and time when the bounce occurred. * `IndividualId` (_string_) The ID of the data privacy record associated with this lead. _Example_ ``` { "attributes": { "type": "Lead", "url": "/services/data/{apiVersion}/sobjects/Lead/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, "JigsawLeadId": null, "CleanStatus": "Pending", "IndividualId": null } ``` ### getUpdatedLeadsResponseBody * `ids` (_array of string_) Each item: Lead IDs that were modified between the start date and the end date. * `latestDateCovered` (_string (date-time)_) The end date for the query.