--- title: "External API Request" slug: "external-api-request" updated: 2025-08-04T18:57:48Z published: 2025-08-04T18:57:48Z canonical: "help.claritysecurity.com/external-api-request" --- > ## Documentation Index > Fetch the complete documentation index at: https://help.claritysecurity.com/llms.txt > Use this file to discover all available pages before exploring further. # External API Request Clarity allows you to attach customizable api requests to any workflow. This allows you to integrate Clarity into any external application, such as your SIEM, ticketing system, or collaboration tools. For instance, you could attach this action to the **Identity Modified** workflow to send a message to your company Slack channel any time an identity is modified. --- ## Configuring the Action Like any other workflow action in Clarity, start by choosing the workflow you would like to attach this action to. For more info on workflows, triggers, and actions check out these articles [What are Workflows?](/docs/what-are-workflows) [Workflow Triggers](/docs/workflow-triggers) [Workflow Actions](/docs/workflow-actions) After selecting your workflow, navigate to Add Step to Workflow and click Add Action ![image.png](https://cdn.document360.io/2d020999-1823-4d4d-b6d2-4b52fb4a9617/Images/Documentation/image%28512%29.png?sv=2026-02-06&spr=https&st=2026-10-27T04%3A23%3A12Z&se=2026-10-27T05%3A23%3A12Z&sr=c&sp=r&sig=QAN07%2FUi1JF0AY%2FywLgKMGuJJntSlTDE727HgbYKLb8%3D) Then select the **Send Configurable API Request** action. ![image.png](https://cdn.document360.io/2d020999-1823-4d4d-b6d2-4b52fb4a9617/Images/Documentation/image%28513%29.png?sv=2026-02-06&spr=https&st=2026-10-27T04%3A23%3A12Z&se=2026-10-27T05%3A23%3A12Z&sr=c&sp=r&sig=QAN07%2FUi1JF0AY%2FywLgKMGuJJntSlTDE727HgbYKLb8%3D) To configure the API request, fill out the form as necessary. ![](https://cdn.document360.io/2d020999-1823-4d4d-b6d2-4b52fb4a9617/Images/Documentation/image(566).png?sv=2026-02-06&spr=https&st=2026-10-27T04%3A23%3A12Z&se=2026-10-27T05%3A23%3A12Z&sr=c&sp=r&sig=QAN07%2FUi1JF0AY%2FywLgKMGuJJntSlTDE727HgbYKLb8%3D) - **API endpoint**: Fill in the url of where you would like the request to go. For instance, to send a request to ServiceNow you might use a url like "https://yourInstance.service-now.com/api/snc/identity-modified". - **API method**: Choose the appropriate HTTP method for your endpoint. In the ServiceNow example that might be a POST request. - **Secret**: Fill in any token or key that may be necessary. This is not a required field, but depending on what API you are sending the data to, it may be necessary. This secret will be included as the **bearer token** of the request. - **Body**: Please refer to the API documentation of the desired service to know how to format the body and what fields you'd like to use. Available Context Parameters Each API request action has certain parameters available to it, depending on which workflow trigger it is attached to. For instance, if you are attaching the action to the **Identity Modified** trigger, Clarity will provide you with the following context parameters: identity_id, auto_or_manual, action_initiating_trigger, internal_or_external, attribute_changes, creator_id, notification_id ## Configuring the Body Below is an example of a properly configured **Body**, but keep in mind this may not be correct for the platform you would like to ingest the data. Check out the **Structured Data** section below to learn why **[[attribute_changes]]** is formatted differently. The parameters must be surrounded in **double quotes**, so that the inserted data is captured in a double quotes to complete the JSON key-value pair. ```json { "title":"Identity Modified", "identity":"[[identity_id]]", "identity_email":"[[identity_email]]", "identity_role":"[[identity_role]]", "identity_attribute_changes":[[attribute_changes]], "action_initiating_trigger":"[[action_initiating_trigger]]", "auto_or_manual":"[[auto_or_manual]]", "internal_or_external":"[[internal_or_external]]", "notification_id":"[[notification_id]]", "creator":"[[creator_id]]", "creator_email":"[[creator_email]]", "creator_role":"[[creator_role]]" } ``` ### Structured Data Certain Parameters provided by the workflow may contain structured data, such as JSON objects or an array of JSON objects, and these may need to be handled differently based on the contents they will insert into the Body. Structured data parameters may contain certain characters that may need to be escaped (such as additional “double quotes”). #### Escape Structured Data You can use the **Escape Structured Data** checkbox to ensure the format of the inserted data remains a string. This is accomplished by preceding every `“` (double quote) with a `\` (backslash), | Parameter | Data Type | Example | | --- | --- | --- | | [[attribute_changes]] | This will insert an `[array]` of `{“JSON”: “objects”}` for each Attribute that was changed for this event. | ```json [{"attribute": "Supervisor", "new_value": null, "old_value": "123456"}, {"attribute": "fullname", "new_value": "First Last", "old_value": null}] ``` | | [[meta]] | This will insert a `{“JSON”: “object”}` containing metadata context about the event that triggered the workflow. | ```json {"action": "add", "reason": "Entitlement Role Exclusion Removed", "created_by": 1234, "expiration": ""} ``` | ## Example In our example below, any time an Identity in Clarity is modified, we would send a POST request to a ServiceNow endpoint using a bearer token for authentication. The request body would be formatted **JSON**, and would include context around the Identity that was modified, as well as the initiating action and whatever attributes were changed. Your request body can reference any of these parameters available in the **Available Context**, using [[double bracket syntax]] surrounded by “double quotes” (Ex: **“[[identity_id]]”**). Once you have configured the action appropriately, click **Save Action Step** and be sure to **Save** the workflow as well after making any other desired changes. ![](https://cdn.document360.io/2d020999-1823-4d4d-b6d2-4b52fb4a9617/Images/Documentation/image(567).png?sv=2026-02-06&spr=https&st=2026-10-27T04%3A23%3A12Z&se=2026-10-27T05%3A23%3A12Z&sr=c&sp=r&sig=QAN07%2FUi1JF0AY%2FywLgKMGuJJntSlTDE727HgbYKLb8%3D) --- ## Need help? If you have any problems, contact your customer success team. You can also get in touch with our general support [via email](mailto:support@claritysecurity.io), open a [support ticket](https://support.claritysecurity.com/home). Our general support team is available Monday - Friday from 8:00 AM - 6:30 PM CST. An attribute is a piece of information used to describe a service user, entitlement, or identity. Common examples include First Name, Last Name, Job Title, Department, etc. ## Related - [What are Workflows?](/what-are-workflows.md) - [Workflow Triggers](/workflow-triggers.md) - [Workflow Actions](/workflow-actions.md) - [Workflow Conditions](/workflow-conditions.md) - [Webhooks](/webhooks.md)