openapi: 3.1.0
info:
  title: Sinch Brands Access Control Lists Projects 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: 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:
    ServiceId:
      name: service_id
      in: path
      required: true
      description: The unique service identifier
      schema:
        type: string
    ProjectId:
      name: project_id
      in: path
      required: true
      description: The unique project identifier
      schema:
        type: string
  schemas:
    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'
    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
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication.
externalDocs:
  description: Sinch Brands API Documentation
  url: https://developers.sinch.com/docs/brands