Contact API

Watch

Save as PDF

Share this page

Feedback

API implementation and reference

HomeXanadu API ReferenceAPI implementation and referenceAPI referenceREST API referenceContact API

Table of Contents

Contact API

Release version:
Xanadu
Yokohama
Washington DC
Vancouver
UpdatedAug 1, 2024
19 minutes to read

Xanadu
API reference

The Contact API provides endpoints that enable you to retrieve and update Customer Service Management (CSM) contact records.

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

The Contact API requires the Customer Service plugin (com.sn_customerservice) and is provided within the now namespace.

Users need the csm_ws_integration role for full API access.

Contact - GET /now/contact

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

URL format

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

Default URL: /api/now/contact

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)
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 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.
500	Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.
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 Contact [customer_contact] table. For additional information on these elements, refer to your specific table definition [System Definition > Tables].

Search:


Element	Description
account	Sys_id of the account record to which the contact is associated; Account [customer_account] table. Data type: String
active	Flag that indicates whether the contact is active within the system. Possible values: true: Contact is active false: Contact is inactive Data type: Boolean Default: true
agent_status	Status of the agent. Possible values: Off work On break On route On site Data type: String Maximum length: 40
building	Sys_id of the record that describes the building in which the contact resides; Building [cmn_building] table. Data type: String
calendar_integration	Calendar application that the contact uses. 1: Outlook Data type: Number (Integer) Default: 1
city	City in which the contact resides. Data type: String Maximum length: 40
company	Sys_id of the company record to which the contact is associated; Company [core_company] table. Data type: String
cost_center	Sys_id of the cost center associated with the contact; Cost Center [cmn_cost_center] table. Data type: String
country	Country code of the country in which the contact resides. Data type: String Maximum length: 3
date_format	Format in which to display dates to contacts. 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)
default_perspective	Sys_id of the default perspective for the contact. Located in the Menu List [sys_perspective] table. Data type: String
department	Sys_id of the department associated with the contact. Located in the Department [cmn_department] table. Data type: String
edu_status	Education status of the associated contact. Data type: String Maximum length: 40 Default: faculty
email	Contact email address. Data type: String
employee_number	Contact employee number. Data type: String
enable_multifactor_authn	Flag that indicates whether multifactor authorization is required for the contact to log in to the service portal. Possible values: true: Multifactor authorization enabled false: Multifactor authorization disabled Data type: Boolean Default: false
failed_attempts	Number of failed log in attempts. Data type: Number (Integer)
first_name	Contact first name. Data type: String Maximum length: 50
gender	Contact gender. Data type: String Maximum length: 40
geolocation_tracked	Flag that indicates whether the contact location is obtained through geotracking. Possible values: true: Contact location obtained through geotracking false: Contact location not obtained through geotracking Data type: Boolean Default value: false
home_phone	Contact home phone number. Data type: String Maximum length: 40
internal_integration_user	Flag that indicates whether the contact is an internal integration user. Possible values: true: Internal integration user false: Other type of user Data type: Boolean Default: false
introduction	Introduction Data type: String Maximum length: 40
last_login	Date on which the contact last logged into the system. Data type: String (Date)
last_login_device	Device the consumer used the last time they logged in to the system. Data type: String Maximum length: 40
last_login_time	Date and time the contact logged in to the system. Data type: String (Date/time)
last_name	Contact last name. Data type: String Maximum length: 50
last_position_update	Date and time the last position was updated. Data type: String (Date/time)
latitude	Latitude coordinate of the contact. Data type: Number (Floating point) Maximum length: 40
ldap_server	Sys_id of the LDAP server used by the contact to last log in to the system; LDAP Server [ldap_server_config] table. Data type: String
location	Sys_id of the record that describes the location of the contact; Location [cmn_location] table. Data type: String
locked_out	Flag that indicates if the contact is locked-out. Possible values: true: Contact locked-out false: Contact not locked-out Data type: Boolean Default: false
longitude	Longitude coordinate of the contact. Data type: Number (Floating point) Maximum length: 40
manager	Sys_id of the record that describes the direct supervisor of the contact; User [sys_user] table. Data type: String
middle_name	Contact middle name. Data type: Number (Floating point) Maximum length: 50
mobile_phone	Contact mobile phone number. Data type: String Maximum length: 40
name	Contact full name. Data type: String Maximum length: 151
notification	Indicates whether the contact should receive notifications. Valid values: 1: Disabled 2: Enabled Data type: Number (Integer) Default: 2
on_schedule	Indicates the timeliness of dispatched service personnel. Valid values: Ahead: Ahead of schedule. behind_less30: Behind schedule, but less than 30 minutes. behind_30to60: Behind schedule between 30 and 60 minutes. behind_more60: Behind schedule more than 60 minutes. on_time: On schedule. Data type: String Maximum length: 40
phone	Contact business phone number. Data type: String Maximum length: 40
photo	Photo image of the contact. Data type: Image
preferred_language	Country code of the contact primary language. Data type: String Maximum length: 3
roles	List of user roles associated with the contact. Data type: String Maximum length: 40
schedule	Sys_id of the record that describes the work schedule for the associated contact; Schedule [cmn_schedule] table. Data type: String
source	Source of the contact. Data type: String Maximum length: 255
state	State in which the contact resides. Data type: String Maximum length: 40
street	Contact street address. Data type: String Maximum length: 255
sys_class_name	Table that contains the contact record. Data type: String Maximum length: 80
sys_created_by	User that originally created the associated contact record. Data type: String Maximum length: 40
sys_created_on	Data and time the associated contact was originally created. Data type: String (Date/time)
sys_domain	ServiceNow instance domain of the associated contact record. Data type: String
sys_domain_path	Contact record domain path. Data type: String Maximum length: 255 Default: / (global)
sys_id	Unique identifier for the associated contact record. Data type: String
sys_mod_count	Number of times that the associated contact record has been modified. Data type: Number (Integer)
sys_tags	System tags. Data type: String
sys_updated_by	User that last updated the associated contact information. Data type: String Maximum length: 40
sys_updated_on	Data and time the associated contact information was updated. Data type: String (Date/time)
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_sheet_policy	Sys_id of the record that contains the time sheet policy for the associated contact; Time Sheet Policy [time_sheet_policy] table. Data type: String
time_zone	Time zone in which the contact resides, such as Canada/Central or US/Eastern. Data type: String Maximum length: 40
title	Contact business title such as Manager, Software Developer, or Contractor. Data type: String Maximum length: 60
user_name	Contact user ID. Data type: String Maximum length: 40
vip	Flag that indicates whether the associated contact has VIP status. Possible values: true: VIP false: Not VIP Data type: Boolean Default: false
web_service_access_only	Flag that indicates whether the contact can only access services through the web. Possible values: true: Web access only false: Access through all available methods Data type: Boolean Default: false
zip	Contact zip code. Data type: String Maximum length: 40

Example: cURL request

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

{
  "result": [
    {
      "country": "",
      "calendar_integration": "1",
      "last_position_update": "",
      "last_login_time": "2018-03-10 21:48:11",
      "last_login_device": "",
      "source": "",
      "sys_updated_on": "2019-01-03 05:49:34",
      "building": "",
      "web_service_access_only": "false",
      "notification": "2",
      "sys_updated_by": "system",
      "enable_multifactor_authn": "false",
      "sys_created_on": "2018-03-04 20:26:32",
      "sys_domain": "global",
      "agent_status": "",
      "state": "",
      "vip": "false",
      "sys_created_by": "admin",
      "longitude": "",
      "zip": "",
      "home_phone": "",
      "time_format": "",
      "last_login": "",
      "default_perspective": "",
      "geolocation_tracked": "false",
      "active": "true",
      "time_sheet_policy": "",
      "sys_domain_path": "/",
      "phone": "+1 858 287 7834",
      "cost_center": "",
      "name": "George Warren",
      "employee_number": "",
      "gender": "",
      "city": "",
      "user_name": "george.warren",
      "failed_attempts": "",
      "edu_status": "",
      "latitude": "",
      "roles": "",
      "title": "Network Administrator",
      "sys_class_name": "customer_contact",
      "sys_id": "ddce70866f9331003b3c498f5d3ee417",
      "internal_integration_user": "false",
      "ldap_server": "",
      "mobile_phone": "+1 858 867 7857",
      "street": "",
      "company": "86837a386f0331003b3c498f5d3ee4ca",
      "department": "",
      "first_name": "George",
      "preferred_language": "",
      "introduction": "",
      "email": "geo.warren@mailinator.com",
      "manager": "",
      "locked_out": "false",
      "sys_mod_count": "3",
      "last_name": "Warren",
      "photo": "",
      "sys_tags": "",
      "middle_name": "",
      "time_zone": "",
      "schedule": "",
      "on_schedule": "",
      "date_format": "",
      "location": "25ab8e460a0a0bb300857304ff811af5",
      "account": "86837a386f0331003b3c498f5d3ee4ca"
    },
    {
      "country": "",
      "calendar_integration": "1",
      "last_position_update": "",
      "last_login_time": "2019-01-03 15:08:57",
      "last_login_device": "73.71.157.241",
      "source": "",
      "sys_updated_on": "2019-01-03 23:26:12",
      "building": "",
      "web_service_access_only": "false",
      "notification": "2",
      "sys_updated_by": "admin",
      "enable_multifactor_authn": "false",
      "sys_created_on": "2019-01-03 15:07:25",
      "sys_domain": "global",
      "agent_status": "",
      "state": "",
      "vip": "false",
      "sys_created_by": "carl.customer",
      "longitude": "",
      "zip": "",
      "home_phone": "",
      "time_format": "",
      "last_login": "",
      "default_perspective": "",
      "geolocation_tracked": "false",
      "active": "true",
      "time_sheet_policy": "",
      "sys_domain_path": "/",
      "phone": "+16692627777",
      "cost_center": "",
      "name": "Jane Contact",
      "employee_number": "",
      "gender": "",
      "city": "",
      "user_name": "Jane.Contact",
      "failed_attempts": "",
      "edu_status": "faculty",
      "latitude": "",
      "roles": "",
      "title": "",
      "sys_class_name": "customer_contact",
      "sys_id": "0a232a0013691200042ab3173244b075",
      "internal_integration_user": "false",
      "ldap_server": "",
      "mobile_phone": "",
      "street": "",
      "company": "86837a386f0331003b3c498f5d3ee4ca",
      "department": "",
      "first_name": "Jane",
      "preferred_language": "",
      "introduction": "",
      "email": "jane.contact@mailinator.com",
      "manager": "",
      "locked_out": "false",
      "sys_mod_count": "3",
      "last_name": "Contact",
      "photo": "",
      "sys_tags": "",
      "middle_name": "",
      "time_zone": "",
      "schedule": "",
      "on_schedule": "",
      "date_format": "",
      "location": "",
      "account": "86837a386f0331003b3c498f5d3ee4ca"
    }
  ]
}

Contact - GET /now/contact/{id}

Retrieves the specified Customer Service Management (CSM) contact.

URL format

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

Default URL: /api/now/contact/{id}

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 contact to retrieve. Located in the Contact [customer_contact] table.

Table 8. Query parameters
Name	Description
None

Table 9. Request body parameters (XML or JSON)
Name	Description
None

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.

Search:

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 does not exist. User does not have access to the case.
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)

Search:


Element	Description
account	Sys_id of the account record to which the contact is associated; Account [customer_account] table. Data type: String
active	Flag that indicates whether the contact is active within the system. Possible values: true: Contact is active false: Contact is inactive Data type: Boolean Default: true
agent_status	Status of the agent. Possible values: Off work On break On route On site Data type: String Maximum length: 40
building	Sys_id of the record that describes the building in which the contact resides; Building [cmn_building] table. Data type: String
calendar_integration	Calendar application that the contact uses. 1: Outlook Data type: Number (Integer) Default: 1
city	City in which the contact resides. Data type: String Maximum length: 40
company	Sys_id of the company record to which the contact is associated; Company [core_company] table. Data type: String
cost_center	Sys_id of the cost center associated with the contact; Cost Center [cmn_cost_center] table. Data type: String
country	Country code of the country in which the contact resides. Data type: String Maximum length: 3
date_format	Format in which to display dates to contacts. 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)
default_perspective	Sys_id of the default perspective for the contact. Located in the Menu List [sys_perspective] table. Data type: String
department	Sys_id of the department associated with the contact. Located in the Department [cmn_department] table. Data type: String
edu_status	Education status of the associated contact. Data type: String Maximum length: 40 Default: faculty
email	Contact email address. Data type: String
employee_number	Contact employee number. Data type: String
enable_multifactor_authn	Flag that indicates whether multifactor authorization is required for the contact to log in to the service portal. Possible values: true: Multifactor authorization enabled false: Multifactor authorization disabled Data type: Boolean Default: false
failed_attempts	Number of failed log in attempts. Data type: Number (Integer)
first_name	Contact first name. Data type: String Maximum length: 50
gender	Contact gender. Data type: String Maximum length: 40
geolocation_tracked	Flag that indicates whether the contact location is obtained through geotracking. Possible values: true: Contact location obtained through geotracking false: Contact location not obtained through geotracking Data type: Boolean Default value: false
home_phone	Contact home phone number. Data type: String Maximum length: 40
internal_integration_user	Flag that indicates whether the contact is an internal integration user. Possible values: true: Internal integration user false: Other type of user Data type: Boolean Default: false
introduction	Introduction Data type: String Maximum length: 40
last_login	Date on which the contact last logged into the system. Data type: String (Date)
last_login_device	Device the consumer used the last time they logged in to the system. Data type: String Maximum length: 40
last_login_time	Date and time the contact logged in to the system. Data type: String (Date/time)
last_name	Contact last name. Data type: String Maximum length: 50
last_position_update	Date and time the last position was updated. Data type: String (Date/time)
latitude	Latitude coordinate of the contact. Data type: Number (Floating point) Maximum length: 40
ldap_server	Sys_id of the LDAP server used by the contact to last log in to the system; LDAP Server [ldap_server_config] table. Data type: String
location	Sys_id of the record that describes the location of the contact; Location [cmn_location] table. Data type: String
locked_out	Flag that indicates if the contact is locked-out. Possible values: true: Contact locked-out false: Contact not locked-out Data type: Boolean Default: false
longitude	Longitude coordinate of the contact. Data type: Number (Floating point) Maximum length: 40
manager	Sys_id of the record that describes the direct supervisor of the contact; User [sys_user] table. Data type: String
middle_name	Contact middle name. Data type: Number (Floating point) Maximum length: 50
mobile_phone	Contact mobile phone number. Data type: String Maximum length: 40
name	Contact full name. Data type: String Maximum length: 151
notification	Indicates whether the contact should receive notifications. Valid values: 1: Disabled 2: Enabled Data type: Number (Integer) Default: 2
on_schedule	Indicates the timeliness of dispatched service personnel. Valid values: Ahead: Ahead of schedule. behind_less30: Behind schedule, but less than 30 minutes. behind_30to60: Behind schedule between 30 and 60 minutes. behind_more60: Behind schedule more than 60 minutes. on_time: On schedule. Data type: String Maximum length: 40
phone	Contact business phone number. Data type: String Maximum length: 40
photo	Photo image of the contact. Data type: Image
preferred_language	Country code of the contact primary language. Data type: String Maximum length: 3
roles	List of user roles associated with the contact. Data type: String Maximum length: 40
schedule	Sys_id of the record that describes the work schedule for the associated contact; Schedule [cmn_schedule] table. Data type: String
source	Source of the contact. Data type: String Maximum length: 255
state	State in which the contact resides. Data type: String Maximum length: 40
street	Contact street address. Data type: String Maximum length: 255
sys_class_name	Table that contains the contact record. Data type: String Maximum length: 80
sys_created_by	User that originally created the associated contact record. Data type: String Maximum length: 40
sys_created_on	Data and time the associated contact was originally created. Data type: String (Date/time)
sys_domain	ServiceNow instance domain of the associated contact record. Data type: String
sys_domain_path	Contact record domain path. Data type: String Maximum length: 255 Default: / (global)
sys_id	Unique identifier for the associated contact record. Data type: String
sys_mod_count	Number of times that the associated contact record has been modified. Data type: Number (Integer)
sys_updated_by	User that last updated the associated contact information. Data type: String Maximum length: 40
sys_updated_on	Data and time the associated contact information was updated. Data type: String (Date/time)
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_sheet_policy	Sys_id of the record that contains the time sheet policy for the associated contact; Time Sheet Policy [time_sheet_policy] table. Data type: String
time_zone	Time zone in which the contact resides, such as Canada/Central or US/Eastern. Data type: String Maximum length: 40
title	Contact business title such as Manager, Software Developer, or Contractor. Data type: String Maximum length: 60
user_name	Contact user ID. Data type: String Maximum length: 40
vip	Flag that indicates whether the associated contact has VIP status. Possible values: true: VIP false: Not VIP Data type: Boolean Default: false
web_service_access_only	Flag that indicates whether the contact can only access services through the web. Possible values: true: Web access only false: Access through all available methods Data type: Boolean Default: false
zip	Contact zip code. Data type: String Maximum length: 40

Example: cURL request

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

{
  "result": {
    "country": "",
    "calendar_integration": "1",
    "last_position_update": "",
    "last_login_time": "2018-03-10 21:48:11",
    "last_login_device": "",
    "source": "",
    "sys_updated_on": "2019-01-03 05:49:34",
    "building": "",
    "web_service_access_only": "false",
    "notification": "2",
    "sys_updated_by": "system",
    "enable_multifactor_authn": "false",
    "sys_created_on": "2018-03-04 20:26:32",
    "sys_domain": "global",
    "agent_status": "",
    "state": "",
    "vip": "false",
    "sys_created_by": "admin",
    "longitude": "",
    "zip": "",
    "home_phone": "",
    "time_format": "",
    "last_login": "",
    "default_perspective": "",
    "geolocation_tracked": "false",
    "active": "true",
    "time_sheet_policy": "",
    "sys_domain_path": "/",
    "phone": "+1 858 287 7834",
    "cost_center": "",
    "name": "George Warren",
    "employee_number": "",
    "gender": "",
    "city": "",
    "user_name": "george.warren",
    "failed_attempts": "",
    "edu_status": "",
    "latitude": "",
    "roles": "",
    "title": "Network Administrator",
    "sys_class_name": "customer_contact",
    "sys_id": "ddce70866f9331003b3c498f5d3ee417",
    "internal_integration_user": "false",
    "ldap_server": "",
    "mobile_phone": "+1 858 867 7857",
    "street": "",
    "company": "86837a386f0331003b3c498f5d3ee4ca",
    "department": "",
    "first_name": "George",
    "preferred_language": "",
    "introduction": "",
    "email": "geo.warren@mailinator.com",
    "manager": "",
    "locked_out": "false",
    "sys_mod_count": "3",
    "last_name": "Warren",
    "photo": "",
    "sys_tags": "",
    "middle_name": "",
    "time_zone": "",
    "schedule": "",
    "on_schedule": "",
    "date_format": "",
    "location": "25ab8e460a0a0bb300857304ff811af5",
    "account": "86837a386f0331003b3c498f5d3ee4ca"
  }
}

Contact - POST /now/contact

Creates a new Customer Service Management (CSM) contact.

In addition, you can create a social media profile for the contact 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}/contact

Default URL: /api/now/contact

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

Search:

Table 15. Request body parameters (XML or JSON)
Element	Description
account	Sys_id of the account record to which the contact is associated; Account [customer_account] table. Data type: String
active	Flag that indicates whether the contact is active within the system. Possible values: true: Contact is active false: Contact is inactive Data type: Boolean Default: true
agent_status	Status of the agent. Possible values: Off work On break On route On site Data type: String Maximum length: 40
building	Sys_id of the record that describes the building in which the contact resides; Building [cmn_building] table. Data type: String
calendar_integration	Calendar application that the contact uses. 1: Outlook Data type: Number (Integer) Default: 1
city	City in which the contact resides. Data type: String Maximum length: 40
company	Sys_id of the company record to which the contact is associated; Company [core_company] table. Data type: String
cost_center	Sys_id of the cost center associated with the contact; Cost Center [cmn_cost_center] table. Data type: String
country	Country code of the country in which the contact resides. Data type: String Maximum length: 3
date_format	Format in which to display dates to contacts. 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)
default_perspective	Sys_id of the default perspective for the contact. Located in the Menu List [sys_perspective] table. Data type: String
department	Sys_id of the department associated with the contact. Located in the Department [cmn_department] table. Data type: String
edu_status	Education status of the associated contact. Data type: String Maximum length: 40 Default: faculty
email	Contact email address. Data type: String
employee_number	Contact employee number. Data type: String
enable_multifactor_authn	Flag that indicates whether multifactor authorization is required for the contact to log in to the service portal. Possible values: true: Multifactor authorization enabled false: Multifactor authorization disabled Data type: Boolean Default: false
failed_attempts	Number of failed log in attempts. Data type: Number (Integer)
first_name	Contact first name. Data type: String Maximum length: 50
gender	Contact gender. Data type: String Maximum length: 40
geolocation_tracked	Flag that indicates whether the contact location is obtained through geotracking. Possible values: true: Contact location obtained through geotracking false: Contact location not obtained through geotracking Data type: Boolean Default value: false
home_phone	Contact home phone number. Data type: String Maximum length: 40
internal_integration_user	Flag that indicates whether the contact is an internal integration user. Possible values: true: Internal integration user false: Other type of user Data type: Boolean Default: false
introduction	Introduction Data type: String Maximum length: 40
last_login_device	Device the consumer used the last time they logged in to the system. Data type: String Maximum length: 40
last_login_time	Date and time the contact logged in to the system. Data type: String (Date/time)
last_name	Contact last name. Data type: String Maximum length: 50
latitude	Latitude coordinate of the contact. Data type: Number (Floating point) Maximum length: 40
ldap_server	Sys_id of the LDAP server used by the contact to last log in to the system; LDAP Server [ldap_server_config] table. Data type: String
location	Sys_id of the record that describes the location of the contact; Location [cmn_location] table. Data type: String
locked_out	Flag that indicates if the contact is locked-out. Possible values: true: Contact locked-out false: Contact not locked-out Data type: Boolean Default: false
longitude	Longitude coordinate of the contact. Data type: Number (Floating point) Maximum length: 40
manager	Sys_id of the record that describes the direct supervisor of the contact; User [sys_user] table. Data type: String
middle_name	Contact middle name. Data type: Number (Floating point) Maximum length: 50
mobile_phone	Contact mobile phone number. Data type: String Maximum length: 40
name	Contact full name. Data type: String Maximum length: 151
notification	Indicates whether the contact should receive notifications. Valid values: 1: Disabled 2: Enabled Data type: Number (Integer) Default: 2
on_schedule	Indicates the timeliness of dispatched service personnel. Valid values: Ahead: Ahead of schedule. behind_less30: Behind schedule, but less than 30 minutes. behind_30to60: Behind schedule between 30 and 60 minutes. behind_more60: Behind schedule more than 60 minutes. on_time: On schedule. Data type: String Maximum length: 40
phone	Contact business phone number. Data type: String Maximum length: 40
photo	Photo image of the contact. Data type: Image
preferred_language	Country code of the contact primary language. Data type: String Maximum length: 3
roles	List of user roles associated with the contact. Data type: String Maximum length: 40
schedule	Sys_id of the record that describes the work schedule for the associated contact; Schedule [cmn_schedule] table. Data type: String
social_channel	Social media channel to which the contact 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 contact's social channel profile. Data type: String
source	Source of the contact. Data type: String Maximum length: 255
state	State in which the contact resides. Data type: String Maximum length: 40
street	Contact street address. Data type: String Maximum length: 255
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_sheet_policy	Sys_id of the record that contains the time sheet policy for the associated contact; Time Sheet Policy [time_sheet_policy] table. Data type: String
time_zone	Time zone in which the contact resides, such as Canada/Central or US/Eastern. Data type: String Maximum length: 40
title	Contact business title such as Manager, Software Developer, or Contractor. Data type: String Maximum length: 60
user_name	Contact user ID. Data type: String Maximum length: 40
vip	Flag that indicates whether the associated contact has VIP status. Possible values: true: VIP false: Not VIP Data type: Boolean Default: false
web_service_access_only	Flag that indicates whether the contact can only access services through the web. Possible values: true: Web access only false: Access through all available methods Data type: Boolean Default: false
zip	Contact zip code. Data type: String Maximum length: 40

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.

Search:

Table 18. Status codes
Status code	Description
201	New contact 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 contact record. Data type: String

Example: cURL request

curl -X POST "https://instance.servicenow.com/api/now/contact" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{ \
  "country": "USA", \
  "calendar_integration": "1", \
  "last_login_time": "2018-03-10 21:48:11", \
  "last_login_device": "tablet", \
  "building": "Cardinal West", \
  "web_service_access_only": "false", \
  "notification": "1", \
  "enable_multifactor_authn": "true", \
  "agent_status": "Travelling", \
  "state": "CA", \
  "vip": "false", \
  "longitude": "123.76", \
  "zip": "92069", \
  "home_phone": "(555)555-1234", \
  "time_format": "hh:mm:ss", \
  "geolocation_tracked": "false", \
  "active": "true", \
  "phone": "+1 858 287 7834", \
  "cost_center": "1345", \
  "name": "Dora Warren", \
  "employee_number": "546", \
  "gender": "Female", \
  "city": "Orlando", \
  "user_name": "dora.warren", \
  "failed_attempts": "2", \
  "edu_status": "current", \
  "latitude": "57.6", \
  "title": "Network Administrator", \
  "internal_integration_user": "false", \
  "ldap_server": "10.24.23.123", \
  "mobile_phone": "+1 858 867 7857", \
  "street": "123 Lagume", \
  "company": "86837a386f0331003b3c498f5d3ee4ca", \
  "department": "IT", \
  "first_name": "Dora", \
  "preferred_language": "Spanish", \
  "email": "dora.warren@mailinator.com", \
  "manager": "ddce70866f9331003b3c498f5d3ee417", \
  "locked_out": "false", \
  "last_name": "Warren", \
  "middle_name": "Dell", \
  "time_zone": "PST", \
  "schedule": "9-5", \
  "date_format": "MM/DD/YY", \
  "location": "25ab8e460a0a0bb300857304ff811af5", \
  "account": "86837a386f0331003b3c498f5d3ee4ca" \
}'
--user 'username':'password'

"result": "62fe1c97db76c3006b7a9646db961999"

Was this topic helpful?

Yes No

Consumer API

Continuous Integration/Continuous Delivery (CICD) API

Consumer API

Continuous Integration/Continuous Delivery (CICD) API

Xanadu API Reference

Filters

Versions

Products

Contact API

Table of contents

Contact API

Contact - GET /now/contact

URL format

Supported request parameters

Headers

Status codes

Response body parameters (JSON or XML)

Example: cURL request

Contact - GET /now/contact/{id}

URL format

Supported request parameters

Headers

Status codes

Response body parameters (JSON or XML)

Example: cURL request

Contact - POST /now/contact

URL format

Supported request parameters

Headers

Status codes

Response body parameters (JSON or XML)

Example: cURL request

On this page

Log in to get a better experience

Please let us know how to improve this content

Save as PDF

Please let us know how to improve this content

Explain this code

Explain this code

Explain this code

Explain this code

Explain this code

Explain this code