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

# Call Reasons

> Configure the call reason text displayed to recipients, explaining why your business is calling.

## Overview

A **call reason** is a short string explaining why your business is calling, for example, "Appointment Reminder" or "Delivery Update". Call reasons are set at the **DIR level** as a list of 1-10 strings (each up to 64 characters) at DIR-create time.

Telnyx maintains a list of **pre-approved call reasons**. When a DIR's `call_reasons` are *all* pre-approved, the call-reason vetting check passes automatically, which can help speed up review. If any reason is custom (not pre-approved), that check is reviewed by a human instead. Either way the DIR still goes through full vetting; pre-approved reasons are not auto-approved.

## API endpoints

| Method | Path                        | Description                                            |
| :----- | :-------------------------- | :----------------------------------------------------- |
| `GET`  | `/v2/call_reasons`          | List pre-approved call reasons.                        |
| `POST` | `/v2/call_reasons/validate` | Check whether a list of reasons is fully pre-approved. |

## List pre-approved call reasons

Default `page[size]` is `100` (max `250`).

```bash theme={null}
curl -g "https://api.telnyx.com/v2/call_reasons?page[size]=100" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Use the returned `reason` strings verbatim in your DIR's `call_reasons` array to help speed up the call-reason check during vetting.

## Validate a list of call reasons

Before creating a DIR, check whether the reasons you plan to use are pre-approved:

```bash theme={null}
curl -X POST https://api.telnyx.com/v2/call_reasons/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '["Appointment Reminder", "Follow-Up Calls"]'
```

> The body is a **bare JSON array of strings**: do **not** wrap it in `{ "call_reasons": [...] }`. This is unusual for Telnyx APIs; copy the example verbatim.

The result is returned under a top-level `data` object with three fields:
`all_pre_approved` (true when *every* reason is pre-approved and enabled),
`requires_manual_vetting` (true when at least one reason is not pre-approved),
and `non_approved_reasons` (the list of reasons that are not pre-approved).

## Constraints

| Limit                     | Value |
| :------------------------ | :---- |
| Min call reasons per DIR  | 1     |
| Max call reasons per DIR  | 10    |
| Max characters per reason | 64    |