# ServiceNow API

Source: https://userguide.qualytics.io/settings/integrations/ticketing/servicenow/api/

Programmatic management of the **ServiceNow integration** itself: connecting it, reading it back, changing its settings, and disconnecting it. Requests share the same base URL and Bearer token authentication as the rest of the platform API.

- **Base URL.** Your deployment's platform host (for example, `https://<your-tenant>.qualytics.io/api`).
- **Auth.** Bearer token in the `Authorization` header. See [Access Tokens](https://userguide.qualytics.io/settings/access-tokens/getting-started/) to create one.
- **Content type.** `application/json` on every request that carries a body.

> **Note: Permissions**
>
> Every endpoint on this page requires the **Manager** role. See [Permissions](https://userguide.qualytics.io/settings/integrations/ticketing/servicenow/deep-dive/permissions/).

> **Tip: Complete API Reference**
>
> The endpoints below are illustrative. For the full request and response schemas, live examples, and every field that each endpoint accepts, see the interactive API reference at [demo.qualytics.io/api/docs](https://demo.qualytics.io/api/docs).

> **Info: Looking for tickets and links?**
>
> Creating an incident for an anomaly, searching incidents, and managing the links between anomalies and incidents are anomaly operations, not integration ones. They live on the [Anomalies API](https://userguide.qualytics.io/anomalies/api/#search-tickets) page.

## Integration Endpoints

| Operation | Method | Endpoint | Description |
| --- | --- | --- | --- |
| Create Integration | POST | `/api/integrations` | Connect ServiceNow. The credentials are validated against the instance before the integration is stored. |
| List Integrations | GET | `/api/integrations` | Return every connected integration, ticketing included. |
| Get Integration | GET | `/api/integrations/{id}` | Return one integration. Credentials are never returned in plain text. |
| Update Integration | PUT | `/api/integrations/{id}` | Change the URL, the credentials, or the sync settings. |
| Get Integration History | GET | `/api/integrations/{id}/history` | Return the change log of the integration, one entry per saved version, with the user who made each change. |
| Disconnect Integration | DELETE | `/api/integrations/{id}` | Remove the integration and every anomaly-ticket link with it. The incidents in ServiceNow are untouched. |

## Connection Form Endpoints

These are what the settings modal calls while you fill it in. The `POST` variants take the credentials being typed, so they work before anything is saved, while the `GET` variants read through a saved integration.

| Operation | Method | Endpoint | Description |
| --- | --- | --- | --- |
| Get Integration Specifications | GET | `/api/integrations-specifications` | Return the field specification each integration type's form is built from. |
| List Ticket Statuses (unsaved) | POST | `/api/integrations/ticketing/statuses` | List the incident states, used to build the status mapping. |
| List Ticket Statuses (saved) | GET | `/api/integrations/{id}/ticketing/statuses` | The same list, through a saved integration. |

ServiceNow fixes its incident states rather than letting each project define them, so the list is always the same six: **New**, **In Progress**, **On Hold**, **Resolved**, **Closed**, and **Canceled**.

> **Warning: Two endpoints do not apply to ServiceNow**
>
> `/api/integrations/ticketing/projects` has no meaning here, because ServiceNow incidents do not belong to a project the way Jira issues do. `/api/integrations/ticketing/webhook` returns no usable URL either, since ServiceNow cannot notify Qualytics the moment an incident changes. Both are Jira capabilities. See the [Jira API](https://userguide.qualytics.io/settings/integrations/ticketing/jira/api/).

## Request Fields

The create and update bodies share the same shape. Only `type` is create-only.

> **Warning: parameters is replaced, not merged**
>
> An update stores the `parameters` object exactly as sent, so any key you leave out is dropped. Send the whole object, even when you are only changing one sync setting. Omitting `parameters` entirely leaves the stored one untouched.

The credentials are only re-tested against ServiceNow when the request changes `api_url` or sends new credentials, so a request that changes sync settings alone is saved without a connection test. The same values are described as they appear in the interface on [Add ServiceNow Connection](https://userguide.qualytics.io/settings/integrations/ticketing/servicenow/how-tos/connection/add-connection/).

| Field | Type | Description |
| --- | --- | --- |
| `type` | `string` | `servicenow`. Required on create, and cannot be changed afterwards. |
| `api_url` | `string` | The ServiceNow instance URL, in the form `https://your-instance.service-now.com`. A trailing slash is stripped. |
| `api_access_token` | `string` | The service account credentials, as `username:password`. Stored encrypted and never returned. |
| `parameters.post_updates` | `bool` | Two-way sync. Absent means on. When false the integration is read only and nothing is written to ServiceNow. |
| `parameters.sync_statuses` | `bool` | Whether anomaly statuses and incident states move together. Defaults to off. |
| `parameters.status_mapping` | `object` | Anomaly status to incident state, for example `{"Active": "New", "Resolved": "Resolved"}`. A `null` value leaves that anomaly status unmapped. Required to be non-empty when `sync_statuses` is on. |

## Sample Requests

> **Example: Connect ServiceNow**
>
> ```bash
> curl -X POST "https://<your-tenant>.qualytics.io/api/integrations" \
>   -H "Authorization: Bearer $QUALYTICS_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "type": "servicenow",
>     "api_url": "https://your-instance.service-now.com",
>     "api_access_token": "qualytics_integration:your_password"
>   }'
> ```
>
> Returns the stored integration. The credentials are not echoed back.

> **Example: Turn on status sync with a mapping**
>
> ```bash
> curl -X PUT "https://<your-tenant>.qualytics.io/api/integrations/3" \
>   -H "Authorization: Bearer $QUALYTICS_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "parameters": {
>       "post_updates": true,
>       "sync_statuses": true,
>       "status_mapping": {
>         "Active": "New",
>         "Acknowledged": "In Progress",
>         "Resolved": "Resolved"
>       }
>     }
>   }'
> ```
>
> Turning `sync_statuses` on with nothing mapped is refused, so send the mapping in the same request. The value on the right has to be one of the six incident states. `post_updates` is repeated for the same reason as everything else in `parameters`: leaving it out drops it, and an absent value reads as on, which would put a read-only integration back into two-way sync.

> **Example: Make the integration read only**
>
> ```bash
> curl -X PUT "https://<your-tenant>.qualytics.io/api/integrations/3" \
>   -H "Authorization: Bearer $QUALYTICS_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "parameters": {
>       "post_updates": false,
>       "sync_statuses": true,
>       "status_mapping": {
>         "Active": "New",
>         "Acknowledged": "In Progress",
>         "Resolved": "Resolved"
>       }
>     }
>   }'
> ```
>
> The sync settings are repeated because `parameters` is stored exactly as sent. Sending `post_updates` on its own would drop the stored `sync_statuses` and `status_mapping` with it. Read the integration first when you do not know what it currently holds.
>
> Reading incidents back continues. To silence a single incident instead, use the ticket link endpoint on the [Anomalies API](https://userguide.qualytics.io/anomalies/api/#search-tickets).

> **Example: Disconnect ServiceNow**
>
> ```bash
> curl -X DELETE "https://<your-tenant>.qualytics.io/api/integrations/3" \
>   -H "Authorization: Bearer $QUALYTICS_TOKEN"
> ```
>
> Removes the integration and every anomaly-ticket link. The incidents stay in ServiceNow.

*Last updated: October 21, 2026.*
