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

 Release :

    - australia

ft:locale :

    - en-US

ft:publication_title :

    - Australia API Reference

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# Scripted REST APIs

# Scripted REST APIs {#ariaid-title1}

Release version: Australia  
Updated March 12, 2026  
![](https://www.servicenow.com/docs/portal-asset/ico-clock) 5 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 Scripted REST APIs

Scripted REST APIs in ServiceNow enable application developers to build custom web service APIs with tailored endpoints, query parameters, schemas, and request/response handling.
These APIs generally follow REST principles but allow customization to meet specific integration needs.
They are defined in the Scripted REST Service form under Scripted Web Services.
Show full answer Show less  

## Key Features

* **Custom URI Structure:** API URIs follow the format `https://<instance>/api/<namespace>/<version>/<apiid>/<relativepath>`, supporting scoped applications, versioning, and multiple resource paths.
* **Versioning Support:** APIs can have multiple versions with a default version to ensure backward compatibility and safe deployment of changes.
* **Resource Definition:** Multiple resources (endpoints) per API can be defined, each specifying HTTP methods, processing scripts, and overrides.
* **Query Parameters:** Define and enforce mandatory or optional parameters for requests, accessible in scripts via the request object.
* **Schemas:** Use OpenAPI 3.0.1 formatted schemas to define request and response structures, ensuring consistent data formats.
* **Security and Access Control:** APIs support varying security levels from public access to authenticated endpoints with ACLs. ACLs can be applied at the API or resource level using RESTEndpoint type rules. API access policies control authentication methods.
* **Error Handling:** Standardized error objects provide consistent HTTP error responses, formatted based on the request's Accept header.
* **Supported Formats:** Default request and response formats include JSON and XML, configurable at the API or resource level.
* **Automated Testing:** Integration with ServiceNow's Automated Test Framework allows creation of inbound REST test steps to automate validation and ensure backward compatibility.
* **Role Requirements:** The `webserviceadmin` role is needed to create and manage scripted REST APIs but not to consume them.

## Practical Considerations for ServiceNow Customers

* Use scripted REST APIs to extend ServiceNow with custom integrations that require specific endpoints and data structures beyond out-of-the-box APIs.
* Leverage versioning to deploy API updates safely without disrupting existing consumers.
* Secure your APIs appropriately using authentication, ACLs, and API access policies to protect sensitive data and control access.
* Define clear query parameters and schemas to ensure data consistency and improve API usability for integrators.
* Use error objects to provide meaningful error messages to API consumers, improving troubleshooting and client integration handling.
* Incorporate automated tests using ATF to verify API functionality during upgrades and changes, ensuring reliability.
* Follow best practices and utilize available examples and developer training to design effective and maintainable APIs.  
The scripted REST API feature allows application developers to build custom web service
APIs.

You can define service endpoints, query parameters, schemas,and headers for a scripted REST API, as well as scripts to manage the request and response.

Scripted REST APIs generally follow the REST architecture, but you can customize them to use
different conventions. You define scripted REST APIs using the Scripted REST Service form found
under Scripted Web Services → Scripted REST APIs.  
Figure 1. Scripted REST Service form  
The following videos offer additional information about scripted REST APIs:

* [Scripted REST APIs -- Design](https://www.youtube.com/watch?v=Tw70sHgDc-w)
* [Scripted REST APIs -- Implementation](https://www.youtube.com/watch?v=LFHV-Qk1-Yk)
{#c_CustomWebServices__ul_bjx_c3b_vzb}

## Scripted REST API URIs {#c_CustomWebServices__section_upf_pn4_zhb}

Scripted REST API URIs have the following format:

https://\<instance.service-now.com\>/api/\<name_space\>/\<version\>/\<api_id\>/\<relative_path\>  
In this URI:

* \<instance.service-now.com\>: Path to the ServiceNow instance where users access the scripted REST API.
* \<name_space\>: For web services in the global scope, the name space is the value of the property glide.appcreator.company.code. For web services in a scoped application, the name space is the scope name, such as x_company_appname. For additional information on name spaces, see [Application scope](https://www.servicenow.com/docs/access?context=c_ApplicationScope&version=australia&pubname=australia-application-development&ft:locale=en-US).
* \<version\>: Optional. Version of the endpoint to access if the API uses versioning, such as v1. You can access the default version of a versioned API by specifying the URI without a version number.
* \<api_id\>: Value of the API ID field on the Scripted REST Service form. By default this value is based on the service name.
* \<relative_path\>: Relative path defined for the resource in the Scripted REST Service form. Specifying a relative resource path allows you to have multiple resources using the same HTTP method, such as GET, in one web service. For example, a resource may specify the path `/{id}` when the web service has only one GET resource, or `/user/{id}` and `/message/{id}` when the web service has different resources for requesting user and message records.
{#c_CustomWebServices__ul_osv_kgc_lr}

## Scripted REST API versioning {#c_CustomWebServices__section_pnw_c44_zhb}

Scripted REST API URIs may include a version number, such as
/api/management/v1/table/{tableName}. Version numbers identify the
endpoint version that a URI accesses. By specifying a version number in your URIs, you can test
and deploy changes without impacting existing integrations.

## Default API version {#c_CustomWebServices__section_jgj_b44_zhb}

A version may be marked as default. Specifying a default version allows users to access that
version using a scripted REST endpoint without a version number. If no version is marked as
default, the latest version is used as the default.

## Scripted REST API resources {#c_CustomWebServices__section_fhh_3nw_23b}

A scripted REST API resource is equivalent to a REST endpoint. It defines the HTTP method to
execute, the processing script, and any override settings from the parent API. You can define
one ore more resources per API.

## Scripted REST API query parameters {#c_CustomWebServices__section_tfl_444_zhb}

Query parameters define values that requesting users can pass in a request. When creating a
scripted REST API, you can specify which parameters are available and which are mandatory for
each request. You can also associate a query parameter with multiple resources.

Access request parameters in scripts using the request object queryParams
field.

## Scripted REST schemas {#c_CustomWebServices__section_wby_4cc_j3c}

Schemas define a structure that can be used for API requests and responses, including data type, expected fields, and formats. You can define multiple schemas within a scripted REST API, which can be used to specify request and response contents of the resources within that API.{#c_CustomWebServices__patch-rn-ap1-1}

Schemas must be defined using [OpenAPI version 3.0.1 format](https://spec.openapis.org/oas/v3.0.1.html).

## Scripted REST API roles {#c_CustomWebServices__section_y5m_xx4_zhb}

To work with scripted REST APIs, you must have the web service administrator \[web_service_admin\] role. Users with this role can read, create, modify, and delete scripted REST APIs and web service resources.  
Note:  
These roles are not required to access a scripted REST API endpoint.

## Request and response formats {#c_CustomWebServices__section_p3s_fkw_23b}

By default, all resources in an API support the following request and response formats:
application/json, application/xml, and text/xml. You can overrride the default formats at the
API level. The new formats apply to all resources belonging to the API, unless an individual
resource overrides the defaults.

## Scripted REST API security {#c_CustomWebServices__section_txq_hx4_zhb}

You can configure your scripted REST APIs with the necessary level of security. From public APIs/endpoints that don't require any security to highly secure APIs/endpoints that require user authentication with tight access
control to all resources.

Use the API access policy feature to control the authentication method for the APIs. For more information, see [API access policy](https://www.servicenow.com/docs/access?context=api-access-policy&version=australia&pubname=australia-platform-security&ft:locale=en-US).

## Scripted REST API access controls {#c_CustomWebServices__section_rbc_zz4_zhb}

Access control lists (ACLs) define criteria, such as the roles needed and conditions that a user must meet to access a scripted REST API or endpoint. A requesting user must satisfy at least one of the ACLs. It is not necessary
to satisfy all selected ACLs. You can define a single ACL for an entire REST API or for an individual endpoint.

When defining a scripted REST API ACL, it must have the Type value REST_Endpoint.

For additional information on ACLs, see [Access control list rules](https://www.servicenow.com/docs/access?context=access-control-rules&version=australia&pubname=australia-platform-security&ft:locale=en-US) and [Configure a scripted REST API resource to require an ACL](https://www.servicenow.com/docs/A1cmPARMRnXw5VgRDXs3hA "By default, API resources/endpoints inherit security settings from the parent API. Define custom Access Control Levels (ACLs) for a specific resource/endpoint to override the inherited settings.").

## Scripted REST API security matrix {#c_CustomWebServices__section_xww_cgp_zhb}

There are multiple possible security configurations for scripted REST APIs. Use this table to identify the scripted REST API security configuration that best suits your needs, and the field values to implement that
configuration.
{#c_CustomWebServices__table_r2p_vbt_tr__entry__3}{#c_CustomWebServices__table_r2p_vbt_tr__entry__8}

| Configuration | Scripted REST API | Scripted REST Resource |||
|   | Default ACLs | Requires authentication | Requires ACL authorization | ACLs |
|-|-|-|-|-|
| The resource is public. No authentication or ACL is required. | Any value | False | Any value | Any value |
| The resource requires basic authentication only. No ACL is required. | Any value | True | False | Any value |
| The resource requires basic authentication only. ACL is required. | No ACL selected | True | True | No ACL selected |
| An ACL selected in the resource record is required. | Any value | True | True | One or more ACLs selected |
| An ACL selected in the scripted REST API record is required. | One or more ACLs selected | True | True | No ACL selected |
[Table 1. Scripted REST API security]

{#c_CustomWebServices__table_r2p_vbt_tr}

## Scripted REST API error objects {#c_CustomWebServices__section_xkj_5gp_zhb}

Scripted REST APIs include error objects that allow you to respond to a request with a
standard HTTP error message when an error occurs during request processing. You can use error
objects in scripted REST API resources to alert requesting clients of errors. Use error objects
to respond to incoming requests, not to catch errors within your server-side code.

## Error response format {#c_CustomWebServices__section_f2v_1hp_zhb}

The content type of the response depends on the request Accept header. If the Accept header
specifies an unsupported format, such as image/jpeg, the error response uses JSON.  
Error responses follow this format:

    {
      "error": {
        "message": "My error message",
        "detail": "My details"  
      },  
      "status": "failure"
    }

The numeric status code, such as 404, is included in the response Status code header, not in the response body.

## Automated Test Framework support

The [Automated Test Framework](https://www.servicenow.com/docs/access?context=automated-test-framework&version=australia&pubname=australia-application-development&ft:locale=en-US) (ATF) supports Inbound REST test steps. You can create
automated tests for custom Inbound REST APIs that you create. Creating tests for your custom
REST APIs simplifies upgrade testing, and makes it possible to verify that modifications to
a REST API are backward compatible. See [Administering REST test step configurations](https://www.servicenow.com/docs/access?context=atf-administer-rest&version=australia&pubname=australia-application-development&ft:locale=en-US) and [ATF REST test step configurations](https://www.servicenow.com/docs/access?context=rest-test-steps&version=australia&pubname=australia-application-development&ft:locale=en-US).

## Developer training {#c_CustomWebServices__section_dk2_2cc_2hb}

In the ServiceNow®
Developer Site, you can find training for [Scripted REST APIs](https://developer.servicenow.com/app.do#!/training/article/app_store_learnv2_rest_paris_scripted_rest_apis/app_store_learnv2_rest_paris_scripted_rest_api_objectives?v=paris).
* **[Create a scripted REST API](https://www.servicenow.com/docs/w60Emb9Lz0kxnsVRqmA8bA)**   
  Create a scripted REST API to define web service endpoints.
* **[Scripted REST APIs good practices](https://www.servicenow.com/docs/lhkzfiOtMX_UgADvfpjWLA)**   
  Follow these guidelines when designing and implementing scripted REST APIs.
* **[Scripted REST API examples](https://www.servicenow.com/docs/eDW_hzL6ZC1rNZd~XvTF3Q)**   
  Mutliple examples are available demonstrating how to create and use scripted REST APIs.