Skip to main content

​
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

MethodPathDescription
GET/v2/call_reasonsList pre-approved call reasons.
POST/v2/call_reasons/validateCheck whether a list of reasons is fully pre-approved.

​
List pre-approved call reasons

Default page[size] is 100 (max 250). 
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: 
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

LimitValue
Min call reasons per DIR1
Max call reasons per DIR10
Max characters per reason64