openapi: 3.1.0
info:
  title: Sinch Registration API
  description: >-
    The Sinch Registration API provides endpoints for managing sender ID
    registrations required by various markets and regulatory bodies. It enables
    developers to retrieve market-specific requirements, create and submit
    registrations for sender IDs, and track the status of registration
    applications. This API helps businesses comply with local messaging
    regulations across different countries where sender registration is
    mandatory for SMS delivery.
  version: '1.0'
  contact:
    name: Sinch Support
    url: https://www.sinch.com/contact-us/
  termsOfService: https://www.sinch.com/terms-of-service/
externalDocs:
  description: Sinch Registration API Documentation
  url: https://developers.sinch.com/docs/registration-api
servers:
  - url: https://registration.api.sinch.com
    description: Global Production Server
tags:
  - name: Market Requirements
    description: >-
      Retrieve market-specific requirements for sender ID registration
      in different countries.
  - name: Registrations
    description: >-
      Create, update, delete, and track sender ID registrations for
      compliance with local messaging regulations.
security:
  - oAuth2: []
paths:
  /v1/projects/{project_id}/registrations:
    get:
      operationId: listRegistrations
      summary: List Registrations
      description: >-
        Returns a list of all sender ID registrations in the project with
        their current status and submission details.
      tags:
        - Registrations
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: status
          in: query
          description: Filter by registration status
          schema:
            type: string
        - 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 registrations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistrationList'
        '401':
          description: Unauthorized
    post:
      operationId: createRegistration
      summary: Create a Registration
      description: >-
        Creates a new sender ID registration for a specific market. The
        registration must include all required fields as defined by the
        market requirements.
      tags:
        - Registrations
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRegistrationRequest'
      responses:
        '200':
          description: Registration created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Registration'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
  /v1/projects/{project_id}/registrations/{registration_id}:
    get:
      operationId: getRegistration
      summary: Get a Registration
      description: >-
        Returns the details and current status of a specific sender ID
        registration.
      tags:
        - Registrations
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/RegistrationId'
      responses:
        '200':
          description: Registration details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Registration'
        '401':
          description: Unauthorized
        '404':
          description: Registration not found
    patch:
      operationId: updateRegistration
      summary: Update a Registration
      description: >-
        Updates a sender ID registration. Only registrations that have not
        yet been submitted for approval can be updated.
      tags:
        - Registrations
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/RegistrationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRegistrationRequest'
      responses:
        '200':
          description: Registration updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Registration'
        '401':
          description: Unauthorized
        '404':
          description: Registration not found
    delete:
      operationId: deleteRegistration
      summary: Delete a Registration
      description: >-
        Deletes a specific sender ID registration.
      tags:
        - Registrations
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/RegistrationId'
      responses:
        '200':
          description: Registration deleted
        '401':
          description: Unauthorized
        '404':
          description: Registration not found
  /v1/projects/{project_id}/registrations/{registration_id}:submit:
    post:
      operationId: submitRegistration
      summary: Submit a Registration
      description: >-
        Submits a sender ID registration for approval. Once submitted, the
        registration enters the review process and cannot be modified.
      tags:
        - Registrations
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/RegistrationId'
      responses:
        '200':
          description: Registration submitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Registration'
        '401':
          description: Unauthorized
        '404':
          description: Registration not found
  /v1/projects/{project_id}/markets:
    get:
      operationId: listMarkets
      summary: List Markets
      description: >-
        Returns a list of available markets with their sender ID registration
        requirements and supported sender types.
      tags:
        - Market Requirements
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: List of markets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketList'
        '401':
          description: Unauthorized
  /v1/projects/{project_id}/markets/{market_id}:
    get:
      operationId: getMarket
      summary: Get Market Requirements
      description: >-
        Returns the detailed registration requirements for a specific market
        including required fields, supported sender types, and approval
        timelines.
      tags:
        - Market Requirements
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: market_id
          in: path
          required: true
          description: The market identifier
          schema:
            type: string
      responses:
        '200':
          description: Market requirements
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Market'
        '401':
          description: Unauthorized
        '404':
          description: Market not found
components:
  securitySchemes:
    oAuth2:
      type: oauth2
      description: >-
        OAuth 2.0 client credentials flow.
      flows:
        clientCredentials:
          tokenUrl: https://auth.sinch.com/oauth2/token
          scopes: {}
  parameters:
    ProjectId:
      name: project_id
      in: path
      required: true
      description: The unique project identifier
      schema:
        type: string
    RegistrationId:
      name: registration_id
      in: path
      required: true
      description: The unique registration identifier
      schema:
        type: string
  schemas:
    Registration:
      type: object
      properties:
        id:
          type: string
          description: The unique registration identifier
        projectId:
          type: string
          description: The project ID
        marketId:
          type: string
          description: The market identifier
        displayName:
          type: string
          description: The display name for the sender
        senderId:
          type: string
          description: The sender ID being registered
        senderType:
          type: string
          description: The sender type
        status:
          type: string
          enum:
            - DRAFT
            - SUBMITTED
            - UNDER_REVIEW
            - APPROVED
            - REJECTED
            - REVOKED
          description: The current registration status
        rejectionReason:
          type: string
          description: Reason for rejection if applicable
        registrationDetails:
          type: object
          description: Market-specific registration details
          additionalProperties: true
        createTime:
          type: string
          format: date-time
          description: When the registration was created
        updateTime:
          type: string
          format: date-time
          description: When the registration was last updated
        submitTime:
          type: string
          format: date-time
          description: When the registration was submitted
    RegistrationList:
      type: object
      properties:
        registrations:
          type: array
          description: List of registrations
          items:
            $ref: '#/components/schemas/Registration'
        nextPageToken:
          type: string
          description: Pagination token
        totalSize:
          type: integer
          description: Total number of registrations
    CreateRegistrationRequest:
      type: object
      required:
        - marketId
        - senderId
      properties:
        marketId:
          type: string
          description: The target market
        displayName:
          type: string
          description: Display name for the sender
        senderId:
          type: string
          description: The sender ID to register
        senderType:
          type: string
          description: The sender type
        registrationDetails:
          type: object
          description: Market-specific registration details
          additionalProperties: true
    UpdateRegistrationRequest:
      type: object
      properties:
        displayName:
          type: string
          description: Updated display name
        registrationDetails:
          type: object
          description: Updated registration details
          additionalProperties: true
    Market:
      type: object
      properties:
        id:
          type: string
          description: The market identifier
        name:
          type: string
          description: The market name
        countryCode:
          type: string
          description: The ISO 3166-1 alpha-2 country code
        senderTypes:
          type: array
          description: Supported sender types
          items:
            type: string
        requiredFields:
          type: array
          description: Fields required for registration
          items:
            type: object
            properties:
              name:
                type: string
                description: The field name
              type:
                type: string
                description: The field type
              required:
                type: boolean
                description: Whether the field is required
              description:
                type: string
                description: Description of the field
        estimatedApprovalTime:
          type: string
          description: Estimated time for approval
    MarketList:
      type: object
      properties:
        markets:
          type: array
          description: List of markets
          items:
            $ref: '#/components/schemas/Market'