---
sourceDocument: Australia Security Management
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/security-management

 Release :

    - australia

ft:locale :

    - en-US

ft:publication_title :

    - Australia Security Management

ft:clusterId :

    - security

bundleId :

    - security

workflow :

    - Technology


---

# REST APIs for third-party integration with Security Operations

# REST APIs for third-party integration with Security Operations {#ariaid-title1}

* Release version: Australia
* 
* Updated March 12, 2026
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 3 minutes to read

Summarize  
![AI sparkle icon](https://servicenow.com/docs/portal-asset/ai-sparkle-icon) Summarized using AI  
This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.  

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

The Security Operations base system provides scripted REST APIs that enable ServiceNow customers and partners to integrate third-party data with their Security Operations deployment.
These APIs allow external scripts---commonly written in languages like Python or Java---to send gathered security data back into the ServiceNow instance via HTTP POST calls.
This integration supports customer-specific processes by importing external intelligence, such as VirusTotal data, directly into ServiceNow.
Show full answer Show less  

## Authentication and Authorization

API access requires platform authentication through the Scripted REST APIs feature, specifically the **SecOps Integration Capabilities API** . Users are authenticated with their domain context, enabling secure record association and audit trails. To ensure proper authorization, users must have the **snseccmn.apiwrite** role, which restricts API usage to authorized Security Operations personnel only. GlideRecordSecure can be used within the API to prevent unauthorized data access.

## Request Parameters and Error Handling

Key request parameters allow control over API behavior:

* **ignoremandatoryfields:** If true, records are saved even if mandatory fields are missing.
* **includewrap:** If true, response includes the standard Scripted REST API wrapper.
* **simpleresponse:** If true, response only indicates success or failure of the operation.

Common error responses include insufficient access (missing role), invalid or empty request bodies, missing mandatory fields, and failures persisting records. Solutions involve correcting the request format or assigning proper roles. Unknown errors require further investigation.

## Use Cases for Data Enrichment and Threat Lookup

The APIs support several practical use cases for enriching Security Operations data with third-party intelligence:

* **Configuration Item (CI) Enrichment:** Write data to the `snseccmncienrichmentresult` table to add detailed third-party information to configuration items.
* **Observable Enrichment:** Write data to the `sntiobservableenrichmentresult` table to enrich observables with external intelligence.
* **Threat Lookup:** Write data to the `sntilookupresult` table to record threat lookup results from external sources.

These capabilities also allow adding new records by passing an `enrichmentmappingid` and a corresponding raw data string for parsing by Security Operations enrichment data mappings.

## What Customers Can Expect

By leveraging these scripted REST APIs, ServiceNow customers can seamlessly integrate external threat intelligence and enrichment data into their Security Operations workflows. This enhances the depth and accuracy of security data within the platform, supports automation, and enables more informed decision-making. Proper authentication and role assignment ensure secure and authorized API use, while configurable request parameters provide flexibility in data ingestion.  
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 {#third-party-script-integrations__section_mpq_xsn_lbb}

All operations within the API definitions use platform authentication provided by the
[Scripted REST APIs](https://www.servicenow.com/docs/access?context=c_CustomWebServices&version=australia&pubname=australia-api-reference&ft:locale=en-US) operation feature. To access, navigate to System Web ServicesScripted Web ServicesScripted 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](https://www.servicenow.com/docs/access?context=p_GlideServerAPIs&version=australia&pubname=australia-api-reference&section=c_UsingGlideRecordSecure&ft:locale=en-US) to prevent any unauthorized access to data.

## Authorization {#third-party-script-integrations__section_plm_yzn_lbb}

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 {#third-party-script-integrations__section_ysc_ft4_lbb}

The following request parameters are available.{#third-party-script-integrations__table_t4d_4bd_5s__entry__3}

| 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. |
[ ]

{#third-party-script-integrations__table_t4d_4bd_5s}

## Error responses {#third-party-script-integrations__section_zxz_rv4_lbb}

The following error responses may occur.{#third-party-script-integrations__table_dsl_tv4_lbb__entry__3}

| 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. |
[ ]

{#third-party-script-integrations__table_dsl_tv4_lbb}

## CI enrichment use case {#third-party-script-integrations__section_hrf_py4_lbb}

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.  
Figure 1. Create-Request for CI enrichment  
Figure 2. Create-Response for CI enrichment

## Observable enrichment use case {#third-party-script-integrations__section_s4l_c1p_lbb}

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.  
Figure 3. Create-Request for observable enrichment  
Figure 4. Create-Response for observable enrichment
Note:  
In addition to enriching existing records, you can also use [Security Operations enrichment data mapping](https://servicenow-prod.fluidtopics.net/tQ0eKbOQeuPSLf~YhSyydw "Enrichment Data Mapping transforms data from XML, JSON, or Properties files to ServiceNow records. Security Operations workflows use enrichment data maps and provide output data to security incidents.") 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 {#third-party-script-integrations__section_kfh_4y4_lbb}

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

*[\>]: and then