Consumer API

  • Release version: Zurich
  • Updated July 31, 2025
  • 14 minutes to read

    • 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 Customer Service plugin (com.sn_customerservice) and is provided within the now namespace.

    Users require the csm_ws_integration role for full API access.

    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

    Table 1. Path 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
    Table 2. Query parameters
    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
    Table 3. Request body parameters (XML or JSON)
    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.

    Table 4. Request headers
    Header Description
    Accept Data format of the response body. Supported types: application/json or application/xml.

    Default: application/json
    Table 5. Response headers
    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.

    Table 6. Status 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

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

    Table 7. Path 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
    id Sys_id of the consumer record to return.

    Data type: String

    Table: Consumer [csm_consumer]
    Table 8. Query parameters
    Name Description
    None
    Table 9. Request body parameters (XML or JSON)
    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.

    Table 10. Request headers
    Header Description
    Accept Data format of the response body. Supported types: application/json or application/xml.

    Default: application/json
    Table 11. Response headers
    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.

    Table 12. Status 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)

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

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

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

    Table 13. Path 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
    Table 14. Query parameters
    Name Description
    None
    Table 15. Request body parameters (XML or JSON)
    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

    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.

    Table 16. Request 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.
    Table 17. Response headers
    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.

    Table 18. Status 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

    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"
    {
    "result": "0f5c13addb93230057c3fd441d9619b8"
}