Sapia.AI - API

Welcome to _Sapia.ai's_ API Documentation. This guide provides detailed information about _Sapia.ai's_ RESTful API endpoints, which enable seamless integration between external system (such as ATSes, recruitment system) with our assessment management system. The API allows you to programmatically access and manage candidate assessment application, job requisitions, and related data. Sapia.ai provides an API that operates across three environments and supports three regions. # Get Started To get started you will require to these details: 1. `customerId` 2. Assigned `atsName` 3. API credentials (see Authentication below or [here](https://go.postman.co/workspace/Sapia.AI---Integration-API~a3926a85-1766-4fdd-af63-3bb49bf13f5c/documentation/38415447-ae3a8247-dd28-4bc7-b494-441bcc84cb65?entity=folder-207c8a33-f02a-4ba8-9a15-c0a7981e71da)) 4. A configured webhook endpoint is required to receive notifications from _Sapia.ai_. Refer to the **Webhook Configuration Guide** section below for implementation details. Please contact your _Sapia.ai_'s representative to obtain `customerId`, `atsName`, and the API credentials above. --- # Environments Sapia.ai offers the following environments: 1. **Production** 1. **Identifier:** `product` 2. **Description:** The live environment where real-world operations occur. Use this for all production-level interactions. 2. **Sandbox** 1. **Identifier:** `sandbox` 2. **Description:** A testing environment designed for safe experimentation without impacting LIVE/production operations. Suitable for API integration testing and validation. 3. **QA** 1. **Identifier:** `qa` 2. **Description:** A development environment used for quality assurance or development purposes. Suitable for API integration development. --- # Regions The API supports the following regions: 1. **Region APAC** 1. **Identifier:** **`ap-southeast-2`** 2. **Description:** For instance in Asia- Pacific region 2. **Region US** 1. **Identifier:** **`us-east-1`** 2. **Description:** For instance in US region 3. **Region EMEA** 1. **Identifier:** **`eu-west-1`** 2. **Description:** For instance in EMEA region --- # General Error Codes | Code | Description | | --- | --- | | 200 | OK - Request successful | | 400 | Bad Request - Invalid parameters provided | | 401 | Unauthorized - Authentication failed | | 404 | Not Found - Resource not available | | 500 | Internal Server Error - Unexpected issue | --- # Webhook Configuration Guide To enable your system to receive real-time notifications (i.e. results/reports available, video interview rated, video interview commented, etc.) from _Sapia.ai_, you must configure a **Webhook Endpoint URL** within **Sapia.ai** instance. Webhook requirements: 1. **Public Endpoint**: The webhook URL **must be publicly accessible** and **must not require authentication**. 2. **Registration**: Once your webhook endpoint is ready, **submit the URL** to your _Sapia.ai_ representative for setup in your _Sapia.ai_ instance. 3. **IP Whitelisting (Optional)**: If your endpoint requires IP whitelisting, **contact Sapia.ai** to obtain the list of IP addresses used for webhook calls. 4. **HTTP Method**: Webhook requests will be sent using the `HTTP POST` method. _Sapia.ai_ will send JSON payload to your webhook endpoint with the following structure: ``` json { "customerId": "xxxxxxxxx", "externalTenantId": "xxxxxxx", "sapiaApplicationId": "xxxxx" } ``` Example: ``` json { "customerId": "57a02bed3b5ef24805d5d254", "externalTenantId": "57a02bed3b5ef24805d5d254", "sapiaApplicationId": "675e9e1cf4874253f8ed1b44" } ``` ### Retry Mechanism If your server does not respond with a `2xx` HTTP status code, Sapia.ai will retry the webhook delivery: - **Retry Interval**: Every 5 minutes - **Maximum Attempts**: Up to 5 retries per event - **Termination**: After 5 unsuccessful attempts, the event will be marked as failed and no further retries will occur. > Ensure the webhook endpoint returns a `2xx` status code on successful receipt to prevent unnecessary retries. --- # Things to Note 1. Replace placeholder values like and with actual data. 2. Ensure you're operating in the correct environment to avoid unintended consequences. --- # API General Structure ``` https://ph-ats-middleware...predictivehire.com//ats/:atsName/... ``` - Replace with the correct identifier (see _Regions_) - Replace with the correct identifier (see _Environments_) - Replace the `atsName` parameter as per required. Contact _Sapia.ai_'s personnel for more info.