> ## 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.

# Validate a list of call reasons

> Check up to 10 candidate `call_reasons` strings against Telnyx's vetting heuristics before sending them on a DIR create or update. The endpoint flags strings that are likely to be rejected during vetting (too generic, banned phrases, length issues, etc.) so you can fix them up front.



## OpenAPI

````yaml https://telnyx-openapi-ng.s3.us-east-1.amazonaws.com/branded-calling/call-reasons.yml post /call_reasons/validate
openapi: 3.1.0
info:
  title: Telnyx Branded Calling Call Reasons API
  version: 2.0.0
  description: >-
    List the approved call reasons and validate the reasons you intend to use on
    a DIR.
  contact:
    email: support@telnyx.com
servers:
  - url: https://api.telnyx.com/v2
security:
  - bearerAuth: []
paths:
  /call_reasons/validate:
    post:
      tags:
        - Reference Data
      summary: Validate a list of call reasons
      description: >-
        Check up to 10 candidate `call_reasons` strings against Telnyx's vetting
        heuristics before sending them on a DIR create or update. The endpoint
        flags strings that are likely to be rejected during vetting (too
        generic, banned phrases, length issues, etc.) so you can fix them up
        front.
      operationId: validateCallReasons
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateCallReasonsRequest'
            example:
              - Appointment reminders
              - Billing inquiries
      responses:
        '200':
          description: Per-string validation result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateCallReasonsResponse'
        default:
          $ref: '#/components/responses/branded-calling_GenericErrorResponse'
        4XX:
          $ref: '#/components/responses/branded-calling_GenericErrorResponse'
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Telnyx from 'telnyx';

            const client = new Telnyx({
              apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
            });

            const response = await client.callReasons.validate({
              body: ['Appointment reminders', 'Billing inquiries'],
            });

            console.log(response.data);
        - lang: Python
          source: |-
            import os
            from telnyx import Telnyx

            client = Telnyx(
                api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
            )
            response = client.call_reasons.validate(
                body=["Appointment reminders", "Billing inquiries"],
            )
            print(response.data)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/team-telnyx/telnyx-go\"\n\t\"github.com/team-telnyx/telnyx-go/option\"\n)\n\nfunc main() {\n\tclient := telnyx.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tresponse, err := client.CallReasons.Validate(context.TODO(), telnyx.CallReasonValidateParams{\n\t\tBody: []string{\"Appointment reminders\", \"Billing inquiries\"},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Data)\n}\n"
        - lang: Java
          source: |-
            package com.telnyx.sdk.example;

            import com.telnyx.sdk.client.TelnyxClient;
            import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
            import com.telnyx.sdk.models.callreasons.CallReasonValidateResponse;
            import java.util.List;

            public final class Main {
                private Main() {}

                public static void main(String[] args) {
                    TelnyxClient client = TelnyxOkHttpClient.fromEnv();

                    List<String> params = List.of(
                      "Appointment reminders", "Billing inquiries"
                    );
                    CallReasonValidateResponse response = client.callReasons().validate(params);
                }
            }
        - lang: Ruby
          source: >-
            require "telnyx"


            telnyx = Telnyx::Client.new(api_key: "My API Key")


            response = telnyx.call_reasons.validate(body: ["Appointment
            reminders", "Billing inquiries"])


            puts(response)
        - lang: PHP
          source: >-
            <?php


            require_once dirname(__DIR__) . '/vendor/autoload.php';


            use Telnyx\Client;

            use Telnyx\Core\Exceptions\APIException;


            $client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API
            Key');


            try {
              $response = $client->callReasons->validate(
                body: ['Appointment reminders', 'Billing inquiries']
              );

              var_dump($response);
            } catch (APIException $e) {
              echo $e->getMessage();
            }
        - lang: CLI
          source: |-
            telnyx call-reasons validate \
              --api-key 'My API Key' \
              --body 'Appointment reminders' \
              --body 'Billing inquiries'
components:
  schemas:
    ValidateCallReasonsRequest:
      type: array
      description: >-
        **Bare JSON array** of candidate call-reason strings (NOT an object -
        there is no top-level `call_reasons` key on this endpoint). 1–10
        strings, each ≤64 characters.
      items:
        type: string
        maxLength: 64
      minItems: 1
      maxItems: 10
      example:
        - Appointment reminders
        - Billing inquiries
    ValidateCallReasonsResponse:
      type: object
      required:
        - data
      properties:
        data:
          type: object
          required:
            - all_pre_approved
            - non_approved_reasons
            - requires_manual_vetting
          properties:
            all_pre_approved:
              type: boolean
              description: >-
                `true` when every supplied reason matches a pre-vetted entry in
                the call-reason library. When `true`, the DIR will sail through
                the call-reasons portion of vetting.
              example: false
            non_approved_reasons:
              type: array
              items:
                type: string
              description: >-
                Subset of the input that does NOT match the pre-vetted library.
                The DIR can still be submitted with these - they will go through
                manual review.
              example:
                - Appointment reminders
                - Billing inquiries
            requires_manual_vetting:
              type: boolean
              description: >-
                `true` when at least one supplied reason is in
                `non_approved_reasons`. Equivalent to
                `non_approved_reasons.length > 0` and the inverse of
                `all_pre_approved`.
              example: true
    branded-calling_Errors:
      type: object
      required:
        - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/branded-calling_Error'
          description: List of one or more error entries. Order is not significant.
      description: >-
        Canonical Telnyx error envelope. Returned on every 4xx and 5xx response
        from this service. `errors` is non-empty; multiple entries indicate
        multiple distinct problems with the same request (e.g. one entry per
        invalid phone number on a bulk operation).
    branded-calling_Error:
      type: object
      required:
        - code
        - title
        - detail
        - meta
      properties:
        code:
          type: string
          example: '10005'
          description: >-
            Stable numeric Telnyx error catalog id. See `meta.url` for the full
            catalog entry.
        title:
          type: string
          example: Invalid parameters
          description: >-
            Short human-readable category, e.g. `Bad Request`, `Duplicate
            resource`, `Not Found`, `Forbidden`. Treat as advisory only - the
            stable identifier is `code`.
        detail:
          type: string
          example: field required
          description: >-
            Context-specific message describing what went wrong on this
            particular request. May embed offending values; do not rely on it
            for programmatic matching - branch on `code`.
        meta:
          type: object
          required:
            - url
          properties:
            url:
              type: string
              format: uri
              example: https://developers.telnyx.com/docs/overview/errors/10005
            pending_check_ids:
              type: array
              items:
                type: string
                format: uuid
              description: >-
                Set on `422 vetting_checks_incomplete` responses from
                `/admin/dir/{id}/approve` and
                `/admin/phone-number-batches/approve`. Lists the still-pending
                vetting check ids.
            pending_check_codes:
              type: array
              items:
                type: string
              description: >-
                Codes of the pending vetting checks (e.g.
                `loa_signature_valid`).
            pending_check_labels:
              type: array
              items:
                type: string
              description: Human-readable labels of the pending vetting checks.
          description: >-
            Carries `url` linking to the Telnyx error catalog entry for this
            `code`. Useful for forwarding the user to documentation.
        source:
          type: object
          description: Optional pointer at the offending field of the request.
          properties:
            pointer:
              type: string
              example: /body/legal_name
            parameter:
              type: string
              example: page[size]
      description: >-
        A single entry in the canonical Telnyx error envelope. `code` is the
        stable Telnyx error catalog id; the human-readable explanation lives at
        `meta.url`. `detail` is a context-specific message; `source.pointer`
        (when present) names the offending field of the request.
  responses:
    branded-calling_GenericErrorResponse:
      description: >-
        An error occurred. The response carries the standard Telnyx error
        envelope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/branded-calling_Errors'
          examples:
            validation_error:
              summary: 422 - request body failed validation
              value:
                errors:
                  - code: '10005'
                    title: Invalid parameters
                    detail: field required
                    meta:
                      url: https://developers.telnyx.com/docs/overview/errors/10005
                    source:
                      pointer: /body/legal_name
            bad_request:
              summary: 400 - request rejected by a state guard
              description: >-
                Returned when the request itself is well-formed but the resource
                is in a state that disallows this action (e.g. updating a DIR
                while it is being vetted, or deleting an enterprise that still
                has DIRs in vetting).
              value:
                errors:
                  - code: '10015'
                    title: Bad Request
                    detail: Cannot update DIR in 'verified' status
                    meta:
                      url: https://developers.telnyx.com/docs/overview/errors/10015
            not_found:
              summary: 404 - resource does not exist or is not yours
              value:
                errors:
                  - code: '10009'
                    title: Resource not found
                    detail: Enterprise not found.
                    meta:
                      url: https://developers.telnyx.com/docs/overview/errors/10009
            conflict:
              summary: 409 - request conflicts with current resource state
              value:
                errors:
                  - code: '10021'
                    title: Resource in use
                    detail: >-
                      DIR has 1 active infringement claim(s). Resolve the claim
                      before making this change.
                    meta:
                      url: https://developers.telnyx.com/docs/overview/errors/10021
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http

````