# Service/API thinklet {% hint style="info" %} The Service/API thinklet supports the following connector credential types: * Basic * Bearer * OAuth 2.0 - Client Credentials * OAuth 2.0 - Authorization Code * No Auth {% endhint %} The Service/API thinklet makes a REST call to an external public API. Use it to retrieve additional information or request actions to be performed. The Service/API thinklet supports the following call methods: * GET * POST * PATCH * PUT * DELETE {% hint style="info" %} The supported payload and response for the Service/API Thinklet are in JSON format. {% endhint %}
* **Name**: Enter a unique name for the Service/API thinklet. * **ID**: The system generates the ID automatically based on the name. * **Description (optional)**: Describe the purpose of the thinklet and what it does. This information is useful for other users of the workflow who may not be familiar with it. * **Credentials**: Select the connection credentials for the integration. You must configure them first on the [Connector credentials](/platform/configuring_nexthink/bringing-data-into-your-nexthink-instance/integrating-nexthink-with-third-party-tools/outbound-connectors/connector-credentials.md) page of the Administration module. * **Request Method**: Select the request connection method. * **Resource**: Specify the endpoint for the connection. Refer to the [#setting-the-resource-path](#setting-the-resource-path "mention")section on this page. * **Add custom header**: Add up to 5 custom headers to pass additional metadata if required. You must add authorization headers in **Credentials** instead. * **Payload**: Enter the [JSON payload](#using-database-and-workflow-values-in-payloads) to be sent to the external system. Dynamic values containing special characters (for example, newline characters) should be properly escaped to prevent invalid JSON. * **Choose parsing language for JSON** to effectively [collect data from API call responses](#collecting-data-from-api-calls). * [Add output configuration](#output-configuration) for data selection and transformation. {% hint style="warning" %} All expressions within a single Service/API thinklet should use the selected **parsing language for JSON**. {% endhint %} #### Setting the Resource path From the Service/API thinklet configuration, define a **Resource** field with the endpoint you want to call, relative to the base URL outlined in your credentials. To ensure the complete URL is constructed correctly and to prevent malformed API requests, mind the use of slashes `/` in the **Resource** path, which can vary based on the credentials: * If the credential URL ends with a slash—such as `https://.service-now.com/`—start the **Resource** without a slash. For example: `api/now/table/incident` . * If your credential URL does not end with a slash—such as `https://.service-now.com`—start the **Resource** with a slash. For example: `/api/now/table/incident` . ## **Collecting data from API calls** From the Service/API thinklet configuration, select a supported **parsing language for JSON** to collect data from API call responses from an external system: * **JSONata** (recommended): This is a powerful query and transformation language for JSON. It allows for complex filtering, calculations, and data restructuring. * **JSONPath**: This is a simpler language for extracting fields from JSON. It is commonly used where the system expects straightforward data access paths. {% hint style="info" %} The Service/API thinklet waits up to 10 seconds for a response from the external system before considering the call a failure. The response from the external system must not exceed 2 MB, regardless of the Service/API thinklet output configuration. {% endhint %} ### Output configuration {% hint style="warning" %} The system supports up to 5 outputs per thinklet. The maximum output size is 30 KB or 3840 characters. {% endhint %} After [choosing parsing language for JSON](#collecting-data-from-api-calls) for the Service/API thinklet, define the data output settings: 1. Click the **Add output** button. 2. Provide a reference **Name** to use in conditions and thinklet inputs. 3. Define the expression for data selection and transformation using the selected JSON syntax. Find below expression examples—in **JSONPath** and **JSONata**—to extract data from the following API sample response: ```json5 { "result": { "number": "INC001" }, "value": [ { "displayName": "Alice", "id": 1, "number": 50 }, { "displayName": "Bob", "id": 2, "number": 120 } ], "@meta": { "key.with.dots": "yes" } } ``` {% hint style="warning" %} Ensure dynamic values in JSON payloads, such as outputs from remote actions, have their special characters (for example, newline characters) **properly escaped** to avoid invalid JSON and failed requests. {% endhint %}
JSONPath expression examples for outputs Use these expression examples to extract specific data from the API responses. | Use case | Expression - JSONPatch | Results for API sample response from above | | ------------------------- | ----------------------------- | ------------------------------------------ | | Root element | `$` | *(entire JSON)* | | Access a key | `$.result` | `{ "number": "INC001" }` | | Access nested element | `$.result.number` | `"INC001"` | | First array element | `$.value[0].displayName` | `"Alice"` | | Special characters in key | `$['@meta']['key.with.dots']` | `"yes"` |
JSONata expression examples for outputs Use these expression examples to extract specific data from the API responses. | Use case | Expression - JSONata | Results for API sample response from above | | ----------------------- | ----------------------------------------- | -------------------------------------------------------------- | | Access a top-level key | `result` | `{ "number": "INC001" }` | | Access a nested element | `result.number` | `"INC001"` | | First item in array | `value[0].displayName` | `"Alice"` | | Filter by condition | `value[number > 100].displayName` | `[ "Bob" ]` | | Map and transform | `value.{ "name": displayName, "id": id }` | `[ { "name": "Alice", "id": 1 }, { "name": "Bob", "id": 2 } ]` | | Perform computation | `value[0].number * 100` | `5000` | | Aggregate | `sum(value.number)` | `170` |
Use an online converter tool to parse JSONPath or JSONata during testing. *** ## **Using database and workflow values in payloads** Reference the data of `users` and `devices` along with [data collected](#collecting-data-from-api-calls) during the execution of the workflow in the **Resource** and **Payload** fields. Refer to the [Parameters and dynamic values](/platform/user-guide/workflows/creating-workflows/parameters-and-dynamic-values.md) documentation for more details on how to reference dynamic values. {% hint style="warning" %} When using workflow values or remote action outputs in payloads, ensure that string values are valid JSON. The Service/API thinklet does not automatically **escape** special characters. {% endhint %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.nexthink.com/platform/user-guide/workflows/creating-workflows/configuring-thinklets/service-api-thinklet.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.