› CIS-DF Hub › Part 8 › REST API & Table API
⬡ Part 8 · Topic 1

REST API & Table API

ServiceNow's Table API is the most commonly used integration mechanism for reading and writing records. Understanding its URL structure, query parameters, and how ACLs apply to API responses is critical for both the exam and real-world integrations.

📋 5 sections ⏱ ~18 min read 🎯 ~8% exam weight 🏷 REST API · Integration
Section 1

Table API Overview

The Table API is a RESTful API that exposes every table in ServiceNow as an HTTP endpoint. Any table you can navigate to in the UI has a corresponding API URL. The API supports all four standard HTTP verbs:

HTTP MethodOperationUse Case
GETRead recordsQuery CIs, retrieve incident details
POSTCreate a new recordCreate a new incident or CI from external system
PUTReplace a record (full update)Overwrite all fields on an existing record
PATCHPartial updateUpdate specific fields without affecting others
DELETEDelete a recordRemove a CI or record by sys_id

URL Structure

GET /api/now/table/{tableName}?sysparm_query=...&sysparm_fields=...&sysparm_limit=...

For example, to get all active P1 incidents with specific fields:

GET /api/now/table/incident?sysparm_query=active=true^priority=1&sysparm_fields=number,short_description,assigned_to&sysparm_limit=100
Section 2

Key Query Parameters

These parameters control what data the Table API returns and how it's formatted:

ParameterPurposeExample
sysparm_queryEncoded query filter (same syntax as list view filters)active=true^priority=1
sysparm_fieldsComma-separated list of fields to return (reduces payload)number,state,assigned_to
sysparm_limitMaximum number of records to return50 (default: 10,000)
sysparm_offsetRecord offset for pagination (skip first N records)100 (skip first 100)
sysparm_display_valueReturn display values instead of raw values (true/false/all)true = labels; false = codes
sysparm_exclude_reference_linkRemove reference link objects from responsetrue (smaller payload)
📘
Core Concept — sysparm_display_value Explained By default, Reference fields return both a display_value (label) and a value (sys_id). Setting sysparm_display_value=true returns only the label. sysparm_display_value=false returns only the sys_id. sysparm_display_value=all returns both. Choice fields behave similarly: false gives the stored value (e.g., "1"), true gives the label (e.g., "P1 - Critical").
Section 3

Authentication

The Table API supports several authentication methods. The exam tests when to use each:

MethodHow It WorksBest For
Basic AuthUsername:Password in Authorization header (Base64 encoded)Quick testing only — never use in production
OAuth 2.0Request access token, include in Authorization: Bearer header. Token expires.External applications integrating with ServiceNow
API Keys (Application Registry)Generate a client ID/secret pair for a specific applicationServer-to-server integrations
Mutual TLSCertificate-based client authenticationHigh-security environments
⚠
Exam Trap — API Calls Use the Calling User's ACLs When an API call is made with Basic Auth as user "john.doe," all data returned is filtered by john.doe's ACLs. If john.doe can't read certain CI fields in the UI, those fields are absent from the API response too. The API is not a backdoor around data security — it enforces the same ACLs as the UI.
Section 4

Table API vs. CMDB API

For CMDB data specifically, there is an important distinction between using the generic Table API and the dedicated CMDB API:

  • Table API (generic) — POST to /api/now/table/cmdb_ci_server creates a CI record directly, bypassing IRE. No duplicate checking, no reconciliation rules. Quick but dangerous for CMDB integrity.
  • CMDB Identification and Reconciliation API — /api/now/cmdb/instance — routes through IRE. Runs identification (match or create), then reconciliation (apply authoritative values). The correct method for CI creation/updates.
🚨
Warning — Never POST CIs Directly via Table API Using the Table API to POST directly to a CI table bypasses IRE completely. This means no duplicate detection and no reconciliation — you can easily create duplicate CI records that are nearly impossible to clean up later. Always use the CMDB Identification and Reconciliation API (or a Service Graph Connector) when creating or updating CIs from external sources.
Section 5

REST API for CMDB — Common Patterns

  • Query CIs by class: GET /api/now/table/cmdb_ci?sysparm_query=sys_class_name=cmdb_ci_server^operational_status=1
  • Get a specific CI by sys_id: GET /api/now/table/cmdb_ci_server/{sys_id}
  • Get CI relationships: GET /api/now/table/cmdb_rel_ci?sysparm_query=parent={sys_id}
  • Update a CI field: PATCH /api/now/table/cmdb_ci_server/{sys_id} with body {"managed_by": "{group_sys_id}"}
💡
Tip — Use sysparm_fields to Reduce Payload Size By default, Table API GET responses include every field on the record — this can be hundreds of fields for CI records. Always specify sysparm_fields to return only the fields you need. This reduces response payload size significantly and speeds up integration processing.
Exam Quick Reference

Common Exam Traps — REST API & Table API

  • Table API URL: /api/now/table/{tableName} — supports GET/POST/PUT/PATCH/DELETE
  • GET returns records; POST creates; PATCH updates specific fields; PUT replaces full record
  • ACLs apply to API calls — calling user's access determines what data is returned/writable
  • Fields user can't read = absent from response (no error); fields user can't write = silently ignored
  • Never POST CIs directly via Table API — bypasses IRE; use CMDB Identification API or SGC
  • sysparm_display_value=true returns labels; false returns raw values/sys_ids
  • Basic Auth = testing only; OAuth 2.0 = production external integrations
Exam Checkpoint

Practice Questions

4 questions · Select an answer to see the explanation immediately.

REST API & Table API Quiz 1 / 4

A developer uses the Table API to POST a new record directly to cmdb_ci_server to create a server CI from an automated deployment pipeline. What problem does this create?

💡 Explanation

B is correct. Direct Table API writes to CMDB tables bypass the IRE pipeline entirely. IRE (Identity and Reconciliation Engine) handles deduplication via Identification Rules and field authority via Reconciliation Rules. When you POST directly to cmdb_ci_server, no Identification Rules run — if a CI for that server already exists, a second (duplicate) CI is created. No Reconciliation Rules run — last-write wins regardless of source authority. The correct approach for programmatic CI creation is the CMDB Identification API (/api/now/cmdb/instance) or a Service Graph Connector, which routes data through IRE.

A Table API GET request for an Incident record includes sysparm_display_value=true. What does the "state" field return for an incident in "In Progress" state?

💡 Explanation

B is correct. The sysparm_display_value parameter controls whether the API returns stored database values or human-readable display values. With sysparm_display_value=true, choice fields return their labels ("In Progress"), reference fields return display names (user's full name) instead of sys_ids, and dates return formatted strings. With sysparm_display_value=false (default), choice fields return stored values ("2"), reference fields return sys_ids, and dates return raw database values. Integrations that filter on field values must use the stored value format (false) for correct comparisons.

An external integration uses Basic Authentication for a production ServiceNow integration that creates Change Requests. Why is this a problem?

💡 Explanation

B is correct. Basic Authentication transmits credentials (username:password as Base64) with every API call. It's suitable for development/testing where security is controlled, but has production drawbacks: credentials don't expire automatically, credential rotation requires updating every integration using them, and there's no fine-grained token scoping. OAuth 2.0 is the recommended production standard: tokens are time-limited (expire and force re-authentication), can be revoked immediately if compromised, and support scoped permissions per integration. The credential-per-call pattern of Basic Auth is a security anti-pattern for production systems handling sensitive ITSM data.

A Table API PATCH request updates an Incident record, including setting a field the calling user doesn't have write ACL for. What happens to that field?

💡 Explanation

B is correct. ServiceNow's ACL enforcement for API calls silently ignores writes to fields the calling user doesn't have write permission for. The rest of the PATCH request succeeds normally — only the ACL-restricted field is not updated. No error is thrown, no warning is returned. This is intentional security behavior (revealing which fields exist could be an information leak) but can cause confusing debugging scenarios where an integration "succeeds" but specific fields don't update. When debugging such issues, always verify the calling user's ACLs against the specific fields being updated.

Score: 0 / 4
IntegrationHub & Flow Designer →