lead API · SN Doc Reader

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.

Extending the Lead API

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: Contains methods that handle the retrieval and creation of lead and lead line item records.
LeadApiValidationUtilOOB: Contains methods that validate the JSON request object for the POST and PATCH endpoints.
LeadAPIHelperOOB: 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.

Parent Topic:REST API reference

lead - GET /sn_lead_mgmt_core/lead

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]

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. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

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

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

|Name|Description| |----|-----------| |None| |

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.

Header	Description
Content-Type	Data format of the request body. Only supports application/json.

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.

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

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.

### Response body parameters

Name	Description
account	Account linked to the lead.Data type: Object Text `"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 Text `"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 Text `"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 Text `"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 Text `"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 Shell "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 Text `"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 CSS `"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 Text `"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 Text `"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 Text `"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 JSON `"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 Text `"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 Text `"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 Text `"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 Text `"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 JSON `"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.

Shell

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:

JSON

[  {    "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}

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]

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. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

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]

|Name|Description| |----|-----------| |None| |

Name	Description
None

Headers

Header	Description
Accept	Data format of the response body. Only supports application/json.

Header	Description
None

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.

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.

Response body parameters

Name	Description
account	Account linked to the lead.Data type: Object Text `"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 Text `"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 Text `"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 Text `"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 Text `"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 Shell "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 Text `"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 CSS `"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 Text `"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 Text `"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 Text `"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 JSON `"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 Text `"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 Text `"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 Text `"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 Text `"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 JSON `"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 retrieve the lead record with the sys_id of 856b6a95ffde8210b85dffffffffffd7.

Shell

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:

JSON

{   "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}

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]

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. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

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]

|Name|Description| |----|-----------| |None| |

Name	Description
account	Details of the account associated with the lead.Data type: Object Text `"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 Text `"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 Text `"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 Text `"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 JavaScript `"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 Text `"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 Text `"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 Text `"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 Text `"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 Text `"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 Text `"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

### Headers

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.

Header	Description
None

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.

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.

### Response body parameters

Name	Description
account	Account linked to the lead.Data type: Object Text `"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 Text `"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 Text `"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 Text `"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 Text `"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 Shell "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 Text `"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 CSS `"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 Text `"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 Text `"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 Text `"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 JSON `"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 Text `"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 Text `"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 Text `"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 Text `"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 JSON `"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.

Shell

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.

JSON

{   "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]<a href='/sn_lead_mgmt_core_lead_line_item.do?sys_id=013daa19ffde8210b85dffffffffff82'>LEADL0000003</a>[/code] has been updated  [code] <b> Quantity </b> [/code] 10 [code] <i>was</i> [/code] 6"    },    {      "author": "Abel Tuter",      "date": "2024-12-11 00:45:52",      "text": "Lead Line Item [code]<a href='/sn_lead_mgmt_core_lead_line_item.do?sys_id=37610e1780925210f877983fa0be6725'>LEADL0001002</a>[/code] has been created  [code] <b> Product Offering </b> [/code] Solana Modem M Series [code] <b> Quantity </b> [/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

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. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

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

|Name|Description| |----|-----------| |None| |

Name	Description
account	Details on the account associated with the lead.Data type: Object Text `"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 Text `"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 Text `"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 Text `"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 JavaScript `"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 Text `"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 Text `"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 Text `"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 Text `"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 Text `"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 Text `"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

### Headers

Header	Description
Accept	Data format of the response body. Only supports application/json.

Header	Description
None

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.

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.

### Response body parameters

Name	Description
account	Account linked to the lead.Data type: Object Text `"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 Text `"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 Text `"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 Text `"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 Text `"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 Shell "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 Text `"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 CSS `"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 Text `"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 Text `"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 Text `"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 JSON `"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 Text `"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 Text `"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 Text `"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 Text `"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 JSON `"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.

Shell

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.

JSON

{  "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]<a href='/sn_lead_mgmt_core_lead_line_item.do?sys_id=830f795380925210f877983fa0be67c5'>LEADL0001001</a>[/code] has been created  [code] <b> Product Offering </b> [/code] Safety Test Coverage [code] <b> Quantity </b> [/code] 1 [code] <b> Unit of Measure </b> [/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    }  ]}

title	lead API
description	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.Retrieves all leads and associated lead line items based on the filter criteria passed in the query parameters.Returns the lead record and all associated lead line items for the specified sys\_id.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.Creates a lead record and its associated lead line items using the specified parameters.
locale	en-US
canonical_url	https://www.servicenow.com/docs/r/australia/api-reference/rest-apis/lead-api.html
release	australia
product	REST APIs
classification	rest-apis
topic_type	concept
last_updated	2026-09-10
reading_time_minutes	64
breadcrumb	REST API referenceAPI referenceAPI implementation and reference