openapi: 3.1.0
info:
  title: Sinch Fax API
  description: >-
    The Sinch Fax API allows developers to send and receive faxes
    programmatically at scale. It supports sending faxes to single or multiple
    recipients, downloading received faxes, and managing fax numbers. The API
    is HIPAA, SOC 2 Type 1, and GDPR compliant, making it suitable for
    healthcare and other regulated industries that require secure document
    transmission. It integrates with the Sinch Numbers API for provisioning
    fax-capable phone numbers.
  version: '3.0'
  contact:
    name: Sinch Support
    url: https://www.sinch.com/contact-us/
  termsOfService: https://www.sinch.com/terms-of-service/
externalDocs:
  description: Sinch Fax API Documentation
  url: https://developers.sinch.com/docs/fax
servers:
  - url: https://fax.api.sinch.com
    description: Global Production Server
tags:
  - name: Fax to Email
    description: >-
      Configure fax-to-email forwarding for incoming faxes on a service.
  - name: Faxes
    description: >-
      Send and manage faxes including sending to single or multiple recipients,
      listing sent and received faxes, and downloading fax content.
security:
  - oAuth2: []
  - basicAuth: []
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
  /v3/projects/{project_id}/services:
    post:
      operationId: createService
      summary: Create a Fax Service
      description: >-
        Creates a new fax service with configuration for sending and receiving
        faxes, including webhook URLs for incoming fax notifications.
      tags: []
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateServiceRequest'
      responses:
        '200':
          description: Service created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
    get:
      operationId: listServices
      summary: List Fax Services
      description: >-
        Returns a list of all fax services in the project.
      tags: []
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: List of services
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceList'
        '401':
          description: Unauthorized
  /v3/projects/{project_id}/services/{service_id}:
    get:
      operationId: getService
      summary: Get a Fax Service
      description: >-
        Returns the details of a specific fax service.
      tags: []
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/ServiceId'
      responses:
        '200':
          description: Service details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '401':
          description: Unauthorized
        '404':
          description: Service not found
    patch:
      operationId: updateService
      summary: Update a Fax Service
      description: >-
        Updates the configuration of a specific fax service.
      tags: []
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/ServiceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateServiceRequest'
      responses:
        '200':
          description: Service updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '401':
          description: Unauthorized
        '404':
          description: Service not found
    delete:
      operationId: deleteService
      summary: Delete a Fax Service
      description: >-
        Deletes a specific fax service.
      tags: []
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/ServiceId'
      responses:
        '200':
          description: Service deleted
        '401':
          description: Unauthorized
        '404':
          description: Service not found
  /v3/projects/{project_id}/services/{service_id}/numbers:
    get:
      operationId: listServiceNumbers
      summary: List Numbers for a Service
      description: >-
        Returns the list of phone numbers assigned to a fax service.
      tags: []
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/ServiceId'
      responses:
        '200':
          description: List of service numbers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceNumberList'
        '401':
          description: Unauthorized
        '404':
          description: Service not found
  /v3/projects/{project_id}/services/{service_id}/emails:
    post:
      operationId: createFaxToEmail
      summary: Create a Fax-to-email Configuration
      description: >-
        Configures an email address to receive incoming faxes for a specific
        fax service.
      tags:
        - Fax to Email
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/ServiceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FaxToEmailRequest'
      responses:
        '200':
          description: Fax-to-email configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FaxToEmail'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
    get:
      operationId: listFaxToEmails
      summary: List Fax-to-email Configurations
      description: >-
        Returns the list of email addresses configured for fax-to-email on
        a service.
      tags:
        - Fax to Email
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/ServiceId'
      responses:
        '200':
          description: List of fax-to-email configurations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FaxToEmailList'
        '401':
          description: Unauthorized
  /v3/projects/{project_id}/services/{service_id}/emails/{email}:
    delete:
      operationId: deleteFaxToEmail
      summary: Delete a Fax-to-email Configuration
      description: >-
        Removes an email address from the fax-to-email configuration.
      tags:
        - Fax to Email
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/ServiceId'
        - name: email
          in: path
          required: true
          description: The email address to remove
          schema:
            type: string
            format: email
      responses:
        '200':
          description: Fax-to-email configuration removed
        '401':
          description: Unauthorized
        '404':
          description: Configuration not found
components:
  securitySchemes:
    oAuth2:
      type: oauth2
      description: >-
        OAuth 2.0 client credentials flow.
      flows:
        clientCredentials:
          tokenUrl: https://auth.sinch.com/oauth2/token
          scopes: {}
    basicAuth:
      type: http
      scheme: basic
      description: >-
        Application key and secret for basic authentication.
  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
    ServiceId:
      name: service_id
      in: path
      required: true
      description: The unique service identifier
      schema:
        type: string
  schemas:
    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
    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
    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
    Service:
      type: object
      properties:
        id:
          type: string
          description: The unique service identifier
        name:
          type: string
          description: The service name
        projectId:
          type: string
          description: The project ID
        incomingWebhookUrl:
          type: string
          format: uri
          description: Webhook URL for incoming fax notifications
        webhookContentType:
          type: string
          description: Content type for webhook payloads
        defaultForProject:
          type: boolean
          description: Whether this is the default service
        numberOfPhoneNumbers:
          type: integer
          description: Number of phone numbers assigned
        createTime:
          type: string
          format: date-time
          description: When the service was created
        imageConversionMethod:
          type: string
          description: Default image conversion method
        saveOutboundFaxDocuments:
          type: boolean
          description: Whether to save outbound fax documents
        saveInboundFaxDocuments:
          type: boolean
          description: Whether to save inbound fax documents
    ServiceList:
      type: object
      properties:
        services:
          type: array
          description: List of services
          items:
            $ref: '#/components/schemas/Service'
    CreateServiceRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: The service name
        incomingWebhookUrl:
          type: string
          format: uri
          description: Webhook URL for incoming faxes
        defaultForProject:
          type: boolean
          description: Whether this is the default service
        imageConversionMethod:
          type: string
          enum:
            - HALFTONE
            - MONOCHROME
          description: Image conversion method
        saveOutboundFaxDocuments:
          type: boolean
          description: Save outbound documents
        saveInboundFaxDocuments:
          type: boolean
          description: Save inbound documents
    UpdateServiceRequest:
      type: object
      properties:
        name:
          type: string
          description: Updated service name
        incomingWebhookUrl:
          type: string
          format: uri
          description: Updated webhook URL
        imageConversionMethod:
          type: string
          description: Updated conversion method
    ServiceNumberList:
      type: object
      properties:
        phoneNumbers:
          type: array
          description: List of phone numbers
          items:
            type: object
            properties:
              phoneNumber:
                type: string
                description: The phone number in E.164 format
              serviceId:
                type: string
                description: The service ID
              projectId:
                type: string
                description: The project ID
    FaxToEmailRequest:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          format: email
          description: The email address for fax-to-email
        phoneNumber:
          type: string
          description: Specific phone number to associate
    FaxToEmail:
      type: object
      properties:
        email:
          type: string
          format: email
          description: The configured email address
        phoneNumber:
          type: string
          description: The associated phone number
        serviceId:
          type: string
          description: The service ID
        projectId:
          type: string
          description: The project ID
    FaxToEmailList:
      type: object
      properties:
        emails:
          type: array
          description: List of fax-to-email configurations
          items:
            $ref: '#/components/schemas/FaxToEmail'