openapi: 3.0.1
info:
  title: Documo Account Fax API
  description: REST API for the Documo (mFax) cloud fax and document delivery platform. The API is organized around REST, accepts form-encoded and JSON request bodies, returns JSON-encoded responses, and is secured with an API key passed in the Authorization header. Send and receive faxes, manage fax numbers, subscribe to delivery events via webhooks, and read account information.
  termsOfService: https://www.documo.com/terms-of-service
  contact:
    name: Documo Support
    url: https://help.documo.com/
  version: '1.0'
servers:
- url: https://api.documo.com/v1
  description: Documo production API
security:
- apiKey: []
tags:
- name: Fax
  description: Send, resend, retrieve, list, and download faxes.
paths:
  /fax/send:
    post:
      operationId: sendFax
      tags:
      - Fax
      summary: Send a fax
      description: Sends a fax to one or more recipients. Documents may be supplied as file attachments (multipart/form-data) or as document URLs. Supports an optional cover page, scheduled send time, tags, and custom fields. The send endpoint exposes the same options available in the web portal.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/SendFaxRequest'
      responses:
        '200':
          description: Fax accepted for delivery.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Fax'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /fax/{messageId}:
    get:
      operationId: getFax
      tags:
      - Fax
      summary: Get a fax
      description: Retrieves the detail and current status of a single fax by its message id.
      parameters:
      - $ref: '#/components/parameters/MessageId'
      responses:
        '200':
          description: Fax detail.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Fax'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /fax/{messageId}/resend:
    post:
      operationId: resendFax
      tags:
      - Fax
      summary: Resend a fax
      description: Resends a fax that previously failed by submitting the message id of the original fax. An optional recipientFax may be supplied to change the destination number.
      parameters:
      - $ref: '#/components/parameters/MessageId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResendFaxRequest'
      responses:
        '200':
          description: Fax accepted for re-delivery.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Fax'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /fax/{messageId}/download:
    get:
      operationId: downloadFax
      tags:
      - Fax
      summary: Download a fax
      description: Downloads the document for a delivered or received fax by message id. The format query parameter selects the returned file type.
      parameters:
      - $ref: '#/components/parameters/MessageId'
      - name: format
        in: query
        description: File format to return.
        required: false
        schema:
          type: string
          enum:
          - pdf
          - tiff
          default: pdf
      responses:
        '200':
          description: Fax document.
          content:
            application/pdf:
              schema:
                type: string
                format: binary
            image/tiff:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /faxes:
    get:
      operationId: listFaxes
      tags:
      - Fax
      summary: List faxes (fax history)
      description: Returns a paginated list of faxes (inbound and outbound) in the account. This fax history endpoint is rate limited; exceeding the limit returns HTTP 429.
      parameters:
      - name: direction
        in: query
        description: Filter by fax direction.
        required: false
        schema:
          type: string
          enum:
          - inbound
          - outbound
      - name: status
        in: query
        description: Filter by fax status.
        required: false
        schema:
          type: string
      - name: dateFrom
        in: query
        description: Inclusive lower bound for the fax date (ISO 8601).
        required: false
        schema:
          type: string
          format: date-time
      - name: dateTo
        in: query
        description: Inclusive upper bound for the fax date (ISO 8601).
        required: false
        schema:
          type: string
          format: date-time
      - name: limit
        in: query
        description: Maximum number of records to return.
        required: false
        schema:
          type: integer
          default: 50
      - name: offset
        in: query
        description: Number of records to skip for pagination.
        required: false
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: A list of faxes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FaxList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    Fax:
      type: object
      properties:
        messageId:
          type: string
          description: Unique identifier of the fax message.
        deliveryId:
          type: string
          description: Identifier of the delivery attempt.
        status:
          type: string
          description: Current status of the fax (e.g. queued, sending, success, failed).
          example: success
        direction:
          type: string
          enum:
          - inbound
          - outbound
        recipientFax:
          type: string
        recipientName:
          type: string
        faxNumber:
          type: string
          description: Account number the fax was sent from or received on.
        faxCsid:
          type: string
          description: Called subscriber identification reported by the remote device.
        faxCallerId:
          type: string
        pagesCount:
          type: integer
          description: Total number of pages in the fax.
        pagesComplete:
          type: integer
          description: Number of pages successfully transmitted.
        duration:
          type: integer
          description: Transmission duration in seconds.
        watermark:
          type: string
        subject:
          type: string
        tags:
          type: array
          items:
            type: string
        createdDate:
          type: string
          format: date-time
        updatedDate:
          type: string
          format: date-time
    SendFaxRequest:
      type: object
      required:
      - recipientFax
      properties:
        recipientFax:
          type: string
          description: Destination fax number in E.164 or national format.
          example: '12345678900'
        recipientName:
          type: string
          description: Name of the recipient.
          example: John Snow
        faxNumber:
          type: string
          description: The account fax number to send from (caller id).
        subject:
          type: string
          description: Subject line used on the cover page.
        notes:
          type: string
          description: Notes or message body used on the cover page.
        coverPage:
          type: boolean
          description: Whether to include a cover page.
          default: false
        coverPageId:
          type: string
          description: Identifier of a saved cover page template to use.
        attachments:
          type: array
          description: One or more document files to fax.
          items:
            type: string
            format: binary
        attachmentUrls:
          type: array
          description: Publicly reachable document URLs to fax instead of file uploads.
          items:
            type: string
            format: uri
        scheduledDate:
          type: string
          format: date-time
          description: Future time at which to send the fax (ISO 8601).
        tags:
          type: array
          description: Tags to associate with the fax for reporting and search.
          items:
            type: string
    ResendFaxRequest:
      type: object
      properties:
        recipientFax:
          type: string
          description: Optional new destination fax number to resend to.
          example: '12345678900'
    FaxList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Fax'
        total:
          type: integer
        limit:
          type: integer
        offset:
          type: integer
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          description: Human-readable error message.
        code:
          type: string
          description: Machine-readable error code.
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Rate limit exceeded. Fax history and reports endpoints are limited to a fixed number of calls per minute; subsequent requests return 429 until the window resets.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request was malformed or missing required parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    MessageId:
      name: messageId
      in: path
      required: true
      description: Unique identifier of the fax message.
      schema:
        type: string
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'API key generated in the Documo web app under Settings > API. The key is sent in the Authorization header. Documo documents this as `Authorization: Basic <API_KEY>`, where the API key itself acts as the bearer credential. Each key carries an admin or user access level that determines which endpoints it may call.'