The ServiceNow Contact API provides endpoints for retrieving and updating Customer Service Management (CSM) contact records. It also supports generating new social media profile records when creating a contact, and requires the Customer Service plugin (com.sn_customerservice).
openapi: 3.1.0
info:
title: ServiceNow Contact API
description: |
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.
**Authentication**: Users need the `csm_ws_integration` role for full API access.
version: Zurich
contact:
name: ServiceNow
url: https://docs.servicenow.com
x-namespace: now
servers:
- url: https://{instance}.servicenow.com/api/now
description: ServiceNow instance
variables:
instance:
default: instance
description: Your ServiceNow instance name
security:
- basicAuth: []
tags:
- name: Contact
description: Operations for managing Customer Service Management contacts
paths:
/contact:
get:
tags:
- Contact
summary: Servicenow Retrieve Contacts
description: Retrieves a specified set of Customer Service Management (CSM) contacts.
operationId: getContacts
parameters:
- name: sysparm_query
in: query
description: Encoded query used to filter the result set. Supports order by using ORDERBY and ORDERBYDESC clauses.
required: false
schema:
type: string
example: "caller_id=javascript:gs.getUserID()^active=true"
- name: sysparm_limit
in: query
description: Maximum number of records to return
required: false
schema:
type: integer
minimum: 1
default: 10
example: 10
- name: sysparm_offset
in: query
description: Starting record index for pagination (do not pass negative numbers)
required: false
schema:
type: integer
minimum: 0
default: 0
example: 10
responses:
'200':
description: Successful. The request was successfully processed.
content:
application/json:
schema:
type: object
properties:
result:
type: array
items:
$ref: '#/components/schemas/Contact'
examples:
Getcontacts200Example:
summary: Default getContacts 200 response
x-microcks-default: true
value:
result:
- sys_id: '500123'
name: Example Title
first_name: example_value
middle_name: example_value
last_name: example_value
user_name: example_value
email: [email protected]
phone: example_value
mobile_phone: example_value
home_phone: example_value
title: Example Title
employee_number: example_value
company: example_value
account: 42
department: example_value
manager: example_value
location: example_value
building: example_value
street: example_value
city: example_value
state: example_value
zip: example_value
country: 42
active: true
vip: true
locked_out: true
web_service_access_only: true
internal_integration_user: true
enable_multifactor_authn: true
geolocation_tracked: true
notification: 1
calendar_integration: 10
failed_attempts: 10
latitude: 42.5
longitude: 42.5
time_zone: example_value
date_format: "dd/mm/yyyy"
time_format: "hh.mm.ss a"
preferred_language: example_value
gender: example_value
photo: example_value
introduction: example_value
source: example_value
roles: example_value
cost_center: example_value
schedule: example_value
time_sheet_policy: example_value
default_perspective: example_value
ldap_server: example_value
agent_status: "Off work"
on_schedule: "Ahead"
edu_status: example_value
last_login: '2026-01-15'
last_login_time: '2026-01-15T10:30:00Z'
last_login_device: example_value
last_position_update: '2026-01-15T10:30:00Z'
sys_class_name: example_value
sys_created_by: example_value
sys_created_on: '2026-01-15T10:30:00Z'
sys_updated_by: example_value
sys_updated_on: '2026-01-15T10:30:00Z'
sys_mod_count: 42
sys_domain: example_value
sys_domain_path: example_value
sys_tags: example_value
application/xml:
schema:
type: object
properties:
result:
type: array
items:
$ref: '#/components/schemas/Contact'
examples:
Getcontacts200Example:
summary: Default getContacts 200 response
x-microcks-default: true
value:
result:
- sys_id: '500123'
name: Example Title
first_name: example_value
middle_name: example_value
last_name: example_value
user_name: example_value
email: [email protected]
phone: example_value
mobile_phone: example_value
home_phone: example_value
title: Example Title
employee_number: example_value
company: example_value
account: 42
department: example_value
manager: example_value
location: example_value
building: example_value
street: example_value
city: example_value
state: example_value
zip: example_value
country: 42
active: true
vip: true
locked_out: true
web_service_access_only: true
internal_integration_user: true
enable_multifactor_authn: true
geolocation_tracked: true
notification: 1
calendar_integration: 10
failed_attempts: 10
latitude: 42.5
longitude: 42.5
time_zone: example_value
date_format: "dd/mm/yyyy"
time_format: "hh.mm.ss a"
preferred_language: example_value
gender: example_value
photo: example_value
introduction: example_value
source: example_value
roles: example_value
cost_center: example_value
schedule: example_value
time_sheet_policy: example_value
default_perspective: example_value
ldap_server: example_value
agent_status: "Off work"
on_schedule: "Ahead"
edu_status: example_value
last_login: '2026-01-15'
last_login_time: '2026-01-15T10:30:00Z'
last_login_device: example_value
last_position_update: '2026-01-15T10:30:00Z'
sys_class_name: example_value
sys_created_by: example_value
sys_created_on: '2026-01-15T10:30:00Z'
sys_updated_by: example_value
sys_updated_on: '2026-01-15T10:30:00Z'
sys_mod_count: 42
sys_domain: example_value
sys_domain_path: example_value
sys_tags: example_value
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
Getcontacts500Example:
summary: Default getContacts 500 response
x-microcks-default: true
value:
error:
message: example_value
detail: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
tags:
- Contact
summary: Servicenow Create a Contact
description: |
Creates a new Customer Service Management (CSM) contact.
You can also create a social media profile for the contact by specifying:
- social_channel
- social_handle
- social_handle_url
**Warning**: This endpoint does not perform parameter validation. Misspelled or invalid parameters are ignored without warning.
operationId: createContact
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ContactCreate'
examples:
CreatecontactRequestExample:
summary: Default createContact request
x-microcks-default: true
value:
name: Example Title
first_name: example_value
middle_name: example_value
last_name: example_value
user_name: example_value
email: [email protected]
phone: example_value
mobile_phone: example_value
home_phone: example_value
title: Example Title
employee_number: example_value
company: example_value
account: 42
department: example_value
manager: example_value
location: example_value
building: example_value
street: example_value
city: example_value
state: example_value
zip: example_value
country: 42
active: true
vip: true
locked_out: true
web_service_access_only: true
internal_integration_user: true
enable_multifactor_authn: true
geolocation_tracked: true
notification: 1
calendar_integration: 10
failed_attempts: 10
latitude: 42.5
longitude: 42.5
time_zone: example_value
date_format: "dd/mm/yyyy"
time_format: "hh.mm.ss a"
preferred_language: example_value
gender: example_value
photo: example_value
introduction: example_value
source: example_value
roles: example_value
cost_center: example_value
schedule: example_value
time_sheet_policy: example_value
default_perspective: example_value
ldap_server: example_value
agent_status: "Off work"
on_schedule: "Ahead"
edu_status: example_value
last_login_time: '2026-01-15T10:30:00Z'
last_login_device: example_value
social_channel: example_value
social_handle: example_value
social_handle_url: https://www.example.com
responses:
'201':
description: New contact record was successfully created
content:
application/json:
schema:
type: object
properties:
result:
type: string
description: Sys_id of the newly created contact record
examples:
Createcontact201Example:
summary: Default createContact 201 response
x-microcks-default: true
value:
result: example_value
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
Createcontact400Example:
summary: Default createContact 400 response
x-microcks-default: true
value:
error:
message: example_value
detail: example_value
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
Createcontact401Example:
summary: Default createContact 401 response
x-microcks-default: true
value:
error:
message: example_value
detail: example_value
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
Createcontact500Example:
summary: Default createContact 500 response
x-microcks-default: true
value:
error:
message: example_value
detail: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/contact/{id}:
get:
tags:
- Contact
summary: Servicenow Retrieve a Specific Contact
description: Retrieves the specified Customer Service Management (CSM) contact.
operationId: getContactById
parameters:
- name: id
in: path
description: Sys_id of the contact to retrieve
required: true
schema:
type: string
example: abc123
responses:
'200':
description: Successful. The request was successfully processed.
content:
application/json:
schema:
type: object
properties:
result:
$ref: '#/components/schemas/Contact'
examples:
Getcontactbyid200Example:
summary: Default getContactById 200 response
x-microcks-default: true
value:
result:
sys_id: '500123'
name: Example Title
first_name: example_value
middle_name: example_value
last_name: example_value
user_name: example_value
email: [email protected]
phone: example_value
mobile_phone: example_value
home_phone: example_value
title: Example Title
employee_number: example_value
company: example_value
account: 42
department: example_value
manager: example_value
location: example_value
building: example_value
street: example_value
city: example_value
state: example_value
zip: example_value
country: 42
active: true
vip: true
locked_out: true
web_service_access_only: true
internal_integration_user: true
enable_multifactor_authn: true
geolocation_tracked: true
notification: 1
calendar_integration: 10
failed_attempts: 10
latitude: 42.5
longitude: 42.5
time_zone: example_value
date_format: "dd/mm/yyyy"
time_format: "hh.mm.ss a"
preferred_language: example_value
gender: example_value
photo: example_value
introduction: example_value
source: example_value
roles: example_value
cost_center: example_value
schedule: example_value
time_sheet_policy: example_value
default_perspective: example_value
ldap_server: example_value
agent_status: "Off work"
on_schedule: "Ahead"
edu_status: example_value
last_login: '2026-01-15'
last_login_time: '2026-01-15T10:30:00Z'
last_login_device: example_value
last_position_update: '2026-01-15T10:30:00Z'
sys_class_name: example_value
sys_created_by: example_value
sys_created_on: '2026-01-15T10:30:00Z'
sys_updated_by: example_value
sys_updated_on: '2026-01-15T10:30:00Z'
sys_mod_count: 42
sys_domain: example_value
sys_domain_path: example_value
sys_tags: example_value
application/xml:
schema:
type: object
properties:
result:
$ref: '#/components/schemas/Contact'
examples:
Getcontactbyid200Example:
summary: Default getContactById 200 response
x-microcks-default: true
value:
result:
sys_id: '500123'
name: Example Title
first_name: example_value
middle_name: example_value
last_name: example_value
user_name: example_value
email: [email protected]
phone: example_value
mobile_phone: example_value
home_phone: example_value
title: Example Title
employee_number: example_value
company: example_value
account: 42
department: example_value
manager: example_value
location: example_value
building: example_value
street: example_value
city: example_value
state: example_value
zip: example_value
country: 42
active: true
vip: true
locked_out: true
web_service_access_only: true
internal_integration_user: true
enable_multifactor_authn: true
geolocation_tracked: true
notification: 1
calendar_integration: 10
failed_attempts: 10
latitude: 42.5
longitude: 42.5
time_zone: example_value
date_format: "dd/mm/yyyy"
time_format: "hh.mm.ss a"
preferred_language: example_value
gender: example_value
photo: example_value
introduction: example_value
source: example_value
roles: example_value
cost_center: example_value
schedule: example_value
time_sheet_policy: example_value
default_perspective: example_value
ldap_server: example_value
agent_status: "Off work"
on_schedule: "Ahead"
edu_status: example_value
last_login: '2026-01-15'
last_login_time: '2026-01-15T10:30:00Z'
last_login_device: example_value
last_position_update: '2026-01-15T10:30:00Z'
sys_class_name: example_value
sys_created_by: example_value
sys_created_on: '2026-01-15T10:30:00Z'
sys_updated_by: example_value
sys_updated_on: '2026-01-15T10:30:00Z'
sys_mod_count: 42
sys_domain: example_value
sys_domain_path: example_value
sys_tags: example_value
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
Getcontactbyid401Example:
summary: Default getContactById 401 response
x-microcks-default: true
value:
error:
message: example_value
detail: example_value
'404':
description: |
Not found. Could be due to:
- Requested contact doesn't exist
- User doesn't have access to the contact
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
Getcontactbyid404Example:
summary: Default getContactById 404 response
x-microcks-default: true
value:
error:
message: example_value
detail: example_value
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
Getcontactbyid500Example:
summary: Default getContactById 500 response
x-microcks-default: true
value:
error:
message: example_value
detail: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: Basic authentication with ServiceNow credentials. User must have the csm_ws_integration role.
schemas:
Contact:
type: object
description: Customer Service Management contact record
properties:
sys_id:
type: string
description: Unique identifier for the contact record
example: '500123'
name:
type: string
maxLength: 151
description: Contact full name
example: Example Title
first_name:
type: string
maxLength: 50
description: Contact first name
example: example_value
middle_name:
type: string
maxLength: 50
description: Contact middle name
example: example_value
last_name:
type: string
maxLength: 50
description: Contact last name
example: example_value
user_name:
type: string
maxLength: 40
description: Contact user ID
example: example_value
email:
type: string
description: Contact email address
example: [email protected]
phone:
type: string
maxLength: 40
description: Contact business phone number
example: example_value
mobile_phone:
type: string
maxLength: 40
description: Contact mobile phone number
example: example_value
home_phone:
type: string
maxLength: 40
description: Contact home phone number
example: example_value
title:
type: string
maxLength: 60
description: Contact business title
example: Example Title
employee_number:
type: string
description: Contact employee number
example: example_value
company:
type: string
description: Sys_id of the company record
example: example_value
account:
type: string
description: Sys_id of the account record
example: 42
department:
type: string
description: Sys_id of the department
example: example_value
manager:
type: string
description: Sys_id of the direct supervisor
example: example_value
location:
type: string
description: Sys_id of the location
example: example_value
building:
type: string
description: Sys_id of the building
example: example_value
street:
type: string
maxLength: 255
description: Contact street address
example: example_value
city:
type: string
maxLength: 40
description: City in which the contact resides
example: example_value
state:
type: string
maxLength: 40
description: State in which the contact resides
example: example_value
zip:
type: string
maxLength: 40
description: Contact zip code
example: example_value
country:
type: string
maxLength: 3
description: Country code
example: 42
active:
type: boolean
default: true
description: Flag indicating whether the contact is active
example: true
vip:
type: boolean
default: false
description: Flag indicating whether the contact has VIP status
example: true
locked_out:
type: boolean
default: false
description: Flag indicating if the contact is locked-out
example: true
web_service_access_only:
type: boolean
default: false
description: Flag indicating whether the contact can only access services through the web
example: true
internal_integration_user:
type: boolean
default: false
description: Flag indicating whether the contact is an internal integration user
example: true
enable_multifactor_authn:
type: boolean
default: false
description: Flag indicating whether multifactor authorization is required
example: true
geolocation_tracked:
type: boolean
default: false
description: Flag indicating whether the contact location is obtained through geotracking
example: true
notification:
type: integer
default: 2
description: Indicates whether the contact should receive notifications (1=Disabled, 2=Enabled)
enum: [1, 2]
example: 1
calendar_integration:
type: integer
default: 1
description: Calendar application that the contact uses (1=Outlook)
example: 10
failed_attempts:
type: integer
description: Number of failed login attempts
example: 10
latitude:
type: number
format: float
maxLength: 40
description: Latitude coordinate of the contact
example: 42.5
longitude:
type: number
format: float
maxLength: 40
description: Longitude coordinate of the contact
example: 42.5
time_zone:
type: string
maxLength: 40
description: Time zone in which the contact resides
example: example_value
date_format:
type: string
maxLength: 40
description: Format in which to display dates
enum:
- "dd/mm/yyyy"
- "dd-mm-yyyy"
- "dd.mm.yyyy"
- "mm-dd-yyyy"
- "yyyy-mm-dd"
example: "dd/mm/yyyy"
time_format:
type: string
maxLength: 40
description: Format in which to display time
enum:
- "hh.mm.ss a"
- "hh:mm:ss a"
- "HH.mm.ss"
- "HH:mm:ss"
example: "hh.mm.ss a"
preferred_language:
type: string
maxLength: 3
description: Country code of the contact primary language
example: example_value
gender:
type: string
maxLength: 40
description: Contact gender
example: example_value
photo:
type: string
description: Photo image of the contact
example: example_value
introduction:
type: string
maxLength: 40
description: Introduction
example: example_value
source:
type: string
maxLength: 255
description: Source of the contact
example: example_value
roles:
type: string
maxLength: 40
description: List of user roles associated with the contact
example: example_value
cost_center:
type: string
description: Sys_id of the cost center
example: example_value
schedule:
type: string
description: Sys_id of the work schedule
example: example_value
time_sheet_policy:
type: string
description: Sys_id of the time sheet policy
example: example_value
default_perspective:
type: string
description: Sys_id of the default perspective
example: example_value
ldap_server:
type: string
description: Sys_id of the LDAP server
example: example_value
agent_status:
type: string
maxLength: 40
description: Status of the agent
enum:
- "Off work"
- "On break"
- "On route"
- "On site"
example: "Off work"
on_schedule:
type: string
maxLength: 40
description: Indicates the timeliness of dispatched service personnel
enum:
- "Ahead"
- "behind_less30"
- "behind_30to60"
- "behind_more60"
- "on_time"
example: "Ahead"
edu_status:
type: string
maxLength: 40
default: faculty
description: Education status of the contact
example: example_va
# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/servicenow/refs/heads/main/openapi/contact-api-openapi.yaml