---
sourceDocument: Zurich API Reference
sourceDocumentLink: https://www.servicenow.com/docs/r/zurich/api-reference
Release :
- zurich
ft:locale :
- en-US
ft:publication_title :
- Zurich API Reference
ft:clusterId :
- crapiref
bundleId :
- crapiref
workflow :
- Creator
---
# Consumer API
# Consumer API {#ariaid-title1}
* 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 {#ariaid-title2}
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](https://www.servicenow.com/docs/sYu7wNPLliq5~U4ai0aL_g "In this tutorial you will use the REST API Explorer to test the ServiceNow REST APIs."). For scripted REST APIs there is additional version information on the [Scripted REST Service form](https://www.servicenow.com/docs/cspfk_WKHcwVeXgD~XuntQ "The scripted REST API feature allows application developers to build custom web service APIs.").
### Supported request parameters
{#consumer-GET__entry__2}{#consumer-GET__version-not_optional-RESTAPI}
| Name | Description |
|-|-|
| api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest. Data type: String |
[Table 1. Path parameters]
{#consumer-GET__entry__6}{#consumer-GET__sysparm-limit-entry}{#consumer-GET__sysparm-offset-entry}{#consumer-GET__sysparm-query-entry}
| 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 2. Query parameters]
{#consumer-GET__entry__14}
| Element | Description |
|-|-|
| None | |
[Table 3. Request body parameters (XML or JSON)]
### Headers
The following request and response headers apply to this HTTP
action only, or apply to this action in a distinct way. For a list of general headers used
in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/5p0ILxi5PWo5cXuREsZCAQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#consumer-GET__entry__18}{#consumer-GET__accept-RESTAPI}
| Header | Description |
|-|-|
| Accept | Data format of the response body. Supported types: application/json or application/xml. Default: application/json |
[Table 4. Request headers]
{#consumer-GET__entry__22}
| Header | Description |
|-|-|
| None | |
[Table 5. Response headers]
### Status codes
The following status codes apply to this HTTP action. For a
list of possible status codes used in the REST API, see [REST API HTTP response
codes](https://www.servicenow.com/docs/5p0ILxi5PWo5cXuREsZCAQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#consumer-GET__entry__26}{#consumer-GET__entry-200-status-code}{#consumer-GET__entry-401-status-code}{#consumer-GET__entry-404-status-code}{#consumer-GET__entry-500-status-code}
| 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. |
[Table 6. Status codes]
### 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 DefinitionTables\].
{#consumer-GET__csmconsumer_response_parms__entry__2}{#consumer-GET__consumertable-active-entry}{#consumer-GET__consumertable-business_phone-entry}{#consumer-GET__consumertable-city-entry}{#consumer-GET__consumertable-country-entry}{#consumer-GET__consumertable-date_format-entry}{#consumer-GET__consumertable-email-entry}{#consumer-GET__consumertable-fax-entry}{#consumer-GET__consumertable-first_name-entry}{#consumer-GET__consumertable-gender-entry}{#consumer-GET__consumertable-home_phone-entry}{#consumer-GET__consumertable-household-entry}{#consumer-GET__consumertable-last_name-entry}{#consumer-GET__consumertable-middle_name-entry}{#consumer-GET__consumertable-mobile_phone-entry}{#consumer-GET__consumertable-name-entry}{#consumer-GET__consumertable-notes-entry}{#consumer-GET__consumertable-notification-entry}{#consumer-GET__consumertable-number-entry}{#consumer-GET__consumertable-photo-entry}{#consumer-GET__consumertable-preferred_language-entry}{#consumer-GET__consumertable-prefix-entry}{#consumer-GET__consumertable-primary-entry}{#consumer-GET__consumertable-state-entry}{#consumer-GET__consumertable-street-entry}{#consumer-GET__consumertable-suffix-entry}{#consumer-GET__consumertable-sys_created_by-entry}{#consumer-GET__consumertable-sys_created_on-entry}{#consumer-GET__consumertable-sys_domain-entry}{#consumer-GET__consumertable-sys_id-entry}{#consumer-GET__consumertable-sys_mod_count-entry}{#consumer-GET__consumertable-sys_updated_by-entry}{#consumer-GET__consumertable-sys_updated_on-entry}{#consumer-GET__consumertable-time_format-entry}{#consumer-GET__consumertable-time_zone-entry}{#consumer-GET__consumertable-title-entry}{#consumer-GET__consumertable-user-entry}{#consumer-GET__consumertable-zip-entry}
| Element | Description |
|-|-|
| active | Flag that indicates whether the consumer is active. Possible values: * true: Consumer active * false: Consumer de-activated {#consumer-GET__ul_asy_4b3_2hb} 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 {#consumer-GET__ul_jsj_qwc_2hb} 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 {#consumer-GET__ul_o5d_pyh_2hb} 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 {#consumer-GET__ul_yns_yb3_2hb} 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) {#consumer-GET__ul_kvg_gxc_2hb} 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} {#ariaid-title3}
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](https://www.servicenow.com/docs/sYu7wNPLliq5~U4ai0aL_g "In this tutorial you will use the REST API Explorer to test the ServiceNow REST APIs."). For scripted REST APIs there is additional version information on the [Scripted REST Service form](https://www.servicenow.com/docs/cspfk_WKHcwVeXgD~XuntQ "The scripted REST API feature allows application developers to build custom web service APIs.").
### Supported request parameters
{#consumer-GET-id__entry__2}{#consumer-GET-id__version-not_optional-RESTAPI}
| Name | Description |
|-|-|
| api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest. Data type: String |
| id | Sys_id of the consumer record to return. Data type: String Table: Consumer \[csm_consumer\] |
[Table 7. Path parameters]
{#consumer-GET-id__entry__8}
| Name | Description |
|-|-|
| None | |
[Table 8. Query parameters]
{#consumer-GET-id__entry__12}
| Name | Description |
|-|-|
| None | |
[Table 9. Request body parameters (XML or JSON)]
### Headers
The following request and response headers apply to this HTTP
action only, or apply to this action in a distinct way. For a list of general headers used
in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/5p0ILxi5PWo5cXuREsZCAQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#consumer-GET-id__entry__16}{#consumer-GET-id__accept-RESTAPI}
| Header | Description |
|-|-|
| Accept | Data format of the response body. Supported types: application/json or application/xml. Default: application/json |
[Table 10. Request headers]
{#consumer-GET-id__entry__20}
| Header | Description |
|-|-|
| None | |
[Table 11. Response headers]
### Status codes
The following status codes apply to this HTTP action. For a
list of possible status codes used in the REST API, see [REST API HTTP response
codes](https://www.servicenow.com/docs/5p0ILxi5PWo5cXuREsZCAQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#consumer-GET-id__entry__24}{#consumer-GET-id__entry-200-status-code}{#consumer-GET-id__entry-401-status-code}{#consumer-GET-id__entry-500-status-code}
| 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. {#consumer-GET-id__ul_ubm_1jl_3v} |
| 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. |
[Table 12. Status codes]
### Response body parameters (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 DefinitionTables\].
{#consumer-GET-id__csmconsumer_response_parms__entry__2}{#consumer-GET-id__consumertable-active-entry}{#consumer-GET-id__consumertable-business_phone-entry}{#consumer-GET-id__consumertable-city-entry}{#consumer-GET-id__consumertable-country-entry}{#consumer-GET-id__consumertable-date_format-entry}{#consumer-GET-id__consumertable-email-entry}{#consumer-GET-id__consumertable-fax-entry}{#consumer-GET-id__consumertable-first_name-entry}{#consumer-GET-id__consumertable-gender-entry}{#consumer-GET-id__consumertable-home_phone-entry}{#consumer-GET-id__consumertable-household-entry}{#consumer-GET-id__consumertable-last_name-entry}{#consumer-GET-id__consumertable-middle_name-entry}{#consumer-GET-id__consumertable-mobile_phone-entry}{#consumer-GET-id__consumertable-name-entry}{#consumer-GET-id__consumertable-notes-entry}{#consumer-GET-id__consumertable-notification-entry}{#consumer-GET-id__consumertable-number-entry}{#consumer-GET-id__consumertable-photo-entry}{#consumer-GET-id__consumertable-preferred_language-entry}{#consumer-GET-id__consumertable-prefix-entry}{#consumer-GET-id__consumertable-primary-entry}{#consumer-GET-id__consumertable-state-entry}{#consumer-GET-id__consumertable-street-entry}{#consumer-GET-id__consumertable-suffix-entry}{#consumer-GET-id__consumertable-sys_created_by-entry}{#consumer-GET-id__consumertable-sys_created_on-entry}{#consumer-GET-id__consumertable-sys_domain-entry}{#consumer-GET-id__consumertable-sys_id-entry}{#consumer-GET-id__consumertable-sys_mod_count-entry}{#consumer-GET-id__consumertable-sys_updated_by-entry}{#consumer-GET-id__consumertable-sys_updated_on-entry}{#consumer-GET-id__consumertable-time_format-entry}{#consumer-GET-id__consumertable-time_zone-entry}{#consumer-GET-id__consumertable-title-entry}{#consumer-GET-id__consumertable-user-entry}{#consumer-GET-id__consumertable-zip-entry}
| Element | Description |
|-|-|
| active | Flag that indicates whether the consumer is active. Possible values: * true: Consumer active * false: Consumer de-activated {#consumer-GET-id__ul_asy_4b3_2hb} 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 {#consumer-GET-id__ul_jsj_qwc_2hb} 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 {#consumer-GET-id__ul_o5d_pyh_2hb} 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 {#consumer-GET-id__ul_yns_yb3_2hb} 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) {#consumer-GET-id__ul_kvg_gxc_2hb} 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 {#ariaid-title4}
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
{#consumer-POST__ul_ntx_lg4_pgb}
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](https://www.servicenow.com/docs/sYu7wNPLliq5~U4ai0aL_g "In this tutorial you will use the REST API Explorer to test the ServiceNow REST APIs."). For scripted REST APIs there is additional version information on the [Scripted REST Service form](https://www.servicenow.com/docs/cspfk_WKHcwVeXgD~XuntQ "The scripted REST API feature allows application developers to build custom web service APIs.").
### Supported request parameters
{#consumer-POST__entry__2}{#consumer-POST__version-not_optional-RESTAPI}
| Name | Description |
|-|-|
| api_version | Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest. Data type: String |
[Table 13. Path parameters]
{#consumer-POST__entry__6}
| Name | Description |
|-|-|
| None | |
[Table 14. Query parameters]
{#consumer-POST__entry__10}{#consumer-POST__consumertable-active-entry}{#consumer-POST__consumertable-business_phone-entry}{#consumer-POST__consumertable-city-entry}{#consumer-POST__consumertable-country-entry}{#consumer-POST__consumertable-date_format-entry}{#consumer-POST__consumertable-email-entry}{#consumer-POST__consumertable-fax-entry}{#consumer-POST__consumertable-first_name-entry}{#consumer-POST__consumertable-gender-entry}{#consumer-POST__consumertable-home_phone-entry}{#consumer-POST__consumertable-household-entry}{#consumer-POST__consumertable-last_name-entry}{#consumer-POST__consumertable-middle_name-entry}{#consumer-POST__consumertable-mobile_phone-entry}{#consumer-POST__consumertable-name-entry}{#consumer-POST__consumertable-notes-entry}{#consumer-POST__consumertable-notification-entry}{#consumer-POST__consumertable-photo-entry}{#consumer-POST__consumertable-preferred_language-entry}{#consumer-POST__consumertable-prefix-entry}{#consumer-POST__consumertable-primary-entry}{#consumer-POST__consumertable-state-entry}{#consumer-POST__consumertable-street-entry}{#consumer-POST__consumertable-suffix-entry}{#consumer-POST__consumertable-time_format-entry}{#consumer-POST__consumertable-time_zone-entry}{#consumer-POST__consumertable-title-entry}{#consumer-POST__consumertable-user-entry}{#consumer-POST__consumertable-zip-entry}
| Element | Description |
|-|-|
| active | Flag that indicates whether the consumer is active. Possible values: * true: Consumer active * false: Consumer de-activated {#consumer-POST__ul_asy_4b3_2hb} 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 {#consumer-POST__ul_jsj_qwc_2hb} 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 {#consumer-POST__ul_o5d_pyh_2hb} 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 {#consumer-POST__ul_yns_yb3_2hb} 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) {#consumer-POST__ul_kvg_gxc_2hb} 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 |
[Table 15. Request body parameters (XML or JSON)]
### Headers
The following request and response headers apply to this HTTP
action only, or apply to this action in a distinct way. For a list of general headers used
in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/5p0ILxi5PWo5cXuREsZCAQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#consumer-POST__entry__76}{#consumer-POST__accept-JSON-only-entry-RESTAPI}{#consumer-POST__content_type-JSON-only-entry-RESTAPI}
| Header | Description |
|-|-|
| Accept | Data format of the response body. Only supports application/json. |
| Content-Type | Data format of the request body. Only supports application/json. |
[Table 16. Request headers]
{#consumer-POST__entry__82}
| Header | Description |
|-|-|
| None | |
[Table 17. Response headers]
### Status codes
The following status codes apply to this HTTP action. For a
list of possible status codes used in the REST API, see [REST API HTTP response
codes](https://www.servicenow.com/docs/5p0ILxi5PWo5cXuREsZCAQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#consumer-POST__entry__86}{#consumer-POST__entry-401-status-code}
| 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. |
[Table 18. Status codes]
### Response body parameters (JSON or XML)
{#consumer-POST__entry__96}
| 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"
}
*[\>]: and then