> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talview.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Talview Workflow Invite Flow

To integrate with Talview WFT (Workflow Tools) Assessment, please follow the steps below.

## Assessment Invite Technical Steps

### 1. Authentication

* Use this [guide](../Authentication) to generate an **`access_token`**.
* The token generated will go in `Authorization` header for all API calls.

### 2. Assessment Invite API

Every assessment invitation sent to Talview, must follow the below payload structure.

**Request header definition**

| Method | POST |
| :- | :- |
| **Host** | [https://api.talview.com](https://api.talview.com) |
| Route | /api/rest/external/assessment/invite |
| Content type | application/json |

**Request payload definition: Standard**

| Attribute | Mandatory | Data Type | Description |
| :- | :- | :- | :- |
| candidate\_email | yes | String | Candidate’s email address |
| candidate\_first\_name | no | String | Candidate's first name |
| candidate\_last\_name | no | String | Candidate's last name |
| candidate\_reference\_id | no | String | Candidate’s ID in the external system |
| workflow\_step\_id | yes | Number | Workflow\_step\_id in Talview System (maps to the exact step in the workflow where the candidate needs to be invited) |
| workflow\_step\_reference\_id | no | String | Workflow Step ID in the external system *(Note: Either workflow\_step\_id or step\_reference\_id is manadatory)* |
| callback\_url | no | String | URL of the external service to be used for sending the reports, scores, playback video, etc. |
| is\_notify | no | Boolean | Whether the candidate needs to be notified or not |
| valid\_till | no | TimeStampz | Assessment window duration in ISO 8601 format: yyyy-MM-dd'T'HH:mm:ss.SSSZ |

**Sample response payload:**

1. Success response: HTTP status code - 201

   ```json theme={null}
   {
     "workflow" : {
       "id" : 12,
       "external_id" : "12-1A",
       "workflow_name": "Java Techincal"
     },
     "candidate": { "external_id": 2932, "email": "abc@xyz.com" },
     "step" : {
       "id": 29103,
       "external_id": "2032-201",
       "type": "ASSESSMENT",
       "workflow_id": 3
     },
     "valid_till": "2025-10-03T17:00:00+00:00",
     "attend_url": "https://cx.talview.com/..."
   }


   ```
2. Error response: HTTP status code - 422

   ```json theme={null}
   {
   	"errors": [{
   		"field": "valid_till",
   		"message": "valid till can not be in past"
   	}]
   }

   ```
3. Error response: HTTP status code - 400

   ```json theme={null}
   {
   	"errors": [{
   		"field": "callback_url",
   		"message": "Callback Url can not be blank"
   	}]
   }

   ```

**Sample CURL request:**

```bash theme={null}
curl --request POST \\
  --url https://api.talview.com/external/assessment/invite \\
  --header 'Authorization: Bearer <:access_token:>' \\
  --data '{
  "valid_till": "2024-06-08T08:30:00.000Z",
  "candidate_first_name": "candidate",
  "candidate_last_name" : "name",
  "candidate_email": "candidate@email.com",
  "candidate_reference_id": "CAN_LAT_10045",
  "workflow_step_id": 10394,
  "workflow_step_reference_id": "AD-1",
  "is_notify": true,
  "callback_url" : "https://<external_service_host_url>.com/scores"
}'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.