Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 39 ยท Integrations and Service Portal

ServiceNow REST APIs: Table API, REST Messages and Scripted REST

Learn the ServiceNow REST Table API, calling outside services with REST Messages and RESTMessageV2, building Scripted REST APIs, and authentication basics.

Systems rarely live alone. A ServiceNow instance exchanges data with monitoring tools, HR systems, chat apps and cloud platforms. The most common way is REST: HTTP requests that send and receive JSON. ServiceNow works in both directions: it exposes REST APIs that others call, and it consumes the REST APIs of other systems.

The requests below need a real instance and credentials, so they are shown as read-only text. Never put real passwords in scripts; use credential records. The runnable blocks are stand-ins that build and parse the same JSON shapes.

The Table API (built in)

Every table is reachable at a standard URL:

TEXT
GET    https://INSTANCE.service-now.com/api/now/table/incident?sysparm_query=active=true^priority=1&sysparm_limit=5
GET    https://INSTANCE.service-now.com/api/now/table/incident/{sys_id}
POST   https://INSTANCE.service-now.com/api/now/table/incident
PATCH  https://INSTANCE.service-now.com/api/now/table/incident/{sys_id}
DELETE https://INSTANCE.service-now.com/api/now/table/incident/{sys_id}

A POST body is JSON with field names:

JSON
{ "short_description": "Badge reader offline", "urgency": "2", "caller_id": "abel.tuter" }

The response wraps the record in a result property:

JSON
{ "result": { "sys_id": "...", "number": "INC0010010", "short_description": "Badge reader offline" } }

Useful query parameters:

Parameter Effect
sysparm_query Encoded query, same syntax as list filters
sysparm_limit, sysparm_offset Paging
sysparm_fields Return only the listed fields
sysparm_display_value=true Display values instead of raw values
sysparm_exclude_reference_link=true Smaller response

The user must have a role permitting access, and ACLs still apply: the API acts as that user. Create a dedicated integration user with minimal roles instead of using an admin account. Other built-in APIs include the Aggregate API (/api/now/stats/{table}), Attachment API and Import Set API.

Authentication choices: basic auth over HTTPS (acceptable for simple server-to-server calls with a dedicated account), OAuth 2.0 (preferred: tokens that expire), and mutual TLS. Pick OAuth for anything serious.

Response codes

200 and 201 success; 400 bad request; 401 not authenticated; 403 forbidden by ACL or role; 404 no such record or table; 429 rate limited. Look at the error.message in the body.

Consuming REST: REST Messages

To call another system from ServiceNow, define a REST Message (System Web Services > Outbound > REST Message). It holds the endpoint, authentication (Basic, OAuth profile, API key) and a list of HTTP Methods with headers and parameters. Variables in ${name} form can be filled at call time.

JavaScript
var r = new sn_ws.RESTMessageV2('Weather Service', 'Get Forecast');
r.setStringParameterNoEscape('city', 'Berlin');
r.setHttpTimeout(10000);            // milliseconds
var response = r.execute();
var status = response.getStatusCode();
var body = response.getBody();
if (status == 200) {
  var data = JSON.parse(body);
  gs.info('Temperature: ' + data.temp);
} else {
  gs.error('Weather call failed: ' + status + ' ' + body);
}

Always check the status code, set a timeout and handle failures. Calls inside a before business rule hold up the user's save, so use async rules, a flow action or a scheduled job.

You can also build the call in Flow Designer with the REST step in a custom action, or by using IntegrationHub spokes (next lesson), which are the preferred low-code route.

Producing REST: Scripted REST APIs

When the Table API is too generic, create Scripted REST APIs (System Web Services > Scripted Web Services > Scripted REST APIs). Create an API with a name and an API ID, then add Resources: an HTTP method, a relative path such as /incidents/{number}, and a script:

JavaScript
(function process(request, response) {
  var number = request.pathParams.number;
  var gr = new GlideRecord('incident');
  if (!gr.get('number', number)) {
    response.setStatus(404);
    response.setBody({ error: 'Not found' });
    return;
  }
  response.setStatus(200);
  response.setBody({ number: gr.getValue('number'), state: gr.getDisplayValue('state') });
})(request, response);

The full path becomes /api/{namespace}/{api_id}/incidents/{number}. Protect it: set Requires authentication and ACLs on the API, validate input, return the right status codes and design stable response shapes. Versions (v1, v2) let you change contracts without breaking clients.

Practice with JSON shapes

The first stand-in builds a Table API URL from a description, to practice the parameter names.

JS Stand-in: build a Table API request URL

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The second stand-in handles a response the way a careful client should: check the status and the shape.

JS Stand-in: handle a Table API response safely

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Design advice

  1. Page results and request only needed fields.
  2. Use a service account per integration with least privilege.
  3. Make calls idempotent where possible (for example look up by external ID before inserting).
  4. Log failures with enough information to retry.
  5. Never hard-code endpoints or secrets: use connection and credential records and system properties.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which URL pattern reads incident records through the built-in API?

    The Table API lives under /api/now/table/{table_name}.
  2. 2. Which parameter limits the fields returned?

    sysparm_fields takes a comma-separated list of field names.
  3. 3. Where should an outbound REST call usually NOT run?

    A slow external call in a before rule makes the user wait, and failures can block the save.
  4. 4. What is the best practice for the account used by an integration?

    Least privilege limits damage and makes the activity traceable.

Summary

  • The Table API gives CRUD on every table, acting as the authenticated user and obeying ACLs.
  • REST Messages and RESTMessageV2 call outside services; check status codes and set timeouts.
  • Scripted REST APIs expose custom endpoints with their own paths, methods and responses.
  • Use dedicated accounts, OAuth when possible, and avoid slow outbound calls in synchronous rules.

Next: IntegrationHub, Spokes and the MID Server