> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.moveworks.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.moveworks.com/_mcp/server.

# 2. Connectors & API Playground

## Overview

* **Objectives:** Learn how to connect external systems to Moveworks and validate that they are working as intended
* **Estimated Time:** 30 minutes
* **Prerequisites:**
  * ServiceNow instance active and running
  * ServiceNow admin username and password

***

### Key Concepts

Moveworks uses connectors to establish secure links with your enterprise systems. Understanding how to validate these connections is the first step in any implementation:

* **Connector Instance:** A unique configuration that stores the authentication credentials (e.g., Basic Auth or OAuth) and the Base URL for an external system like ServiceNow.
* **API Playground:** A built-in testing environment that allows administrators to execute real-time API calls to verify that Moveworks has the correct permissions to fetch data.
* **Response Payload:** The raw JSON data returned by the system. Reviewing this helps you identify the exact field names (e.g., `sys_id`, `user_name`) required for later mapping steps.
* **Status Codes:** Standard HTTP indicators (like 200 for success or 401 for unauthorized) used to diagnose connection or permission issues during setup.

**Relevant Documentation:**

* [Moveworks Help: Creating Connectors](https://help.moveworks.com/agent-studio/connectors/system-connectors)
* [Moveworks Help: Using the API Playground](https://help.moveworks.com/docs/api-playground)

***

## 🛠️ 1: Walkthrough

### 1.1: Instantiate your ServiceNow Connector

1. **Navigate** to **`Connectors > Built-in Connectors`** in **Moveworks Setup**
2. Click **`Create New`**

![](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/66ecf99e90b5d9cf933fdb326a8f1399cc5edd56e0d709c28935dd90f128d6e3/docs/assets/images/setup-labs/lab1_99657262-9857-460a-88a5-aa924e228a1b_image.png)

3. Use the Search Bar in the upper right hand side to find the ServiceNow connector & select it

![](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/6feb8a3e959b15ad20d4db2ec370b87c9d458553495f548dd788caac97e0e137/docs/assets/images/setup-labs/lab1_be1c2c2d-d004-4555-a8dc-bb2723825f11_now_connector.png)

4. **Enter** the following values (everything else can remain blank)

**The connector name must be `snow`.** This exact value is referenced in subsequent sections (User Identity, Enterprise Search, Ticketing). If you use a different name, you will need to substitute your custom value at every step that references `snow` throughout this guide.

> **ServiceNow** (`snow`)
>
> * **Common Base URL**: Your PDI instance (e.g. `dev######`)
> * **Auth Type**: Basic Auth
> * **Username**: `admin` (unless you changed it)
> * **Password**: Your admin password

![](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/f8f90e6e8591a73289e463860d667eaf98d0e48c1fefb3ad9d40a88a42e841db/docs/assets/images/setup-labs/lab1_10060506-4761-430e-bf01-d5a29891d932_now_lab_credentials.png)

![](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/9fbf973885ef3a3d3c13701a85cf7cbbb246cab0d1bb41c5aa423e203e70bec4/docs/assets/images/setup-labs/lab1_e115b223-b2e1-43c3-a483-ef6dd58bcd7f_image.png)

### 1.2: Confirm Connection — API Playground

1. Navigate to **`Connectors > API Playground`**
2. Click **`Select Connector`**
3. Select the **`snow`** connector created in the previous step

![](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/8b637e9d9871f4917a6173fde7f1c5255a7b2bb12079a6415655ffb096e20fcd/docs/assets/images/setup-labs/lab1_9e7bf44c-9573-4f81-b6ee-1c11cf857ee2_api_playground_connector.png)

4. Click into the **`API Collection`** search bar on the left hand side and search for **`sys_user`**
5. Select the GET API query, and then click **`Test`** to validate that the connector is working as expected

![](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/d24dd9083deb8a2d563c6e137f1ab8f606b295b3c1be3be4ad780445f2e5757b/docs/assets/images/setup-labs/lab1_a3864dcf-d428-4b1e-a090-b259693a4a1f_api_playground_test_sys_user.png)

***

## ✅ 2: Verification & Next Steps

**Confirm Access:**

* Validate that when you click test, you are getting a `200 response` indicating that the ServiceNow instance is properly connected to Moveworks

**Note:** Your response object will not have the exact same values as shown in the screenshot. The purpose of this step is to confirm that you are able to successfully do a GET call to the user table within your connected NOW instance.

![](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/57dadc5695c07af0051392bb85b7189fc03abb422f923add241a05b0b25068bd/docs/assets/images/setup-labs/lab1_ba9ab92c-b65d-43ed-89da-4b5c1264e118_image.png)

***

## 🪞 3: Reflecting on This Configuration

Through this guide, you've learned the following:

* How to connect an external system to Moveworks
* How to validate that connection using API Playground

How this will come up during live demos:

* After creating a new connector, **always validate** that the connector has the permissions required to deliver the full integration capabilities. Ensure the connector allows Moveworks to:
  * Query the users in the environment
  * For Knowledge — query the content and permissions for users and groups
  * For Ticketing — query the tables/endpoints that Moveworks will support

***

## ⚙️ 4: Configuration Details

Use the table below to fill in the required fields accurately.

| **Field Name**      | **Action / Value to Enter**              |
| ------------------- | ---------------------------------------- |
| **Connector Name**  | `snow`                                   |
| **Common Base URL** | Your PDI instance URL (e.g. `dev######`) |
| **Auth Type**       | Basic Auth                               |
| **API Collection**  | sys\_user → GET /api/now/table/sys\_user |