---
sourceDocument: Yokohama API Reference
sourceDocumentLink: https://www.servicenow.com/docs/r/yokohama/api-reference

 Release :

    - yokohama

ft:locale :

    - en-US

ft:publication_title :

    - Yokohama API Reference

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# SOAP web service

# SOAP web service {#ariaid-title1}

* Release version: Yokohama
* 
* Updated January 30, 2025
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 9 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 SOAP web service

SOAP (Simple Object Access Protocol) is an XML-based protocol used in ServiceNow to access web services over HTTP, enabling interaction with instance data.
ServiceNow supports WS-I compliant SOAP web services through direct web services, SOAP web service import sets, and scripted SOAP web services.
SOAP messages are sent and decoded as UTF-8 without additional encoding.
Show full answer Show less  
All tables and import sets dynamically generate WSDL (Web Service Definition Language) documents, which describe table schema and operations. These WSDLs can be accessed via URL queries and are licensed under the Apache License 2.0.

## Key Features

* **Long-running SOAP requests:** Supported to prevent socket timeouts during lengthy operations, such as large record retrievals or complex queries, using timeout protection and 307-Temporary Redirect responses under configurable system properties.
* **Security:** SOAP web services enforce security via basic authentication over HTTPS, role-based access control, and system-level ACLs. SOAP roles (e.g., soapquery, soapcreate) govern operation permissions.
* **WS-Security Support:** Enhances security with SOAP Security Policies, supporting signed requests using X.509 certificates, authentication via WS-Security profiles, and error logging for SOAP processing.
* **Strict Security Enforcement:** Optional enforcement requiring users to meet contextual security ACLs in addition to having appropriate SOAP roles.
* **SOAP Session Management:** SOAP sessions are tracked similarly to user sessions, with configurable timeout properties to maintain or invalidate sessions.
* **Custom SOAP Web Services:** Support for scripted SOAP web services and import set interfaces to extend or tailor SOAP web service functionality.
* **Additional Features:** Support for hierarchical data insertion, HTTP compression, prevention of empty elements in messages, and attachment handling via SOAP messages.

## Security Configuration and Management

Administrators can:

* Activate the Enhanced Web Service Provider - Common plugin to enable advanced WS-Security options.
* Create and configure SOAP security policies to specify requirements such as request signing and authentication mechanisms.
* Set the SOAP default security policy via system properties for inbound requests.
* Configure WS-Security profiles to authenticate requests through certificate verification or user credentials.
* Enable detailed WS-Security error logging for troubleshooting SOAP request issues.
* Enforce strict security to restrict SOAP access based on ACLs, ensuring only authorized operations.

## Practical Considerations for ServiceNow Customers

* Use SOAP web services to integrate external systems with ServiceNow data securely and efficiently.
* Ensure users have appropriate SOAP roles and table access permissions to perform desired operations.
* Leverage WS-Security and basic authentication to protect SOAP communications and verify message integrity.
* Configure timeout and session properties to optimize performance for long-running SOAP requests.
* Utilize scripted SOAP web services for custom business logic and import sets for data import automation.
* Monitor SOAP sessions and enable debugging properties to troubleshoot integration issues effectively.  
Simple Object Access Protocol (SOAP) is an XML-based protocol for accessing web services
over HTTP.
You can use SOAP to access data on your instance. Available SOAP web services are WS-I compliant, as outlined in the WS-I Basic Profile 1.0.

## Web service provider

ServiceNow publishes its underlying table structures and associated data using the following web service methods:

* [Direct web services](https://www.servicenow.com/docs/oe4ZHzPuMfB3tRpb_3E3Ag "A direct web service is available for any table in the system if the correct access control list is configured."): Use a URL query to request a table's WSDL.
* [SOAP web
  service import sets](https://www.servicenow.com/docs/Ku77mHr5ZPFbBKOWwfDnMA "Web service import sets complement direct web services and scripted SOAP web services by providing a web service interface to import sets tables."): Use import tables and transform maps to automate web service requests for tables.
* [Scripted SOAP web
  services](https://www.servicenow.com/docs/eex~7GvY7kML3IJAhjcslQ "Scripted SOAP web services allow a ServiceNow administrator to create custom SOAP web services."): Use custom JavaScript to execute SOAP web services requests.

{#c_SOAPWebService__ul_qbh_xrd_gp}  
Note:  
SOAP messages are sent with the assumption that the recipient is XML compliant. No encoding is applied to a SOAP message. SOAP always decodes responses as UTF-8, the XML encoding header is not used.

## WSDL {#c_SOAPWebService__section_nlx_5yx_23b}

All tables and import sets dynamically generate Web Service Definition Language (WSDL) XML
documents that describe its table schema and available operations.  
You can obtain a table's WSDL by issuing a URL call to your instance that contains the name of the table and the WSDL parameter. For example:

    https://myinstance.service-now.com/incident.do?WSDL

All dynamically generated and served ServiceNow WSDLs accessible via HTTP
are available for use under the terms defined in the Open Source Initiative OSI - Apache
License, Version 2.0 license agreement.

## Long-running SOAP request support {#c_SOAPWebService__section_mcy_jqy_23b}

The ServiceNow AI Platform supports long-running
SOAP requests by preventing socket timeouts due to inactivity of the network connection
while the requests are in process.
This functionality improves the efficiency of the ODBC driver when requesting large numbers
of records, doing aggregate queries, or using order by expressions that require sorting.

By default, the system provides timeout protection for web services clients provided by ServiceNow such as the ODBC driver and
the MID Server. You can add timeout protection to your custom web services with system
properties.

## Timeout protection {#c_SOAPWebService__section_fgv_mqy_23b}

Web services clients receive a 307-Temporary Redirect to keep long sessions alive and
prevent a timeout due to socket inactivity. A 307-Temporary Redirect causes web services
clients which support the status code to repeat their last request to the location specified
in the HTTP location header. The value of the location header is the same URL that the web
services client originally specified. The use of 307-Temporary Redirects is WS-I
compliant.  
A web service request that exceeds the timeout limit specified in glide.soap.request_processing_timeout can only receive a 307-Temporary Redirect when all of these conditions are met:

* The value of glide.soapprocessor.allow_long_running_threads is true.
* The request includes a redirectSupported=true URL parameter.
* The request is session-aware (supports HTTP cookies).
* The number of redirects has not exceeded the value set by glide.soap.max_redirects.
{#c_SOAPWebService__ul_m2f_h4h_kp}  
If any of these conditions is not met, the web service client receives a 408 Request Timeout error.  
Note:  
To ensure that applications experience a socket timeout rather than a 408 Request Timeout, set the glide.soap.request_processing_timeout property to a value larger than the shortest socket timeout setting in effect for the connection between the application and the instance (300 seconds for hosted instances).

## SOAP web services security {#c_SOAPWebService__SOAP-web-services-security}

An instance enforces web service security using a combination of basic authentication
challenge/response over the HTTPS protocol and system-level access control lists (ACLs)
using contextual security. Administrators can control what system resources web services
users can access by granting them one of the SOAP roles.

## SOAP roles {#c_SOAPWebService__section_ecx_4ky_23b}

To use SOAP web services, you must have the appropriate role for the operation you want to
perform. Also, you must have any other roles required to access the target tables.
{#c_SOAPWebService__table_b1j_35d_gp__entry__2}

| Role | Description |
|-|-|
| soap | Can perform all SOAP operations. |
| soap_create | Can insert new records. |
| soap_delete | Can delete existing records. |
| soap_ecc | Can query, insert, and delete records on the Queues `[ecc_queue]` table. |
| soap_query | Can query record information. |
| soap_query_update | Can query record information and update records. |
| soap_script | Can run scripts that specify a .do endpoint. This role is required for running scripted web services. |
| soap_update | Can update records. |
| import_admin | Can manage all aspects of import sets and imports. Required for access to the Import Set Row \[sys_import_set_row\] table. |
| import_transformer | Can manage import set transform maps and run transforms. Required for access to the Import Set Row \[sys_import_set_row\] table. |
[Table 1. SOAP Roles]

{#c_SOAPWebService__table_b1j_35d_gp}

## Default web services role requirements {#c_SOAPWebService__section_hnf_fly_23b}

By default, a set of processor ACL rules require users to have the soap_query role to make
WSDL, XSD, and XML schema requests.
If you want to change these role requirements, you can deactivate the ACL rules.  
Figure 1. Web service processor ACLs

## Basic authentication {#c_SOAPWebService__SOAP-basic-auth}

To enforce basic authentication for the user associated with the instance for each WSDL or
SOAP message request, administrators can set the property
`glide.basicauth.required` to true.

When enabled, each WSDL and SOAP request must contain an "Authorization" header as
specified in the [Basic Authentication](http://www.w3.org/Protocols/HTTP/1.0/draft-ietf-http-spec.html#BasicAA) protocol.

Because web services requests are non-interactive, the Authorization
header is always required during a request.  
Note:  
If configured, basic authentication refers to local credentials or LDAP authentication.

Supplying basic authentication information with every request (whether or not it is
required) has the added advantage that the user supplied in the basic authentication
credentials can be associated web service invocation. For example, when creating an Incident
record, the journal field lists the user ID contained in the basic authentication header
instead of the default guest user.

## SOAP security policies {#c_SOAPWebService__section_std_wny_23b}

The Enhanced Web Service Provider - Common plugin adds the SOAP Security Policies module to the System Web Services application. This module allows administrators to set the following security policies:

* Enable or disable signing SOAP requests when consuming an external web service
* Specify the authentication requirements SOAP requests must meet when communicating over WS-Security.
{#c_SOAPWebService__ul_tyn_ytm_2r}

To know more about SOAP access policy, see [SOAP API access policies](https://www.servicenow.com/docs/access?context=soap-api-access-policies&version=yokohama&pubname=yokohama-platform-security&ft:locale=en-US).  
Figure 2. SOAP security policies

## Certificates required for signed SOAP requests {#c_SOAPWebService__section_ayd_d4y_23b}

To sign SOAP requests for WS-Security communications, the following certificates are
required:  
* X.509 certificate from the requester
* X.509 CA certificate of the certificate authority who signed the requester's certificate
{#c_SOAPWebService__ul_ksf_bym_2r}

## SOAP default security policy {#c_SOAPWebService__SOAP-default-sec-policy}

Administrators can specify the SOAP security policy an instance uses with the system
property `glide.soap.default_security_policy`. The
`glide.soap.default_security_policy` system property specifies the name of
the SOAP security policy the instance uses when enforcing Web Services-Security (WSS) for
inbound requests.  
{#c_SOAPWebService__table_lyn_bb5_2r__entry__2}

| Field | Description |
|-|-|
| Type | String |
| Default value | Default Security Policy |
| Location | [Add a system property](https://www.servicenow.com/docs/access?context=t_AddAPropertyUsingSysPropsList&version=yokohama&pubname=yokohama-platform-administration&ft:locale=en-US) to the System Properties \[sys_properties\] table |
[Table 2. SOAP default security policy settings]

{#c_SOAPWebService__table_lyn_bb5_2r}

## WS-Security {#c_SOAPWebService__WS-Security}

You can validate signed web services requests using WS-security. Enable WS-Security to:

* Verify that SOAP messages originate from a known sender
* Verify that SOAP messages have not been altered in transit

{#c_SOAPWebService__ul_p2c_1bj_dr} ServiceNow supports [WS-Security 1.1](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wss) to validate signed web services requests.  
Note:  
WS-Security is not used as an encryption mechanism, HTTPS protocol is used to encrypt all communications.

WS-Security is intended to work with basic authentication. When an instance receives a SOAP
message, it reviews the basic authentication header to determine if the SOAP user has rights
to the instance. It reviews the WS-Security header to determine the validity of the incoming
message. Requests affected by attacks, such as a man-in-the-middle attack, have an invalid
WS-Security header and are blocked.

## WS-Security profiles {#c_SOAPWebService__WS-Security-profiles}

A WS-security profile determines how a web services message is authenticated when
WS-security is enabled. The following mechanisms can be used to authenticate web services
requests:  
{#c_SOAPWebService__table_n3x_4tj_dr__entry__2}

| Authentication mechanism | Description |
|-|-|
| Certificate verification | Verifies the certificate associated with the request. Verifying the request's certificate requires uploading the requester's certificate and certificate authority. |
| User credentials | Authenticates the web services request by verifying the user credentials associated with the request. This type of authentication can either verify that the request's credentials match an existing user's credentials or that the request's credentials match a user name and password provided in the profile record. |
[Table 3. Web service authentication mechanisms]

{#c_SOAPWebService__table_n3x_4tj_dr}Specify the authentication mechanism you want to use when you [create a
new WS-security profile](https://www.servicenow.com/docs/CSYCMADeBB43gUoaEOugPg "Create a new WS Security profile to define how to authenticate a web services message when WS-Security is enabled.").

The WS-Security Profiles module lists the WS-Security profiles that are currently in
effect.  
Figure 3. WS-Security Profiles module

## WS-Security error logging {#c_SOAPWebService__section_h5j_p4y_23b}

The `glide.processor.debug.SOAPProcessor` system property allows error
messages about WS-security to be displayed in the transaction log.

The system property `glide.processor.debug.SOAPProcessor` enables (true) or
disables (false) debugging messages for SOAP processing such as certificate and keystore
checks.  
{#c_SOAPWebService__table_lyn_be5_2r__entry__2}

| Field | Description |
|-|-|
| Type | true \| false |
| Default value | false |
| Location | [Add a system property](https://www.servicenow.com/docs/access?context=t_AddAPropertyUsingSysPropsList&version=yokohama&pubname=yokohama-platform-administration&ft:locale=en-US) to the System Properties \[sys_properties\] table |
[Table 4. glide.processor.debug.SOAPProcessor fields]

{#c_SOAPWebService__table_lyn_be5_2r}

## WSS X.509 Token Profile {#c_SOAPWebService__section_cwj_2ny_23b}

Use the X.509 framework for a WSS X.509 security profile. An X.509 certificate is used to validate a public key that is then used to sign the incoming SOAP message. It specifies a binding between a public key and a set of attributes that includes at least the following:

* subject name
* issuer name
* serial number
* validity interval
{#c_SOAPWebService__ul_yfn_yw2_2r}

Use the [X.509 authentication framework](https://www.oasis-open.org/committees/download.php/16785/wss-v1.1-spec-os-x509TokenProfile.pdf) as defined by the
[Web Services Security: SOAP Message Security specification](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wss).

Upload the certificate and reference it in the X509 Certificate
field. If a bound session, select the user to impersonate when the WS-Security
authentication succeeds.  
Figure 4. WSS X.509 Security Profile

## WSS UsernameToken Profile {#c_SOAPWebService__section_xdc_kny_23b}

When specifying the X.509 Token Profile, you can also supply a UsernameToken in the SOAP
request.

A UsernameToken is used as a means of identifying the requester by "user name", and
optionally using a password, shared secret, or password equivalent, to authenticate that
identity.

There are two ways to authenticate a UsernameToken.

1. Authenticate with existing user credentials.  
   Figure 5. Authenticate with existing user credentials

   Use the user name of the incoming SOAP request to look up a user by the specified
   User field to match the UserName value.
   The system uses the password value in the incoming UsernameToken to authenticate the
   request. When the Bind session option is selected, the user that
   authenticates successfully is used for the session.
2. Authenticate with specified user credentials.  
   Figure 6. Authenticate with specified user credentials

   Authenticate using login credentials unrelated to users in the User table. When the
   Bind session option is selected, the user that is specified in
   the Run as user field is used for the session.

{#c_SOAPWebService__ol_sjx_sdf_2r}  
Note:  
The [UsernameToken Profile](https://www.oasis-open.org/committees/download.php/16782/wss-v1.1-spec-os-UsernameTokenProfile.pdf) cannot be used independent of the X.509 Token Profile.

## Strict security for web services {#c_SOAPWebService__section_pzc_1py_23b}

By default, basic authentication for web services only determines whether a user is
authorized to access the instance with a SOAP connection. Once authorized, any user can
access any table published as a web service.

The system property Enforce strict security on incoming SOAP requests changes this behavior and requires that users meet [Contextual Security Manager](https://www.servicenow.com/docs/access?context=r_ContextualSecurity&version=yokohama&pubname=yokohama-platform-security&ft:locale=en-US) requirements to access instance resources from web services.

With this property enabled, only users that have the proper SOAP role and also meet the ACL
conditions the table and operation can perform that operation from a SOAP connection.

## Mutual authentication for web services {#c_SOAPWebService__section_ey2_fpy_23b}

Mutual authentication is supported for outbound web services.

## SOAP session management and reporting {#c_SOAPWebService__section_tqn_wpy_23b}

A SOAP session is a Glide session established with an instance by any external SOAP client,
such as a web services client application, a ServiceNow MID Server, or the ServiceNow ODBC driver. SOAP sessions
are included in the list of user sessions at User AdministrationLogged in users. The ?SOAP URLs identify SOAP sessions.

## SOAP session properties {#c_SOAPWebService__section_qfh_gqy_23b}

Certain properties control how SOAP sessions are maintained.
{#c_SOAPWebService__table_bdx_vly_25__entry__2}

| Property | Description |
|-|-|
| glide.soap.invalidate_session_timeout | Duration, in seconds, that an active session remains open. After this duration is reached, the instance deactivates the session and reclaims any system resources. If the client sends another request after the timeout duration is reached, the instance establishes a new session. This property accepts values from 5 to 1200 seconds (20 minutes). * Type: integer * Default value: 60 * Location: Add to the System Properties `[sys_properties]` table {#c_SOAPWebService__ul_bb1_kph_kp} |
[Table 5. SOAP session properties]

{#c_SOAPWebService__table_bdx_vly_25}  
Note:  
To learn more about properties that affect SOAP web services processing, see the following topics in Instance Security Hardening Settings:

* [Access control (instance security hardening)](https://www.servicenow.com/docs/access?context=sc-access-control&version=yokohama&pubname=yokohama-platform-security&ft:locale=en-US)
* [Basic auth: SOAP
  requests](https://www.servicenow.com/docs/access?context=sc-soap-request-authorization&version=yokohama&pubname=yokohama-platform-security&ft:locale=en-US)
{#c_SOAPWebService__ul_vwk_krn_rkb}
* **[Scripted SOAP web services](https://www.servicenow.com/docs/eex~7GvY7kML3IJAhjcslQ)**   
  Scripted SOAP web services allow a ServiceNow administrator to create custom SOAP web services.
* **[Direct web services](https://www.servicenow.com/docs/oe4ZHzPuMfB3tRpb_3E3Ag)**   
  A direct web service is available for any table in the system if the correct access control list is configured.
* **[SOAP web service import sets](https://www.servicenow.com/docs/Ku77mHr5ZPFbBKOWwfDnMA)**   
  Web service import sets complement direct web services and scripted SOAP web services by providing a web service interface to import sets tables.
* **[AttachmentCreator SOAP web service](https://www.servicenow.com/docs/X8q1EgHAy95Pk~vQ9pYpvw)**   
  Attach documents to records in ServiceNow by sending a SOAP message targeting the ecc_queue table.
* **[Override a SOAP endpoint](https://www.servicenow.com/docs/A8z2xOxuZzbo2zQp1xVSVA)**   
  The SOAP endpoint address where the SOAP message is posted is consistent with the endpoint of the WSDL.
* **[Enable HTTP compression](https://www.servicenow.com/docs/NgFzA2zv_U_YmwRbkxeJxQ)**   
  By default, the SOAP request is accepted un-compressed and the result of the request is returned un-compressed.
* **[Prevent empty elements in SOAP messages](https://www.servicenow.com/docs/uk_Dj1UoBh~eUo6wLBqmFA)**   
  By default, an instance does not omit empty elements, elements with NULL or NIL values, from SOAP messages.
* **[Insert related records using SOAP](https://www.servicenow.com/docs/SeOVWYyZaFH2_kcrsVYojQ)**   
  Support is available for inserting hierarchical data into tables or web service import set tables. The hierarchical data in the Insert API is automatically mapped to related records of the targeted table.
* **[Specify requirement for signed SOAP requests](https://www.servicenow.com/docs/gaGW7Plk6gCQgZGeA9GISg)**   
  Use a SOAP security policy to specify whether the instance requires signed SOAP requests for all inbound SOAP traffic.
* **[Activate the Enhanced Web Service Provider - Common plugin](https://www.servicenow.com/docs/~uCdfK2WKIGCHwVVMBOBYA)**   
  Administrators can activate the Enhanced Web Service Provider - Common plugin to enable unsigned WS-Security requests and specify what authentication requirements SOAP requests have.
* **[Configure SOAP security](https://www.servicenow.com/docs/uEx03jkJewSnaILKGkW6gA)**   
  Administrators can configure web service security for inbound SOAP requests made to the ServiceNow instance.
* **[Set the SOAP default security policy](https://www.servicenow.com/docs/mI6JuRL~vDwXo92ScnMP~Q)**   
  Set the SOAP default security policy.
* **[Create a new security policy](https://www.servicenow.com/docs/Xd1uwJXHPi1tJlcrqK~KBw)**   
  Administrators can specify which security profiles WS-Security communications must meet by creating a new security policy.
* **[Create a new WS-Security profile](https://www.servicenow.com/docs/CSYCMADeBB43gUoaEOugPg)**   
  Create a new WS Security profile to define how to authenticate a web services message when WS-Security is enabled.
* **[Enforce strict security for inbound SOAP](https://www.servicenow.com/docs/eV94RCn07jXiEPdc2xfJkA)**   
  Strict security for web services requires that users meet Contextual Security requirements to access instance resources.
* **[Enable WS-Security verification](https://www.servicenow.com/docs/py~lokLOECD6AaPO9ED5Ng)**   
  Administrators can enable Web Services Security (WSS) verification from the Web Services system properties.
* **[Debug incoming SOAP envelope](https://www.servicenow.com/docs/I1g19y0yCm0v8y7sdUZTQg)**   
  To capture incoming SOAP envelope XML in the system log, add the property glide.processor.debug.SOAPProcessor with a value of true.
* **[View a SOAP session log](https://www.servicenow.com/docs/9xQDbJYkFrGrUBdOc2q~MA)**   
  You can view a user's log from a SOAP session.
* **[Basic authentication code samples](https://www.servicenow.com/docs/KLZ1msJWpghkQijsAELrwA)**   
  Samples of basic authentication code for several programming languages and versions.
* **[Example WS-Security SOAP envelope header](https://www.servicenow.com/docs/4Ms3qA0JyenJ6hbVM7sj4A)**   
  An example of a valid WS-Security SOAP envelope header.
* **[WS-Security properties](https://www.servicenow.com/docs/IeXNeCQegojC0DA_s9FecQ)**   
  These properties control the behavior of WS-Security X.509 tokens.
* **[WS-Security error messages](https://www.servicenow.com/docs/5jyiO~1bxWi4GHm8bvuT5Q)**   
  An instances produces one of the following error messages when it encounters an issue with a WS-security SOAP message.
* **[WS-Security reference](https://www.servicenow.com/docs/~OZeDhnkHbQcGhTOEUSBBw)**   
  Support for WS-Security 1.1 in the form of WSS X.509 Token Profile and WSS Username Token Profile is available for incoming SOAP requests.
* **[LongRunningSOAPRequestProps](https://www.servicenow.com/docs/4ucDtDE_zeG4v~RuYGBAGg)**   
  The following properties are available for long-running SOAP requests.

*[\>]: and then