Sinch Projects API

openapi: 3.2.0
info:
  title: Sinch Fax Projects 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/
servers:
- url: https://fax.api.sinch.com
  description: Global Production Server
security:
- oAuth2: []
- basicAuth: []
tags:
- name: Projects
paths:
  /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:
      - Projects
      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:
      - Projects
      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:
      - Projects
      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:
      - Projects
      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:
      - Projects
      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:
      - Projects
      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
components:
  parameters:
    ProjectId:
      name: project_id
      in: path
      required: true
      description: The unique project identifier
      schema:
        type: string
    ServiceId:
      name: service_id
      in: path
      required: true
      description: The unique service identifier
      schema:
        type: string
  schemas:
    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
    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
    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
    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'
  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.
externalDocs:
  description: Sinch Fax API Documentation
  url: https://developers.sinch.com/docs/fax