> ## 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<br />(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 <br />*(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"
}'
```