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

# Generate Delivery Report

> Create CSV delivery reports for SMS/messages in a date range

<Info>
  Use the `downloadUrl` from the response to download the CSV file directly. There is no separate download endpoint—reports are available for **30 days** after generation.
</Info>

## CSV content

The downloaded CSV includes these columns:

| Column          | Description                                         |
| --------------- | --------------------------------------------------- |
| Message ID      | Internal message identifier (`smsId`)               |
| Phone Number    | Recipient phone number                              |
| Sender ID       | Sender ID name (or "System")                        |
| Cost (IQD)      | Cost in IQD                                         |
| Message Type    | OTP, Custom, WhatsApp Template, or Other            |
| Delivery Status | `pending`, `sent`, `delivered`, `read`, or `failed` |
| Error Reason    | Last error in the message flow (empty if none)      |
| Refunded        | Yes/No                                              |
| Created At      | ISO 8601                                            |
| Sent At         | ISO 8601 (if sent)                                  |


## OpenAPI

````yaml POST /reports/generate
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:
  /reports/generate:
    post:
      tags:
        - Delivery Reports
      summary: Generate delivery report
      description: >-
        Creates a new delivery report for the authenticated project for the
        given date range. The report is generated as a CSV, uploaded to storage,
        and the response includes a **download URL** to fetch the file. No
        separate download endpoint is used.
      operationId: generateDeliveryReport
      requestBody:
        description: Report generation parameters. startDate and endDate are required.
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - startDate
                - endDate
              properties:
                startDate:
                  type: string
                  format: date-time
                  description: >-
                    Start of the date range (ISO 8601, e.g.
                    2026-01-01T00:00:00.000Z)
                  examples:
                    - '2026-01-01T00:00:00.000Z'
                endDate:
                  type: string
                  format: date-time
                  description: >-
                    End of the date range (ISO 8601). Must be on or after
                    startDate.
                  examples:
                    - '2026-01-31T23:59:59.999Z'
                phoneNumbers:
                  type: array
                  items:
                    type: string
                    pattern: ^\+?[0-9]+$
                  description: >-
                    If provided, only messages to these phone numbers are
                    included
                  examples:
                    - - '+9647701234567'
                statuses:
                  type: array
                  items:
                    type: string
                    enum:
                      - pending
                      - sent
                      - delivered
                      - read
                      - failed
                  description: >-
                    If provided, only messages with these delivery statuses are
                    included
                  examples:
                    - - sent
                      - failed
            examples:
              basic:
                summary: Date range only
                value:
                  startDate: '2026-01-01T00:00:00.000Z'
                  endDate: '2026-01-31T23:59:59.999Z'
              filtered:
                summary: With filters
                value:
                  startDate: '2026-01-01T00:00:00.000Z'
                  endDate: '2026-01-31T23:59:59.999Z'
                  phoneNumbers:
                    - '+9647701234567'
                  statuses:
                    - sent
                    - failed
      responses:
        '201':
          description: >-
            Delivery report generated successfully. Use downloadUrl to fetch the
            CSV file.
          content:
            application/json:
              schema:
                type: object
                required:
                  - _id
                  - reportId
                  - downloadUrl
                  - recordCount
                  - dateRange
                  - expiresAt
                  - status
                  - message
                properties:
                  _id:
                    type: string
                    description: MongoDB ObjectId of the report
                    examples:
                      - 65a1b2c3d4e5f6789012345
                  reportId:
                    type: string
                    description: Same as _id; convenience for API consumers
                  project:
                    type: string
                    description: Project ObjectId
                  filename:
                    type: string
                    description: Storage filename
                  fileId:
                    type: string
                    description: Storage provider file identifier
                  downloadUrl:
                    type: string
                    format: uri
                    description: >-
                      Use this URL to download the CSV. No separate download
                      endpoint.
                  recordCount:
                    type: integer
                    description: Number of message rows in the report
                  dateRange:
                    type: object
                    properties:
                      startDate:
                        type: string
                        format: date-time
                      endDate:
                        type: string
                        format: date-time
                  filters:
                    type: object
                    properties:
                      startDate:
                        type: string
                      endDate:
                        type: string
                      phoneNumbers:
                        type: array
                      statuses:
                        type: array
                  expiresAt:
                    type: string
                    format: date-time
                    description: Reports valid for 30 days
                  status:
                    type: string
                    enum:
                      - available
                      - expired
                      - deleted
                  createdAt:
                    type: string
                    format: date-time
                  updatedAt:
                    type: string
                    format: date-time
                  message:
                    type: string
                    description: Success message
                    examples:
                      - Delivery report generated successfully
              examples:
                success:
                  summary: Successful response
                  value:
                    _id: 65a1b2c3d4e5f6789012345
                    reportId: 65a1b2c3d4e5f6789012345
                    filename: >-
                      delivery-report-myproject-2026-02-12T12-00-00-000Z-a1b2c3d4.csv
                    fileId: 4_z1234567890_f1020304050607080
                    downloadUrl: https://cdn.example.com/files/delivery-report-....csv
                    recordCount: 150
                    dateRange:
                      startDate: '2026-01-01T00:00:00.000Z'
                      endDate: '2026-01-31T23:59:59.999Z'
                    filters:
                      startDate: '2026-01-01T00:00:00.000Z'
                      endDate: '2026-01-31T23:59:59.999Z'
                      phoneNumbers:
                        - '+9647701234567'
                      statuses:
                        - sent
                        - failed
                    expiresAt: '2026-03-14T12:00:00.000Z'
                    status: available
                    createdAt: '2026-02-12T12:00:00.000Z'
                    updatedAt: '2026-02-12T12:00:00.000Z'
                    message: Delivery report generated successfully
        '400':
          description: Validation failed (invalid dates, status values, etc.)
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: string
              examples:
                date_range:
                  summary: Invalid date range
                  value:
                    error: Start date cannot be after end date
                invalid_status:
                  summary: Invalid status value
                  value:
                    error: 'Invalid status: invalid_status'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Project not found or no messages in date range
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: string
              examples:
                project:
                  summary: Project not found
                  value:
                    error: Project not found
                no_data:
                  summary: No messages in range
                  value:
                    error: No data found for the specified date range
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - bearerAuth: []
components:
  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            required:
              - message
            properties:
              message:
                type: string
                description: Unauthorized error message
                examples:
                  - Unauthorized, please use your project api key
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            type: object
            required:
              - message
            properties:
              message:
                type: string
                description: Internal server error message
                examples:
                  - Internal server error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Project API key (`sk_live…` or `sk_dev…`). Send it as `Authorization:
        Bearer <api_key>`.

````