Consumer API · SN Doc Reader

The Consumer API provides endpoints to retrieve and update Customer Service Management (CSM) consumer records.

In addition, you can generate new social media profile records when creating a consumer.

The Consumer API requires the Case Management Core plugin (com.sn_customerservice) and is provided within the now namespace.

Users require the csm_ws_integration role for full API access.

Parent Topic:REST API reference

Consumer - GET /now/consumer

Retrieves a specified set of Customer Service Management (CSM) consumer records.

URL format

Versioned URL: /api/now/{api_version}/consumer

Default URL: /api/now/consumer

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_limit	Maximum number of records to return. For requests that exceed this number of records, use the sysparm_offset parameter to paginate record retrieval. In the response, the boolean parameter hasMore is returned. It indicates whether there are more records to return that meet the filter criteria. Data type: Number Default: 10
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. Do not 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

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.

In the response, the boolean parameter hasMore is returned. It indicates whether there are more records to return that meet the filter criteria.

Data type: Number

Default: 10

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.

Do not 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

|Element|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
Accept	Data format of the response body. Supported types: application/json or application/xml. Default: 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.
401	Unauthorized. The user credentials are incorrect or have not been passed.
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 (JSON or XML)

The endpoint may return the following JSON or XML elements in the response body. In addition to the list of elements defined below (which define the elements in a base system), the endpoint also returns any custom fields added to the Consumer [csm_consumer] table. For additional information on these elements, refer to your specific table definition [System Definition > Tables].

Element	Description
active	Flag that indicates whether the consumer is active.Possible values: true: Consumer active false: Consumer de-activated Data type: Boolean Default: true
business_phone	Business phone number of the consumer.Data type: String Maximum length: 40
city	City in which the consumer resides.Data type: String Maximum length: 100
country	Country in which the consumer resides.Data type: String Maximum length: 40
date_format	Format in which to display dates.Valid values: dd-mm-yyyy dd/mm/yyyy dd.mm.yyyy mm-dd-yyyy yyyy-mm-dd Data type: String Maximum length: 40 Default: blank (system date format)
email	Email address of the consumer.Data type: String Maximum length: 100
fax	Fax number of the consumer.Data type: String Maximum length: 40
first_name	Consumer first name.Data type: String Maximum length: 50
gender	Gender of the consumer.Data type: String Maximum length: 40
home_phone	Home phone number of the consumer.Data type: String Maximum length: 40
household	Sys_id of the record that describes the household characteristics.Data type: String Table: Household [csm_household]
last_name	Consumer last name.Data type: String Maximum length: 50
middle_name	Consumer middle name.Data type: String Maximum length: 50
mobile_phone	Consumer mobile phone number.Data type: String Maximum length: 40
name	Consumer full name; first_name+middle_name+last_name.Data type: String Maximum length: 152
notes	Notes on consumer.Data type: String Maximum length: 4,000
notification	Indicates whether the consumer should receive notifications.Valid values: 1: Disabled 2: Enabled Data type: Number (Integer) Maximum length: 40 Default: 2
number	Unique number associated with the consumer.Data type: String Maximum length: 40
photo	Photo of the consumer.Data type: Image
preferred_language	Consumer primary language.Data type: String Maximum length: 3
prefix	Consumer name prefix such as, Dr., Mr., Mrs., or Ms.Data type: String Maximum length: 40
primary	Flag that indicates whether this is the primary consumer.Possible values: true: Primary consumer false: Not primary consumer Data type: Boolean Default: false
state	State in which the consumer resides.Data type: String Maximum length: 100
street	Consumer street address.Data type: String Maximum length: 255
suffix	Consumer name suffix such as Jr., Sr., or II.Data type: String
sys_created_by	User that created the consumer record.Data type: String Maximum length: 40
sys_created_on	Date and time the consumer record was originally created.Data type: String
sys_domain	ServiceNow domain in which the consumer information resides.Data type: String
sys_id	Unique identifier for the consumer.Data type: String
sys_mod_count	Number of times that the associated consumer information has been modified.Data type: Number (Integer)
sys_tags	System tags.Data type: String
sys_updated_by	User that last updated the consumer information.Data type: String Maximum length: 40
sys_updated_on	Date and time when the consumer information was last updated.Data type: String
time_format	Format in which to display time.Valid values: hh.mm.ss a: hh.mm.ss (12 hour) hh:mm:ss a: hh:mm:ss (12 hour) HH.mm.ss: hh.mm.ss (24 hour) HH:mm:ss: hh:mm:ss (24 hour) Data type: String Maximum length: 40 Default: blank (system time format)
time_zone	Consumer time zone, such as Canada/Central or US/Eastern.Data type: String Maximum length: 40
title	Consumer business title such as Manager, Software Developer, or Contractor.Data type: String Maximum length: 60
user	Sys_id of the consumer user. Data type: String Table: Consumer User [csm_consumer_user]
zip	Consumer zip code. Data type: String Maximum length: 40

### cURL request

Shell

curl "https://instance.servicenow.com/api/now/consumer?sysparm_query=account=86837a386f0331003b3c498f5d3ee4ca&sysparm_limit=2&sysparm_offset=2>;rel="next" \--request GET \--header "Accept:application/json" \--user "username":"password"

JSON

{  "result": [    {      "country": "USA",      "notes": "",      "gender": "Male",      "city": "Plano",      "prefix": "",      "sys_updated_on": "2016-08-12 00:19:12",      "suffix": "",      "title": "",      "number": "CSMR0000004",      "notification": "2",      "sys_id": "01d8403fdb1b1200b6075200cf961941",      "business_phone": "",      "sys_updated_by": "prithvi",      "mobile_phone": "",      "street": "6900 Dallas Pkwy",      "sys_created_on": "2016-06-16 19:20:13",      "sys_domain": "global",      "state": "TX",      "fax": "",      "first_name": "Harding",      "email": "harding.asher@mailinator.com",      "preferred_language": "",      "sys_created_by": "guest",      "zip": "75024",      "home_phone": "",      "time_format": "",      "sys_mod_count": "8",      "last_name": "Asher",      "photo": "",      "active": "true",      "middle_name": "",      "time_zone": "",      "sys_tags": "",      "name": "Harding Asher",      "household": "",      "date_format": "",      "user": "c3d35d82c37122005871d44d81d3ae91",      "primary": "false"    },    {      "country": "USA",      "notes": "",      "gender": "Male",      "city": "San Francisco",      "prefix": "",      "sys_updated_on": "2016-08-12 00:20:27",      "suffix": "",      "title": "",      "number": "CSMR0000002",      "notification": "2",      "sys_id": "a0488cfbdb1b1200b6075200cf9619db",      "business_phone": "",      "sys_updated_by": "prithvi",      "mobile_phone": "",      "street": "144 2nd St",      "sys_created_on": "2016-06-16 19:17:44",      "sys_domain": "global",      "state": "CA",      "fax": "",      "first_name": "Sam",      "email": "sam.collins@mailinator.com",      "preferred_language": "",      "sys_created_by": "guest",      "zip": "94105",      "home_phone": "",      "time_format": "",      "sys_mod_count": "13",      "last_name": "Collins",      "photo": "",      "active": "true",      "middle_name": "",      "time_zone": "",      "sys_tags": "",      "name": "Sam Collins",      "household": "",      "date_format": "",      "user": "64488cfbdb1b1200b6075200cf9619db",      "primary": "false"    }  ]}

Consumer - GET /now/consumer/{id}

Retrieves the specified Customer Service Management (CSM) consumer record.

URL format

Versioned URL: /api/now/{api_version}/consumer/{id}

Default URL: /api/now/consumer/{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 of the consumer record to return.Data type: String

Table: Consumer [csm_consumer]

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

Name	Description
None

Headers

Header	Description
Accept	Data format of the response body. Supported types: application/json or application/xml. Default: 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.
401	Unauthorized. The user credentials are incorrect or have not been passed.
404	Indicates that the request is invalid. Could be due to one of the following reasons:- Requested case doesn't exist. User doesn't have access to the consumer record.
500	Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

### Response body parameters \(JSON or XML\)

Element	Description
active	Flag that indicates whether the consumer is active.Possible values: true: Consumer active false: Consumer de-activated Data type: Boolean Default: true
business_phone	Business phone number of the consumer.Data type: String Maximum length: 40
city	City in which the consumer resides.Data type: String Maximum length: 100
country	Country in which the consumer resides.Data type: String Maximum length: 40
date_format	Format in which to display dates.Valid values: dd-mm-yyyy dd/mm/yyyy dd.mm.yyyy mm-dd-yyyy yyyy-mm-dd Data type: String Maximum length: 40 Default: blank (system date format)
email	Email address of the consumer.Data type: String Maximum length: 100
fax	Fax number of the consumer.Data type: String Maximum length: 40
first_name	Consumer first name.Data type: String Maximum length: 50
gender	Gender of the consumer.Data type: String Maximum length: 40
home_phone	Home phone number of the consumer.Data type: String Maximum length: 40
household	Sys_id of the record that describes the household characteristics.Data type: String Table: Household [csm_household]
last_name	Consumer last name.Data type: String Maximum length: 50
middle_name	Consumer middle name.Data type: String Maximum length: 50
mobile_phone	Consumer mobile phone number.Data type: String Maximum length: 40
name	Consumer full name; first_name+middle_name+last_name.Data type: String Maximum length: 152
notes	Notes on consumer.Data type: String Maximum length: 4,000
notification	Indicates whether the consumer should receive notifications.Valid values: 1: Disabled 2: Enabled Data type: Number (Integer) Maximum length: 40 Default: 2
number	Unique number associated with the consumer.Data type: String Maximum length: 40
photo	Photo of the consumer.Data type: Image
preferred_language	Consumer primary language.Data type: String Maximum length: 3
prefix	Consumer name prefix such as, Dr., Mr., Mrs., or Ms.Data type: String Maximum length: 40
primary	Flag that indicates whether this is the primary consumer.Possible values: true: Primary consumer false: Not primary consumer Data type: Boolean Default: false
state	State in which the consumer resides.Data type: String Maximum length: 100
street	Consumer street address.Data type: String Maximum length: 255
suffix	Consumer name suffix such as Jr., Sr., or II.Data type: String
sys_created_by	User that created the consumer record.Data type: String Maximum length: 40
sys_created_on	Date and time the consumer record was originally created.Data type: String
sys_domain	ServiceNow domain in which the consumer information resides.Data type: String
sys_id	Unique identifier for the consumer.Data type: String
sys_mod_count	Number of times that the associated consumer information has been modified.Data type: Number (Integer)
sys_updated_by	User that last updated the consumer information.Data type: String Maximum length: 40
sys_updated_on	Date and time when the consumer information was last updated.Data type: String
time_format	Format in which to display time.Valid values: hh.mm.ss a: hh.mm.ss (12 hour) hh:mm:ss a: hh:mm:ss (12 hour) HH.mm.ss: hh.mm.ss (24 hour) HH:mm:ss: hh:mm:ss (24 hour) Data type: String Maximum length: 40 Default: blank (system time format)
time_zone	Consumer time zone, such as Canada/Central or US/Eastern.Data type: String Maximum length: 40
title	Consumer business title such as Manager, Software Developer, or Contractor.Data type: String Maximum length: 60
user	Sys_id of the consumer user. Data type: String Table: Consumer User [csm_consumer_user]
zip	Consumer zip code. Data type: String Maximum length: 40

### cURL request

Shell

curl "https://instance.servicenow.com/api/now/consumer/01d8403fdb1b1200b6075200cf961941 \--request GET \--header "Accept:application/json" \--user "username":"password"

JSON

{  "result": {    "country": "USA",    "notes": "",    "gender": "Male",    "city": "Plano",    "prefix": "",    "sys_updated_on": "2016-08-12 00:19:12",    "suffix": "",    "title": "",    "number": "CSMR0000004",    "notification": "2",    "sys_id": "01d8403fdb1b1200b6075200cf961941",    "business_phone": "",    "sys_updated_by": "prithvi",    "mobile_phone": "",    "street": "6900 Dallas Pkwy",    "sys_created_on": "2016-06-16 19:20:13",    "sys_domain": "global",    "state": "TX",    "fax": "",    "first_name": "Harding",    "email": "harding.asher@mailinator.com",    "preferred_language": "",    "sys_created_by": "guest",    "zip": "75024",    "home_phone": "",    "time_format": "",    "sys_mod_count": "8",    "last_name": "Asher",    "photo": "",    "active": "true",    "middle_name": "",    "time_zone": "",    "sys_tags": "",    "name": "Harding Asher",    "household": "",    "date_format": "",    "user": "c3d35d82c37122005871d44d81d3ae91",    "primary": "false"  }}

Consumer - POST /now/consumer

Creates a new Customer Service Management (CSM) consumer.

In addition, you can create a social media profile for the consumer using this endpoint. To create the profile, you must specify the following parameters in the request body:

social_channel
social_handle
social_handle_url

Warning: This endpoint does not perform parameter validation as doing so can create excessive overhead. If a request parameter is misspelled, is not valid, or is not supported by the endpoint, it is ignored without warning.

URL format

Versioned URL: /api/now/{api_version}/consumer

Default URL: /api/now/consumer

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

Element	Description
active	Flag that indicates whether the consumer is active.Possible values: true: Consumer active false: Consumer de-activated Data type: Boolean Default: true
business_phone	Business phone number of the consumer.Data type: String Maximum length: 40
city	City in which the consumer resides.Data type: String Maximum length: 100
country	Country in which the consumer resides.Data type: String Maximum length: 40
date_format	Format in which to display dates.Valid values: dd-mm-yyyy dd/mm/yyyy dd.mm.yyyy mm-dd-yyyy yyyy-mm-dd Data type: String Maximum length: 40 Default: blank (system date format)
email	Email address of the consumer.Data type: String Maximum length: 100
fax	Fax number of the consumer.Data type: String Maximum length: 40
first_name	Consumer first name.Data type: String Maximum length: 50
gender	Gender of the consumer.Data type: String Maximum length: 40
home_phone	Home phone number of the consumer.Data type: String Maximum length: 40
household	Sys_id of the record that describes the household characteristics.Data type: String Table: Household [csm_household]
last_name	Consumer last name.Data type: String Maximum length: 50
middle_name	Consumer middle name.Data type: String Maximum length: 50
mobile_phone	Consumer mobile phone number.Data type: String Maximum length: 40
name	Consumer full name; first_name+middle_name+last_name.Data type: String Maximum length: 152
notes	Notes on consumer.Data type: String Maximum length: 4,000
notification	Indicates whether the consumer should receive notifications.Valid values: 1: Disabled 2: Enabled Data type: Number (Integer) Maximum length: 40 Default: 2
photo	Photo of the consumer.Data type: Image
preferred_language	Consumer primary language.Data type: String Maximum length: 3
prefix	Consumer name prefix such as, Dr., Mr., Mrs., or Ms.Data type: String Maximum length: 40
primary	Flag that indicates whether this is the primary consumer.Possible values: true: Primary consumer false: Not primary consumer Data type: Boolean Default: false
social_channel	Social media channel to which the consumer is associated such as Twitter, Facebook, or Instagram.Data type: String
social_handle	User handle on the social media channel.Data type: String
social_handle_url	URL to the consumer's social channel handle.Data type: String
state	State in which the consumer resides.Data type: String Maximum length: 100
street	Consumer street address.Data type: String Maximum length: 255
suffix	Consumer name suffix such as Jr., Sr., or II.Data type: String
time_format	Format in which to display time.Valid values: hh.mm.ss a: hh.mm.ss (12 hour) hh:mm:ss a: hh:mm:ss (12 hour) HH.mm.ss: hh.mm.ss (24 hour) HH:mm:ss: hh:mm:ss (24 hour) Data type: String Maximum length: 40 Default: blank (system time format)
time_zone	Consumer time zone, such as Canada/Central or US/Eastern.Data type: String Maximum length: 40
title	Consumer business title such as Manager, Software Developer, or Contractor.Data type: String Maximum length: 60
user	Sys_id of the consumer user. Data type: String Table: Consumer User [csm_consumer_user]
zip	Consumer zip code. Data type: String Maximum length: 40

### 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
201	New consumer record was successfully created.
400	Bad Request. A bad request type or malformed request was detected.
401	Unauthorized. The user credentials are incorrect or have not been passed.
500	Internal Server Error. A logic error on the server-side code occurred.

Response body parameters (JSON or XML)

Element	Description
result	Sys_id of the newly created consumer record.Data type: String

### cURL request

Shell

curl -X POST "https://instance.servicenow.com/api/now/consumer" \-H "Accept: application/json" \-H "Content-Type: application/json" \-d " { \  "country": "USA", \  "notes": "Never comes in before 10am", \  "gender": "Female", \  "city": "San Marcos", \  "prefix": "Ms", \  "title": "Director", \  "notification": "1", \  "business_phone": "(555)555-1234", \  "mobile_phone": "(555)555-1235", \  "street": "123 Sesame St", \  "state": "CA", \  "fax": "(555)555-1236", \  "first_name": "Jane", \  "zip": "92001", \  "home_phone": "(555)555-1234", \  "last_name": "Brown", \  "active": "true", \  "middle_name": "Dell", \  "time_zone": "PST", \  "name": "Jane Brown", \  "household": "4", \  "user": "c3d35d82c37122005871d44d81d3ae91", \  "primary": "false" \}"--user "username":"password"

JSON

{    "result": "0f5c13addb93230057c3fd441d9619b8"}

title	Consumer API
description	The Consumer API provides endpoints to retrieve and update Customer Service Management \(CSM\) consumer records.Retrieves a specified set of Customer Service Management \(CSM\) consumer records.Retrieves the specified Customer Service Management \(CSM\) consumer record.Creates a new Customer Service Management \(CSM\) consumer.
locale	en-US
canonical_url	https://www.servicenow.com/docs/r/api-reference/rest-apis/consumer-api.html
release	brazil
product	REST APIs
classification	rest-apis
topic_type	concept
last_updated	2026-09-10
reading_time_minutes	17
breadcrumb	REST API referenceAPI referenceAPI implementation and reference