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

# Generate Call Disposition

> [!NOTE]
>
> This endpoint is **AI-powered** and rate limited to 5 requests/minute. It generates a call disposition verdict plan from a call script and its structured data plan.

## What it returns

* **disposition** — The final verdict the AI should derive from each call (e.g. Suitable / Needs Review / Unsuitable). Pass directly to [Initiate AI Call](https://docs.tidyhire.app/api-reference/endpoint/call-initiate.md) as `disposition`.

> [!TIP]
>
> Typical flow: call [Generate AI Call Script](https://docs.tidyhire.app/api-reference/endpoint/generate-script.md) first, then pass its `instructions` as `call_script` and its `extract_variables` as `structured_data_plan` to this endpoint.

The request ID for tracing is returned in the `X-AI-Request-Id` response header.

```bash cURL theme={null} theme={"system"}
curl --request POST \
  --url https://api.tidyhire.app/api/public/v1/ai/generate-disposition \
  --header 'x-tidyhire-api-key: <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "call_script": "You are a recruiter for Acme Corp screening candidates for the Senior Software Engineer role...",
  "structured_data_plan": [
    {
      "label": "Is Interested In Role",
      "key": "is_interested_in_role",
      "type": "boolean",
      "description": "Captures whether the candidate expresses explicit interest in pursuing the discussed job role. Infer true if they say they are interested, want to apply, or want to learn more. Infer false if they decline, say they are not interested, or want to opt-out. Default to null if not discussed.",
      "format_example": "true",
      "choices": [],
      "required": false
    }
  ]
}'
```

```javascript JavaScript theme={null} theme={"system"}
fetch('https://api.tidyhire.app/api/public/v1/ai/generate-disposition', {
  method: 'POST',
  headers: {
    'x-tidyhire-api-key': '<token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    call_script:
      'You are a recruiter for Acme Corp screening candidates for the Senior Software Engineer role...',
    structured_data_plan: [
      {
        label: 'Is Interested In Role',
        key: 'is_interested_in_role',
        type: 'boolean',
        description:
          'Captures whether the candidate expresses explicit interest in pursuing the discussed job role.',
        format_example: 'true',
        choices: [],
        required: false,
      },
    ],
  }),
})
  .then((response) => response.json())
  .then((data) => console.log(data))
  .catch((error) => console.error('Error:', error));
```

```php PHP theme={null} theme={"system"}
<?php

$url = 'https://api.tidyhire.app/api/public/v1/ai/generate-disposition';

$data = [
    'call_script' => 'You are a recruiter for Acme Corp screening candidates for the Senior Software Engineer role...',
    'structured_data_plan' => [
        [
            'label' => 'Is Interested In Role',
            'key' => 'is_interested_in_role',
            'type' => 'boolean',
            'description' => 'Captures whether the candidate expresses explicit interest in pursuing the discussed job role.',
            'format_example' => 'true',
            'choices' => [],
            'required' => false
        ]
    ]
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'x-tidyhire-api-key: <token>',
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>
```

```go Go theme={null} theme={"system"}
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    url := "https://api.tidyhire.app/api/public/v1/ai/generate-disposition"

    payload := map[string]interface{}{
        "call_script": "You are a recruiter for Acme Corp screening candidates for the Senior Software Engineer role...",
        "structured_data_plan": []map[string]interface{}{
            {
                "label":          "Is Interested In Role",
                "key":            "is_interested_in_role",
                "type":           "boolean",
                "description":    "Captures whether the candidate expresses explicit interest in pursuing the discussed job role.",
                "format_example": "true",
                "choices":        []string{},
                "required":       false,
            },
        },
    }

    jsonData, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header.Set("x-tidyhire-api-key", "<token>")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println("Error:", err)
        return
    }
    defer resp.Body.Close()

    fmt.Println("Response Status:", resp.Status)
}
```

```java Java theme={null} theme={"system"}
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;

public class GenerateDisposition {
    public static void main(String[] args) {
        try {
            URL url = new URL("https://api.tidyhire.app/api/public/v1/ai/generate-disposition");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();

            con.setRequestMethod("POST");
            con.setRequestProperty("x-tidyhire-api-key", "<token>");
            con.setRequestProperty("Content-Type", "application/json");
            con.setDoOutput(true);

            String jsonInputString = "{\n" +
                "  \"call_script\": \"You are a recruiter for Acme Corp screening candidates for the Senior Software Engineer role...\",\n" +
                "  \"structured_data_plan\": [{\n" +
                "    \"label\": \"Is Interested In Role\",\n" +
                "    \"key\": \"is_interested_in_role\",\n" +
                "    \"type\": \"boolean\",\n" +
                "    \"description\": \"Captures whether the candidate expresses explicit interest in pursuing the discussed job role.\",\n" +
                "    \"format_example\": \"true\",\n" +
                "    \"choices\": [],\n" +
                "    \"required\": false\n" +
                "  }]\n" +
                "}";

            try (OutputStream os = con.getOutputStream()) {
                byte[] input = jsonInputString.getBytes(StandardCharsets.UTF_8);
                os.write(input, 0, input.length);
            }

            int status = con.getResponseCode();
            System.out.println("Response Status: " + status);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

```ruby Ruby theme={null} theme={"system"}
require 'net/http'
require 'json'
require 'uri'

uri = URI('https://api.tidyhire.app/api/public/v1/ai/generate-disposition')

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.path)
request['x-tidyhire-api-key'] = '<token>'
request['Content-Type'] = 'application/json'

request.body = {
  call_script: 'You are a recruiter for Acme Corp screening candidates for the Senior Software Engineer role...',
  structured_data_plan: [
    {
      label: 'Is Interested In Role',
      key: 'is_interested_in_role',
      type: 'boolean',
      description: 'Captures whether the candidate expresses explicit interest in pursuing the discussed job role.',
      format_example: 'true',
      choices: [],
      required: false
    }
  ]
}.to_json

response = http.request(request)
puts response.body
```

```json Response theme={null} theme={"system"}
{
  "success": true,
  "data": {
    "disposition": {
      "type": "single_select",
      "description": "Unsuitable — select when the candidate expresses no interest in the opportunity or declines to participate. Needs Review — select when the candidate completes the screening but expresses hesitation or provides vague information. Suitable — select when the candidate completes the screening and provides complete, satisfactory details about their experience, availability, and salary expectations.",
      "choices": ["Unsuitable", "Needs Review", "Suitable"]
    }
  }
}
```

***

### Authorizations

**Authorizations** `string | header` *required*

API key of the form `<token>`, passed as the `x-tidyhire-api-key` header.

### Body

**call\_script** `string` *required*

The call script the AI will follow on the call. Pass `instructions` returned by [Generate AI Call Script](https://docs.tidyhire.app/api-reference/endpoint/generate-script.md).

Example: `"You are a recruiter for Acme Corp screening candidates for the Senior Software Engineer role..."`

**structured\_data\_plan** `object[]`

Structured data fields the AI extracts during the call. Pass `extract_variables` returned by [Generate AI Call Script](https://docs.tidyhire.app/api-reference/endpoint/generate-script.md). Defaults to `[]`.

**child attributes**

**structured\_data\_plan.label** `string` *required*

Human-readable name for the variable.

Example: `"Is Interested In Role"`

**structured\_data\_plan.key** `string` *required*

Machine-readable key for the variable.

Example: `"is_interested_in_role"`

**structured\_data\_plan.type** `string` *required*

Data type of the variable. One of `string`, `single_select`, `boolean`, `integer`, `number`, `array`, `date`, `datetime`.

Example: `"boolean"`

**structured\_data\_plan.description** `string` *required*

What the AI should extract.

Example: `"Whether the candidate expresses explicit interest in pursuing the role."`

**structured\_data\_plan.format\_example** `string`

Example of the expected output format.

Example: `"true"`

**structured\_data\_plan.choices** `string[]`

Allowed values for `single_select` type.

Example: `["true", "false"]`

**structured\_data\_plan.required** `boolean`

Whether the AI must fill this field during the call. Defaults to `false`.

### Response

Call disposition generated successfully

**success** `boolean`

Indicates if the request was successful. Example: `true`

**data** `object`

**child attributes**

**data.disposition** `object`

Final verdict the AI should derive from each call.

**child attributes**

**data.disposition.type** `string`

Data type of the verdict. One of `string`, `boolean`, `single_select`, `integer`.

**data.disposition.description** `string`

Rule the AI uses to derive this verdict from the call.

**data.disposition.format\_example** `string`

Example of the expected output format.

**data.disposition.choices** `string[]`

Allowed values for `single_select` type (min 2).

***

## Common Errors

> [tab] 400 Bad Request
>
> **Reason:** The request body is not valid JSON.
>
> ```json theme={"system"}
> {
>   "success": false,
>   "message": "Invalid JSON in request body"
> }
> ```

> [tab] 401 Unauthorized
>
> **Reason:** Missing or invalid `x-tidyhire-api-key` header.
>
> ```json theme={"system"}
> {
>   "success": false,
>   "message": "Unauthorized, Please reach out at support@tidyhire.app"
> }
> ```

> [tab] 422 Validation Error
>
> **Reason:** Missing or invalid fields — each entry in `errors` points to a specific field.
>
> ```json theme={"system"}
> {
>   "success": false,
>   "message": "Validation error: Call script is required",
>   "errors": [
>     { "path": "call_script", "message": "Call script is required" }
>   ]
> }
> ```

> [tab] 422 Generation Failed
>
> **Reason:** The AI service failed to generate a valid disposition (e.g. invalid type or `single_select` with fewer than 2 choices).
>
> ```json theme={"system"}
> {
>   "success": false,
>   "message": "Failed to generate call disposition"
> }
> ```

> [tab] 429 Too Many Requests
>
> **Reason:** More than 5 requests in a minute.
>
> ```json theme={"system"}
> {
>   "success": false,
>   "message": "Too many requests, please try again later"
> }
> ```


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