ServiceNow REST API: Complete Developer Reference

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

// Get active P1 incidents, return only key fields
GET /api/now/table/incident
?sysparm_query=active=true^priority=1
&sysparm_fields=number,short_description,assigned_to,state
&sysparm_limit=100
&sysparm_offset=0
&sysparm_display_value=true

Authorization: Basic <base64(username:password)>

// Step 1: Get access token
POST /oauth_token.do
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=<your_client_id>
&client_secret=<your_client_secret>
&username=<integration_user>
&password=<integration_user_password>

// Response
{
  "access_token": "abc123...",
  "token_type": "Bearer",
  "expires_in": 1800
}

// Step 2: Use the token
GET /api/now/table/incident
Authorization: Bearer abc123...

// Example: Custom endpoint that returns incident metrics
(function process(request, response) {
    var ga = new GlideAggregate('incident');
    ga. For a complete walkthrough, see our guide to building a Scripted REST API.addEncodedQuery('active=true');
    ga.addAggregate('COUNT', 'priority');
    ga.groupBy('priority');
    ga.query();
    
    var metrics = {};
    while (ga.next()) {
        metrics[ga.priority.getDisplayValue()] = 
            ga.getAggregate('COUNT', 'priority');
    }
    
    response.setStatus(200);
    response.setContentType('application/json');
    response.setBody(JSON.stringify(metrics));
})(request, response);

// Check response headers for total count
X-Total-Count: 45823

// Paginate using offset
GET /api/now/table/incident?sysparm_limit=1000&sysparm_offset=0
GET /api/now/table/incident?sysparm_limit=1000&sysparm_offset=1000
GET /api/now/table/incident?sysparm_limit=1000&sysparm_offset=2000
// ... continue until offset >= X-Total-Count

POST /api/now/v1/batch
{
  "batch_request_id": "batch_001",
  "rest_requests": [
    {
      "id": "create_incident",
      "method": "POST",
      "url": "/api/now/table/incident",
      "body": { "short_description": "Test", "category": "software" }
    },
    {
      "id": "get_user",
      "method": "GET", 
      "url": "/api/now/table/sys_user?sysparm_query=user_name=john.smith"
    }
  ]
}

Choosing the right ServiceNow REST API

ServiceNow exposes multiple REST API types. The Table API (/api/now/table/{tablename}) is the default for external systems reading or writing ServiceNow records — incidents, users, CIs, catalog requests. It requires no custom development and supports all standard operations. The Aggregate API (/api/now/stats/{tablename}) returns aggregate values (COUNT, SUM, AVG) rather than individual records — use it when you need summary metrics without loading full records. The Attachment API handles file attachments. Scripted REST APIs provide custom endpoints when the standard APIs do not fit your use case — complex business logic, non-table data, custom authentication requirements. Start with the Table API; build a Scripted REST API only when the Table API cannot express what you need.

Rate limits and pagination

ServiceNow's REST APIs enforce rate limits — too many requests in a short period returns a 429 response. The exact limits depend on your instance size and contract. Build retry logic with exponential backoff for 429 responses, and implement pagination using the sysparm_limit and sysparm_offset parameters for large result sets. The X-Total-Count response header tells you the total number of matching records so you know how many pages to request. Never assume all results fit in one response — for tables with millions of records, a query without a limit will either timeout or return partial results.

Related: Table API reference · Scripted REST APIs · OAuth 2.0 · HTTP status codes

Inbound vs Outbound REST: Two Distinct Models

ServiceNow's REST capabilities split into two completely separate models. Inbound REST means external systems calling ServiceNow — using the Table API, Scripted REST APIs, or the Import Set API to read or write ServiceNow data. Outbound REST means ServiceNow calling external systems — using RESTMessageV2, IntegrationHub spokes, or Flow Designer REST steps. Most integration guides conflate these two models, which creates confusion when debugging. An authentication error on inbound means the calling system's credentials are wrong. An authentication error on outbound means ServiceNow's stored credentials for the target system are wrong. Always establish which direction the call is flowing before starting to investigate.

Table API Deep Dive

The Table API is ServiceNow's most-used inbound interface and supports full CRUD operations on any table. GET requests accept encoded query strings via the sysparm_query parameter — the same query syntax used in GlideRecord encoded queries, making it easy to translate existing report filters into API queries. The sysparm_fields parameter limits which fields are returned, which is critical for performance on tables with many fields. The sysparm_limit and sysparm_offset parameters implement pagination — there is no cursor-based pagination in the Table API, so large result sets require iterating offset values. The default limit is 10,000 records per call, but calling without a limit on a large table can trigger timeout errors in both the calling system and ServiceNow.

Aggregate API for Summary Data

The Aggregate API exposes GlideAggregate functionality over REST. It supports COUNT, SUM, MIN, MAX, and AVG operations with GROUP BY, returning summary statistics without returning individual records. This is the right choice when external dashboards or reporting tools need aggregate data from ServiceNow — it is dramatically more efficient than retrieving thousands of records and aggregating them client-side. A dashboard showing open incidents by priority and assignment group can retrieve that entire dataset in a single Aggregate API call that returns six numbers, rather than a Table API call returning thousands of incident records.

Import Set API for Bulk Data Load

The Import Set API is purpose-built for loading external data into ServiceNow in bulk. Rather than using repeated Table API inserts, the Import Set API accepts a JSON or XML payload that gets staged in an import table, processed through a Transform Map, and loaded into the target table. This approach is more efficient for bulk operations, provides a processing audit trail through the Import Sets framework, and handles data transformation and coercion in the transform layer rather than requiring the calling system to format data exactly as ServiceNow expects. The tradeoff is asynchronous processing — data does not appear in the target table immediately but after the transform job runs.

Scripted REST APIs for Custom Endpoints

When the standard APIs do not fit the integration contract — the external system expects a specific URL structure, response format, or business logic — Scripted REST APIs provide a way to build custom endpoints that run arbitrary server-side logic. A Scripted REST API can aggregate data from multiple tables, apply business rules before returning data, accept custom authentication schemes, or return responses formatted to match a legacy system's expectations. The building guide covers the full implementation pattern including request object access, response formatting, and error handling.

Choosing Between Table API and Scripted REST

Most inbound integration requirements are fully served by the Table API without any custom development. Before building a Scripted REST API, verify that the Table API with appropriate sysparm_fields and sysparm_query parameters does not already meet the requirement. The cases where Scripted REST is genuinely necessary are: the calling system cannot handle ServiceNow's standard response envelope structure; the integration needs to perform multi-table operations atomically; the endpoint needs to implement custom authentication or business logic before returning data; or the URL structure is dictated by the external system and does not match ServiceNow's standard API path format. Building Scripted REST APIs for requirements that the Table API can meet adds maintenance cost without adding capability — every custom endpoint is code that needs testing, documentation, and updating when platform changes affect its dependencies.

Authentication Options for API Consumers

ServiceNow supports multiple authentication mechanisms for inbound API calls. Basic authentication (username and password) is simplest to implement but transmits credentials on every call and does not support fine-grained token expiry. OAuth 2.0 is the recommended approach for any external system integration — it issues short-lived tokens that expire and can be revoked without changing the underlying user credentials. Session-based authentication (logging in through the standard login endpoint and using the session cookie) works for browser-based integrations but is impractical for server-to-server calls. For internal scripts that use the API, a dedicated integration service account with the minimum required roles (not admin) reduces the blast radius if the credentials are compromised. Never use personal user credentials for integrations — when that person leaves the organisation, the integration breaks.