Sinch Sender ID Registrations API

openapi: 3.2.0
components:
  schemas:
    Attachment:
      properties:
        attachmentId:
          description: Unique identifier of the attachment.
          example: d1c7ccbf-919d-462f-8587-dec95a1b11ee
          type: string
        createTime:
          description: Create time of the request. ISO date time format in UTC without timezone offset.
          example: '2021-11-03T14:30:03'
          type: string
        fileName:
          description: Human readable name of the attachment.
          example: sender_id_registration_form.docx
          type: string
        mimeType:
          description: MIME type of the attachment file.
          example: application/vnd.openxmlformats-officedocument.wordprocessingml.document
          type: string
        updateTime:
          description: Update time of the request. ISO date time format in UTC without timezone offset.
          example: '2021-11-03T14:30:03'
          type: string
        uploadStatus:
          description: Status of the file uploaded
          enum:
          - COMPLETED
          - WAITING
          - FAILED
          x-enumDescriptions:
            COMPLETED: Attachment successfully uploaded and linked to the registration
            WAITING: Attachment processing is still ongoing.
            FAILED: Attachment uploading has failed for any reason.
          example: COMPLETED
          type: string
        documentType:
          description: Type of document attached.
          example: Passport
          type: string
      type: object
    AttachmentDefinition:
      properties:
        description:
          description: Attachment description
          example: This document is required for any Third party registration in MK local.
          type: string
        id:
          description: Attachment Definition Id
          example: '43342642354352344'
          type: string
        mandatory:
          description: whether the attachment is mandatory in this policy
          type: boolean
        template:
          description: Whether the attachment contains a template or not. Templates can be downloaded with /template endpoint
          type: boolean
        title:
          description: Attachment title
          example: Third Party Authority Form
          type: string
        allowedMimeTypes:
          description: Array of allowed mime types. If empty, no restrictions are applied.
          example:
          - application/pdf
          - application/pdf
          type: array
          items:
            type: string
        allowedDocumentTypes:
          description: Document types allowed for this attachment. If specified, the documentType field in the attachment must be one of the allowed types.
          example:
          - Passport
          - Driver's License
          type: array
          items:
            type: string
      type: object
    CallbackConfigurationResponse:
      properties:
        hmacSecret:
          description: The HMAC secret used for hashing the callback body using the HMAC-SHA1 algorithm - and for creating the X-Sinch-Signature header.
          example: d1c7ccbf-919d-462f-8587-dec95a1b11ee
          type: string
        projectId:
          type: string
      type: object
    CallbackConfigurationUpdateBody:
      properties:
        hmacSecret:
          description: The HMAC secret to be updated for the specified project
          example: d1c7ccbf-919d-462f-8587-dec95a1b11ee
          type: string
      type: object
    CallbackEventBody:
      description: Callback Event Object body
      properties:
        comment:
          description: Additional comment related to the latest status change
          example: Hi, the NOC letter contains phone numbers, and this is not allowed. Please have this updated to proceed forward. Regards, XX
          type: string
        eventId:
          description: The ID of the event.
          example: ee34ccbf-919d-462f-8587-dec95a1b11ee
          type: string
        eventType:
          description: The type of the event.
          enum:
          - REGISTRATION_STATUS_CHANGE
          - REGISTRATION_CODE_ASSIGNED
          x-enumDescriptions:
            REGISTRATION_STATUS_CHANGE: Event informs about a registration status change.
            REGISTRATION_CODE_ASSIGNED: Event informs that one or more sender IDs (e.g. Short Code or Long Number) have been assigned to the registration.
          example: REGISTRATION_STATUS_CHANGE
          type: string
        projectId:
          description: The ID of the project to which the event belongs.
          example: aad4ccbf-919d-462f-8587-dec95a1b11b0
          type: string
        resourceId:
          description: Corresponds to the registration id
          example: 01hh51s80tpvjy7pe0mt6nd7at
          type: string
        resourceType:
          description: Type of the registration id
          enum:
          - ALPHANUMERIC_SENDER_ID
          - SHORT_CODE
          - LONG_NUMBER
          x-enumDescriptions:
            ALPHANUMERIC_SENDER_ID: Alpha sender IDs
            SHORT_CODE: Short Code sender IDs
            LONG_NUMBER: Long Numbers sender IDs
          example: ALPHANUMERIC_SENDER_ID
          type: string
        status:
          description: The new status of the registration
          enum:
          - IN_QUEUE
          - IN_PROGRESS
          - APPROVED
          - REJECTED
          - PENDING
          - ON_HOLD
          - PENDING_APPROVAL
          - PENDING_ATTACHMENTS
          x-enumDescriptions:
            IN_QUEUE: Registration has been successfully submitted, but it is waiting for support.
            IN_PROGRESS: Registration is being processing by Sinch.
            APPROVED: Registration has been approved and sender ID has been provisioned for the customer.
            REJECTED: Registration has been rejected. A comment should be present in the logs with the reason.
            PENDING: Registration must be updated by the customer. Please check the registration logs to understand the reason.
            ON_HOLD: Registration is on hold for any reason. Please check the comments in the logs.
            PENDING_APPROVAL: For those policies with MANUAL price, Account Managers must approve the operation. Until registration has the approval it will stay in this state.
            PENDING_ATTACHMENTS: Registration has been submitted, but at least one mandatory attachment must be provided.
          example: IN_QUEUE
          type: string
        timestamp:
          deprecated: true
          description: The date and time when the callback was created and added to the callbacks queue. It's crucial to note that the callback service doesn't guarantee delivery order; hence, this timestamp serves as the source of truth for sequencing. This field is deprecated, please use createTime instead.
          format: date-time
          example: '2023-06-06T07:45:27.785357Z'
          type: string
        createTime:
          description: The date and time when the callback was created and added to the callbacks queue. It's crucial to note that the callback service doesn't guarantee delivery order; hence, this createTime serves as the source of truth for sequencing.
          format: date-time
          example: '2023-06-06T07:45:27.785357Z'
          type: string
        senderIds:
          deprecated: true
          description: Deprecated, use senderElements. List of sender IDs associated with this registration that were not individually rejected. If the sender IDs are not provided in the request, they will be assigned after registration approval.
          example:
          - senderId1
          - senderId2
          type: array
          items:
            type: string
        senderElements:
          type: array
          items:
            $ref: '#/components/schemas/SenderId'
          description: List of sender IDs associated with this registration, including the ones that were individually rejected. If the sender IDs are not provided in the request, they will be assigned after registration approval.
        attachmentIds:
          description: IDs of the attachments that were replaced or corrected by the review team and should be re-downloaded. Only present when the status change was caused by the review team requesting an update to a document.
          example:
          - 01m20g6mnrd9kpbdv3wwm8zfyy
          - 01m21521k39d17a0atk05th8c8
          type: array
          items:
            type: string
      type: object
    ChainedSpecialCondition:
      properties:
        answer:
          description: Answer to previous question
          example: 'No'
          type: string
        description:
          example: Promotional, marketing or advertising purposes
          type: string
          description: The Description field provides context or additional information to help users understand the purpose and usage of the Answer field.
        chainedSpecialConditions:
          description: A chained special conditions that contains an answer of a previous question, a new question/answers if needed, a policy id if there are no more questions
          items:
            $ref: '#/components/schemas/ChainedSpecialCondition'
          type: array
        policyId:
          description: In markets without special conditions, the policy id is here. This field will be ignored (not exist) if there are chained special conditions
          example: '43342642354352344'
          type: string
        prompt:
          description: A question to be answered with the chained special conditions. This field will be ignored (not exist) if there are not chained special conditions
          example: Is this brand registered as a local legal entity in this market?
          type: string
      type: object
    ErrorDetails:
      type: object
    GetRegistrationResponse:
      description: Registration content
      properties:
        attachments:
          description: Files attached to this registration
          items:
            $ref: '#/components/schemas/Attachment'
          type: array
        callbackUrl:
          description: Webhook URL to specify an endpoint for delivery of notifications about registration updates
          example: senderid.registrations.api.sinch.com
          type: string
        createTime:
          description: Creation time of the request. ISO date time format in UTC without timezone offset.
          example: '2021-11-03T14:30:03'
          type: string
        etaDate:
          description: Expected date of the registration approval. ISO date format.
          example: '2024-11-03'
          type: string
        id:
          description: Unique registration identifier.
          example: d1c7ccbf-919d-462f-8587-dec95a1b11ee
          type: string
        logs:
          description: Detailed history of the status changes this registration went through
          items:
            $ref: '#/components/schemas/LogEntry'
          type: array
        notificationContacts:
          description: Email addresses that will be notified of any status changes of the registration.
          example:
          - jane.doe@example.com
          - john.doe@example.com
          items:
            type: string
          type: array
        owner:
          description: Display name of the user that created the registration.
          example: Jane Doe
          type: string
        policyId:
          description: Unique identifier of the policy for this registration.
          example: d1c7ccbf-919d-462f-8587-dec95a1b11ee
          type: string
        price:
          $ref: '#/components/schemas/Pricing'
        registrationType:
          description: Specify the sender ID type
          enum:
          - ALPHANUMERIC_SENDER_ID
          - LONG_NUMBER
          - SHORT_CODE
          - RCS_AGENT
          x-enumDescriptions:
            ALPHANUMERIC_SENDER_ID: Alpha sender IDs
            LONG_NUMBER: Long Numbers for SMS
            SHORT_CODE: Short Codes for SMS
            RCS_AGENT: RCS agent
          example: ALPHANUMERIC_SENDER_ID
          format: enum
          type: string
        requestDetails:
          description: Details of the sender IDs to be registered. Details depend on the specific market requirements defined in the policy.
          items:
            $ref: '#/components/schemas/RequestDetails'
          type: array
        senderIds:
          deprecated: true
          description: Deprecated, use senderElements. List of sender IDs associated with this registration that were not individually rejected. If the sender IDs are not provided in the request, they will be assigned after registration approval.
          type: array
          items:
            type: string
          example:
          - senderId1
          - senderId2
        senderElements:
          type: array
          items:
            $ref: '#/components/schemas/SenderId'
          description: List of sender IDs associated with this registration, including the ones that were individually rejected. If the sender IDs are not provided in the request, they will be assigned after registration approval.
        status:
          description: Status of the registration.
          enum:
          - DRAFT
          - IN_QUEUE
          - IN_PROGRESS
          - APPROVED
          - REJECTED
          - PENDING
          - ON_HOLD
          - PENDING_APPROVAL
          - PENDING_ATTACHMENTS
          x-enumDescriptions:
            DRAFT: Registration not submitted by the customer. This functionality is not available through Public API, but it is possible to retrieve a registration created in the Sinch Customer Dashboard under the same project Id.
            IN_QUEUE: Registration has been successfully submitted, but it is waiting for support.
            IN_PROGRESS: Registration is being processing by Sinch.
            APPROVED: Registration has been approved and sender ID has been provisioned for the customer.
            REJECTED: Registration has been rejected. A comment should be present in the logs with the reason.
            PENDING: Registration must be updated by the customer. Please check the registration logs to understand the reason.
            ON_HOLD: Registration is on hold for any reason. Please check the comments in the logs.
            PENDING_APPROVAL: For those policies with MANUAL price, Account Managers must approve the operation. Until registration has the approval it will stay in this state.
            PENDING_ATTACHMENTS: Registration has been submitted, but at least one mandatory attachment must be provided.
          example: IN_QUEUE
          type: string
        tags:
          description: User tags used for the registration. Tag have to start from '#' and contains only alphanumerics and dashes.
          example:
          - '#myTag1'
          - '#myTag2'
          items:
            type: string
          type: array
        updateTime:
          description: Update time of the request. ISO date time format in UTC without timezone offset.
          example: '2021-11-03T14:30:03'
          type: string
        servicePlanId:
          example: a23dccbf-919d-462f-8587-dec95a1b44de
          type: string
          description: Service plan ID or System ID that the registration applies to. When included, the sender id will be configured linked to the service/system plan.
      type: object
    SenderId:
      type: object
      properties:
        value:
          example: senderId1
          type: string
          description: The sender id value.
        isRejected:
          example: false
          type: boolean
          description: True when this sender id was individually rejected and is not part of the approval.
    InternalRestError:
      properties:
        code:
          format: int32
          type: integer
        details:
          items:
            $ref: '#/components/schemas/ErrorDetails'
          type: array
        message:
          type: string
        status:
          type: string
      type: object
    ListAvailableMarketsResponse:
      description: List of market codes available for registration under request filters.
      properties:
        markets:
          description: List of countries that matches with the request criteria.
          items:
            $ref: '#/components/schemas/MarketDescription'
          type: array
      type: object
    ListMarketVersionsResponse:
      properties:
        marketVersions:
          description: List of Market versions that matches with the request criteria.
          items:
            $ref: '#/components/schemas/MarketVersion'
          type: array
        nextPageToken:
          description: next token to be used to retrieve more markets
          example: CgptYXJrZXRDb2RlEk4KRnR5cGUuZ29vZ2xlYXBpcy5jb20vc2luY2gubnVtcmVnLnBvbGljeS52MWFscGhhMi5NYXJrZXRWZXJzaW9uUGFnZU1hcmsSBAoCS1o=
          type: string
        totalSize:
          description: Total Number of markets.
          example: 50
          format: int32
          type: integer
      type: object
    ListRegistrationsResponse:
      properties:
        nextPageToken:
          description: Page token that can be used to retrieve next page of registrations if they exist. Will be empty if next page does not exist
          type: string
        registrations:
          description: List of registrations
          items:
            $ref: '#/components/schemas/GetRegistrationResponse'
          type: array
        totalSize:
          description: Total count of registrations matching provided search criteria
          format: int32
          type: integer
      type: object
    LogEntry:
      properties:
        createTime:
          description: Create time of this log entry. ISO date time format in UTC
          example: '2021-11-03T14:30:03'
          type: string
        message:
          description: Optional message with details of the registration status update. Can contain information provided by the agent handling the request.
          example: Please update the attachment connected to your request.
          type: string
        registrationState:
          description: State of the registration after this entry was created
          example: PENDING
          type: string
      type: object
    MarketDescription:
      description: Market description contains for each market, the market name and the market ISO Code (2 characters)
      properties:
        marketCode:
          description: ISO market code (ex. 'IT', 'AU', 'AE', etc.)
          example: AE
          pattern: ^[A-Z]{2}$
          type: string
        marketName:
          description: Market Name
          example: United Arab Emirates
          type: string
      type: object
    MarketVersion:
      description: Each Market Version object contains id, market code, registration type, market status and a set of special conditions.
      properties:
        createTime:
          description: Creation time of this major/minor market version.
          example: '2023-09-17 06:22:34.372747'
          format: date-time
          type: string
        id:
          description: Market Version Id.
          example: ddede333432ededed2
          type: string
        majorVersion:
          description: Major version of the policy. Indicates market requirement changes that may require resubmitting requests in progress.
          example: 1
          format: int32
          type: integer
        marketCode:
          description: ISO country code.
          example: AU
          type: string
        minorVersion:
          description: Minor version of the policy. Indicates market requirement changes that do not require resubmitting requests in progress.
          example: 0
          format: int32
          type: integer
        registrationType:
          description: Type of Sender ID referenced by this market.
          enum:
          - ALPHANUMERIC_SENDER_ID
          - LONG_NUMBER
          - SHORT_CODE
          - RCS_AGENT
          x-enumDescriptions:
            ALPHANUMERIC_SENDER_ID: Alpha sender IDs
            LONG_NUMBER: Long Numbers for SMS
            SHORT_CODE: Short Codes for SMS
            RCS_AGENT: RCS agent
          example: ALPHANUMERIC_SENDER_ID
          format: enum
          type: string
        specialConditions:
          $ref: '#/components/schemas/SpecialCondition'
        status:
          description: Market status, it can be active or disabled
          enum:
          - ACTIVE
          - DISABLED
          x-enumDescriptions:
            ACTIVE: Market is available to request sender IDs.
            DISABLED: Market has been deactivated and sender IDs cannot be requested.
          example: ACTIVE
          format: enum
          type: string
      type: object
    Policy:
      description: Policy response, contains the fields and attachments required, multi type configuration, status and fees
      properties:
        attachments:
          description: Attachment Definition
          items:
            $ref: '#/components/schemas/AttachmentDefinition'
          type: array
        fees:
          deprecated: true
          description: True if policy registration has any fees associated
          type: boolean
        id:
          description: Policy Version Id
          example: '43342642354352344'
          type: string
        jsonPolicy:
          $ref: '#/components/schemas/Policy_JsonPolicy'
        policyMultiType:
          description: Indicates whether the policy accepts single or multi sender id requested in each registration process
          enum:
          - SINGLE
          - MULTI_SENDER
          x-enumDescriptions:
            SINGLE: Only one sender ID is allowed per registration.
            MULTI_SENDER: Up to 50 sender IDs are allowed per registration. They can be included in the senderIdDetails array (one object per sender ID)
          example: SINGLE
          format: enum
          type: string
        policyStatus:
          description: Policy status
          enum:
          - ENABLED
          - DISABLED
          - INACTIVE
          x-enumDescriptions:
            ENABLED: Policy is in use.
            DISABLED: Policies that for any reason has been deactivated. There are several reasons to do so, but they are mainly due to changes in the regulations, which require some manual intervention.
            INACTIVE: Market version has been deactivated because a new version has been published. This policy is no longer valid.
          example: ENABLED
          format: enum
          type: string
        price:
          $ref: '#/components/schemas/Policy_Pricing'
        isOpenPolicy:
          description: Indicates if the policy has open registration system. This means that any sender ID requested is automatically approved, without any manual intervention.
          type: boolean
        statusDisclaimer:
          description: Contains disclaimer for disabled policies. Empty if policy is ACTIVE
          example: Policy has been disabled as Registrations for these market conditions are now dynamic.
          type: string
      type: object
    Policy_JsonPolicy:
      properties:
        companyDetailsTemplate:
          description: Policy section related to company details
          properties:
            properties:
              items:
                $ref: '#/components/schemas/Policy_JsonPolicy_Property'
              type: array
          type: object
        contactPersonTemplate:
          description: Policy section related to contact person details
          properties:
            properties:
              items:
                $ref: '#/components/schemas/Policy_JsonPolicy_Property'
              type: array
          type: object
        senderIdTemplate:
          description: Policy section related to sender ID details
          properties:
            properties:
              items:
                $ref: '#/components/schemas/Policy_JsonPolicy_Property'
              type: array
          type: object
        marketSpecificDetailsTemplate:
          description: Only available for RCS Agent policies. This section shows some market specific requirements, while others are general for all markets.
          properties:
            properties:
              items:
                $ref: '#/components/schemas/Policy_JsonPolicy_Property'
              type: array
          type: object
      type: object
    Policy_JsonPolicy_Property:
      description: Object with fields properties containing field rules and description
      properties:
        description:
          description: Description of the field
          example: Between 3 - 11 characters.\nMust be related to the brand name.\nMarketing SIDs are currently not allowed.
          type: string
        x-placeholder:
          description: Placeholder text shown in the field when it is empty. An example of what should be entered in the field
          example: e.g. name.surname@yourCompany.com
          type: string
        maxLength:
          description: Max length of text field
          example: 11
          type: integer
        minLength:
          description: Min length of text field
          example: 3
          type: integer
        name:
          description: Name of the field. Serves as a key (reference) to a field
          example: senderId
          type: string
        required:
          description: Indicator that specifies whether a field is optional or required
          example: false
          type: boolean
        title:
          description: Name of field shown in user interface. In some cases, there is a question for which an answer is expected in the field
          example: Alphanumeric Sender ID
          type: string
        type:
          description: Type of field. Possible types are 'string' - for a simple text field or enum or 'array' - for multiple texts in one field
          example: string
          type: string
          enum:
          - string
          - array
          x-enumDescriptions:
            string: Field value expected is an string value
            array: Field value expected is an array of values. In this case, the items are described in field 'items'
        examples:
          description: Used as suggestions for possible response in the field
          example:
          - By subscribing to our loyalty program
          - By making a purchase in-store or online
          type: array
          items:
            type: string
        pattern:
          description: Regex pattern validation
          example: ^[+][0-9]+$
          type: string
        message:
          description: Pattern validation message
          properties:
            pattern:
              description: Pattern validation message
              example: The number needs to start with country code. For example +1
              type: string
            maxLength:
              description: Max length of the field value
              example: 11
              type: integer
            minLength:
              description: Min length of the field value
              example: 3
              type: integer
          type: object
        items:
          description: When the field type is 'array', this object describes the array items. Typically a checkbox. Contains an enum when the array items are restricted to a set of values.
          properties:
            enum:
              description: Possible values for the array items
              oneOf:
              - type: array
                items:
                  type: string
                  example: '+1'
              - type: array
                items:
                  type: integer
                  example: 44
            type:
              description: Type of the array items. Possible types are 'string' or 'integer'
              example: string
              type: string
              enum:
              - string
              - integer
              x-enumDescriptions:
                string: Text array items
                integer: Numeric array items
          type: object
        minItems:
          description: Minimum number of items selected when the field type is 'array'
          example: 1
          type: integer
        enum:
          description: Possible values for the field when the field type is not an array. Typically a dropdown. In some cases the enum contains true and null. This is for mandatory checks according to market regulations.
          oneOf:
          - type: array
            items:
              type: string
              example: By subscribing to our loyalty program
          - type: array
            items:
              type: integer
              example: 3
          - type: array
            description: This can be a true false option or a true checkbox, that contains [true, null] as options
            items:
              type: boolean
              example: true
      type: object
    Policy_Pricing:
      properties:
        mode:
          description: Type of policy pricing.
          enum:
          - SUBSCRIBED
          - MANUAL
          - NONE
          x-enumDescriptions:
            SUBSCRIBED: 'policy which has automatic fees assigned: setup fee or/and recurrent fee'
            MANUAL: policy contains fees associated in the market, those are managed and approved by customer's account manager
            NONE: no fee associated
          example: SUBSCRIBED
          format: enum
          type: string
        subscription:
          $ref: '#/components/schemas/Pricing_Subscription'
      type: object
    Pricing:
      properties:
        currency:
          description: Currency of the fees
          example: USD
          type: string
        frequency:
          description: Recurrent subscription period in month, 0 if no subscription fees
          example: 1
          format: int32
          type: integer
        mode:
          description: Type of policy pricing.
          enum:
          - SUBSCRIBED
          - MANUAL
          - NONE
          x-enumDescriptions:
            SUBSCRIBED: 'policy which has automatic fees assigned: setup fee or/and recurrent fee'
            MANUAL: policy contains fees associated in the market, those are managed and approved by customer's account manager
            NONE: no fee associated
          example: SUBSCRIBED
          format: enum
          type: string
        recurrentFeeAmount:
          description: Recurrent subscription fee amount
          example: '2'
          type: string
        setupFeeAmount:
          description: One time setup fee amount
          example: '5'
          type: string
      type: object
    Pricing_Subscription:
      properties:
        currency:
          description: Currency of user
          type: string
        frequency:
          description: Frequency of recurrent fee, is 0 when there is not recurrent fee. The number ranges from 0 to 12, where 1 indicates monthly payments and 12 indicates yearly payments
          format: int32
          type: integer
        recurrentFeeAmount:
          description: Amount of recurrent fee
          type: string
        setupFeeAmount:
          description: Amount of setup fee
          type: string
      type: object
    RegistrationCreateBody:
      properties:
        callbackUrl:
          description: Webhook URL to specify an endpoint for delivery of notifications about registration updates
          example: senderid.registrations.api.sinch.com
          type: string
        notificationContacts:
          description: Email addresses that will be notified of any status changes of the registration.
          example:
          - jane.doe@example.com
          - john.doe@example.com
          items:
            type: string
          type: array
        policyId:
          description: Policy id that applies the registration.
          example: d1c7ccbf-919d-462f-8587-dec95a1b11ee
          type: string
        requestDetails:
          description: Details of the sender IDs to be registered. Details depend on the specific market requirements defined in the policy.
          items:
            $ref: '#/components/schemas/RequestDetails'
          type: array
        tags:
          description: User tags used for the registration. Tag have to start from '#' and contains only alphanumerics and dashes.
          example:
          - '#myTag1'
          - '#myTag2'
          items:
            type: string
          type: array
        servicePlanId:
          example: a23dccbf-919d-462f-8587-dec95a1b44de
          type: string

# --- truncated at 32 KB (64 KB total) ---
# Full source: https://artifacts.apis.io/sinch/openapi/sinch-sender-id-registrations-api-openapi.yml