Sinch Brands API

openapi: 3.2.0
info:
  title: Sinch Brands 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: Brands
  description: Create, update, list, and delete customer brand profiles used for messaging campaigns and sender registrations.
paths:
  /v1/projects/{project_id}/brands:
    get:
      operationId: listBrands
      summary: List Brands
      description: Returns a list of all brand profiles in the project with pagination support.
      tags:
      - Brands
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - name: pageSize
        in: query
        description: Number of results per page
        schema:
          type: integer
          default: 20
      - name: pageToken
        in: query
        description: Pagination token
        schema:
          type: string
      responses:
        '200':
          description: List of brands
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandList'
        '401':
          description: Unauthorized
    post:
      operationId: createBrand
      summary: Create a Brand
      description: Creates a new brand profile with business identity information including name, address, industry, and contact details.
      tags:
      - Brands
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBrandRequest'
      responses:
        '200':
          description: Brand created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Brand'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
  /v1/projects/{project_id}/brands:submit:
    post:
      operationId: createAndSubmitBrand
      summary: Create and Submit a Brand
      description: Creates a new brand profile and immediately submits it for verification in a single operation.
      tags:
      - Brands
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBrandRequest'
      responses:
        '200':
          description: Brand created and submitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Brand'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
  /v1/projects/{project_id}/brands/{brand_id}:
    get:
      operationId: getBrand
      summary: Get a Brand
      description: Returns the details of a specific brand profile including its verification status.
      tags:
      - Brands
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/BrandId'
      responses:
        '200':
          description: Brand details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Brand'
        '401':
          description: Unauthorized
        '404':
          description: Brand not found
    put:
      operationId: updateBrand
      summary: Update a Brand
      description: Updates the details of an existing brand profile.
      tags:
      - Brands
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/BrandId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBrandRequest'
      responses:
        '200':
          description: Brand updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Brand'
        '401':
          description: Unauthorized
        '404':
          description: Brand not found
    delete:
      operationId: deleteBrand
      summary: Delete a Brand
      description: Deletes a specific brand profile from the project.
      tags:
      - Brands
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/BrandId'
      responses:
        '200':
          description: Brand deleted
        '401':
          description: Unauthorized
        '404':
          description: Brand not found
  /v1/projects/{project_id}/brands/{brand_id}:submit:
    post:
      operationId: submitBrand
      summary: Submit a Brand for Verification
      description: Submits an existing brand profile for verification. Once submitted, the brand enters the review process.
      tags:
      - Brands
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/BrandId'
      responses:
        '200':
          description: Brand submitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Brand'
        '401':
          description: Unauthorized
        '404':
          description: Brand not found
components:
  parameters:
    ProjectId:
      name: project_id
      in: path
      required: true
      description: The unique project identifier
      schema:
        type: string
    BrandId:
      name: brand_id
      in: path
      required: true
      description: The unique brand identifier
      schema:
        type: string
  schemas:
    BrandList:
      type: object
      properties:
        brands:
          type: array
          description: List of brands
          items:
            $ref: '#/components/schemas/Brand'
        nextPageToken:
          type: string
          description: Pagination token
        totalSize:
          type: integer
          description: Total number of brands
    UpdateBrandRequest:
      type: object
      properties:
        displayName:
          type: string
          description: Updated display name
        companyName:
          type: string
          description: Updated company name
        entityType:
          type: string
          description: Updated entity type
        ein:
          type: string
          description: Updated EIN
        country:
          type: string
          description: Updated country
        street:
          type: string
          description: Updated street
        city:
          type: string
          description: Updated city
        state:
          type: string
          description: Updated state
        postalCode:
          type: string
          description: Updated postal code
        website:
          type: string
          format: uri
          description: Updated website
        verticalType:
          type: string
          description: Updated vertical
        contactEmail:
          type: string
          format: email
          description: Updated contact email
        contactPhone:
          type: string
          description: Updated contact phone
    CreateBrandRequest:
      type: object
      required:
      - displayName
      - companyName
      - country
      properties:
        displayName:
          type: string
          description: The brand display name
        companyName:
          type: string
          description: The legal company name
        entityType:
          type: string
          description: Business entity type
        ein:
          type: string
          description: Employer Identification Number
        country:
          type: string
          description: Country of incorporation
        street:
          type: string
          description: Street address
        city:
          type: string
          description: City
        state:
          type: string
          description: State or province
        postalCode:
          type: string
          description: Postal code
        website:
          type: string
          format: uri
          description: Brand website
        verticalType:
          type: string
          description: Business vertical
        contactEmail:
          type: string
          format: email
          description: Contact email
        contactPhone:
          type: string
          description: Contact phone
    Brand:
      type: object
      properties:
        id:
          type: string
          description: The unique brand identifier
        projectId:
          type: string
          description: The project ID
        displayName:
          type: string
          description: The brand display name
        companyName:
          type: string
          description: The legal company name
        entityType:
          type: string
          description: The business entity type
        ein:
          type: string
          description: Employer Identification Number
        country:
          type: string
          description: The country of incorporation
        street:
          type: string
          description: Street address
        city:
          type: string
          description: City
        state:
          type: string
          description: State or province
        postalCode:
          type: string
          description: Postal or ZIP code
        website:
          type: string
          format: uri
          description: Brand website URL
        verticalType:
          type: string
          description: The business vertical or industry
        contactEmail:
          type: string
          format: email
          description: Contact email address
        contactPhone:
          type: string
          description: Contact phone number
        status:
          type: string
          enum:
          - DRAFT
          - SUBMITTED
          - VERIFIED
          - UNVERIFIED
          - REJECTED
          description: The current brand verification status
        identityStatus:
          type: string
          description: The identity verification status
        createTime:
          type: string
          format: date-time
          description: When the brand was created
        updateTime:
          type: string
          format: date-time
          description: When the brand was last updated
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication.
externalDocs:
  description: Sinch Brands API Documentation
  url: https://developers.sinch.com/docs/brands