--- sourceDocument: Zurich API Reference sourceDocumentLink: https://www.servicenow.com/docs/r/zurich/api-reference Release : - zurich ft:locale : - en-US ft:publication_title : - Zurich API Reference ft:clusterId : - crapiref bundleId : - crapiref workflow : - Creator --- # lead API # lead API {#ariaid-title1} * Release version: Zurich * * Updated July 31, 2025 * * ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 58 minutes to read The lead API provides endpoints that enable you to create, update, and query/retrieve marketing leads and their associated lead line items from an instance. Use this API to integrate your instance with external websites and systems such as automated lead capture systems, or to provide lead information to external reporting systems. This API is provided within the `sn_lead_mgmt_core` namespace. To access the API, the Lead Management Data Model (sn_lead_mgmt_core) plugin must be activated on the instance, and the calling user must have the sn_lead_mgmt_core.lead_integrator role. For additional information on Lead Management, see [Using Lead Management](https://www.servicenow.com/docs/access?context=lead-management-using&version=zurich&pubname=zurich-order-management&ft:locale=en-US). ## Extending the Lead API {#lead-api__section_ntp_vvc_tdc} You can extend the lead API by overriding the methods in its associated script includes. The default API functionality is located in script includes ending in "OOB", such as LeadAPIProcessUtilOOB. To override this functionality, create methods with identical names and parameters in the script include that has the same file name, but doesn't end in "OOB", such as LeadAPIProcessUtil. The following is a list of the script includes that you can override to change the behavior of the lead API: * [LeadAPIProcessUtilOOB](https://www.servicenow.com/docs/1LCdGAaBLKQaXcp0WWjxEQ#LeadAPIProcessUtilOOBAPI "The LeadAPIProcessUtilOOB script include provides methods that are called by the lead REST API to retrieve lead records and their associated lead line item records."): Contains methods that handle the retrieval and creation of lead and lead line item records. * [LeadApiValidationUtilOOB](https://www.servicenow.com/docs/KzSXVqL8SPAuC1pD6VbzWw#LeadAPIValidationUtilOOBAPI "The LeadAPIValidationUtilOOB script include provides methods that are called by the lead REST API to validate lead records and associated lead line item records when they are created (POST) or updated (PATCH)."): Contains methods that validate the JSON request object for the POST and PATCH endpoints. * [LeadAPIHelperOOB](https://www.servicenow.com/docs/MFtjXTYoi3fJyJbHN25qhw#LeadAPIHelperOOBAPI "The LeadAPIHelperOOB script include provides helper methods called by the lead REST API to perform various functions, such as converting a set of lead records from a GlideRecord object into a JSON array or JSON object and transforming fields within a lead object."): Contains API helper methods that: * Return an array of leads and related lead line items. * Return a JSON object from the associated GlideRecord. * Remove all ignored fields from a JSON object and perform other transformations. * LeadAPIConstantsOOB: Contains constants, status codes, and messages for all API operations. It also includes the list of fields that are ignored by the POST and PATCH endpoints. ## lead - GET /sn_lead_mgmt_core/lead {#ariaid-title2} Retrieves all leads and associated lead line items based on the filter criteria passed in the query parameters. This endpoint returns a paginated response as per the specified limit and offset. It retrieves information from the following tables: * Lead \[sn_lead_mgmt_core_lead\] * Lead Line Item \[sn_lead_mgmt_core_lead_line_item\] {#lead-GET-lead__ul_n5f_xzn_sdc} ### URL format Versioned URL: /api/sn_lead_mgmt_core/{api_version}/lead Default URL: /api/sn_lead_mgmt_core/{api_version}/lead Note: Available versions are specified in the [REST API Explorer](https://www.servicenow.com/docs/sYu7wNPLliq5~U4ai0aL_g "In this tutorial you will use the REST API Explorer to test the ServiceNow REST APIs."). For scripted REST APIs there is additional version information on the [Scripted REST Service form](https://www.servicenow.com/docs/cspfk_WKHcwVeXgD~XuntQ "The scripted REST API feature allows application developers to build custom web service APIs."). ### Supported request parameters {#lead-GET-lead__entry__2}{#lead-GET-lead__version-not_optional-RESTAPI} | Name | Description | |-|-| | api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest. Data type: String | [Table 1. Path parameters] {#lead-GET-lead__entry__6}{#lead-GET-lead__sysparm_fields_entry-RESTAPI}{#lead-GET-lead__sysparm-limit-RESTAPI}{#lead-GET-lead__sysparm_offset-ph-RESTAPI} | Name | Description | |-|-| | sysparm_fields | Comma-separated list of fields to return in the response. Invalid fields are ignored. Data type: String Default: Return all fields. | | sysparm_limit | Maximum number of records to return. For requests that exceed this number of records, use the sysparm_offset parameter to paginate record retrieval. This limit is applied before ACL evaluation. If no records return, including records you have access to, rearrange the record order so records you have access to return first. Note: Unusually large sysparm_limit values can impact system performance. Data type: Number Default: 10000 | | sysparm_offset | Starting record index for which to begin retrieving records. Use this value to paginate record retrieval. This functionality enables the retrieval of all records, regardless of the number of records, in small manageable chunks. For example, the first time you call this endpoint, sysparm_offset is set to "0". To simply page through all available records, use `sysparm_offset=sysparm_offset+sysparm_limit`, until you reach the end of all records.{#lead-GET-lead__sysparm_offset-p-RESTAPI} Don't pass a negative number in the sysparm_offset parameter. Data type: Number Default: 0 | | sysparm_query | Encoded query used to filter the result set. For example: `(sysparm_query=caller_id=javascript:gs.getUserID()^active=true)` The encoded query supports order by. To sort responses based on certain fields, use the ORDERBY and ORDERBYDESC clauses in sysparm_query. For example, `sysparm_query=active=true^ORDERBYnumber^ORDERBYDESCcategory` filters all active records and orders the results in ascending order by number first, and then in descending order by category. If part of the query is invalid, such as by specifying an invalid field name, the instance ignores the invalid part. It then returns rows using only the valid portion of the query. You can control this behavior using the property glide.invalid_query.returns_no_rows. Set this property to true to return no rows on an invalid query. Note: The glide.invalid_query.returns_no_rows property controls the behavior of all queries across the instance, such as in lists, scripts (GlideRecord.query()), and web service APIs. Data type: String | [Table 2. Query parameters] {#lead-GET-lead__entry__16} | Name | Description | |-|-| | None | | [Table 3. Request body parameters] ### Headers The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/5p0ILxi5PWo5cXuREsZCAQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#lead-GET-lead__entry__20}{#lead-GET-lead__content_type-JSON-only-entry-RESTAPI} | Header | Description | |-|-| | Content-Type | Data format of the request body. Only supports application/json. | [Table 4. Request headers] {#lead-GET-lead__entry__24}{#lead-GET-lead__accept-JSON-only-entry-RESTAPI} | Header | Description | |-|-| | Accept | Data format of the response body. Only supports application/json. | | Content-Range | Range of content returned in a paginated call. For example, if offset=2 and limit=3, the value of the Content-Range header is items 3-5. | | Links | Links through which to navigate the query results: * first * last * next * previous * self | | Total-Count | Total number of filtered records. | [Table 5. Response headers] ### Status codes The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://www.servicenow.com/docs/5p0ILxi5PWo5cXuREsZCAQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#lead-GET-lead__entry__34}{#lead-GET-lead__entry-200-status-code}{#lead-GET-lead__entry-404-status-code}{#lead-GET-lead__entry-500-status-code} | Status code | Description | |-|-| | 200 | Request was successfully processed. All responses returned (no pagination). | | 206 | Request successfully processed. Partial resource returned in response (with pagination). | | 400 | Error. Possible reasons: * Invalid limit/limit greater than maximum allowed. * Invalid offset. | | 403 | Record denied access. Insufficient permission to query the record. | | 404 | Not found. The requested item wasn't found. | | 500 | Internal server error. An unexpected error occurred while processing the request. | [Table 6. Status codes] ### Response body parameters {#lead-GET-lead__entry__48}{#lead-GET-lead__lead-account-entry}{#lead-GET-lead__lead-account.name-entry}{#lead-GET-lead__lead-account.sys_id-entry}{#lead-GET-lead__lead-business_phone-entry}{#lead-GET-lead__lead-city-entry}{#lead-GET-lead__lead-closed_date-ph}{#lead-GET-lead__lead-closed_date.display_value-entry}{#lead-GET-lead__lead-closed_date.value-entry}{#lead-GET-lead__lead-company-entry}{#lead-GET-lead__lead-consumer-ph}{#lead-GET-lead__lead-consumer.name-entry}{#lead-GET-lead__lead-consumer.sys_id-entry}{#lead-GET-lead__lead-contact-ph}{#lead-GET-lead__lead-contact.name-entry}{#lead-GET-lead__lead-contact.sys_id-entry}{#lead-GET-lead__lead-country-entry}{#lead-GET-lead__lead-do_not_call-entry}{#lead-GET-lead__lead-do_not_email-entry}{#lead-GET-lead__lead-do_not_share-entry}{#lead-GET-lead__lead-email-entry}{#lead-GET-lead__lead-external_id-entry}{#lead-GET-lead__lead-external_system-entry}{#lead-GET-lead__lead-first_name-entry}{#lead-GET-lead__lead-industry-entry}{#lead-GET-lead__lead-last_name-entry}{#lead-GET-lead__lead-lead_group-entry}{#lead-GET-lead__lead-lead_group.name-entry}{#lead-GET-lead__lead-lead_group.sys_id-entry}{#lead-GET-lead__lead-lead_line_items-entry}{#lead-GET-lead__lead-lead_line_items.external_id-entry}{#lead-GET-lead__lead-lead_line_items.external_system-entry}{#lead-GET-lead__lead-lead_line_items.lead-entry}{#lead-GET-lead__lead-lead_line_items.lead.name-entry}{#lead-GET-lead__lead-lead_line_items.lead.sys_id-entry}{#lead-GET-lead__lead-lead_line_items.number-entry}{#lead-GET-lead__lead-lead_line_items.product_offering-ph}{#lead-GET-lead__lead-lead_line_items.product_offering.code-entry}{#lead-GET-lead__lead-lead_line_items.product_offering.name-entry}{#lead-GET-lead__lead-lead_line_items.product_offering.sys_id-entry}{#lead-GET-lead__lead-lead_line_items.quantity-entry}{#lead-GET-lead__lead-lead_line_items.sys_created_by-entry}{#lead-GET-lead__lead-lead_line_items.sys_created_on-entry}{#lead-GET-lead__lead-lead_line_items.sys_created_on.display_value-entry}{#lead-GET-lead__lead-lead_line_items.sys_created_on.value-entry}{#lead-GET-lead__lead-lead_line_items.sys_domain-entry}{#lead-GET-lead__lead-lead_line_items.sys_domain_path-entry}{#lead-GET-lead__lead-lead_line_items.sys_id-entry}{#lead-GET-lead__lead-lead_line_items.sys_mod_count-entry}{#lead-GET-lead__lead-lead_line_items.sys_tags-entry}{#lead-GET-lead__lead-lead_line_items.sys_updated_by-entry}{#lead-GET-lead__lead-lead_line_items.sys_updated_on-entry}{#lead-GET-lead__lead-lead_line_items.sys_updated_on.display_value-entry}{#lead-GET-lead__lead-lead_line_items.sys_updated_on.value-entry}{#lead-GET-lead__lead-lead_line_items.unit_of_measurement-entry}{#lead-GET-lead__lead-lead_line_items.unit_of_measurement.name-entry}{#lead-GET-lead__lead-lead_line_items.unit_of_measurement.sys_id-entry}{#lead-GET-lead__lead-lead_line_items.work_notes-entry}{#lead-GET-lead__lead-lead_line_items.work_notes.author-entry}{#lead-GET-lead__lead-lead_line_items.work_notes.date-entry}{#lead-GET-lead__lead-lead_line_items.work_notes.text-entry}{#lead-GET-lead__lead-lead_rating-entry}{#lead-GET-lead__lead-lead_score-entry}{#lead-GET-lead__lead-lead_source-entry}{#lead-GET-lead__lead-lead_type-entry}{#lead-GET-lead__lead-middle_name-entry}{#lead-GET-lead__lead-mobile_phone-entry}{#lead-GET-lead__lead-number-entry}{#lead-GET-lead__lead-other_reason-entry}{#lead-GET-lead__lead-owner-entry}{#lead-GET-lead__lead-owner.name-entry}{#lead-GET-lead__lead-owner.sys_id-entry}{#lead-GET-lead__lead-reason-entry}{#lead-GET-lead__lead-short_description-entry}{#lead-GET-lead__lead-similar_lead-entry}{#lead-GET-lead__lead-similar_lead.name-entry}{#lead-GET-lead__lead-similar_lead.sys_id-entry}{#lead-GET-lead__lead-stage-entry}{#lead-GET-lead__lead-state-entry}{#lead-GET-lead__lead-street-entry}{#lead-GET-lead__lead-sys_class_name-entry}{#lead-GET-lead__lead-sys_created_by-entry}{#lead-GET-lead__lead-sys_created_on-entry}{#lead-GET-lead__lead-sys_created_on.display_value-entry}{#lead-GET-lead__lead-sys_created_on.value-entry}{#lead-GET-lead__lead-sys_domain-entry}{#lead-GET-lead__lead-sys_domain_path-entry}{#lead-GET-lead__lead-sys_id-entry}{#lead-GET-lead__lead-sys_mod_count-entry}{#lead-GET-lead__lead-sys_tags-entry}{#lead-GET-lead__lead-sys_updated_by-entry}{#lead-GET-lead__lead-sys_updated_on-entry}{#lead-GET-lead__lead-sys_updated_on.display_value-entry}{#lead-GET-lead__lead-sys_updated_on.value-entry}{#lead-GET-lead__lead-title-entry}{#lead-GET-lead__lead-website-entry}{#lead-GET-lead__lead-work_notes-entry}{#lead-GET-lead__lead-work_notes.author-entry}{#lead-GET-lead__lead-work_notes.date-entry}{#lead-GET-lead__lead-work_notes.text-entry}{#lead-GET-lead__lead-zip-entry} | Name | Description | |-|-| | account | Account linked to the lead. Data type: Object "account": { "name": "String", "sys_id": "String" } | | account.name | Name of the account. Data type: String | | account.sys_id | Sys_id of the associated account record. Data type: String Table: Account \[customer_account\] | | business_phone | Lead's business phone number. Data type: String | | city | City in which the lead resides. Data type: String | | closed_date | Date and time when the lead was closed. Data type: Object "closed_date": { "display_value": "String", "value": "String" } | | closed_date.​display_value | Date and time as displayed in the UI. Data type: String Format: User's format and time zone. | | closed_date.value | Date and time that the lead closed as defined in the associated record. Data type: String Format: UTC | | company | Lead's company name. Data type: String | | consumer | Consumer associated with the lead. Data type: Object "consumer": { "name": "String", "sys_id": "String" } | | consumer.name | Name of the associated consumer. Data type: String | | consumer.sys_id | Sys_id of the associated consumer record. Data type: String Table: Consumer \[csm_consumer\] | | contact | Contact associated with the lead account. Data type: Object "contact": { "name": "String", "sys_id": "String" } | | contact.name | Contact's name. Data type: String | | contact.sys_id | Sys_id of the associated contact record. Data type: String Table: Contact \[customer_contact\] | | country | Country in which the lead resides. Data type: String | | do_not_call | Flag that indicates whether the mode of communication is by phone. Valid values: * true: Can call contact. * false: Don't call contact. Data type: Boolean | | do_not_email | Flag that indicates whether the mode of communication is by email. Valid values: * true: Can email contact. * false: Don't email contact. Data type: Boolean | | do_not_share | Flag that indicates whether the lead details can be shared. Valid values: * true: Lead details can be shared. * false: Lead details can't be shared. Data type: Boolean | | email | Lead's email address. Data type: String | | external_id | ID used by the system that generated the lead to identify the lead in the associated system. Data type: String | | external_system | Name of the external system associated with the lead, such as HubSpot or pipedrive. Data type: String | | first_name | First name of the contact associated with the lead. Data type: String | | industry | Industry to which the lead belongs. Data type: String Table: Located in the industry field of the Account \[customer_account\] table. | | last_name | Last name of the contact associated with the lead. Data type: String | | lead_group | Group to which the lead belongs. Data type: Object "lead_group": { "name: "String", "sys_id": "String" } | | lead_group.name | Lead group's name. Data type: String | | lead_group.sys_id | Sys_id of the lead group record. Data type: String Table: Group \[sys_user_group\] | | lead_line_items | Details of the lead line items associated with the lead. Data type: Array of Objects "lead_line_items": [ { "external_id": "String", "external_system": "String", "lead": {Object}, "number": "String", "product_offering": {Object}, "quantity": Number, "sys_created_by": "String", "sys_created_on {Object}, "sys_domain": "String", "sys_domain_path": "String", "sys_id": "String", "sys_mod_count": Number, "sys_tags": [Array], "sys_updated_by: "String", "sys_updated_on: {Object}, "unit_of_measurement": {Object}, "work_notes": [Array] } ] | | lead_line_items.​external_id | ID used by the system that generated the lead line item to identify the line item in the associated system. Data type: String | | lead_line_items.​external_system | Name of the external system associated with the lead line item, such as HubSpot or pipedrive. Data type: String | | lead_line_items.​lead | Details about the lead associated with the line item. Data type: Object "lead: { "name": "String", "sys_id": "String" } | | lead_line_items.​lead.name | Associated lead's name. Data type: String | | lead_line_items.​lead.sys_id | Sys_id of the associated lead record. Data type: String | | lead_line_items.​number | Unique system-generated number of the lead line item record. Data type: String | | lead_line_items.​product_offering | Information about the product offering associated with the lead line item. Data type: Object "product_offering": { "code": " String", "name": "String", "sys_id": "String" } | | lead_line_items.​product_offering.code | Code linked to the product offering. Note: This is a system-generated alphanumeric number based on the product name. Although system generated, you can edit the code to represent a SKU or any other industry specific product codes. Data type: String | | lead_line_items.​product_offering.name | Product offering's name. Data type: String | | lead_line_items.​product_offering.sys_id | Sys_id of the product offering record associated with the lead line item. Data type: String Table: Product Offering \[sn_prd_pm_product_offering\] | | lead_line_items.​quantity | Quantity of items the lead wants to purchase of the associated product offering. Data type: Number (Integer) | | lead_line_items.​sys_created_by | User name of the person that created the lead line item. Data type: String | | lead_line_items.​sys_created_on | System-generated date and time that the lead line item was created. Data type: Object "sys_created_on": { "display_value": "String", "value": "String" } | | lead_line_items.​sys_created_on.display_value | Date and time that the lead line item was created. Data type: String Format: Default instance format and time zone | | lead_line_items.​sys_created_on.value | Date and time that the lead line item was created. Data type: String Format: UTC | | lead_line_items.​sys_domain | Sys_id of the domain record to which the lead line item belongs. Note: This parameter is only returned in the response if domain separation is enabled. Data type: String | | lead_line_items.sys_domain_path | Path of the domain to which the lead line item belongs. Note: This parameter is only returned in the response if domain separation is enabled. Data type: String | | lead_line_items.​sys_id | Sys_id of the lead line item record. Data type: String | | lead_line_items.​sys_mod_count | Number of times the associated lead line item record has been modified. Data type: Number (Integer) | | lead_line_items.​sys_tags | List of system tags associated with the lead line item. Data type: Array | | lead_line_items.​sys_updated_by | User name of the person that last updated the associated lead line item. Data type: String | | lead_line_items.​sys_updated_on | System-generated date and time when the lead line item was last updated. Data type: Object "sys_created_on": { "display_value": "String", "value": "String" } | | lead_line_items.​sys_updated_on.​display_value | Date and time that the lead line item was last updated. Data type: String Format: Default instance format and time zone | | lead_line_items.​sys_updated_on.​value | Date and time that the lead line item was last updated. Data type: String Format: UTC | | lead_line_items.​unit_of_measurement | Details of the measuring unit of lead line item. Data type: Object "unit_of_measurement": { "name": "String", "sys_id": "String" } | | lead_line_items.​unit_of_measurement.​name | Name of the measuring unit such as, each or cubic foot. Data type: String | | lead_line_items.​unit_of_measurement.​sys_id | Sys_id of the record that describes the measuring unit. Data type: String Table: Unit of Measure \[sn_prd_pm_uom\] | | lead_line_items.​work_notes | List that describes the work notes created for the lead line item. Data type: Array of Objects "work_notes": [ { "author": "String", "date": "String", "text": "String" } ] | | lead_line_items.​work_notes.​author | User name of the person that authored the associated work note. Data type: String | | lead_line_items.​work_notes.​date | Date that the note was created. Data type: String | | lead_line_items.​work_notes.​text | Text of the note made by the author. Data type: String | | lead_rating | Rating for the lead such as, 100_cold, 200_warm, 300_hot, or 400_super_hot. Note: This is a choice field. It must contain one of the choice items defined in the lead_rating field of the Leads table. Data type: String | | lead_score | Score for the lead. Data type: Decimal Range: 1 to 100 | | lead_source | Originator of the lead. Note: This is a choice field. It must contain one of the choice items defined in the lead_source field of the Leads table. Data type: String | | lead_type | Type of lead, such as New Business or Existing Business. Note: This is a choice field. It must contain one of the choice items defined in the lead_type field of the Leads table. Data type: String | | middle_name | Middle name of the contact for the lead. Data type: String | | mobile_phone | Phone number of the contact for the lead. Data type: String | | number | Unique system-generated number of the lead record. Data type: String | | other_reason | Additional reason for the lead disqualification. Data type: String Max length: 160 characters | | owner | Details of the person associated with the lead. Data type: Object "owner": { "name": "String", "sys_id": "String" } | | owner.name | Name of the person that owns the lead. Data type: String | | owner.sys_id | Sys_id of the user record of the person that owns the lead. Data type: String Table: User \[sys_user\] | | reason | Reason for the lead disqualification such as, Disqualify. Data type: String Max length: 40 characters | | short_description | Short description of the lead. Data type: String Max length: 160 characters | | similar_lead | Details on any similar lead. Use this for possible lead disqualification. Data type: Object "similar_lead": { "name": "String", "sys_id": "String" } | | similar_lead.name | Name of the duplicate lead. Data type: String | | similar_lead.sys_id | Sys_id of the lead record that is a possible duplicate lead. Data type: String Table: Lead \[sn_lead_mgmt_core_lead\] | | stage | Stage of the lead such as, 100_new. Note: This is a choice field. It must contain one of the choice items defined in the stage field of the Leads table. Data type: String | | state | State in which the lead resides. Data type: String | | street | Street on which the lead resides. Data type: String | | sys_class_name | System-generated class name of the Lead table. Data type: String | | sys_created_by | User name of the person that created the lead. Data type: String | | sys_created_on | System-generated date and time that the lead was created. Data type: Object "sys_created_on": { "display_value": "String", "value": "String" } | | sys_created_on.​display_value | Date and time when the lead was created. Data type: String Format: Default instance format and time zone | | sys_created_on.​value | Date and time when the lead was created. Data type: String Format: UTC | | sys_domain | Sys_id of the domain record to which the lead belongs. Note: This parameter is only returned in the response if domain separation is enabled. Data type: String | | sys_domain_path | Path of the domain to which the lead belongs. Note: This parameter is only returned in the response if domain separation is enabled. Data type: String | | sys_id | Sys_id of the lead record. Data type: String Table: Lead \[sn_lead_mgmt_core_lead\] | | sys_mod_count | Number of times the associated lead record has been modified. Data type: Number (Integer) | | sys_tags | List of system tags associated with the lead. You can use these tags to categorize leads. Data type: Array | | sys_updated_by | User name of the person that last updated the lead record. Data type: String | | sys_updated_on | System-generated date and time when the lead was last updated. Data type: Object "sys_created_on": { "display_value": "String", "value": "String" } | | sys_updated_on.​display_value | Date and time that the lead was last updated. Data type: String Format: Instance's default format and time zone | | sys_updated_on.​value | Date and time that the lead was last updated. Data type: String Format: UTC | | title | Lead's title. Data type: String | | website | Lead's website URL. Data type: String | | work_notes | List of work notes created for the lead. Data type: Array of Objects "work_notes": [ { "author": "String", "date": "String", "text": "String" } ] | | work_notes.​author | User name of the person that authored the associated work note. Data type: String | | work_notes.​date | Date that the note was created. Data type: String | | work_notes.​text | Text of the note made by the author. Data type: String | | zip | Zip code of the associated lead. Data type: String | [ ] ### cURL request The following code example shows how to pass query parameters to specify the leads to return. curl "https://instance.service-now.com/api/sn_lead_mgmt_core/lead?sysparm_query=stage%3D400_closed_won&sysparm_fields=sys_id%2Cfirst_name%2Clast_name%2Cshort_description%2Cstage%2Clead_line_items&sysparm_offset=2" \ --request GET \ --header "Accept:application/json" \ --user "username":"password" Leads are return in an array of objects: [ { "short_description": "Looking for a quote on preventative maintenance plans for their corporate office building elevators.", "reason": null, "country": "USA", "closed_date": null, "city": "San Francisco", "lead_source": "inbound_phone", "external_id": null, "industry": "manufacturing", "sys_updated_on": { "value": "2024-05-31 11:01:55", "display_value": "2024-05-31 04:01:55" }, "title": "Director of Building operations", "sys_class_name": "Lead", "number": "LEAD0000001", "sys_id": "856b6a95ffde8210b85dffffffffffd7", "business_phone": "+1 (555) 123-4567", "similar_lead": null, "sys_updated_by": "admin", "mobile_phone": null, "street": "789, Industrial drive", "sys_created_on": { "value": "2024-05-20 10:32:41", "display_value": "2024-05-20 03:32:41" }, "contact": null, "company": "Lee Manufacturing Inc", "state": "CA", "first_name": "James", "email": "james.wilson@email.com", "consumer": null, "sys_created_by": "admin", "zip": "94016", "owner": { "sys_id": "60058fe943fe3110d6c6cd60afb8f203", "name": "Max Blaze" }, "website": null, "lead_group": null, "sys_mod_count": 1, "last_name": "Wilson", "other_reason": null, "middle_name": null, "sys_tags": null, "do_not_share": false, "lead_score": 92, "stage": "300_nurturing", "do_not_email": false, "lead_type": null, "work_notes": [ { "author": "Abel Tuter", "date": "2024-12-04 06:52:07", "text": "Work notes for lead" } ], "do_not_call": false, "lead_rating": "400_super_hot", "account": null, "external_system": null, "lead_line_items": [ { "quantity": 6, "product_offering": { "sys_id": "32619d9fd0a63110f8770dbf976be1f9", "name": "Safety Test Coverage", "code": "SAFETSTCVG1" }, "sys_mod_count": 0, "external_id": null, "sys_updated_on": { "value": "2024-05-20 10:38:41", "display_value": "2024-05-20 03:38:41" }, "sys_tags": null, "lead": { "sys_id": "856b6a95ffde8210b85dffffffffffd7", "name": "LEAD0000001" }, "number": "LEADL0000003", "sys_id": "013daa19ffde8210b85dffffffffff82", "unit_of_measurement": { "sys_id": "cb2795d553020110286eddeeff7b12ff", "name": "Each" }, "sys_updated_by": "admin", "sys_created_on": { "value": "2024-05-20 10:38:41", "display_value": "2024-05-20 03:38:41" }, "work_notes": null, "sys_created_by": "admin", "external_system": null } ] }, { "short_description": "Partner referral for a company interested in a reliable internet bundle with strong security features for their office.", "reason": null, "country": "USA", "closed_date": null, "city": "San Francisco", "lead_source": "partner_referral", "external_id": null, "industry": "technology_services", "sys_updated_on": { "value": "2024-05-20 10:53:59", "display_value": "2024-05-20 03:53:59" }, "title": "IT Director", "sys_class_name": "Lead", "number": "LEAD0000002", "sys_id": "e71fa6d9ffde8210b85dffffffffff51", "business_phone": "(626) 722-6969", "similar_lead": null, "sys_updated_by": "admin", "mobile_phone": null, "street": "747 Howard St", "sys_created_on": { "value": "2024-05-20 10:49:12", "display_value": "2024-05-20 03:49:12" }, "contact": { "sys_id": "4d147a386f0331003b3c498f5d3ee437", "name": "" }, "company": "Boxeo", "state": "CA", "first_name": "Julie", "email": "julie.lewis@example.com", "consumer": null, "sys_created_by": "admin", "zip": "94013", "owner": { "sys_id": "60058fe943fe3110d6c6cd60afb8f203", "name": "Max Blaze" }, "website": null, "lead_group": null, "sys_mod_count": 0, "last_name": "Lewis", "other_reason": null, "middle_name": null, "sys_tags": null, "do_not_share": false, "lead_score": 78, "stage": "400_closed_won", "do_not_email": false, "lead_type": null, "work_notes": [ { "author": "Abel Tuter", "date": "2024-12-03 03:52:51", "text": "Work noted for LEAD0000002" } ], "do_not_call": false, "lead_rating": "200_warm", "account": { "sys_id": "86837a386f0331003b3c498f5d3ee4ca", "name": "" }, "external_system": null, "lead_line_items": [ { "quantity": 50, "product_offering": { "sys_id": "0b61dd9fd0a63110f8770dbf976be171", "name": "Solana Modem M Series", "code": "SOLANAMODE2" }, "sys_mod_count": 0, "external_id": null, "sys_updated_on": { "value": "2024-05-20 10:51:57", "display_value": "2024-05-20 03:51:57" }, "sys_tags": null, "lead": { "sys_id": "e71fa6d9ffde8210b85dffffffffff51", "name": "LEAD0000002" }, "number": "LEADL0000009", "sys_id": "2130fa1dffde8210b85dffffffffffff", "unit_of_measurement": { "sys_id": "cb2795d553020110286eddeeff7b12ff", "name": "Each" }, "sys_updated_by": "admin", "sys_created_on": { "value": "2024-05-20 10:51:25", "display_value": "2024-05-20 03:51:25" }, "work_notes": null, "sys_created_by": "admin", "external_system": null } ] } ] ## lead - GET /sn_lead_mgmt_core/lead/{sys_id} {#ariaid-title3} Returns the lead record and all associated lead line items for the specified sys_id. This endpoint retrieves information from the following tables: * Lead \[sn_lead_mgmt_core_lead\] * Lead Line Item \[sn_lead_mgmt_core_lead_line_item\] {#lead-GET-lead-sys_id__ul_w1b_f1m_rdc} ### URL format Versioned URL: /api/sn_lead_mgmt_core/{api_version}/lead/{sys_id} Default URL: /api/sn_lead_mgmt_core/{api_version}/lead/{sys_id} Note: Available versions are specified in the [REST API Explorer](https://www.servicenow.com/docs/sYu7wNPLliq5~U4ai0aL_g "In this tutorial you will use the REST API Explorer to test the ServiceNow REST APIs."). For scripted REST APIs there is additional version information on the [Scripted REST Service form](https://www.servicenow.com/docs/cspfk_WKHcwVeXgD~XuntQ "The scripted REST API feature allows application developers to build custom web service APIs."). ### Supported request parameters {#lead-GET-lead-sys_id__entry__2}{#lead-GET-lead-sys_id__version-not_optional-RESTAPI} | Name | Description | |-|-| | api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest. Data type: String | | sys_id | Sys_id of the lead to retrieve. Data type: String Table: Lead \[sn_lead_mgmt_core_lead\] | [Table 7. Path parameters] {#lead-GET-lead-sys_id__entry__8} | Name | Description | |-|-| | None | | [Table 8. Query parameters] {#lead-GET-lead-sys_id__entry__12} | Name | Description | |-|-| | None | | [Table 9. Request body parameters (XML or JSON)] ### Headers The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/5p0ILxi5PWo5cXuREsZCAQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#lead-GET-lead-sys_id__entry__16}{#lead-GET-lead-sys_id__accept-JSON-only-entry-RESTAPI} | Header | Description | |-|-| | Accept | Data format of the response body. Only supports application/json. | [Table 10. Request headers] {#lead-GET-lead-sys_id__entry__20} | Header | Description | |-|-| | None | | [Table 11. Response headers] ### Status codes The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://www.servicenow.com/docs/5p0ILxi5PWo5cXuREsZCAQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#lead-GET-lead-sys_id__entry__24}{#lead-GET-lead-sys_id__entry-200-status-code}{#lead-GET-lead-sys_id__entry-403-status-code}{#lead-GET-lead-sys_id__entry-404-status-code}{#lead-GET-lead-sys_id__entry-500-status-code} | Status code | Description | |-|-| | 200 | Successful. The request was successfully processed. | | 403 | Forbidden. The user doesn't have access rights to the specified record. | | 404 | Not found. The requested item wasn't found. | | 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. | [Table 12. Status codes] ### Response body parameters {#lead-GET-lead-sys_id__table_h4v_1hp_sdc__entry__2}{#lead-GET-lead-sys_id__lead-account-entry}{#lead-GET-lead-sys_id__lead-account.name-entry}{#lead-GET-lead-sys_id__lead-account.sys_id-entry}{#lead-GET-lead-sys_id__lead-business_phone-entry}{#lead-GET-lead-sys_id__lead-city-entry}{#lead-GET-lead-sys_id__lead-closed_date-ph}{#lead-GET-lead-sys_id__lead-closed_date.display_value-entry}{#lead-GET-lead-sys_id__lead-closed_date.value-entry}{#lead-GET-lead-sys_id__lead-company-entry}{#lead-GET-lead-sys_id__lead-consumer-ph}{#lead-GET-lead-sys_id__lead-consumer.name-entry}{#lead-GET-lead-sys_id__lead-consumer.sys_id-entry}{#lead-GET-lead-sys_id__lead-contact-ph}{#lead-GET-lead-sys_id__lead-contact.name-entry}{#lead-GET-lead-sys_id__lead-contact.sys_id-entry}{#lead-GET-lead-sys_id__lead-country-entry}{#lead-GET-lead-sys_id__lead-do_not_call-entry}{#lead-GET-lead-sys_id__lead-do_not_email-entry}{#lead-GET-lead-sys_id__lead-do_not_share-entry}{#lead-GET-lead-sys_id__lead-email-entry}{#lead-GET-lead-sys_id__lead-external_id-entry}{#lead-GET-lead-sys_id__lead-external_system-entry}{#lead-GET-lead-sys_id__lead-first_name-entry}{#lead-GET-lead-sys_id__lead-industry-entry}{#lead-GET-lead-sys_id__lead-last_name-entry}{#lead-GET-lead-sys_id__lead-lead_group-entry}{#lead-GET-lead-sys_id__lead-lead_group.name-entry}{#lead-GET-lead-sys_id__lead-lead_group.sys_id-entry}{#lead-GET-lead-sys_id__lead-lead_line_items-entry}{#lead-GET-lead-sys_id__lead-lead_line_items.external_id-entry}{#lead-GET-lead-sys_id__lead-lead_line_items.external_system-entry}{#lead-GET-lead-sys_id__lead-lead_line_items.lead-entry}{#lead-GET-lead-sys_id__lead-lead_line_items.lead.name-entry}{#lead-GET-lead-sys_id__lead-lead_line_items.lead.sys_id-entry}{#lead-GET-lead-sys_id__lead-lead_line_items.number-entry}{#lead-GET-lead-sys_id__lead-lead_line_items.product_offering-ph}{#lead-GET-lead-sys_id__lead-lead_line_items.product_offering.code-entry}{#lead-GET-lead-sys_id__lead-lead_line_items.product_offering.name-entry}{#lead-GET-lead-sys_id__lead-lead_line_items.product_offering.sys_id-entry}{#lead-GET-lead-sys_id__lead-lead_line_items.quantity-entry}{#lead-GET-lead-sys_id__lead-lead_line_items.sys_created_by-entry}{#lead-GET-lead-sys_id__lead-lead_line_items.sys_created_on-entry}{#lead-GET-lead-sys_id__lead-lead_line_items.sys_created_on.display_value-entry}{#lead-GET-lead-sys_id__lead-lead_line_items.sys_created_on.value-entry}{#lead-GET-lead-sys_id__lead-lead_line_items.sys_domain-entry}{#lead-GET-lead-sys_id__lead-lead_line_items.sys_domain_path-entry}{#lead-GET-lead-sys_id__lead-lead_line_items.sys_id-entry}{#lead-GET-lead-sys_id__lead-lead_line_items.sys_mod_count-entry}{#lead-GET-lead-sys_id__lead-lead_line_items.sys_tags-entry}{#lead-GET-lead-sys_id__lead-lead_line_items.sys_updated_by-entry}{#lead-GET-lead-sys_id__lead-lead_line_items.sys_updated_on-entry}{#lead-GET-lead-sys_id__lead-lead_line_items.sys_updated_on.display_value-entry}{#lead-GET-lead-sys_id__lead-lead_line_items.sys_updated_on.value-entry}{#lead-GET-lead-sys_id__lead-lead_line_items.unit_of_measurement-entry}{#lead-GET-lead-sys_id__lead-lead_line_items.unit_of_measurement.name-entry}{#lead-GET-lead-sys_id__lead-lead_line_items.unit_of_measurement.sys_id-entry}{#lead-GET-lead-sys_id__lead-lead_line_items.work_notes-entry}{#lead-GET-lead-sys_id__lead-lead_line_items.work_notes.author-entry}{#lead-GET-lead-sys_id__lead-lead_line_items.work_notes.date-entry}{#lead-GET-lead-sys_id__lead-lead_line_items.work_notes.text-entry}{#lead-GET-lead-sys_id__lead-lead_rating-entry}{#lead-GET-lead-sys_id__lead-lead_score-entry}{#lead-GET-lead-sys_id__lead-lead_source-entry}{#lead-GET-lead-sys_id__lead-lead_type-entry}{#lead-GET-lead-sys_id__lead-middle_name-entry}{#lead-GET-lead-sys_id__lead-mobile_phone-entry}{#lead-GET-lead-sys_id__lead-number-entry}{#lead-GET-lead-sys_id__lead-other_reason-entry}{#lead-GET-lead-sys_id__lead-owner-entry}{#lead-GET-lead-sys_id__lead-owner.name-entry}{#lead-GET-lead-sys_id__lead-owner.sys_id-entry}{#lead-GET-lead-sys_id__lead-reason-entry}{#lead-GET-lead-sys_id__lead-short_description-entry}{#lead-GET-lead-sys_id__lead-similar_lead-entry}{#lead-GET-lead-sys_id__lead-similar_lead.name-entry}{#lead-GET-lead-sys_id__lead-similar_lead.sys_id-entry}{#lead-GET-lead-sys_id__lead-stage-entry}{#lead-GET-lead-sys_id__lead-state-entry}{#lead-GET-lead-sys_id__lead-street-entry}{#lead-GET-lead-sys_id__lead-sys_class_name-entry}{#lead-GET-lead-sys_id__lead-sys_created_by-entry}{#lead-GET-lead-sys_id__lead-sys_created_on-entry}{#lead-GET-lead-sys_id__lead-sys_created_on.display_value-entry}{#lead-GET-lead-sys_id__lead-sys_created_on.value-entry}{#lead-GET-lead-sys_id__lead-sys_domain-entry}{#lead-GET-lead-sys_id__lead-sys_domain_path-entry}{#lead-GET-lead-sys_id__lead-sys_id-entry}{#lead-GET-lead-sys_id__lead-sys_mod_count-entry}{#lead-GET-lead-sys_id__lead-sys_tags-entry}{#lead-GET-lead-sys_id__lead-sys_updated_by-entry}{#lead-GET-lead-sys_id__lead-sys_updated_on-entry}{#lead-GET-lead-sys_id__lead-sys_updated_on.display_value-entry}{#lead-GET-lead-sys_id__lead-sys_updated_on.value-entry}{#lead-GET-lead-sys_id__lead-title-entry}{#lead-GET-lead-sys_id__lead-website-entry}{#lead-GET-lead-sys_id__lead-work_notes-entry}{#lead-GET-lead-sys_id__lead-work_notes.author-entry}{#lead-GET-lead-sys_id__lead-work_notes.date-entry}{#lead-GET-lead-sys_id__lead-work_notes.text-entry}{#lead-GET-lead-sys_id__lead-zip-entry} | Name | Description | |-|-| | account | Account linked to the lead. Data type: Object "account": { "name": "String", "sys_id": "String" } | | account.name | Name of the account. Data type: String | | account.sys_id | Sys_id of the associated account record. Data type: String Table: Account \[customer_account\] | | business_phone | Lead's business phone number. Data type: String | | city | City in which the lead resides. Data type: String | | closed_date | Date and time when the lead was closed. Data type: Object "closed_date": { "display_value": "String", "value": "String" } | | closed_date.​display_value | Date and time as displayed in the UI. Data type: String Format: User's format and time zone. | | closed_date.value | Date and time that the lead closed as defined in the associated record. Data type: String Format: UTC | | company | Lead's company name. Data type: String | | consumer | Consumer associated with the lead. Data type: Object "consumer": { "name": "String", "sys_id": "String" } | | consumer.name | Name of the associated consumer. Data type: String | | consumer.sys_id | Sys_id of the associated consumer record. Data type: String Table: Consumer \[csm_consumer\] | | contact | Contact associated with the lead account. Data type: Object "contact": { "name": "String", "sys_id": "String" } | | contact.name | Contact's name. Data type: String | | contact.sys_id | Sys_id of the associated contact record. Data type: String Table: Contact \[customer_contact\] | | country | Country in which the lead resides. Data type: String | | do_not_call | Flag that indicates whether the mode of communication is by phone. Valid values: * true: Can call contact. * false: Don't call contact. Data type: Boolean | | do_not_email | Flag that indicates whether the mode of communication is by email. Valid values: * true: Can email contact. * false: Don't email contact. Data type: Boolean | | do_not_share | Flag that indicates whether the lead details can be shared. Valid values: * true: Lead details can be shared. * false: Lead details can't be shared. Data type: Boolean | | email | Lead's email address. Data type: String | | external_id | ID used by the system that generated the lead to identify the lead in the associated system. Data type: String | | external_system | Name of the external system associated with the lead, such as HubSpot or pipedrive. Data type: String | | first_name | First name of the contact associated with the lead. Data type: String | | industry | Industry to which the lead belongs. Data type: String Table: Located in the industry field of the Account \[customer_account\] table. | | last_name | Last name of the contact associated with the lead. Data type: String | | lead_group | Group to which the lead belongs. Data type: Object "lead_group": { "name: "String", "sys_id": "String" } | | lead_group.name | Lead group's name. Data type: String | | lead_group.sys_id | Sys_id of the lead group record. Data type: String Table: Group \[sys_user_group\] | | lead_line_items | Details of the lead line items associated with the lead. Data type: Array of Objects "lead_line_items": [ { "external_id": "String", "external_system": "String", "lead": {Object}, "number": "String", "product_offering": {Object}, "quantity": Number, "sys_created_by": "String", "sys_created_on {Object}, "sys_domain": "String", "sys_domain_path": "String", "sys_id": "String", "sys_mod_count": Number, "sys_tags": [Array], "sys_updated_by: "String", "sys_updated_on: {Object}, "unit_of_measurement": {Object}, "work_notes": [Array] } ] | | lead_line_items.​external_id | ID used by the system that generated the lead line item to identify the line item in the associated system. Data type: String | | lead_line_items.​external_system | Name of the external system associated with the lead line item, such as HubSpot or pipedrive. Data type: String | | lead_line_items.​lead | Details about the lead associated with the line item. Data type: Object "lead: { "name": "String", "sys_id": "String" } | | lead_line_items.​lead.name | Associated lead's name. Data type: String | | lead_line_items.​lead.sys_id | Sys_id of the associated lead record. Data type: String | | lead_line_items.​number | Unique system-generated number of the lead line item record. Data type: String | | lead_line_items.​product_offering | Information about the product offering associated with the lead line item. Data type: Object "product_offering": { "code": " String", "name": "String", "sys_id": "String" } | | lead_line_items.​product_offering.code | Code linked to the product offering. Note: This is a system-generated alphanumeric number based on the product name. Although system generated, you can edit the code to represent a SKU or any other industry specific product codes. Data type: String | | lead_line_items.​product_offering.name | Product offering's name. Data type: String | | lead_line_items.​product_offering.sys_id | Sys_id of the product offering record associated with the lead line item. Data type: String Table: Product Offering \[sn_prd_pm_product_offering\] | | lead_line_items.​quantity | Quantity of items the lead wants to purchase of the associated product offering. Data type: Number (Integer) | | lead_line_items.​sys_created_by | User name of the person that created the lead line item. Data type: String | | lead_line_items.​sys_created_on | System-generated date and time that the lead line item was created. Data type: Object "sys_created_on": { "display_value": "String", "value": "String" } | | lead_line_items.​sys_created_on.display_value | Date and time that the lead line item was created. Data type: String Format: Default instance format and time zone | | lead_line_items.​sys_created_on.value | Date and time that the lead line item was created. Data type: String Format: UTC | | lead_line_items.​sys_domain | Sys_id of the domain record to which the lead line item belongs. Note: This parameter is only returned in the response if domain separation is enabled. Data type: String | | lead_line_items.sys_domain_path | Path of the domain to which the lead line item belongs. Note: This parameter is only returned in the response if domain separation is enabled. Data type: String | | lead_line_items.​sys_id | Sys_id of the lead line item record. Data type: String | | lead_line_items.​sys_mod_count | Number of times the associated lead line item record has been modified. Data type: Number (Integer) | | lead_line_items.​sys_tags | List of system tags associated with the lead line item. Data type: Array | | lead_line_items.​sys_updated_by | User name of the person that last updated the associated lead line item. Data type: String | | lead_line_items.​sys_updated_on | System-generated date and time when the lead line item was last updated. Data type: Object "sys_created_on": { "display_value": "String", "value": "String" } | | lead_line_items.​sys_updated_on.​display_value | Date and time that the lead line item was last updated. Data type: String Format: Default instance format and time zone | | lead_line_items.​sys_updated_on.​value | Date and time that the lead line item was last updated. Data type: String Format: UTC | | lead_line_items.​unit_of_measurement | Details of the measuring unit of lead line item. Data type: Object "unit_of_measurement": { "name": "String", "sys_id": "String" } | | lead_line_items.​unit_of_measurement.​name | Name of the measuring unit such as, each or cubic foot. Data type: String | | lead_line_items.​unit_of_measurement.​sys_id | Sys_id of the record that describes the measuring unit. Data type: String Table: Unit of Measure \[sn_prd_pm_uom\] | | lead_line_items.​work_notes | List that describes the work notes created for the lead line item. Data type: Array of Objects "work_notes": [ { "author": "String", "date": "String", "text": "String" } ] | | lead_line_items.​work_notes.​author | User name of the person that authored the associated work note. Data type: String | | lead_line_items.​work_notes.​date | Date that the note was created. Data type: String | | lead_line_items.​work_notes.​text | Text of the note made by the author. Data type: String | | lead_rating | Rating for the lead such as, 100_cold, 200_warm, 300_hot, or 400_super_hot. Note: This is a choice field. It must contain one of the choice items defined in the lead_rating field of the Leads table. Data type: String | | lead_score | Score for the lead. Data type: Decimal Range: 1 to 100 | | lead_source | Originator of the lead. Note: This is a choice field. It must contain one of the choice items defined in the lead_source field of the Leads table. Data type: String | | lead_type | Type of lead, such as New Business or Existing Business. Note: This is a choice field. It must contain one of the choice items defined in the lead_type field of the Leads table. Data type: String | | middle_name | Middle name of the contact for the lead. Data type: String | | mobile_phone | Phone number of the contact for the lead. Data type: String | | number | Unique system-generated number of the lead record. Data type: String | | other_reason | Additional reason for the lead disqualification. Data type: String Max length: 160 characters | | owner | Details of the person associated with the lead. Data type: Object "owner": { "name": "String", "sys_id": "String" } | | owner.name | Name of the person that owns the lead. Data type: String | | owner.sys_id | Sys_id of the user record of the person that owns the lead. Data type: String Table: User \[sys_user\] | | reason | Reason for the lead disqualification such as, Disqualify. Data type: String Max length: 40 characters | | short_description | Short description of the lead. Data type: String Max length: 160 characters | | similar_lead | Details on any similar lead. Use this for possible lead disqualification. Data type: Object "similar_lead": { "name": "String", "sys_id": "String" } | | similar_lead.name | Name of the duplicate lead. Data type: String | | similar_lead.sys_id | Sys_id of the lead record that is a possible duplicate lead. Data type: String Table: Lead \[sn_lead_mgmt_core_lead\] | | stage | Stage of the lead such as, 100_new. Note: This is a choice field. It must contain one of the choice items defined in the stage field of the Leads table. Data type: String | | state | State in which the lead resides. Data type: String | | street | Street on which the lead resides. Data type: String | | sys_class_name | System-generated class name of the Lead table. Data type: String | | sys_created_by | User name of the person that created the lead. Data type: String | | sys_created_on | System-generated date and time that the lead was created. Data type: Object "sys_created_on": { "display_value": "String", "value": "String" } | | sys_created_on.​display_value | Date and time when the lead was created. Data type: String Format: Default instance format and time zone | | sys_created_on.​value | Date and time when the lead was created. Data type: String Format: UTC | | sys_domain | Sys_id of the domain record to which the lead belongs. Note: This parameter is only returned in the response if domain separation is enabled. Data type: String | | sys_domain_path | Path of the domain to which the lead belongs. Note: This parameter is only returned in the response if domain separation is enabled. Data type: String | | sys_id | Sys_id of the lead record. Data type: String Table: Lead \[sn_lead_mgmt_core_lead\] | | sys_mod_count | Number of times the associated lead record has been modified. Data type: Number (Integer) | | sys_tags | List of system tags associated with the lead. You can use these tags to categorize leads. Data type: Array | | sys_updated_by | User name of the person that last updated the lead record. Data type: String | | sys_updated_on | System-generated date and time when the lead was last updated. Data type: Object "sys_created_on": { "display_value": "String", "value": "String" } | | sys_updated_on.​display_value | Date and time that the lead was last updated. Data type: String Format: Instance's default format and time zone | | sys_updated_on.​value | Date and time that the lead was last updated. Data type: String Format: UTC | | title | Lead's title. Data type: String | | website | Lead's website URL. Data type: String | | work_notes | List of work notes created for the lead. Data type: Array of Objects "work_notes": [ { "author": "String", "date": "String", "text": "String" } ] | | work_notes.​author | User name of the person that authored the associated work note. Data type: String | | work_notes.​date | Date that the note was created. Data type: String | | work_notes.​text | Text of the note made by the author. Data type: String | | zip | Zip code of the associated lead. Data type: String | [ ] {#lead-GET-lead-sys_id__table_h4v_1hp_sdc} ### cURL request The following code example shows how to retrieve the lead record with the sys_id of 856b6a95ffde8210b85dffffffffffd7. curl "https://instance.service-now.com /api/sn_lead_mgmt_core/lead/856b6a95ffde8210b85dffffffffffd7" \ --request GET \ --header "Accept:application/json" \ --user "username":"password" The following are the return results: { "short_description": "Looking for a quote on preventative maintenance plans for their corporate office building elevators.", "reason": null, "country": "USA", "closed_date": null, "city": "San Francisco", "lead_source": "inbound_phone", "external_id": null, "industry": "manufacturing", "sys_updated_on": { "value": "2024-05-31 11:01:55", "display_value": "2024-05-31 04:01:55" }, "title": "Director of Building operations", "sys_class_name": "Lead", "number": "LEAD0000001", "sys_id": "856b6a95ffde8210b85dffffffffffd7", "business_phone": "+1 (555) 123-4567", "similar_lead": null, "sys_updated_by": "abel.tuter", "mobile_phone": null, "street": "789, Industrial drive", "sys_created_on": { "value": "2024-05-20 10:32:41", "display_value": "2024-05-20 03:32:41" }, "contact": null, "company": "Lee Manufacturing Inc", "state": "CA", "first_name": "James", "email": "james.wilson@email.com", "consumer": null, "sys_created_by": "abel.tuter", "zip": "94016", "owner": { "sys_id": "60058fe943fe3110d6c6cd60afb8f203", "name": "Max Blaze" }, "website": null, "lead_group": null, "sys_mod_count": 1, "last_name": "Wilson", "other_reason": null, "middle_name": null, "sys_tags": null, "do_not_share": false, "lead_score": 92, "stage": "300_nurturing", "do_not_email": false, "lead_type": null, "work_notes": [ { "author": "Abel Tuter", "date": "2024-12-04 06:52:07", "text": "Work notes for lead" } ], "do_not_call": false, "lead_rating": "400_super_hot", "account": null, "external_system": null, "lead_line_items": [ { "quantity": 6, "product_offering": { "sys_id": "32619d9fd0a63110f8770dbf976be1f9", "name": "Safety Test Coverage", "code": "SAFETSTCVG1" }, "sys_mod_count": 0, "external_id": null, "sys_updated_on": { "value": "2024-05-20 10:38:41", "display_value": "2024-05-20 03:38:41" }, "sys_tags": null, "lead": { "sys_id": "856b6a95ffde8210b85dffffffffffd7", "name": "LEAD0000001" }, "number": "LEADL0000003", "sys_id": "013daa19ffde8210b85dffffffffff82", "unit_of_measurement": { "sys_id": "cb2795d553020110286eddeeff7b12ff", "name": "Each" }, "sys_updated_by": "abel.tuter", "sys_created_on": { "value": "2024-05-20 10:38:41", "display_value": "2024-05-20 03:38:41" }, "work_notes": null, "sys_created_by": "abel.tuter", "external_system": null } ] } ## lead - PATCH /sn_lead_mgmt_core/lead/{sys_id} {#ariaid-title4} Updates the specified lead record and its associated lead line items. You can also use this endpoint to associate new lead line items to the specified lead. This endpoint updates information in the following tables: * Lead \[sn_lead_mgmt_core_lead\] * Lead Line Item \[sn_lead_mgmt_core_lead_line_item\] {#lead-PATCH-lead__ul_ebj_kg4_sdc} Rules for passed-in parameters: * Invalid parameter names are ignored. * Invalid values for non-mandatory choice and reference fields are ignored. * If field WRITE access is denied for one or more fields, the restricted fields are ignored. * You can't insert system field values using this API. Any provided values are ignored. System fields are a part of the ignored fields list, which is configurable. * The values of the parameters account, contact, and consumer are ignored if both the account and consumer parameters are non-empty. * Unless otherwise specified, the default value for all non-passed parameters is 'null'. Note: This endpoint only modifies the specified parameters. If a parameter that exists in the current lead or lead line item record is not specified in the call, its contents remain unchanged. ### URL format Versioned URL: /api/sn_lead_mgmt_core/{api_version}/lead/{sys_id} Default URL: /api/sn_lead_mgmt_core/{api_version}/lead/{sys_id} Note: Available versions are specified in the [REST API Explorer](https://www.servicenow.com/docs/sYu7wNPLliq5~U4ai0aL_g "In this tutorial you will use the REST API Explorer to test the ServiceNow REST APIs."). For scripted REST APIs there is additional version information on the [Scripted REST Service form](https://www.servicenow.com/docs/cspfk_WKHcwVeXgD~XuntQ "The scripted REST API feature allows application developers to build custom web service APIs."). ### Supported request parameters {#lead-PATCH-lead__entry__2}{#lead-PATCH-lead__version-not_optional-RESTAPI} | Name | Description | |-|-| | api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest. Data type: String | | sys_id | Sys_id of the lead record to update. Data type: String Table: Lead \[sn_lead_mgmt_core_lead\] | [Table 13. Path parameters] {#lead-PATCH-lead__entry__8} | Name | Description | |-|-| | None | | [Table 14. Query parameters] {#lead-PATCH-lead__entry__12}{#lead-PATCH-lead__lead-account-entry}{#lead-PATCH-lead__lead-account.sys_id-entry}{#lead-PATCH-lead__lead-business_phone-entry}{#lead-PATCH-lead__lead-city-entry}{#lead-PATCH-lead__lead-company-entry}{#lead-PATCH-lead__lead-consumer.sys_id-entry}{#lead-PATCH-lead__lead-contact.sys_id-entry}{#lead-PATCH-lead__lead-country-entry}{#lead-PATCH-lead__lead-do_not_call-entry}{#lead-PATCH-lead__lead-do_not_email-entry}{#lead-PATCH-lead__lead-do_not_share-entry}{#lead-PATCH-lead__lead-email-entry}{#lead-PATCH-lead__lead-external_id-entry}{#lead-PATCH-lead__lead-external_system-entry}{#lead-PATCH-lead__lead-first_name-entry}{#lead-PATCH-lead__lead-industry-entry}{#lead-PATCH-lead__lead-lead_group.sys_id-entry}{#lead-PATCH-lead__lead-lead_line_items.external_id-entry}{#lead-PATCH-lead__lead-lead_line_items.external_system-entry}{#lead-PATCH-lead__lead-lead_line_items.work_notes.text-entry}{#lead-PATCH-lead__lead-lead_rating-entry}{#lead-PATCH-lead__lead-lead_score-entry}{#lead-PATCH-lead__lead-lead_source-entry}{#lead-PATCH-lead__lead-lead_type-entry}{#lead-PATCH-lead__lead-middle_name-entry}{#lead-PATCH-lead__lead-mobile_phone-entry}{#lead-PATCH-lead__lead-other_reason-entry}{#lead-PATCH-lead__lead-owner.sys_id-entry}{#lead-PATCH-lead__lead-reason-entry}{#lead-PATCH-lead__lead-short_description-entry}{#lead-PATCH-lead__lead-similar_lead.sys_id-entry}{#lead-PATCH-lead__lead-stage-entry}{#lead-PATCH-lead__lead-state-entry}{#lead-PATCH-lead__lead-street-entry}{#lead-PATCH-lead__lead-title-entry}{#lead-PATCH-lead__lead-website-entry}{#lead-PATCH-lead__lead-work_notes.text-entry}{#lead-PATCH-lead__lead-zip-entry} | Name | Description | |-|-| | account | Details of the account associated with the lead. Data type: Object "account": { "sys_id": "String" } | | account.sys_id | Sys_id of the associated account record. Data type: String Table: Account \[customer_account\] | | business_phone | Lead's business phone number. Data type: String | | city | City in which the lead resides. Data type: String | | company | Lead's company name. Data type: String | | consumer | Consumer associated with the lead. Data type: Object "consumer": { "sys_id": "String" } | | consumer.sys_id | Sys_id of the associated consumer record. Data type: String Table: Consumer \[csm_consumer\] | | contact | Contact associated with the lead account. Data type: Object "contact": { "sys_id": "String" } | | contact.sys_id | Sys_id of the associated contact record. Data type: String Table: Contact \[customer_contact\] | | country | Country in which the lead resides. Data type: String | | do_not_call | Flag that indicates whether the mode of communication is by phone. Valid values: * true: Can call contact. * false: Don't call contact. Data type: Boolean | | do_not_email | Flag that indicates whether the mode of communication is by email. Valid values: * true: Can email contact. * false: Don't email contact. Data type: Boolean | | do_not_share | Flag that indicates whether the lead details can be shared. Valid values: * true: Lead details can be shared. * false: Lead details can't be shared. Data type: Boolean | | email | Lead's email address. Data type: String | | external_id | ID used by the system that generated the lead to identify the lead in the associated system. Data type: String | | external_system | Name of the external system associated with the lead, such as HubSpot or pipedrive. Data type: String | | first_name | First name of the contact associated with the lead. Data type: String | | industry | Industry to which the lead belongs. Data type: String Table: Located in the industry field of the Account \[customer_account\] table. | | last_name | Required. Last name of the contact associated with the lead. Data type: String | | lead_group | Group to which the lead belongs. Data type: Object "lead_group": { "sys_id": "String" } | | lead_group.sys_id | Sys_id of the lead group record. Data type: String Table: Group \[sys_user_group\] | | lead_line_items | List of lead line items to associated with the lead. Group to which the lead belongs. Data type: Object "lead_line_items": [ { "external_id": "String", "external_system": "String", "product_offering": {Object}, "quantity": Number, "work_notes": [Array], "unit_of_measurement": {Object} } ] Maximum line items: 100 - any over that are ignored | | lead_line_items.​external_id | ID used by the system that generated the lead line item to identify the line item in the associated system. Data type: String | | lead_line_items.​external_system | Name of the external system associated with the lead line item, such as HubSpot or pipedrive. Data type: String | | lead_line_items.product_offering | Required. Information about the product offering associated with the lead line item. Data type: Object "product_offering": { "sys_id": "String" } | | lead_line_items.product_offering.sys_id | Required. Sys_id of the product offering record associated with the lead line item. Data type: String Table: Product Offering \[sn_prd_pm_product_offering\] | | lead_line_items.quantity | Quantity of items the lead wants to purchase of the associated product offering. Data type: Number (Integer) | | lead_line_items.​unit_of_measurement | Details of the measuring unit of lead line item. Data type: Object "unit_of_measurement": { "sys_id": "String" } | | lead_line_items.​unit_of_measurement​.sys_id | Sys_id of the record that describes the measuring unit. Data type: String Table: Unit of Measure \[sn_prd_pm_uom\] | | lead_line_items.work_notes | List that describes the work notes created for the lead line item. Data type: Array of Objects "work_notes": [ "text": "String" } ] | | lead_line_items.​work_notes.​text | Text of the note made by the author. Data type: String | | lead_rating | Rating for the lead such as, 100_cold, 200_warm, 300_hot, or 400_super_hot. Note: This is a choice field. It must contain one of the choice items defined in the lead_rating field of the Leads table. Data type: String | | lead_score | Score for the lead. Data type: Decimal Range: 1 to 100 | | lead_source | Originator of the lead. Note: This is a choice field. It must contain one of the choice items defined in the lead_source field of the Leads table. Data type: String | | lead_type | Type of lead, such as New Business or Existing Business. Note: This is a choice field. It must contain one of the choice items defined in the lead_type field of the Leads table. Data type: String | | middle_name | Middle name of the contact for the lead. Data type: String | | mobile_phone | Phone number of the contact for the lead. Data type: String | | other_reason | Additional reason for the lead disqualification. Data type: String Max length: 160 characters | | owner | Details of the person associated with the lead. Data type: Object "owner": { "sys_id": "String" } | | owner.sys_id | Sys_id of the user record of the person that owns the lead. Data type: String Table: User \[sys_user\] | | reason | Reason for the lead disqualification such as, Disqualify. Data type: String Max length: 40 characters | | short_description | Short description of the lead. Data type: String Max length: 160 characters | | similar_lead | Details on any similar lead. Use this for possible lead disqualification. Data type: Object "similar_lead": { "sys_id": "String" } | | similar_lead.sys_id | Sys_id of the lead record that is a possible duplicate lead. Data type: String Table: Lead \[sn_lead_mgmt_core_lead\] | | stage | Stage of the lead such as, 100_new. Note: This is a choice field. It must contain one of the choice items defined in the stage field of the Leads table. Data type: String | | state | State in which the lead resides. Data type: String | | street | Street on which the lead resides. Data type: String | | title | Lead's title. Data type: String | | website | Lead's website URL. Data type: String | | work_notes | List of work notes created for the lead. Data type: Array of Objects "work_notes": [ { "text": "String" } ] Note: An array of work notes in the request is inserted as a single text. This text is generated by combining the content from all work note objects in the request, with each entry separated by a comma (,). | | work_notes.​text | Text of the note made by the author. Data type: String | | zip | Zip code of the associated lead. Data type: String | [Table 15. Request body parameters] ### Headers The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/5p0ILxi5PWo5cXuREsZCAQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#lead-PATCH-lead__entry__118}{#lead-PATCH-lead__accept-JSON-only-entry-RESTAPI}{#lead-PATCH-lead__content_type-JSON-only-entry-RESTAPI} | Header | Description | |-|-| | Accept | Data format of the response body. Only supports application/json. | | Content-Type | Data format of the request body. Only supports application/json. | [Table 16. Request headers] {#lead-PATCH-lead__entry__124} | Header | Description | |-|-| | None | | [Table 17. Response headers] ### Status codes The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://www.servicenow.com/docs/5p0ILxi5PWo5cXuREsZCAQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#lead-PATCH-lead__entry__128}{#lead-PATCH-lead__lead-400-status_code-entry}{#lead-PATCH-lead__entry-403-status-code}{#lead-PATCH-lead__entry-404-status-code}{#lead-PATCH-lead__entry-500-status-code} | Status code | Description | |-|-| | 200 | Successful. Lead and lead line items records were successfully updated. | | 400 | Error. Possible reasons: * Invalid payload: Invalid/empty request body. * Invalid payload: Invalid field value for email/phone number fields. * Invalid payload: Mandatory field is absent, or its value is empty. * Invalid payload: Stage is '400_closed_won'. Qualifying lead is not supported using the API. * If the stage of the lead to be updated is already in the closed state and you are trying to update it. | | 403 | Forbidden. The user doesn't have access rights to the specified record. | | 404 | Not found. The requested item wasn't found. | | 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. | [Table 18. Status codes] ### Response body parameters {#lead-PATCH-lead__entry__140}{#lead-PATCH-lead__d3104e67}{#lead-PATCH-lead__lead-account.name-entry}{#lead-PATCH-lead__d3104e91}{#lead-PATCH-lead__d3104e108}{#lead-PATCH-lead__d3104e119}{#lead-PATCH-lead__lead-closed_date-ph}{#lead-PATCH-lead__lead-closed_date.display_value-entry}{#lead-PATCH-lead__lead-closed_date.value-entry}{#lead-PATCH-lead__d3104e171}{#lead-PATCH-lead__lead-consumer-ph}{#lead-PATCH-lead__lead-consumer.name-entry}{#lead-PATCH-lead__d3104e208}{#lead-PATCH-lead__lead-contact-ph}{#lead-PATCH-lead__lead-contact.name-entry}{#lead-PATCH-lead__d3104e250}{#lead-PATCH-lead__d3104e267}{#lead-PATCH-lead__d3104e278}{#lead-PATCH-lead__d3104e303}{#lead-PATCH-lead__d3104e327}{#lead-PATCH-lead__d3104e351}{#lead-PATCH-lead__d3104e362}{#lead-PATCH-lead__d3104e373}{#lead-PATCH-lead__d3104e384}{#lead-PATCH-lead__d3104e396}{#lead-PATCH-lead__lead-last_name-entry}{#lead-PATCH-lead__lead-lead_group-entry}{#lead-PATCH-lead__lead-lead_group.name-entry}{#lead-PATCH-lead__d3104e454}{#lead-PATCH-lead__lead-lead_line_items-entry}{#lead-PATCH-lead__d3104e481}{#lead-PATCH-lead__d3104e492}{#lead-PATCH-lead__lead-lead_line_items.lead-entry}{#lead-PATCH-lead__lead-lead_line_items.lead.name-entry}{#lead-PATCH-lead__lead-lead_line_items.lead.sys_id-entry}{#lead-PATCH-lead__lead-lead_line_items.number-entry}{#lead-PATCH-lead__lead-lead_line_items.product_offering-ph}{#lead-PATCH-lead__lead-lead_line_items.product_offering.code-entry}{#lead-PATCH-lead__lead-lead_line_items.product_offering.name-entry}{#lead-PATCH-lead__lead-lead_line_items.product_offering.sys_id-entry}{#lead-PATCH-lead__lead-lead_line_items.quantity-entry}{#lead-PATCH-lead__lead-lead_line_items.sys_created_by-entry}{#lead-PATCH-lead__lead-lead_line_items.sys_created_on-entry}{#lead-PATCH-lead__lead-lead_line_items.sys_created_on.display_value-entry}{#lead-PATCH-lead__lead-lead_line_items.sys_created_on.value-entry}{#lead-PATCH-lead__lead-lead_line_items.sys_domain-entry}{#lead-PATCH-lead__lead-lead_line_items.sys_domain_path-entry}{#lead-PATCH-lead__lead-lead_line_items.sys_id-entry}{#lead-PATCH-lead__lead-lead_line_items.sys_mod_count-entry}{#lead-PATCH-lead__lead-lead_line_items.sys_tags-entry}{#lead-PATCH-lead__lead-lead_line_items.sys_updated_by-entry}{#lead-PATCH-lead__lead-lead_line_items.sys_updated_on-entry}{#lead-PATCH-lead__lead-lead_line_items.sys_updated_on.display_value-entry}{#lead-PATCH-lead__lead-lead_line_items.sys_updated_on.value-entry}{#lead-PATCH-lead__lead-lead_line_items.unit_of_measurement-entry}{#lead-PATCH-lead__lead-lead_line_items.unit_of_measurement.name-entry}{#lead-PATCH-lead__lead-lead_line_items.unit_of_measurement.sys_id-entry}{#lead-PATCH-lead__lead-lead_line_items.work_notes-entry}{#lead-PATCH-lead__lead-lead_line_items.work_notes.author-entry}{#lead-PATCH-lead__lead-lead_line_items.work_notes.date-entry}{#lead-PATCH-lead__d3104e862}{#lead-PATCH-lead__d3104e873}{#lead-PATCH-lead__d3104e886}{#lead-PATCH-lead__d3104e899}{#lead-PATCH-lead__d3104e912}{#lead-PATCH-lead__d3104e930}{#lead-PATCH-lead__d3104e942}{#lead-PATCH-lead__lead-number-entry}{#lead-PATCH-lead__d3104e964}{#lead-PATCH-lead__lead-owner-entry}{#lead-PATCH-lead__lead-owner.name-entry}{#lead-PATCH-lead__d3104e1005}{#lead-PATCH-lead__d3104e1019}{#lead-PATCH-lead__d3104e1032}{#lead-PATCH-lead__lead-similar_lead-entry}{#lead-PATCH-lead__lead-similar_lead.name-entry}{#lead-PATCH-lead__d3104e1073}{#lead-PATCH-lead__d3104e1086}{#lead-PATCH-lead__d3104e1103}{#lead-PATCH-lead__d3104e1114}{#lead-PATCH-lead__lead-sys_class_name-entry}{#lead-PATCH-lead__lead-sys_created_by-entry}{#lead-PATCH-lead__lead-sys_created_on-entry}{#lead-PATCH-lead__lead-sys_created_on.display_value-entry}{#lead-PATCH-lead__lead-sys_created_on.value-entry}{#lead-PATCH-lead__lead-sys_domain-entry}{#lead-PATCH-lead__lead-sys_domain_path-entry}{#lead-PATCH-lead__lead-sys_id-entry}{#lead-PATCH-lead__lead-sys_mod_count-entry}{#lead-PATCH-lead__lead-sys_tags-entry}{#lead-PATCH-lead__lead-sys_updated_by-entry}{#lead-PATCH-lead__lead-sys_updated_on-entry}{#lead-PATCH-lead__lead-sys_updated_on.display_value-entry}{#lead-PATCH-lead__lead-sys_updated_on.value-entry}{#lead-PATCH-lead__d3104e1299}{#lead-PATCH-lead__d3104e1310}{#lead-PATCH-lead__lead-work_notes-entry}{#lead-PATCH-lead__lead-work_notes.author-entry}{#lead-PATCH-lead__lead-work_notes.date-entry}{#lead-PATCH-lead__d3104e1361}{#lead-PATCH-lead__d3104e1372} | Name | Description | |-|-| | account | Account linked to the lead. Data type: Object "account": { "name": "String", "sys_id": "String" } | | account.name | Name of the account. Data type: String | | account.sys_id | Sys_id of the associated account record. Data type: String Table: Account \[customer_account\] | | business_phone | Lead's business phone number. Data type: String | | city | City in which the lead resides. Data type: String | | closed_date | Date and time when the lead was closed. Data type: Object "closed_date": { "display_value": "String", "value": "String" } | | closed_date.​display_value | Date and time as displayed in the UI. Data type: String Format: User's format and time zone. | | closed_date.value | Date and time that the lead closed as defined in the associated record. Data type: String Format: UTC | | company | Lead's company name. Data type: String | | consumer | Consumer associated with the lead. Data type: Object "consumer": { "name": "String", "sys_id": "String" } | | consumer.name | Name of the associated consumer. Data type: String | | consumer.sys_id | Sys_id of the associated consumer record. Data type: String Table: Consumer \[csm_consumer\] | | contact | Contact associated with the lead account. Data type: Object "contact": { "name": "String", "sys_id": "String" } | | contact.name | Contact's name. Data type: String | | contact.sys_id | Sys_id of the associated contact record. Data type: String Table: Contact \[customer_contact\] | | country | Country in which the lead resides. Data type: String | | do_not_call | Flag that indicates whether the mode of communication is by phone. Valid values: * true: Can call contact. * false: Don't call contact. Data type: Boolean | | do_not_email | Flag that indicates whether the mode of communication is by email. Valid values: * true: Can email contact. * false: Don't email contact. Data type: Boolean | | do_not_share | Flag that indicates whether the lead details can be shared. Valid values: * true: Lead details can be shared. * false: Lead details can't be shared. Data type: Boolean | | email | Lead's email address. Data type: String | | external_id | ID used by the system that generated the lead to identify the lead in the associated system. Data type: String | | external_system | Name of the external system associated with the lead, such as HubSpot or pipedrive. Data type: String | | first_name | First name of the contact associated with the lead. Data type: String | | industry | Industry to which the lead belongs. Data type: String Table: Located in the industry field of the Account \[customer_account\] table. | | last_name | Last name of the contact associated with the lead. Data type: String | | lead_group | Group to which the lead belongs. Data type: Object "lead_group": { "name: "String", "sys_id": "String" } | | lead_group.name | Lead group's name. Data type: String | | lead_group.sys_id | Sys_id of the lead group record. Data type: String Table: Group \[sys_user_group\] | | lead_line_items | Details of the lead line items associated with the lead. Data type: Array of Objects "lead_line_items": [ { "external_id": "String", "external_system": "String", "lead": {Object}, "number": "String", "product_offering": {Object}, "quantity": Number, "sys_created_by": "String", "sys_created_on {Object}, "sys_domain": "String", "sys_domain_path": "String", "sys_id": "String", "sys_mod_count": Number, "sys_tags": [Array], "sys_updated_by: "String", "sys_updated_on: {Object}, "unit_of_measurement": {Object}, "work_notes": [Array] } ] | | lead_line_items.​external_id | ID used by the system that generated the lead line item to identify the line item in the associated system. Data type: String | | lead_line_items.​external_system | Name of the external system associated with the lead line item, such as HubSpot or pipedrive. Data type: String | | lead_line_items.​lead | Details about the lead associated with the line item. Data type: Object "lead: { "name": "String", "sys_id": "String" } | | lead_line_items.​lead.name | Associated lead's name. Data type: String | | lead_line_items.​lead.sys_id | Sys_id of the associated lead record. Data type: String | | lead_line_items.​number | Unique system-generated number of the lead line item record. Data type: String | | lead_line_items.​product_offering | Information about the product offering associated with the lead line item. Data type: Object "product_offering": { "code": " String", "name": "String", "sys_id": "String" } | | lead_line_items.​product_offering.code | Code linked to the product offering. Note: This is a system-generated alphanumeric number based on the product name. Although system generated, you can edit the code to represent a SKU or any other industry specific product codes. Data type: String | | lead_line_items.​product_offering.name | Product offering's name. Data type: String | | lead_line_items.​product_offering.sys_id | Sys_id of the product offering record associated with the lead line item. Data type: String Table: Product Offering \[sn_prd_pm_product_offering\] | | lead_line_items.​quantity | Quantity of items the lead wants to purchase of the associated product offering. Data type: Number (Integer) | | lead_line_items.​sys_created_by | User name of the person that created the lead line item. Data type: String | | lead_line_items.​sys_created_on | System-generated date and time that the lead line item was created. Data type: Object "sys_created_on": { "display_value": "String", "value": "String" } | | lead_line_items.​sys_created_on.display_value | Date and time that the lead line item was created. Data type: String Format: Default instance format and time zone | | lead_line_items.​sys_created_on.value | Date and time that the lead line item was created. Data type: String Format: UTC | | lead_line_items.​sys_domain | Sys_id of the domain record to which the lead line item belongs. Note: This parameter is only returned in the response if domain separation is enabled. Data type: String | | lead_line_items.sys_domain_path | Path of the domain to which the lead line item belongs. Note: This parameter is only returned in the response if domain separation is enabled. Data type: String | | lead_line_items.​sys_id | Sys_id of the lead line item record. Data type: String | | lead_line_items.​sys_mod_count | Number of times the associated lead line item record has been modified. Data type: Number (Integer) | | lead_line_items.​sys_tags | List of system tags associated with the lead line item. Data type: Array | | lead_line_items.​sys_updated_by | User name of the person that last updated the associated lead line item. Data type: String | | lead_line_items.​sys_updated_on | System-generated date and time when the lead line item was last updated. Data type: Object "sys_created_on": { "display_value": "String", "value": "String" } | | lead_line_items.​sys_updated_on.​display_value | Date and time that the lead line item was last updated. Data type: String Format: Default instance format and time zone | | lead_line_items.​sys_updated_on.​value | Date and time that the lead line item was last updated. Data type: String Format: UTC | | lead_line_items.​unit_of_measurement | Details of the measuring unit of lead line item. Data type: Object "unit_of_measurement": { "name": "String", "sys_id": "String" } | | lead_line_items.​unit_of_measurement.​name | Name of the measuring unit such as, each or cubic foot. Data type: String | | lead_line_items.​unit_of_measurement.​sys_id | Sys_id of the record that describes the measuring unit. Data type: String Table: Unit of Measure \[sn_prd_pm_uom\] | | lead_line_items.​work_notes | List that describes the work notes created for the lead line item. Data type: Array of Objects "work_notes": [ { "author": "String", "date": "String", "text": "String" } ] | | lead_line_items.​work_notes.​author | User name of the person that authored the associated work note. Data type: String | | lead_line_items.​work_notes.​date | Date that the note was created. Data type: String | | lead_line_items.​work_notes.​text | Text of the note made by the author. Data type: String | | lead_rating | Rating for the lead such as, 100_cold, 200_warm, 300_hot, or 400_super_hot. Note: This is a choice field. It must contain one of the choice items defined in the lead_rating field of the Leads table. Data type: String | | lead_score | Score for the lead. Data type: Decimal Range: 1 to 100 | | lead_source | Originator of the lead. Note: This is a choice field. It must contain one of the choice items defined in the lead_source field of the Leads table. Data type: String | | lead_type | Type of lead, such as New Business or Existing Business. Note: This is a choice field. It must contain one of the choice items defined in the lead_type field of the Leads table. Data type: String | | middle_name | Middle name of the contact for the lead. Data type: String | | mobile_phone | Phone number of the contact for the lead. Data type: String | | number | Unique system-generated number of the lead record. Data type: String | | other_reason | Additional reason for the lead disqualification. Data type: String Max length: 160 characters | | owner | Details of the person associated with the lead. Data type: Object "owner": { "name": "String", "sys_id": "String" } | | owner.name | Name of the person that owns the lead. Data type: String | | owner.sys_id | Sys_id of the user record of the person that owns the lead. Data type: String Table: User \[sys_user\] | | reason | Reason for the lead disqualification such as, Disqualify. Data type: String Max length: 40 characters | | short_description | Short description of the lead. Data type: String Max length: 160 characters | | similar_lead | Details on any similar lead. Use this for possible lead disqualification. Data type: Object "similar_lead": { "name": "String", "sys_id": "String" } | | similar_lead.name | Name of the duplicate lead. Data type: String | | similar_lead.sys_id | Sys_id of the lead record that is a possible duplicate lead. Data type: String Table: Lead \[sn_lead_mgmt_core_lead\] | | stage | Stage of the lead such as, 100_new. Note: This is a choice field. It must contain one of the choice items defined in the stage field of the Leads table. Data type: String | | state | State in which the lead resides. Data type: String | | street | Street on which the lead resides. Data type: String | | sys_class_name | System-generated class name of the Lead table. Data type: String | | sys_created_by | User name of the person that created the lead. Data type: String | | sys_created_on | System-generated date and time that the lead was created. Data type: Object "sys_created_on": { "display_value": "String", "value": "String" } | | sys_created_on.​display_value | Date and time when the lead was created. Data type: String Format: Default instance format and time zone | | sys_created_on.​value | Date and time when the lead was created. Data type: String Format: UTC | | sys_domain | Sys_id of the domain record to which the lead belongs. Note: This parameter is only returned in the response if domain separation is enabled. Data type: String | | sys_domain_path | Path of the domain to which the lead belongs. Note: This parameter is only returned in the response if domain separation is enabled. Data type: String | | sys_id | Sys_id of the lead record. Data type: String Table: Lead \[sn_lead_mgmt_core_lead\] | | sys_mod_count | Number of times the associated lead record has been modified. Data type: Number (Integer) | | sys_tags | List of system tags associated with the lead. You can use these tags to categorize leads. Data type: Array | | sys_updated_by | User name of the person that last updated the lead record. Data type: String | | sys_updated_on | System-generated date and time when the lead was last updated. Data type: Object "sys_created_on": { "display_value": "String", "value": "String" } | | sys_updated_on.​display_value | Date and time that the lead was last updated. Data type: String Format: Instance's default format and time zone | | sys_updated_on.​value | Date and time that the lead was last updated. Data type: String Format: UTC | | title | Lead's title. Data type: String | | website | Lead's website URL. Data type: String | | work_notes | List of work notes created for the lead. Data type: Array of Objects "work_notes": [ { "author": "String", "date": "String", "text": "String" } ] | | work_notes.​author | User name of the person that authored the associated work note. Data type: String | | work_notes.​date | Date that the note was created. Data type: String | | work_notes.​text | Text of the note made by the author. Data type: String | | zip | Zip code of the associated lead. Data type: String | [ ] ### cURL request The following code example shows how to update the lead record with the sys_id 856b6a95ffde8210b85dffffffffffd7. curl " https://instance.service-now.com/api/sn_lead_mgmt_core/v1/lead/856b6a95ffde8210b85dffffffffffd7" \ --request PATCH \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --data " { "lead_source": "inbount_web", "business_phone": "+1 (555) 123-4567", "do_not_share": true, "lead_score": 40, "stage": "300_nurturning", "do_not_email": false, "lead_type": "new_business", "work_notes": [ { "text": "Work notes for lead" } ], "lead_rating": "200_warm", "lead_line_items": [ { "sys_id" : "013daa19ffde8210b85dffffffffff82", "quantity": 10 }, { "product_offering": { "sys_id": "0b61dd9fd0a63110f8770dbf976be171" } } ] }" The response contains all lead record fields. { "short_description": "Looking for a quote on preventative maintenance plans for their corporate office building elevators.", "reason": null, "country": "USA", "closed_date": null, "city": "San Francisco", "lead_source": "inbount_web", "external_id": null, "industry": "manufacturing", "sys_updated_on": { "value": "2024-12-11 08:45:52", "display_value": "2024-12-11 00:45:52" }, "title": "Director of Building operations", "sys_class_name": "Lead", "number": "LEAD0000001", "sys_id": "856b6a95ffde8210b85dffffffffffd7", "business_phone": "+1 (555) 123-4567", "similar_lead": null, "sys_updated_by": "abel.tuter", "mobile_phone": null, "street": "789, Industrial drive", "sys_created_on": { "value": "2024-05-20 10:32:41", "display_value": "2024-05-20 03:32:41" }, "contact": null, "company": "Lee Manufacturing Inc", "state": "CA", "first_name": "James", "email": "james.wilson@email.com", "consumer": null, "sys_created_by": "abel.tuter", "zip": "94016", "owner": { "sys_id": "60058fe943fe3110d6c6cd60afb8f203", "name": "Max Blaze" }, "website": null, "lead_group": null, "sys_mod_count": 4, "last_name": "Wilson", "other_reason": null, "middle_name": null, "sys_tags": null, "do_not_share": true, "lead_score": 40, "stage": "300_nurturing", "do_not_email": false, "lead_type": "new_business", "work_notes": [ { "author": "Abel Tuter", "date": "2024-12-11 00:45:52", "text": "Lead Line Item [code]LEADL0000003[/code] has been updated [code] Quantity [/code] 10 [code] was [/code] 6" }, { "author": "Abel Tuter", "date": "2024-12-11 00:45:52", "text": "Lead Line Item [code]LEADL0001002[/code] has been created [code] Product Offering [/code] Solana Modem M Series [code] Quantity [/code] 1" }, { "author": "Abel Tuter", "date": "2024-12-11 00:45:51", "text": "Work notes for lead" } ], "do_not_call": false, "lead_rating": "200_warm", "account": null, "external_system": null, "lead_line_items": [ { "quantity": 10, "product_offering": { "sys_id": "32619d9fd0a63110f8770dbf976be1f9", "name": "Safety Test Coverage", "code": "SAFETSTCVG1" }, "sys_mod_count": 1, "external_id": null, "sys_updated_on": { "value": "2024-12-11 08:45:52", "display_value": "2024-12-11 00:45:52" }, "sys_tags": null, "lead": { "sys_id": "856b6a95ffde8210b85dffffffffffd7", "name": "LEAD0000001" }, "number": "LEADL0000003", "sys_id": "013daa19ffde8210b85dffffffffff82", "unit_of_measurement": { "sys_id": "cb2795d553020110286eddeeff7b12ff", "name": "Each" }, "sys_updated_by": "abel.tuter", "sys_created_on": { "value": "2024-05-20 10:38:41", "display_value": "2024-05-20 03:38:41" }, "work_notes": null, "sys_created_by": "abel.tuter", "external_system": null }, { "quantity": 1, "product_offering": { "sys_id": "0b61dd9fd0a63110f8770dbf976be171", "name": "Solana Modem M Series", "code": "SOLANAMODE2" }, "sys_mod_count": 0, "external_id": null, "sys_updated_on": { "value": "2024-12-11 08:45:52", "display_value": "2024-12-11 00:45:52" }, "sys_tags": null, "lead": { "sys_id": "856b6a95ffde8210b85dffffffffffd7", "name": "LEAD0000001" }, "number": "LEADL0001002", "sys_id": "37610e1780925210f877983fa0be6725", "unit_of_measurement": null, "sys_updated_by": "abel.tuter", "sys_created_on": { "value": "2024-12-11 08:45:52", "display_value": "2024-12-11 00:45:52" }, "work_notes": null, "sys_created_by": "abel.tuter", "external_system": null } ] } ## lead - POST /sn_lead_mgmt_core/lead {#ariaid-title5} Creates a lead record and its associated lead line items using the specified parameters. Once processed, records are created in the following tables: * Lead \[sn_lead_mgmt_core_lead\] * Lead Line Item \[sn_lead_mgmt_core_lead_line_item\] Rules for passed-in parameters: * Invalid parameter names are ignored. * Invalid values for non-mandatory choice and reference fields are ignored. * If field WRITE access is denied for one or more fields, the restricted fields are ignored. * You can't insert system field values using this API. Any provided values are ignored. System fields are a part of the ignored fields list, which is configurable. * The values of the parameters account, contact, and consumer are ignored if both the account and consumer parameters are non-empty. * Unless otherwise specified, the default value for all non-passed parameters is 'null'. ### URL format Versioned URL: /api/sn_lead_mgmt_core/{api_version}/lead Default URL: /api/sn_lead_mgmt_core/{api_version}/lead Note: Available versions are specified in the [REST API Explorer](https://www.servicenow.com/docs/sYu7wNPLliq5~U4ai0aL_g "In this tutorial you will use the REST API Explorer to test the ServiceNow REST APIs."). For scripted REST APIs there is additional version information on the [Scripted REST Service form](https://www.servicenow.com/docs/cspfk_WKHcwVeXgD~XuntQ "The scripted REST API feature allows application developers to build custom web service APIs."). ### Supported request parameters {#lead-POST-lead__entry__2}{#lead-POST-lead__version-not_optional-RESTAPI} | Name | Description | |-|-| | api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest. Data type: String | [Table 19. Path parameters] {#lead-POST-lead__entry__6} | Name | Description | |-|-| | None | | [Table 20. Query parameters] {#lead-POST-lead__entry__10}{#lead-POST-lead__lead-account-entry}{#lead-POST-lead__lead-account.sys_id-entry}{#lead-POST-lead__lead-business_phone-entry}{#lead-POST-lead__lead-city-entry}{#lead-POST-lead__lead-company-entry}{#lead-POST-lead__lead-consumer.sys_id-entry}{#lead-POST-lead__lead-contact.sys_id-entry}{#lead-POST-lead__lead-country-entry}{#lead-POST-lead__lead-email-entry}{#lead-POST-lead__lead-external_id-entry}{#lead-POST-lead__lead-external_system-entry}{#lead-POST-lead__lead-first_name-entry}{#lead-POST-lead__lead-industry-entry}{#lead-POST-lead__lead-lead_group.sys_id-entry}{#lead-POST-lead__lead-lead_line_items.external_id-entry}{#lead-POST-lead__lead-lead_line_items.external_system-entry}{#lead-POST-lead__lead-lead_line_items.unit_of_measurement.sys_id-entry}{#lead-POST-lead__lead-lead_line_items.work_notes.text-entry}{#lead-POST-lead__lead-lead_rating-entry}{#lead-POST-lead__lead-lead_score-entry}{#lead-POST-lead__lead-lead_source-entry}{#lead-POST-lead__lead-lead_type-entry}{#lead-POST-lead__lead-middle_name-entry}{#lead-POST-lead__lead-mobile_phone-entry}{#lead-POST-lead__lead-other_reason-entry}{#lead-POST-lead__lead-owner.sys_id-entry}{#lead-POST-lead__lead-reason-entry}{#lead-POST-lead__lead-short_description-entry}{#lead-POST-lead__lead-similar_lead.sys_id-entry}{#lead-POST-lead__lead-state-entry}{#lead-POST-lead__lead-street-entry}{#lead-POST-lead__lead-title-entry}{#lead-POST-lead__lead-website-entry}{#lead-POST-lead__lead-work_notes.text-entry}{#lead-POST-lead__lead-zip-entry} | Name | Description | |-|-| | account | Details on the account associated with the lead. Data type: Object "account": { "sys_id": "String" } | | account.sys_id | Sys_id of the associated account record. Data type: String Table: Account \[customer_account\] | | business_phone | Lead's business phone number. Data type: String | | city | City in which the lead resides. Data type: String | | company | Lead's company name. Data type: String | | consumer | Consumer associated with the lead. Data type: Object "consumer": { "sys_id": "String" } | | consumer.sys_id | Sys_id of the associated consumer record. Data type: String Table: Consumer \[csm_consumer\] | | contact | Contact associated with the lead account. Data type: Object "contact": { "sys_id": "String" } | | contact.sys_id | Sys_id of the associated contact record. Data type: String Table: Contact \[customer_contact\] | | country | Country in which the lead resides. Data type: String | | do_not_call | Flag that indicates whether the mode of communication is by phone. Valid values: * true: Can call contact. * false: Don't call contact. Data type: Boolean Default: false | | do_not_email | Flag that indicates whether the mode of communication is by email. Valid values: * true: Can email contact. * false: Don't email contact. Data type: Boolean Default: false | | do_not_share | Flag that indicates whether the lead details can be shared. Valid values: * true: Lead details can be shared. * false: Lead details can't be shared. Data type: Boolean Default: false | | email | Lead's email address. Data type: String | | external_id | ID used by the system that generated the lead to identify the lead in the associated system. Data type: String | | external_system | Name of the external system associated with the lead, such as HubSpot or pipedrive. Data type: String | | first_name | First name of the contact associated with the lead. Data type: String | | industry | Industry to which the lead belongs. Data type: String Table: Located in the industry field of the Account \[customer_account\] table. | | last_name | Required. Last name of the contact associated with the lead. Data type: String | | lead_group | Group to which the lead belongs. Data type: Object "lead_group": { "sys_id": "String" } | | lead_group.sys_id | Sys_id of the lead group record. Data type: String Table: Group \[sys_user_group\] | | lead_line_items | List of lead line items to associated with the lead. Group to which the lead belongs. Data type: Object "lead_line_items": [ { "external_id": "String", "external_system": "String", "product_offering": {Object}, "quantity": Number, "work_notes": [Array], "unit_of_measurement": {Object} } ] Maximum line items: 100 - any over that are ignored | | lead_line_items.​external_id | ID used by the system that generated the lead line item to identify the line item in the associated system. Data type: String | | lead_line_items.​external_system | Name of the external system associated with the lead line item, such as HubSpot or pipedrive. Data type: String | | lead_line_items.product_offering | Required. Information about the product offering associated with the lead line item. Data type: Object "product_offering": { "sys_id": "String" } | | lead_line_items.product_offering.sys_id | Required. Sys_id of the product offering record associated with the lead line item. Data type: String Table: Product Offering \[sn_prd_pm_product_offering\] | | lead_line_items.quantity | Quantity of items the lead wants to purchase of the associated product offering. Data type: Number (Integer) Default: 1 | | lead_line_items.unit_of_measurement | Details of the measuring unit of lead line item. Data type: Object "unit_of_measurement": { "sys_id": "String" } | | lead_line_items.​unit_of_measurement.​sys_id | Sys_id of the record that describes the measuring unit. Data type: String Table: Unit of Measure \[sn_prd_pm_uom\] | | lead_line_items.work_notes | List that describes the work notes created for the lead line item. Data type: Array of Objects "work_notes": [ "text": "String" } ] Default: Empty array | | lead_line_items.​work_notes.​text | Text of the note made by the author. Data type: String | | lead_rating | Rating for the lead such as, 100_cold, 200_warm, 300_hot, or 400_super_hot. Note: This is a choice field. It must contain one of the choice items defined in the lead_rating field of the Leads table. Data type: String | | lead_score | Score for the lead. Data type: Decimal Range: 1 to 100 | | lead_source | Originator of the lead. Note: This is a choice field. It must contain one of the choice items defined in the lead_source field of the Leads table. Data type: String | | lead_type | Type of lead, such as New Business or Existing Business. Note: This is a choice field. It must contain one of the choice items defined in the lead_type field of the Leads table. Data type: String | | middle_name | Middle name of the contact for the lead. Data type: String | | mobile_phone | Phone number of the contact for the lead. Data type: String | | other_reason | Additional reason for the lead disqualification. Data type: String Max length: 160 characters | | owner | Details of the person associated with the lead. Data type: Object "owner": { "sys_id": "String" } | | owner.sys_id | Sys_id of the user record of the person that owns the lead. Data type: String Table: User \[sys_user\] | | reason | Reason for the lead disqualification such as, Disqualify. Data type: String Max length: 40 characters | | short_description | Short description of the lead. Data type: String Max length: 160 characters | | similar_lead | Details on any similar lead. Use this for possible lead disqualification. Data type: Object "similar_lead": { "sys_id": "String" } | | similar_lead.sys_id | Sys_id of the lead record that is a possible duplicate lead. Data type: String Table: Lead \[sn_lead_mgmt_core_lead\] | | stage | Stage of the lead such as, 100_new. Note: This is a choice field. It must contain one of the choice items defined in the stage field of the Leads table. Data type: String Default: 100_new | | state | State in which the lead resides. Data type: String | | street | Street on which the lead resides. Data type: String | | title | Lead's title. Data type: String | | website | Lead's website URL. Data type: String | | work_notes | List of work notes created for the lead. Data type: Array of Objects "work_notes": [ { "text": "String" } ] Note: An array of work notes in the request is inserted as a single text. This text is generated by combining the content from all work note objects in the request, with each entry separated by a comma (,). Default: Empty array | | work_notes.​text | Text of the note made by the author. Data type: String | | zip | Zip code of the associated lead. Data type: String | [Table 21. Request body parameters] ### Headers The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/5p0ILxi5PWo5cXuREsZCAQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#lead-POST-lead__entry__116}{#lead-POST-lead__accept-JSON-only-entry-RESTAPI} | Header | Description | |-|-| | Accept | Data format of the response body. Only supports application/json. | [Table 22. Request headers] {#lead-POST-lead__entry__120} | Header | Description | |-|-| | None | | [Table 23. Response headers] ### Status codes The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://www.servicenow.com/docs/5p0ILxi5PWo5cXuREsZCAQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#lead-POST-lead__entry__124}{#lead-POST-lead__lead-400-status_code-entry}{#lead-POST-lead__entry-403-status-code}{#lead-POST-lead__entry-500-status-code} | Status code | Description | |-|-| | 201 | Successful. Lead and its associated line items are inserted successfully. | | 400 | Error. Possible reasons: * Invalid payload: Invalid/empty request body. * Invalid payload: Invalid field value for email/phone number fields. * Invalid payload: Mandatory field is absent, or its value is empty. * Business rule/data policy violation. | | 403 | Forbidden. The user doesn't have access rights to the specified record. | | 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. | [Table 24. Status codes] ### Response body parameters {#lead-POST-lead__entry__134}{#lead-POST-lead__d3104e67}{#lead-POST-lead__lead-account.name-entry}{#lead-POST-lead__d3104e91}{#lead-POST-lead__d3104e108}{#lead-POST-lead__d3104e119}{#lead-POST-lead__lead-closed_date-ph}{#lead-POST-lead__lead-closed_date.display_value-entry}{#lead-POST-lead__lead-closed_date.value-entry}{#lead-POST-lead__d3104e171}{#lead-POST-lead__lead-consumer-ph}{#lead-POST-lead__lead-consumer.name-entry}{#lead-POST-lead__d3104e208}{#lead-POST-lead__lead-contact-ph}{#lead-POST-lead__lead-contact.name-entry}{#lead-POST-lead__d3104e250}{#lead-POST-lead__d3104e267}{#lead-POST-lead__lead-do_not_call-entry}{#lead-POST-lead__lead-do_not_email-entry}{#lead-POST-lead__lead-do_not_share-entry}{#lead-POST-lead__d3104e351}{#lead-POST-lead__d3104e362}{#lead-POST-lead__d3104e373}{#lead-POST-lead__d3104e384}{#lead-POST-lead__d3104e396}{#lead-POST-lead__lead-last_name-entry}{#lead-POST-lead__lead-lead_group-entry}{#lead-POST-lead__lead-lead_group.name-entry}{#lead-POST-lead__d3104e454}{#lead-POST-lead__lead-lead_line_items-entry}{#lead-POST-lead__d3104e481}{#lead-POST-lead__d3104e492}{#lead-POST-lead__lead-lead_line_items.lead-entry}{#lead-POST-lead__lead-lead_line_items.lead.name-entry}{#lead-POST-lead__lead-lead_line_items.lead.sys_id-entry}{#lead-POST-lead__lead-lead_line_items.number-entry}{#lead-POST-lead__lead-lead_line_items.product_offering-ph}{#lead-POST-lead__lead-lead_line_items.product_offering.code-entry}{#lead-POST-lead__lead-lead_line_items.product_offering.name-entry}{#lead-POST-lead__lead-lead_line_items.product_offering.sys_id-entry}{#lead-POST-lead__lead-lead_line_items.quantity-entry}{#lead-POST-lead__lead-lead_line_items.sys_created_by-entry}{#lead-POST-lead__lead-lead_line_items.sys_created_on-entry}{#lead-POST-lead__lead-lead_line_items.sys_created_on.display_value-entry}{#lead-POST-lead__lead-lead_line_items.sys_created_on.value-entry}{#lead-POST-lead__lead-lead_line_items.sys_domain-entry}{#lead-POST-lead__lead-lead_line_items.sys_domain_path-entry}{#lead-POST-lead__lead-lead_line_items.sys_id-entry}{#lead-POST-lead__lead-lead_line_items.sys_mod_count-entry}{#lead-POST-lead__lead-lead_line_items.sys_tags-entry}{#lead-POST-lead__lead-lead_line_items.sys_updated_by-entry}{#lead-POST-lead__lead-lead_line_items.sys_updated_on-entry}{#lead-POST-lead__lead-lead_line_items.sys_updated_on.display_value-entry}{#lead-POST-lead__lead-lead_line_items.sys_updated_on.value-entry}{#lead-POST-lead__lead-lead_line_items.unit_of_measurement-entry}{#lead-POST-lead__lead-lead_line_items.unit_of_measurement.name-entry}{#lead-POST-lead__d3104e809}{#lead-POST-lead__lead-lead_line_items.work_notes-entry}{#lead-POST-lead__lead-lead_line_items.work_notes.author-entry}{#lead-POST-lead__lead-lead_line_items.work_notes.date-entry}{#lead-POST-lead__d3104e862}{#lead-POST-lead__d3104e873}{#lead-POST-lead__d3104e886}{#lead-POST-lead__d3104e899}{#lead-POST-lead__d3104e912}{#lead-POST-lead__d3104e930}{#lead-POST-lead__d3104e942}{#lead-POST-lead__lead-number-entry}{#lead-POST-lead__d3104e964}{#lead-POST-lead__lead-owner-entry}{#lead-POST-lead__lead-owner.name-entry}{#lead-POST-lead__d3104e1005}{#lead-POST-lead__d3104e1019}{#lead-POST-lead__d3104e1032}{#lead-POST-lead__lead-similar_lead-entry}{#lead-POST-lead__lead-similar_lead.name-entry}{#lead-POST-lead__d3104e1073}{#lead-POST-lead__lead-stage-entry}{#lead-POST-lead__d3104e1103}{#lead-POST-lead__d3104e1114}{#lead-POST-lead__lead-sys_class_name-entry}{#lead-POST-lead__lead-sys_created_by-entry}{#lead-POST-lead__lead-sys_created_on-entry}{#lead-POST-lead__lead-sys_created_on.display_value-entry}{#lead-POST-lead__lead-sys_created_on.value-entry}{#lead-POST-lead__lead-sys_domain-entry}{#lead-POST-lead__lead-sys_domain_path-entry}{#lead-POST-lead__lead-sys_id-entry}{#lead-POST-lead__lead-sys_mod_count-entry}{#lead-POST-lead__lead-sys_tags-entry}{#lead-POST-lead__lead-sys_updated_by-entry}{#lead-POST-lead__lead-sys_updated_on-entry}{#lead-POST-lead__lead-sys_updated_on.display_value-entry}{#lead-POST-lead__lead-sys_updated_on.value-entry}{#lead-POST-lead__d3104e1299}{#lead-POST-lead__d3104e1310}{#lead-POST-lead__lead-work_notes-entry}{#lead-POST-lead__lead-work_notes.author-entry}{#lead-POST-lead__lead-work_notes.date-entry}{#lead-POST-lead__d3104e1361}{#lead-POST-lead__d3104e1372} | Name | Description | |-|-| | account | Account linked to the lead. Data type: Object "account": { "name": "String", "sys_id": "String" } | | account.name | Name of the account. Data type: String | | account.sys_id | Sys_id of the associated account record. Data type: String Table: Account \[customer_account\] | | business_phone | Lead's business phone number. Data type: String | | city | City in which the lead resides. Data type: String | | closed_date | Date and time when the lead was closed. Data type: Object "closed_date": { "display_value": "String", "value": "String" } | | closed_date.​display_value | Date and time as displayed in the UI. Data type: String Format: User's format and time zone. | | closed_date.value | Date and time that the lead closed as defined in the associated record. Data type: String Format: UTC | | company | Lead's company name. Data type: String | | consumer | Consumer associated with the lead. Data type: Object "consumer": { "name": "String", "sys_id": "String" } | | consumer.name | Name of the associated consumer. Data type: String | | consumer.sys_id | Sys_id of the associated consumer record. Data type: String Table: Consumer \[csm_consumer\] | | contact | Contact associated with the lead account. Data type: Object "contact": { "name": "String", "sys_id": "String" } | | contact.name | Contact's name. Data type: String | | contact.sys_id | Sys_id of the associated contact record. Data type: String Table: Contact \[customer_contact\] | | country | Country in which the lead resides. Data type: String | | do_not_call | Flag that indicates whether the mode of communication is by phone. Valid values: * true: Can call contact. * false: Don't call contact. Data type: Boolean | | do_not_email | Flag that indicates whether the mode of communication is by email. Valid values: * true: Can email contact. * false: Don't email contact. Data type: Boolean | | do_not_share | Flag that indicates whether the lead details can be shared. Valid values: * true: Lead details can be shared. * false: Lead details can't be shared. Data type: Boolean | | email | Lead's email address. Data type: String | | external_id | ID used by the system that generated the lead to identify the lead in the associated system. Data type: String | | external_system | Name of the external system associated with the lead, such as HubSpot or pipedrive. Data type: String | | first_name | First name of the contact associated with the lead. Data type: String | | industry | Industry to which the lead belongs. Data type: String Table: Located in the industry field of the Account \[customer_account\] table. | | last_name | Last name of the contact associated with the lead. Data type: String | | lead_group | Group to which the lead belongs. Data type: Object "lead_group": { "name: "String", "sys_id": "String" } | | lead_group.name | Lead group's name. Data type: String | | lead_group.sys_id | Sys_id of the lead group record. Data type: String Table: Group \[sys_user_group\] | | lead_line_items | Details of the lead line items associated with the lead. Data type: Array of Objects "lead_line_items": [ { "external_id": "String", "external_system": "String", "lead": {Object}, "number": "String", "product_offering": {Object}, "quantity": Number, "sys_created_by": "String", "sys_created_on {Object}, "sys_domain": "String", "sys_domain_path": "String", "sys_id": "String", "sys_mod_count": Number, "sys_tags": [Array], "sys_updated_by: "String", "sys_updated_on: {Object}, "unit_of_measurement": {Object}, "work_notes": [Array] } ] | | lead_line_items.​external_id | ID used by the system that generated the lead line item to identify the line item in the associated system. Data type: String | | lead_line_items.​external_system | Name of the external system associated with the lead line item, such as HubSpot or pipedrive. Data type: String | | lead_line_items.​lead | Details about the lead associated with the line item. Data type: Object "lead: { "name": "String", "sys_id": "String" } | | lead_line_items.​lead.name | Associated lead's name. Data type: String | | lead_line_items.​lead.sys_id | Sys_id of the associated lead record. Data type: String | | lead_line_items.​number | Unique system-generated number of the lead line item record. Data type: String | | lead_line_items.​product_offering | Information about the product offering associated with the lead line item. Data type: Object "product_offering": { "code": " String", "name": "String", "sys_id": "String" } | | lead_line_items.​product_offering.code | Code linked to the product offering. Note: This is a system-generated alphanumeric number based on the product name. Although system generated, you can edit the code to represent a SKU or any other industry specific product codes. Data type: String | | lead_line_items.​product_offering.name | Product offering's name. Data type: String | | lead_line_items.​product_offering.sys_id | Sys_id of the product offering record associated with the lead line item. Data type: String Table: Product Offering \[sn_prd_pm_product_offering\] | | lead_line_items.​quantity | Quantity of items the lead wants to purchase of the associated product offering. Data type: Number (Integer) | | lead_line_items.​sys_created_by | User name of the person that created the lead line item. Data type: String | | lead_line_items.​sys_created_on | System-generated date and time that the lead line item was created. Data type: Object "sys_created_on": { "display_value": "String", "value": "String" } | | lead_line_items.​sys_created_on.display_value | Date and time that the lead line item was created. Data type: String Format: Default instance format and time zone | | lead_line_items.​sys_created_on.value | Date and time that the lead line item was created. Data type: String Format: UTC | | lead_line_items.​sys_domain | Sys_id of the domain record to which the lead line item belongs. Note: This parameter is only returned in the response if domain separation is enabled. Data type: String | | lead_line_items.sys_domain_path | Path of the domain to which the lead line item belongs. Note: This parameter is only returned in the response if domain separation is enabled. Data type: String | | lead_line_items.​sys_id | Sys_id of the lead line item record. Data type: String | | lead_line_items.​sys_mod_count | Number of times the associated lead line item record has been modified. Data type: Number (Integer) | | lead_line_items.​sys_tags | List of system tags associated with the lead line item. Data type: Array | | lead_line_items.​sys_updated_by | User name of the person that last updated the associated lead line item. Data type: String | | lead_line_items.​sys_updated_on | System-generated date and time when the lead line item was last updated. Data type: Object "sys_created_on": { "display_value": "String", "value": "String" } | | lead_line_items.​sys_updated_on.​display_value | Date and time that the lead line item was last updated. Data type: String Format: Default instance format and time zone | | lead_line_items.​sys_updated_on.​value | Date and time that the lead line item was last updated. Data type: String Format: UTC | | lead_line_items.​unit_of_measurement | Details of the measuring unit of lead line item. Data type: Object "unit_of_measurement": { "name": "String", "sys_id": "String" } | | lead_line_items.​unit_of_measurement.​name | Name of the measuring unit such as, each or cubic foot. Data type: String | | lead_line_items.​unit_of_measurement.​sys_id | Sys_id of the record that describes the measuring unit. Data type: String Table: Unit of Measure \[sn_prd_pm_uom\] | | lead_line_items.​work_notes | List that describes the work notes created for the lead line item. Data type: Array of Objects "work_notes": [ { "author": "String", "date": "String", "text": "String" } ] | | lead_line_items.​work_notes.​author | User name of the person that authored the associated work note. Data type: String | | lead_line_items.​work_notes.​date | Date that the note was created. Data type: String | | lead_line_items.​work_notes.​text | Text of the note made by the author. Data type: String | | lead_rating | Rating for the lead such as, 100_cold, 200_warm, 300_hot, or 400_super_hot. Note: This is a choice field. It must contain one of the choice items defined in the lead_rating field of the Leads table. Data type: String | | lead_score | Score for the lead. Data type: Decimal Range: 1 to 100 | | lead_source | Originator of the lead. Note: This is a choice field. It must contain one of the choice items defined in the lead_source field of the Leads table. Data type: String | | lead_type | Type of lead, such as New Business or Existing Business. Note: This is a choice field. It must contain one of the choice items defined in the lead_type field of the Leads table. Data type: String | | middle_name | Middle name of the contact for the lead. Data type: String | | mobile_phone | Phone number of the contact for the lead. Data type: String | | number | Unique system-generated number of the lead record. Data type: String | | other_reason | Additional reason for the lead disqualification. Data type: String Max length: 160 characters | | owner | Details of the person associated with the lead. Data type: Object "owner": { "name": "String", "sys_id": "String" } | | owner.name | Name of the person that owns the lead. Data type: String | | owner.sys_id | Sys_id of the user record of the person that owns the lead. Data type: String Table: User \[sys_user\] | | reason | Reason for the lead disqualification such as, Disqualify. Data type: String Max length: 40 characters | | short_description | Short description of the lead. Data type: String Max length: 160 characters | | similar_lead | Details on any similar lead. Use this for possible lead disqualification. Data type: Object "similar_lead": { "name": "String", "sys_id": "String" } | | similar_lead.name | Name of the duplicate lead. Data type: String | | similar_lead.sys_id | Sys_id of the lead record that is a possible duplicate lead. Data type: String Table: Lead \[sn_lead_mgmt_core_lead\] | | stage | Stage of the lead such as, 100_new. Note: This is a choice field. It must contain one of the choice items defined in the stage field of the Leads table. Data type: String | | state | State in which the lead resides. Data type: String | | street | Street on which the lead resides. Data type: String | | sys_class_name | System-generated class name of the Lead table. Data type: String | | sys_created_by | User name of the person that created the lead. Data type: String | | sys_created_on | System-generated date and time that the lead was created. Data type: Object "sys_created_on": { "display_value": "String", "value": "String" } | | sys_created_on.​display_value | Date and time when the lead was created. Data type: String Format: Default instance format and time zone | | sys_created_on.​value | Date and time when the lead was created. Data type: String Format: UTC | | sys_domain | Sys_id of the domain record to which the lead belongs. Note: This parameter is only returned in the response if domain separation is enabled. Data type: String | | sys_domain_path | Path of the domain to which the lead belongs. Note: This parameter is only returned in the response if domain separation is enabled. Data type: String | | sys_id | Sys_id of the lead record. Data type: String Table: Lead \[sn_lead_mgmt_core_lead\] | | sys_mod_count | Number of times the associated lead record has been modified. Data type: Number (Integer) | | sys_tags | List of system tags associated with the lead. You can use these tags to categorize leads. Data type: Array | | sys_updated_by | User name of the person that last updated the lead record. Data type: String | | sys_updated_on | System-generated date and time when the lead was last updated. Data type: Object "sys_created_on": { "display_value": "String", "value": "String" } | | sys_updated_on.​display_value | Date and time that the lead was last updated. Data type: String Format: Instance's default format and time zone | | sys_updated_on.​value | Date and time that the lead was last updated. Data type: String Format: UTC | | title | Lead's title. Data type: String | | website | Lead's website URL. Data type: String | | work_notes | List of work notes created for the lead. Data type: Array of Objects "work_notes": [ { "author": "String", "date": "String", "text": "String" } ] | | work_notes.​author | User name of the person that authored the associated work note. Data type: String | | work_notes.​date | Date that the note was created. Data type: String | | work_notes.​text | Text of the note made by the author. Data type: String | | zip | Zip code of the associated lead. Data type: String | [ ] ### cURL request The following code example shows how to create a new lead record with one lead line item. curl " https://instance.service-now.com/api/sn_lead_mgmt_core/v1/lead" \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --data " { "short_description": "Looking for a quote on preventative maintenance plans for their corporate office building elevators.", "country": "USA", "city": "San Francisco", "lead_source": "inbound_phone", "industry": "manufacturing", "title": "Director of Building operations", "business_phone": "+1 (555) 123-4567", "street": "789, Industrial drive", "company": "Lee Manufacturing Inc", "state": "CA", "first_name": "James", "email": "james.wilson@email.com", "consumer": { "sys_id": "46ce64ef99ca5210f8779c3cc41bb03c" }, "zip": "94016", "website": "example.com", "last_name": "Wilson", "middle_name": null, "do_not_share": false, "lead_score": 92, "stage": "100_new", "do_not_email": false, "lead_type": "existing_business", "work_notes": [ { "text": "Work notes for lead" } ], "do_not_call": true, "lead_rating": "200_warm", "lead_line_items": [ { "quantity": 1, "product_offering": { "sys_id": "32619d9fd0a63110f8770dbf976be1f9" }, "unit_of_measurement": { "sys_id": "cb2795d553020110286eddeeff7b12ff" } } ] } The response contains the fields in the lead and lead line items records. { "short_description": "Looking for a quote on preventative maintenance plans for their corporate office building elevators.", "reason": null, "country": "USA", "closed_date": null, "city": "San Francisco", "lead_source": "inbound_phone", "external_id": null, "industry": "manufacturing", "sys_updated_on": { "value": "2024-12-11 08:35:26", "display_value": "2024-12-11 00:35:26" }, "title": "Director of Building operations", "sys_class_name": "Lead", "number": "LEAD0001001", "sys_id": "030f795380925210f877983fa0be67c0", "business_phone": "+1 (555) 123-4567", "similar_lead": null, "sys_updated_by": "abel.tuter", "mobile_phone": null, "street": "789, Industrial drive", "sys_created_on": { "value": "2024-12-11 08:35:26", "display_value": "2024-12-11 00:35:26" }, "contact": null, "company": "Lee Manufacturing Inc", "state": "CA", "first_name": "James", "email": "james.wilson@email.com", "consumer": { "sys_id": "46ce64ef99ca5210f8779c3cc41bb03c", "name": "test" }, "sys_created_by": "abel.tuter", "zip": "94016", "owner": { "sys_id": "62826bf03710200044e0bfc8bcbe5df1", "name": "Abel Tuter" }, "website": "example.com", "lead_group": null, "sys_mod_count": 1, "last_name": "Wilson", "other_reason": null, "middle_name": null, "sys_tags": null, "do_not_share": false, "lead_score": 92, "stage": "100_new", "do_not_email": false, "lead_type": "existing_business", "work_notes": [ { "author": "Abel Tuter", "date": "2024-12-11 00:35:26", "text": "Work notes for lead" }, { "author": "Abel Tuter", "date": "2024-12-11 00:35:26", "text": "Lead Line Item [code]LEADL0001001[/code] has been created [code] Product Offering [/code] Safety Test Coverage [code] Quantity [/code] 1 [code] Unit of Measure [/code] Each" } ], "do_not_call": true, "lead_rating": "200_warm", "account": null, "external_system": null, "lead_line_items": [ { "quantity": 1, "product_offering": { "sys_id": "32619d9fd0a63110f8770dbf976be1f9", "name": "Safety Test Coverage", "code": "SAFETSTCVG1" }, "sys_mod_count": 0, "external_id": null, "sys_updated_on": { "value": "2024-12-11 08:35:26", "display_value": "2024-12-11 00:35:26" }, "sys_tags": null, "lead": { "sys_id": "030f795380925210f877983fa0be67c0", "name": "LEAD0001001" }, "number": "LEADL0001001", "sys_id": "830f795380925210f877983fa0be67c5", "unit_of_measurement": { "sys_id": "cb2795d553020110286eddeeff7b12ff", "name": "Each" }, "sys_updated_by": "abel.tuter", "sys_created_on": { "value": "2024-12-11 08:35:26", "display_value": "2024-12-11 00:35:26" }, "work_notes": null, "sys_created_by": "abel.tuter", "external_system": null } ] }