openapi: 3.1.0
info:
  title: Sinch Brands Access Control Lists Faxes API
  description: The Sinch Brands API allows developers to create, update, and manage customer brand profiles used across Sinch messaging products. Brands represent the business identity associated with messaging campaigns and sender registrations. The API provides endpoints for creating brand records, updating brand details, listing brands, and deleting brands, enabling programmatic management of the brand entities required for compliant business messaging.
  version: '1.0'
  contact:
    name: Sinch Support
    url: https://www.sinch.com/contact-us/
  termsOfService: https://www.sinch.com/terms-of-service/
servers:
- url: https://brands.api.sinch.com
  description: Global Production Server
security:
- bearerAuth: []
tags:
- name: Faxes
  description: Send and manage faxes including sending to single or multiple recipients, listing sent and received faxes, and downloading fax content.
paths:
  /v3/projects/{project_id}/faxes:
    post:
      operationId: sendFax
      summary: Send a Fax
      description: Sends a fax to one or more recipients. The fax content can be provided as a URL to a document or as a file upload. Supports PDF and TIFF formats.
      tags:
      - Faxes
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendFaxRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/SendFaxMultipartRequest'
      responses:
        '200':
          description: Fax sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Fax'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
    get:
      operationId: listFaxes
      summary: List Faxes
      description: Returns a list of sent and received faxes with pagination and filtering support.
      tags:
      - Faxes
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - name: page
        in: query
        description: The page number to retrieve
        schema:
          type: integer
          default: 1
      - name: pageSize
        in: query
        description: The number of faxes per page
        schema:
          type: integer
          default: 20
          maximum: 100
      - name: direction
        in: query
        description: Filter by direction
        schema:
          type: string
          enum:
          - INBOUND
          - OUTBOUND
      - name: status
        in: query
        description: Filter by fax status
        schema:
          type: string
      - name: createTime.gte
        in: query
        description: Filter faxes created after this time
        schema:
          type: string
          format: date-time
      - name: createTime.lte
        in: query
        description: Filter faxes created before this time
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: List of faxes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FaxList'
        '401':
          description: Unauthorized
  /v3/projects/{project_id}/faxes/{fax_id}:
    get:
      operationId: getFax
      summary: Get a Fax
      description: Returns the details of a specific fax including its status, page count, and content URL.
      tags:
      - Faxes
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/FaxId'
      responses:
        '200':
          description: Fax details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Fax'
        '401':
          description: Unauthorized
        '404':
          description: Fax not found
    delete:
      operationId: deleteFaxContent
      summary: Delete Fax Content
      description: Deletes the content of a specific fax while retaining the metadata.
      tags:
      - Faxes
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/FaxId'
      responses:
        '200':
          description: Fax content deleted
        '401':
          description: Unauthorized
        '404':
          description: Fax not found
  /v3/projects/{project_id}/faxes/{fax_id}/file:
    get:
      operationId: downloadFaxContent
      summary: Download Fax Content
      description: Downloads the content of a received or sent fax as a PDF file.
      tags:
      - Faxes
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/FaxId'
      responses:
        '200':
          description: Fax file content
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '401':
          description: Unauthorized
        '404':
          description: Fax not found
components:
  schemas:
    Fax:
      type: object
      properties:
        id:
          type: string
          description: The unique fax identifier
        direction:
          type: string
          enum:
          - INBOUND
          - OUTBOUND
          description: The fax direction
        from:
          type: string
          description: The sender fax number
        to:
          type: string
          description: The recipient fax number
        status:
          type: string
          description: The fax status
        pageCount:
          type: integer
          description: The number of pages
        contentUrl:
          type: string
          format: uri
          description: URL to download the fax content
        createTime:
          type: string
          format: date-time
          description: When the fax was created
        completedTime:
          type: string
          format: date-time
          description: When the fax was completed
        projectId:
          type: string
          description: The project ID
        serviceId:
          type: string
          description: The service ID
        headerText:
          type: string
          description: The header text on the fax
    SendFaxRequest:
      type: object
      required:
      - to
      properties:
        to:
          type: string
          description: The recipient fax number in E.164 format
        from:
          type: string
          description: The sender fax number
        contentUrl:
          type: string
          format: uri
          description: URL to the document to fax
        serviceId:
          type: string
          description: The fax service to use
        headerText:
          type: string
          description: Header text to include on the fax
        headerPageNumbers:
          type: boolean
          description: Whether to include page numbers in the header
        imageConversionMethod:
          type: string
          enum:
          - HALFTONE
          - MONOCHROME
          description: Image conversion method for the fax
    SendFaxMultipartRequest:
      type: object
      required:
      - to
      - file
      properties:
        to:
          type: string
          description: The recipient fax number in E.164 format
        from:
          type: string
          description: The sender fax number
        file:
          type: string
          format: binary
          description: The document file to fax
        serviceId:
          type: string
          description: The fax service to use
    FaxList:
      type: object
      properties:
        faxes:
          type: array
          description: List of faxes
          items:
            $ref: '#/components/schemas/Fax'
        page:
          type: integer
          description: Current page number
        pageSize:
          type: integer
          description: Number of faxes per page
        totalItems:
          type: integer
          description: Total number of faxes
  parameters:
    ProjectId:
      name: project_id
      in: path
      required: true
      description: The unique project identifier
      schema:
        type: string
    FaxId:
      name: fax_id
      in: path
      required: true
      description: The unique fax identifier
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication.
externalDocs:
  description: Sinch Brands API Documentation
  url: https://developers.sinch.com/docs/brands