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

# Get Recipient Schema

> Get the required JSON schema for building the recipient payload for a specific template

<Tip>
  Use this endpoint to understand the exact shape of the `templateParameters` required for your chosen template before attaching recipients.
</Tip>


## OpenAPI

````yaml GET /whatsapp/campaigns/recipient-payload
openapi: 3.1.1
info:
  title: OTPIQ SMS API
  description: >-
    Enterprise-grade SMS and messaging API for sending verification codes,
    custom messages, and managing sender IDs. Supports multiple providers
    including SMS, WhatsApp, and Telegram with intelligent fallback routing.


    ## Features


    * **Multi-Provider Support**: Send messages via SMS, WhatsApp, or Telegram

    * **Smart Fallback Routes**: Automatic provider switching for maximum
    delivery success

    * **Verification Codes**: Automated OTP delivery with customizable codes

    * **Custom Messages**: Send personalized messages with custom sender IDs

    * **Rate Limiting**: Built-in protection against abuse

    * **Spending Controls**: Configurable spending thresholds and credit
    management

    * **Real-time Tracking**: Monitor message delivery status

    * **Sender ID Management**: Register and manage custom sender IDs

    * **Webhook Notifications**: Real-time delivery status updates via webhooks


    ## Provider Options


    OTPIQ now offers 6 provider options including smart fallback routes:


    - **`whatsapp-sms`**: Try WhatsApp first, fallback to SMS

    - **`telegram-sms`**: Try Telegram first, fallback to SMS

    - **`whatsapp-telegram-sms`**: Try WhatsApp → Telegram → SMS (maximum
    delivery success)

    - **`sms`**: SMS only

    - **`whatsapp`**: WhatsApp only

    - **`telegram`**: Telegram only


    ## Authentication


    All API requests require authentication using your project API key. Include
    it in the Authorization header:


    ```

    Authorization: Bearer sk_live_your_api_key_here

    ```


    ## Webhooks


    OTPIQ provides real-time delivery status notifications via webhooks. See the
    Webhooks section for detailed documentation and examples.


    ## Support


    * **Documentation**: [https://docs.otpiq.com](https://docs.otpiq.com)

    * **Support Email**: info@otpiq.com
  version: 1.0.0
  contact:
    name: OTPIQ Support
    url: https://otpiq.com
    email: info@otpiq.com
  license:
    name: Commercial
    url: https://otpiq.com/terms
servers:
  - url: https://api.otpiq.com/api
    description: Production API
security:
  - bearerAuth: []
tags:
  - name: Authentication
    description: API key authentication and project information
  - name: SMS
    description: >-
      Send SMS messages, verification codes, and track delivery with multiple
      provider options and fallback routing
  - name: Sender IDs
    description: Manage custom sender IDs for your messages
  - name: Webhooks
    description: Real-time delivery status notifications via webhooks
  - name: Delivery Reports
    description: Generate and list CSV delivery reports for SMS/messages in a date range
  - name: Pricing
    description: Retrieve international SMS pricing information
  - name: WhatsApp
    description: >-
      List WhatsApp businesses, accounts, phone numbers, and message templates
      connected to a project
externalDocs:
  description: OTPIQ Documentation
  url: https://docs.otpiq.com
paths:
  /whatsapp/campaigns/recipient-payload:
    get:
      tags:
        - WhatsApp Campaigns
      summary: Get recipient JSON schema for a template
      description: >
        Returns `template`, `fields`, and `exampleRecipient` for building
        recipient JSON.

        Provide exactly one of `templateId` or campaign id (`_id` or
        `campaignId`, same MongoDB id).
      operationId: getWhatsAppCampaignRecipientPayload
      parameters:
        - name: templateId
          in: query
          required: false
          schema:
            type: string
            pattern: ^[a-fA-F0-9]{24}$
          description: MongoDB template id from GET /api/whatsapp/resources
        - name: _id
          in: query
          required: false
          schema:
            type: string
            pattern: ^[a-fA-F0-9]{24}$
          description: Campaign MongoDB id (uses the campaign's linked template)
        - name: campaignId
          in: query
          required: false
          schema:
            type: string
            pattern: ^[a-fA-F0-9]{24}$
          description: Alias for `_id` (campaign MongoDB id)
      responses:
        '200':
          description: Payload schema and examples
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecipientPayloadResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
components:
  schemas:
    RecipientPayloadResponse:
      allOf:
        - $ref: '#/components/schemas/SuccessResponse'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/RecipientPayloadData'
    SuccessResponse:
      type: object
      required:
        - success
        - data
      properties:
        success:
          type: boolean
          enum:
            - true
        data:
          type: object
          additionalProperties: true
    RecipientPayloadData:
      type: object
      required:
        - template
        - fields
        - exampleRecipient
      properties:
        template:
          $ref: '#/components/schemas/RecipientPayloadTemplate'
        fields:
          type: array
          items:
            $ref: '#/components/schemas/RecipientPayloadField'
        exampleRecipient:
          $ref: '#/components/schemas/CampaignRecipientInput'
    ApiErrorResponse:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          type: string
        unsupportedPhoneNumbers:
          type: array
          items:
            type: string
          description: Present when one or more recipient countries are unsupported
      additionalProperties: true
    MessageOnly:
      type: object
      properties:
        message:
          type: string
      additionalProperties: true
    RecipientPayloadTemplate:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        language:
          type: string
        category:
          type: string
          enum:
            - MARKETING
            - UTILITY
    RecipientPayloadField:
      type: object
      required:
        - key
        - label
        - required
        - example
        - templateParametersPath
      properties:
        key:
          type: string
          example: '1'
        label:
          type: string
          example: Body {{1}}
        required:
          type: boolean
        example:
          type: string
        templateParametersPath:
          type: string
          example: templateParameters.body.1
    CampaignRecipientInput:
      type: object
      required:
        - phoneNumber
      properties:
        phoneNumber:
          type: string
          minLength: 8
          maxLength: 20
          description: Digits only, international format (e.g. 9647712345678)
          example: '9647712345678'
        templateParameters:
          $ref: '#/components/schemas/TemplateParameters'
          description: Required when the template has variables; omit otherwise
    TemplateParameters:
      type: object
      properties:
        body:
          type: object
          additionalProperties:
            type: string
          description: Body variable values keyed by placeholder index (e.g. `"1"`, `"2"`)
        header:
          type: object
          additionalProperties:
            type: string
          description: >
            Header variable values keyed by placeholder index, or media URLs:

            `imageUrl`, `videoUrl`, `documentUrl` depending on template header
            format
        buttons:
          type: object
          additionalProperties:
            type: object
            additionalProperties:
              type: string
          description: Button URL variables keyed by button index, then variable index
      additionalProperties: false
  responses:
    BadRequestError:
      description: Validation or business rule error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          example:
            success: false
            error: Recipients cannot exceed 1000 per request
    UnauthorizedError:
      description: Missing, invalid, or unknown API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MessageOnly'
          example:
            message: Unauthorized, please use your project api key
    ForbiddenError:
      description: Forbidden (IP allowlist, dev key restrictions, etc.)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
    NotFoundError:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          example:
            success: false
            error: Campaign not found
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Project API key (`sk_live…` or `sk_dev…`). Send it as `Authorization:
        Bearer <api_key>`.

````