Sinch Brand Webhooks Delivery API

openapi: 3.2.0
info:
  x-sinch-standards-version: standards-2026-03-31
  description: 'This API describes the set of endpoints available to create customer brands.


    The list of endpoints allows to create, update and delete a customer brand and also get the current state.'
  title: Sinch Compliance API - Brands Brand Webhooks Delivery API
  version: 1.0.0
  contact:
    name: Support
    url: https://www.sinch.com
    email: Support@sinch.com
  license:
    name: MIT
    url: https://www.sinch.com/toc
servers:
- description: Production server. Data processed and stored within Europe.
  url: https://compliance.api.sinch.com
tags:
- description: Brand Webhook events.
  name: brand-webhooks-delivery
  x-displayName: Brand Webhooks
paths: {}
webhooks:
  BrandOrderStatusUpdated:
    post:
      x-sinch-stability: preview
      tags:
      - brand-webhooks-delivery
      summary: Callback for brand order status update
      description: The endpoint receives a callback when the brand order status is updated. To receive callback notifications, the customer must provide a callback URL in the create Order (/us/brands/{brandId}/orders) request body or when importing (/us/brands/import) a brand. The callback URL must be a valid URL and must be reachable from Sinch. Read brands callback configuration documentation for more details.
      operationId: brandOrderStatusCallback
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CallbackBrandOrderStatusUpdatedBody'
      responses:
        '200':
          description: OK
      security:
      - hmacAuth: []
components:
  schemas:
    BrandOrderEventData:
      description: Business payload carried in the `data` property of a brand order CloudEvent. Contains the brand order status update details that triggered the event.
      type: object
      properties:
        projectId:
          description: The ID of the project to which the event belongs.
          examples:
          - aad4ccbf-919d-462f-8587-dec95a1b11b0
          type: string
          readOnly: true
        resourceId:
          description: Corresponds to the order id the event belongs to.
          examples:
          - aad4ccbf-919d-462f-8587-dec953242342
          type: string
          readOnly: true
        resourceType:
          description: The brand order type.
          $ref: '#/components/schemas/BrandOrderMetadata'
        status:
          description: Status of the brand order after the update that triggered the event. This field is useful to quickly check the status of the order without having to call the Get Brand Order endpoint.
          $ref: '#/components/schemas/BrandOrderStatus'
        comments:
          description: Comments related to the brand order status update. For instance, an incomplete brand order status update can include the reason why the brand order is incomplete, or the fields that must be updated.
          examples:
          - Brand Order is incomplete. Please update the address field.
          type: string
          readOnly: true
    CallbackBrandOrderStatusUpdatedBody:
      description: 'CloudEvents v1.0 payload delivered by Sinch when a brand order status changes. The envelope follows the CloudEvents structured content mode with `Content-Type: application/json`.


        The `type` field uses the reverse-DNS prefix `com.sinch.registrations.brand.order.v1` and the event version is the last component. The `data` property carries the brand-order-specific payload.'
      type: object
      allOf:
      - $ref: '#/components/schemas/CloudEventBase'
      - type: object
        properties:
          data:
            description: Brand order event payload. Contains the details of the brand order status update that triggered the event.
            allOf:
            - $ref: '#/components/schemas/BrandOrderEventData'
    CloudEventBase:
      description: Base fields required by the CloudEvents spec v1.0 (https://cloudevents.io). All Sinch webhook payloads conform to this structure.
      type: object
      required:
      - specversion
      - id
      - source
      - type
      - time
      properties:
        specversion:
          description: The version of the CloudEvents specification which the event uses. Always "1.0".
          type: string
          enum:
          - '1.0'
          x-enumDescriptions:
            '1.0': CloudEvents specification version 1.0.
          examples:
          - '1.0'
          readOnly: true
        id:
          description: Unique identifier for the event within the scope of the source. Clients MUST treat events with the same source+id as duplicates.
          type: string
          examples:
          - ee34ccbf-919d-462f-8587-dec95a1b11ee
          readOnly: true
        source:
          description: URI-reference identifying the context in which the event occurred. Combined with id, this MUST be globally unique per event.
          type: string
          format: uri
          examples:
          - https://compliance.api.sinch.com/v1/projects/us/brand/212421442412/orders/dec95a1b11b0
          readOnly: true
        type:
          description: Reverse-DNS-prefixed event type string. The last component identifies the event version (e.g. com.sinch.registrations.brand.order.v1.BrandOrderStatusUpdate).
          type: string
          examples:
          - com.sinch.registrations.brand.order.v1.BrandOrderStatusUpdate
          readOnly: true
        time:
          description: Timestamp of when the event was produced, in RFC-3339 format with timezone.
          type: string
          format: date-time
          examples:
          - '2023-10-01T12:00:00Z'
          readOnly: true
    BrandOrderStatus:
      description: Brand order status represents the current state of the brand order in the system. When a brand order is created, it is in NEW status. After that, it can be moved to PENDING status when the validation process starts, then it can be moved to REJECTED or INCOMPLETE if the validation process fails, or to COMPLETED if the validation process is successful. When a brand order is in INCOMPLETE status, customer can update the brand/brand order. Updating the brand order moves the brand order to PENDING_REVIEW state, what means that is waiting for another review after the customer changes. Finally, a brand order can be moved to ARCHIVED status after a cancellation.
      enum:
      - NEW
      - PENDING
      - PENDING_REVIEW
      - REJECTED
      - INCOMPLETE
      - COMPLETED
      - ARCHIVED
      x-enumDescriptions:
        NEW: A new brand order created, not processed yet.
        PENDING: The brand order info is under review.
        PENDING_REVIEW: When a brand order is in incomplete status, customer can update the brand/brand order. Updating the brand order moves the brand order to PENDING_REVIEW state, what means that is waiting for another review after the customer changes.
        REJECTED: The brand order has been rejected.
        INCOMPLETE: The brand order is incomplete. The customer can update the brand/brand order to complete it.
        COMPLETED: The brand order validation has been completed and the brand order is approved for integration against the channel specification.
        ARCHIVED: The brand order is archived after a cancellation. It can not be updated or submitted for validation.
      type: string
      examples:
      - INCOMPLETE
    BrandOrderMetadata:
      description: 'These are the different processes the customers can request to add different channels to the Brand.


        **Note:** US_SC_REGISTRY is only used to retrieve existing brand orders. It cannot be used for new ones.'
      enum:
      - US_SC_REGISTRY
      - US_SC_GCH
      - US_SC_GCH_CONTENT_PROVIDER
      - US_10DLC_TCR_PRIVATE_BRAND_REGISTRATION
      - US_10DLC_TCR_PUBLIC_BRAND_REGISTRATION
      - US_10DLC_TCR_PRIVATE_BRAND_UPDATE
      - US_10DLC_TCR_PUBLIC_BRAND_UPDATE
      - US_10DLC_TCR_PRIVATE_MOCK
      - US_10DLC_TCR_PUBLIC_MOCK
      - US_10DLC_TCR_SOLE_PROPRIETOR
      - US_10DLC_TCR_PRIVATE_STANDARD_BRAND_REGISTRATION
      - US_10DLC_TCR_PRIVATE_ENHANCED_BRAND_REGISTRATION
      - US_10DLC_TCR_PUBLIC_STANDARD_BRAND_REGISTRATION
      - US_10DLC_TCR_PUBLIC_ENHANCED_BRAND_REGISTRATION
      - US_RCS_TCR_PRIVATE_BRAND_REGISTRATION
      - US_RCS_TCR_PUBLIC_BRAND_REGISTRATION
      - US_RCS_TCR_UPDATE_ASSETS
      x-enumDescriptions:
        US_SC_REGISTRY: For US Short Code brand verification. This is a legacy manual process that is now disabled and read-only. New registrations are not possible through this process. For new Short Code registrations, please use US_SC_GCH.
        US_SC_GCH: 'Unified US Short Code verification process via the US Short Code Registry. The specific process to be applied is automatically determined by the brand''s programType field: Standard → standard process, Government → government process, Charitable Organization → charity process, Political → political process. This process is free of charge and, upon successful completion, the SHORT_CODE channel will be granted to the brand.'
        US_SC_GCH_CONTENT_PROVIDER: US Short Code verification process for Content Provider entities. This process internally uses the US Short Code Registry and is free of charge. Upon successful completion, the SHORT_CODE channel will be granted to the content provider.
        US_10DLC_TCR_SOLE_PROPRIETOR: To register as a Sole Proprietor for 10-Digit Long Code (10DLC) messaging via 10DLC, you can complete the registration process without needing an Employer Identification Number (EIN). Upon initiating the registration, a One-Time Password (OTP) will be automatically sent to the provided mobile number for identity verification, which you must subsequently submit using the endpoint /v1/projects/{projectId}/us/brands/{brandId}/orders/{orderId}/verifyOtp to successfully authorize and finalize the process.
        US_10DLC_TCR_PRIVATE_BRAND_REGISTRATION: 'Simple brand registration with 10DLC for private companies to obtain the 10DLC channel in the US. This process does not include vetting. You will receive a TCR ID upon completion (approx. 1 minute). Provides lower throughput and a maximum of 3 numbers. Once completed, this process can be re-requested if any data needs to be modified (there are some fields not allowed for edition: legalCompanyName, entityType, federalTaxId and taxCountry). This process can be initiated again for revetting the brand, in case that critical information needs to be updated: entityType, legalCompanyName, federalTaxId or taxCountry. In this case, the brand will go through the same process as a new registration, with the same time of completion, but keeping the same TCR ID and the history of previous registrations.'
        US_10DLC_TCR_PUBLIC_BRAND_REGISTRATION: 'Simple brand registration with 10DLC for public companies to obtain the 10DLC channel in the US. This process does not include vetting. You will receive a TCR ID upon completion (approx. 1 minutes). Provides lower throughput and a maximum of 3 numbers. Once completed, this process can be re-requested if any data needs to be modified (there are some fields not allowed for edition: legalCompanyName, entityType, federalTaxId and taxCountry). This process can be initiated again for revetting the brand, in case that critical information needs to be updated: entityType, legalCompanyName, federalTaxId or taxCountry. In this case, the brand will go through the same process as a new registration, with the same time of completion, but keeping the same TCR ID and the history of previous registrations.'
        US_10DLC_TCR_PRIVATE_BRAND_UPDATE: 'Brand data update process with 10DLC for private companies that already have the 10DLC channel. This process is used to update any brand data that needs to be modified after a successful registration, except for critical information such as entityType, legalCompanyName, federalTaxId or taxCountry. Cost: free. You will receive a confirmation of the update upon completion (approx. 1 minute). This process does not affect the TCR ID, the throughput or the number of phone numbers allowed. Update process cannot be used after standard or enhanced vetting, as the brand needs to be revetted in case of any critical information update.'
        US_10DLC_TCR_PUBLIC_BRAND_UPDATE: 'Brand data update process with 10DLC for public companies that already have the 10DLC channel. This process is used to update any brand data that needs to be modified after a successful registration, except for critical information such as entityType, legalCompanyName, federalTaxId or taxCountry. Cost: free. You will receive a confirmation of the update upon completion (approx. 1 minute). This process does not affect the TCR ID, the throughput or the number of phone numbers allowed. Update process cannot be used after standard or enhanced vetting, as the brand needs to be revetted in case of any critical information update.'
        US_10DLC_TCR_PRIVATE_MOCK: A free-of-charge mock process for private companies to test the 10DLC integration. Successfully completing this process does not grant the 10DLC channel but serves as a preliminary check to ensure that subsequent paid TCR registrations will be successful.
        US_10DLC_TCR_PUBLIC_MOCK: A free-of-charge mock process for public companies to test the 10DLC integration. Successfully completing this process does not grant the 10DLC channel but serves as a preliminary check to ensure that subsequent paid TCR registrations will be successful.
        US_10DLC_TCR_PRIVATE_STANDARD_BRAND_REGISTRATION: 'Initiates a standard brand registration with 10DLC for a private company, which involves an automated review of compliance history, employee count, and other business metrics. The process, which typically takes 5-10 days, is used to verify the brand and assign a vetting score from 0-100 that determines the brand''s throughput level with network carriers. A successful registration provides higher throughput and allows for unlimited campaigns and numbers. Once completed, this process can be re-requested if any data not included in US_TCR_PATCH_BRAND needs to be modified. Once completed, this process can be re-requested if any data needs to be modified (there are some fields not allowed for edition: legalCompanyName, entityType, federalTaxId and taxCountry)'
        US_10DLC_TCR_PUBLIC_STANDARD_BRAND_REGISTRATION: 'Initiates a standard brand registration with 10DLC for a public company, which involves an automated review of compliance history, employee count, and other business metrics. The process, which typically takes 5-10 days, is used to verify the brand and assign a vetting score from 0-100 that determines the brand''s throughput level with network carriers. A successful registration provides higher throughput and allows for unlimited campaigns and numbers. Once completed, this process can be re-requested if any data needs to be modified (there are some fields not allowed for edition: legalCompanyName, entityType, federalTaxId and taxCountry)'
        US_10DLC_TCR_PRIVATE_ENHANCED_BRAND_REGISTRATION: Initiates an enhanced brand registration for a private company, which is recommended if you are dissatisfied with your Standard vet score and believe a more thorough review could yield a higher rating. This process is designed to improve the brand's vetting score and potentially achieve better throughput. Please note that this enhanced vet can only be ordered after a STANDARD registration is complete.
        US_10DLC_TCR_PUBLIC_ENHANCED_BRAND_REGISTRATION: Initiates an enhanced brand registration for a public company, which is recommended if you are dissatisfied with your Standard vet score and believe a more thorough review could yield a higher rating. This process is designed to improve the brand's vetting score and potentially achieve better throughput. Please note that this enhanced vet can only be ordered after a STANDARD registration is complete.
        US_RCS_TCR_PRIVATE_BRAND_REGISTRATION: US RCS brand registration process with RCS for private companies. This process is used to verify a private brand for RCS in the US. Upon successful completion, the RCS channel will be granted to the brand.
        US_RCS_TCR_PUBLIC_BRAND_REGISTRATION: US RCS brand registration process with RCS for public companies. This process is used to verify a public brand for RCS in the US. Upon successful completion, the RCS channel will be granted to the brand.
        US_RCS_TCR_UPDATE_ASSETS: US RCS asset update process with RCS. This process is used to update the brand assets required for RCS, such as logos or banners, after the brand has already been registered.
      type: string
      examples:
      - US_SC_REGISTRY
      - US_SC_GCH
      - US_10DLC_TCR_PRIVATE_BRAND_REGISTRATION
      - US_RCS_TCR_PRIVATE_BRAND_REGISTRATION
  securitySchemes:
    OAuth2:
      description: The username and password are your Key ID and Key Secret from the Access keys section in the Sinch Customer Dashboard. Exchange these for a bearer token (access token).
      flows:
        clientCredentials:
          scopes:
            read: read
            write: write
          tokenUrl: https://auth.sinch.com/oauth2/token
      type: oauth2
    hmacAuth:
      type: apiKey
      in: header
      name: X-Sinch-Signature
      description: HMAC-SHA256 signature used to authenticate webhook deliveries. The signature is computed over the request body using the project's HMAC secret and sent in the X-Sinch-Signature header. Please refer to the Brand Callback endpoints for more information.
externalDocs:
  description: All endpoints available under this API require Bearer token authentication. Please check oauth api documentation if you need more details.
  url: https://developers.sinch.com/docs/numbers/api-reference/authentication/oauth/
x-explorer-enabled: false
x-samples-languages:
- curl
- java
- csharp
- node
- php