ServiceNow REST API Basics

ServiceNow's REST API lets external systems communicate with ServiceNow over the internet using standard HTTP requests. Any application that can make an HTTP call — a mobile app, a Python script, a monitoring tool, or another cloud platform — can create, read, update, and delete ServiceNow records through the REST API without anyone logging into the browser interface.

What REST Means

REST stands for Representational State Transfer. It is the most widely used standard for web APIs. REST APIs communicate through HTTP methods (GET, POST, PUT, PATCH, DELETE) and exchange data in JSON format. ServiceNow's REST API follows this standard, making it compatible with virtually every modern programming language and integration tool.

HTTP Method → ServiceNow Action
──────────────────────────────────────────────────────
GET         → Read records from a table
POST        → Create a new record
PUT         → Replace an entire record's fields
PATCH       → Update specific fields on a record
DELETE      → Remove a record
──────────────────────────────────────────────────────

The Table API: ServiceNow's Core REST Endpoint

The Table API is the most frequently used ServiceNow REST API. It provides direct access to any table in the instance using a predictable URL pattern:

Base URL pattern:
https://<instance>.service-now.com/api/now/table/<table_name>

Examples:
Read all incidents:
  GET  https://acme.service-now.com/api/now/table/incident

Read one incident by sys_id:
  GET  https://acme.service-now.com/api/now/table/incident/<sys_id>

Create a new incident:
  POST https://acme.service-now.com/api/now/table/incident

Update an incident:
  PATCH https://acme.service-now.com/api/now/table/incident/<sys_id>

Delete an incident:
  DELETE https://acme.service-now.com/api/now/table/incident/<sys_id>

Authentication

Every REST API call must authenticate. ServiceNow supports two primary authentication methods:

Basic Authentication

The caller sends a username and password encoded in the HTTP request header. Simple to set up but less secure for production integrations because credentials travel with every request.

HTTP Header:
Authorization: Basic <base64-encoded username:password>

OAuth 2.0

The preferred method for production integrations. The external system first requests an access token from ServiceNow using client credentials. It then uses that token in subsequent API calls. Tokens expire after a set period and can be refreshed without re-sending credentials.

OAuth Flow:
External App → POST /oauth_token.do (client_id + client_secret)
             ← ServiceNow responds with access_token
External App → GET /api/now/table/incident
               Authorization: Bearer <access_token>
             ← ServiceNow returns incident data

Query Parameters

Query parameters in the URL filter and shape the API response. They are appended after a question mark in the URL:

sysparm_query

Filters records using ServiceNow's encoded query syntax. This is the URL equivalent of the condition builder in the UI.

GET .../table/incident?sysparm_query=state=1^priority=1
→ Returns only Critical New incidents

sysparm_fields

Limits which fields the API returns. By default the API returns all fields — often over 100 per record. Specifying only needed fields dramatically reduces response size and improves speed.

GET .../table/incident?sysparm_fields=number,short_description,state,priority
→ Returns only these 4 fields per record

sysparm_limit and sysparm_offset

Control pagination. sysparm_limit caps how many records return per call. sysparm_offset skips a number of records, enabling the caller to retrieve the next page of results.

GET .../table/incident?sysparm_limit=10&sysparm_offset=0  → Page 1
GET .../table/incident?sysparm_limit=10&sysparm_offset=10 → Page 2

sysparm_display_value

By default the API returns stored values (numbers, sys_ids). Setting sysparm_display_value=true returns human-readable display values instead. Setting it to "all" returns both stored and display values for every field.

Default:    "state": "1"
With true:  "state": "New"
With "all": "state": {"value": "1", "display_value": "New"}

Creating a Record with POST

POST https://acme.service-now.com/api/now/table/incident
Content-Type: application/json
Authorization: Basic <credentials>

Request body:
{
  "short_description": "VPN not connecting",
  "category": "network",
  "urgency": "2",
  "caller_id": "john.smith"
}

Response:
{
  "result": {
    "number": "INC0001567",
    "sys_id": "abc123...",
    "state": {"display_value": "New"},
    "short_description": "VPN not connecting"
  }
}

The REST API Explorer

ServiceNow includes a built-in REST API Explorer at System Web Services > REST API Explorer. It generates sample request code in multiple languages (curl, Python, JavaScript, Ruby) for any table and operation. Developers use the Explorer to test API calls directly from the browser before building integrations, eliminating the need for external tools like Postman for initial testing.