openapi: 3.0.1
info:
  title: Documo 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.
  - name: Numbers
    description: Search, provision, list, and release inbound fax numbers.
  - name: Webhooks
    description: Manage webhook subscriptions for fax and number events.
  - name: Account
    description: Read account profile and settings.
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'
  /numbers:
    get:
      operationId: listNumbers
      tags:
        - Numbers
      summary: List provisioned numbers
      description: Lists the inbound fax numbers provisioned on the account.
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 50
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: A list of provisioned numbers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumberList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: provisionNumber
      tags:
        - Numbers
      summary: Provision a number
      description: Provisions (adds) an available inbound fax number to the account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProvisionNumberRequest'
      responses:
        '200':
          description: The provisioned number.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FaxNumber'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /numbers/search:
    get:
      operationId: searchNumbers
      tags:
        - Numbers
      summary: Search available numbers
      description: >-
        Searches for available inbound fax numbers that can be provisioned,
        optionally filtered by area code, region, or country.
      parameters:
        - name: areaCode
          in: query
          description: Area code to search within.
          required: false
          schema:
            type: string
        - name: region
          in: query
          description: State or region code.
          required: false
          schema:
            type: string
        - name: country
          in: query
          description: ISO country code.
          required: false
          schema:
            type: string
            default: US
      responses:
        '200':
          description: Available numbers matching the search.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumberList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /numbers/{numberId}:
    delete:
      operationId: releaseNumber
      tags:
        - Numbers
      summary: Release a number
      description: Releases (removes) a provisioned inbound fax number from the account.
      parameters:
        - name: numberId
          in: path
          required: true
          description: Identifier of the provisioned number.
          schema:
            type: string
      responses:
        '200':
          description: Number released.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /webhooks:
    get:
      operationId: listWebhooks
      tags:
        - Webhooks
      summary: List webhooks
      description: Lists webhook subscriptions configured on the account.
      responses:
        '200':
          description: A list of webhooks.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createWebhook
      tags:
        - Webhooks
      summary: Create a webhook
      description: >-
        Creates a webhook subscription that posts event payloads to a target
        URL. Webhooks can be set at the account level or scoped to a specific
        number.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookRequest'
      responses:
        '200':
          description: The created webhook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /webhooks/{webhookId}:
    delete:
      operationId: deleteWebhook
      tags:
        - Webhooks
      summary: Delete a webhook
      description: Deletes a webhook subscription by id.
      parameters:
        - name: webhookId
          in: path
          required: true
          description: Identifier of the webhook subscription.
          schema:
            type: string
      responses:
        '200':
          description: Webhook deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /account:
    get:
      operationId: getAccount
      tags:
        - Account
      summary: Get account
      description: Retrieves the authenticated account's profile and settings.
      responses:
        '200':
          description: Account detail.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  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.
  parameters:
    MessageId:
      name: messageId
      in: path
      required: true
      description: Unique identifier of the fax message.
      schema:
        type: string
  responses:
    BadRequest:
      description: The request was malformed or missing required parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      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'
  schemas:
    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'
    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
    FaxList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Fax'
        total:
          type: integer
        limit:
          type: integer
        offset:
          type: integer
    ProvisionNumberRequest:
      type: object
      required:
        - faxNumber
      properties:
        faxNumber:
          type: string
          description: The available number to provision, in E.164 format.
          example: '+12025550143'
        label:
          type: string
          description: Friendly label for the number.
    FaxNumber:
      type: object
      properties:
        numberId:
          type: string
        faxNumber:
          type: string
        label:
          type: string
        region:
          type: string
        country:
          type: string
        status:
          type: string
        createdDate:
          type: string
          format: date-time
    NumberList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/FaxNumber'
        total:
          type: integer
    CreateWebhookRequest:
      type: object
      required:
        - url
        - events
      properties:
        url:
          type: string
          format: uri
          description: HTTPS endpoint that receives event payloads.
          example: https://example.com/webhooks/documo
        events:
          type: array
          description: Event types to subscribe to.
          items:
            type: string
            enum:
              - fax.v1.inbound.succeed
              - fax.v1.inbound.failed
              - fax.v1.outbound.succeed
              - fax.v1.outbound.failed
              - fax.v1.number.add
              - fax.v1.number.release
        faxNumber:
          type: string
          description: >-
            Optional number to scope the webhook to; when omitted the webhook
            applies at the account level.
    Webhook:
      type: object
      properties:
        webhookId:
          type: string
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            type: string
        faxNumber:
          type: string
        createdDate:
          type: string
          format: date-time
    WebhookList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Webhook'
        total:
          type: integer
    WebhookEvent:
      type: object
      description: Payload posted to a subscribed webhook URL when an event occurs.
      properties:
        event:
          type: string
          description: The event type that fired.
          example: fax.v1.outbound.succeed
        messageId:
          type: string
        data:
          $ref: '#/components/schemas/Fax'
    Account:
      type: object
      properties:
        accountId:
          type: string
        name:
          type: string
        email:
          type: string
          format: email
        accessLevel:
          type: string
          enum:
            - admin
            - user
        plan:
          type: string
        createdDate:
          type: string
          format: date-time
    DeleteResult:
      type: object
      properties:
        success:
          type: boolean
        id:
          type: string
    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.