REST APIs for third-party integration with Security Operations

Release version: Zurich

Updated March 12, 2026

3 minutes to read

Summarize

Summarized using AI

Summary of REST APIs for third-party integration with Security Operations

The Security Operations (SecOps) base system in ServiceNow Zurich release includes scripted REST APIs designed to facilitate integration with third-party systems. These APIs enable customers and partners to collect data externally—such as from VirusTotal—and send it into their SecOps instance. They support scripts written in any language capable of making HTTP POST calls with JSON payloads, enabling flexible, customer-specific automation and enrichment workflows.

Show full answer Show less

Authentication and Authorization

Authentication: Uses platform authentication via Scripted REST APIs; user and domain context are available to tie records to users, maintain audit trails, and enforce domain separation.
Authorization: Access is restricted to users with the snseccmn.apiwrite role, ensuring that only authorized users can create or update records through these APIs.

Request Parameters and Error Handling

Request Parameters: Includes options such as ignoremandatoryfields (to save records even if mandatory fields are missing), includewrap (to include standard response wrappers), and simpleresponse (to simplify response to success status).
Error Responses: Common errors include insufficient access (missing role), invalid or empty request bodies, missing mandatory fields, and persistence failures. Guidance is provided to resolve each error, typically by adhering to API and table definitions or assigning proper roles.

Use Cases for Data Enrichment and Threat Lookup

Configuration Item (CI) Enrichment: Third-party scripts can write enrichment data to the snseccmncienrichmentresult table, adding detailed external information to existing CI records.
Observable Enrichment: Scripts can populate the sntiobservableenrichmentresult table to enrich observable data with external intelligence.
Threat Lookup: Scripts can send threat intelligence data to the sntilookupresult table to provide insights from third-party sources.
Additional Capability: Besides enriching existing records, the APIs support adding new records by using an enrichment mapping ID and raw data string, enabling automated parsing and ingestion of external data.

Practical Benefits for ServiceNow Customers

These REST APIs empower ServiceNow customers to seamlessly integrate external threat intelligence and enrichment data into their Security Operations workflows. This capability enhances situational awareness, automates data ingestion from diverse sources, and maintains strict access control for secure data handling. Customers can leverage their existing scripts or applications in various languages to extend the value of their SecOps deployment with tailored, real-time intelligence updates.

The Security Operations base system includes a series of scripted REST APIs that allow customers and partners to easily integrate with an existing Security Operations deployment. The APIs allow you to gather data from outside of your system (for example, a Python script is used to receive data from VirusTotal) and send it back to your instance.

Scripts written in almost any language (Python, for example) can be used with the APIs to perform customer-specific processes. The scripts must be written in a language able to make an outside-facing HTTP Post call. For example, if you have a Java application, you must use a library, such as the java.net.HttpUrlConnection package, to construct an HTTP call and pass in a JSON string as Body for the message.

The API is solely used to add data that was gathered outside of our system. For example, if you entered VT python script and received data from VT, you could send that data back to the SN instance.

Authentication

All operations within the API definitions use platform authentication provided by the Scripted REST APIs operation feature. To access, navigate to System Web Services > Scripted Web Services > Scripted REST APIs and locate the SecOps Integration Capabilities API.

The user and the user’s domain are readily available within the context of the API. Records can be tied to a user, an audit path to be established, and domain separation accomplished. Also, since you are authenticated as a specific user, you can use Using GlideRecordSecure to prevent any unauthorized access to data.

Authorization

To protect the record creation process from users outside of the Security Operations application, you must have the sn_sec_cmn.api_write role. Only users with this role can access the APIs.

Configuration request parameters

The following request parameters are available.


Name	Default	Description
ignore_mandatory_fields	false	If set to true, the record persists even if mandatory fields are not filled in.
include_wrap	false	If set to true, the response includes the instance-provided standard wrapper for Scripted REST APIs.
simple_response	false	If set to true, the response includes only whether the operation was successful.

Error responses

The following error responses may occur.


Error message	When does it occur?	Solution
Insufficient access	User does not have the sn_sec_cmn.api_write role.	Add the role to the user.
Invalid post body	Request body is empty or an empty object.	Conform to the API definition.
No fields supplied	Data fields provided to persist are empty.	Conform to the API definition.
Mandatory fields missing: x,y,z	Mandatory fields are missing.	Conform to the table definition of the target table or set ignore_mandatory_fields to true.
Unable to persist record	Unable to persist parsed record.	GlideRecord insert() failed, further analysis is required.
Unknown error	Occurs if no known error path has been followed.	Further analysis is required.

CI enrichment use case

Using your third-party scripts, you can write to the Configuration Item Enrichment [sn_sec_cmn_ci_enrichment_result] table for CI enrichment. The enrichment records are based on existing capabilities that provide detailed information about a record from a third-party source.

Sample request and responses for the CI enrichment use case are shown here.

CI Enrichment: Create –Request — Figure 1. Create-Request for CI enrichment

CI Enrichment: Create –Response — Figure 2. Create-Response for CI enrichment

Observable enrichment use case

Using your third-party scripts, you can write to the Observable Enrichment Result [sn_ti_observable_enrichment_result] table for observable enrichment. The enrichment records are based on existing capabilities that provide detailed information about a record from a third-party source.

Sample request and responses for the observable enrichment use case are shown here.

Observable Enrichment: Create–Request — Figure 3. Create-Request for observable enrichment

Observable Enrichment: Create Response — Figure 4. Create-Response for observable enrichment

Note:

In addition to enriching existing records, you can also use Security Operations enrichment data mapping to add new records to tables by passing in an enrichment_mapping_id for an existing enrichment mapping and a corresponding raw_data string that can be parsed by the mapping process.

Threat lookup use case

Using your third-party scripts, you can write to the Threat Lookup Result [sn_ti_lookup_result] table for threat lookup results. The lookup records are based on existing capabilities that provide detailed information about a record from a third-party source.

Sample request and responses for the threat lookup use case are shown here.

Figure 5. Create-Request for threat lookups

Figure 6. Create-Response for threat lookups