openapi: 3.0.0
info:
  title: Smart Assign
  description: >
    API endpoints for managing default sender settings in a user's account.

    The Smart Assign Service API automatically selects a compliant SenderID for
    each country you send to, with an option to set your own default. It also
    lets you retrieve a list of compliant SenderIDs per country, providing
    transparency, control, and confidence in SMS delivery.
servers:
  - url: https://rest.clicksend.com
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
  schemas:
    default_sender:
      type: object
      properties:
        id:
          type: string
          description: ID of the default sender.
          example: f99872cc-11a6-48ba-a9f2-bcfb6dd1e3d4
        user_id:
          type: integer
          description: User ID from the version 3 system.
          example: 123456
        subaccount_id:
          type: integer
          description: Subaccount ID from version 3.
          example: 45678
        country_code:
          type: string
          description: ISO 3166-1 alpha-2 formatted country code.
          example: AU
        product_type:
          type: string
          description: Type of product for which the setting is applied.
          enum:
            - SMS
          example: SMS
        default_sender_strategies:
          type: array
          description: Default sender strategies. Must contain 1 or more objects.
          minItems: 1
          items:
            type: object
            properties:
              sender_type:
                type: string
                description: Type of the sender.
                enum:
                  - alpha_tag
                  - 10DLC
                  - tollfree
                  - own_number
                  - shortcode
                  - longcode
                  - shared_longcode
                example: alpha_tag
              sender_id:
                type: string
                description: Identifier for the sender. Must be between 3-20 characters.
                example: ClickSend
              sender_country_code:
                type: string
                description: ISO 3166-1 alpha-2 formatted country code.
                example: null
              priority:
                type: integer
                description: >-
                  Priority level of the sender in the strategy. Must be a
                  positive integer.
                example: 1
              status:
                type: string
                description: Status of the sender in the strategy.
                enum:
                  - ENABLED
                  - DISABLED
                example: ENABLED
              note:
                type: string
                description: >-
                  Note providing additional context about the sender. Maximum
                  length of 200 characters. Optional.
                example: This is a test default sender
            required:
              - sender_type
              - sender_id
              - priority
              - status
        status:
          type: string
          description: Overall status of the default sender.
          enum:
            - ENABLED
            - DISABLED
          example: ENABLED
        created_timestamp:
          type: string
          description: >-
            Timestamp of when the default sender was created. Must be in ISO
            8601 format.
          example: '2021-08-02T00:00:00Z'
        updated_timestamp:
          type: string
          description: >-
            Timestamp of the last update to the default sender. Must be in ISO
            8601 format.
          example: '2021-08-02T00:00:00Z'
      required:
        - id
        - user_id
        - subaccount_id
        - country_code
        - product_type
        - default_sender_strategies
        - status
        - created_timestamp
        - updated_timestamp
    get-default-senders-list:
      type: object
      properties:
        http_code:
          type: integer
          description: HTTP status code of the response.
          example: 200
        response_code:
          type: string
          description: Code indicating the result of the response.
          example: SUCCESS
        response_msg:
          type: string
          description: Message providing additional information.
          example: Default senders retrieved successfully
        data:
          type: object
          properties:
            data:
              type: array
              description: List of default senders.
              items:
                $ref: '#/components/schemas/default_sender'
            per_page:
              type: integer
              description: Number of items per page.
              example: 1
            self_page_url:
              type: string
              description: URL for the current page.
              example: >-
                https://api.clicksend.com/v4/sender_assignment_settings?offset=f99872cc-11a6-48ba-a9f2-bcfb6dd1e3d4#8fa5ebc2-777b-45db-a448-ec76a40d4384&per_page=1
            next_page_url:
              type: string
              description: URL for the next page.
              example: >-
                https://api.clicksend.com/v4/sender_assignment_settings?offset=f99872cc-11a6-48ba-a9f2-bcfb6dd1e3d4#8fa5ebc2-777b-45db-a448-ec76a40d4384&per_page=1
      required:
        - http_code
        - response_code
        - response_msg
        - data
    create-default-sender:
      type: object
      properties:
        http_code:
          type: integer
          description: HTTP status code of the response.
          example: 200
        response_code:
          type: string
          description: Code indicating the result of the response.
          example: SUCCESS
        response_msg:
          type: string
          description: Message providing additional information.
          example: Operation completed successfully
        data:
          $ref: '#/components/schemas/default_sender'
      required:
        - http_code
        - response_code
        - response_msg
        - data
    default_sender_error:
      type: object
      properties:
        http_code:
          type: integer
          description: HTTP status code of the response.
          example: 400
        response_code:
          type: string
          description: Code indicating the result of the response.
          example: BAD_REQUEST
        response_msg:
          type: string
          description: Message providing additional information.
          example: Failed to process default sender
        data:
          type: object
          nullable: true
          example: null
        details:
          type: array
          description: List of error details
          items:
            type: object
            properties:
              field:
                type: string
                description: The field that caused the error
                example: default_sender_strategies[0].sender_id
              reason:
                type: string
                description: The error message
                example: Invalid sender ID format
          example:
            - field: default_sender_strategies[0].sender_id
              reason: Invalid sender ID format
            - field: default_sender_strategies[0].sender_type
              reason: Sender type is required
      required:
        - http_code
        - response_code
        - response_msg
        - details
    get-default-sender-details:
      type: object
      properties:
        http_code:
          type: integer
          description: HTTP status code of the response.
          example: 200
        response_code:
          type: string
          description: Code indicating the result of the response.
          example: SUCCESS
        response_msg:
          type: string
          description: Message providing additional information.
          example: Operation completed successfully
        data:
          $ref: '#/components/schemas/default_sender'
      required:
        - http_code
        - response_code
        - response_msg
        - data
    update-default-sender:
      type: object
      properties:
        http_code:
          type: integer
          description: HTTP status code of the response.
          example: 200
        response_code:
          type: string
          description: Code indicating the result of the response.
          example: SUCCESS
        response_msg:
          type: string
          description: Message providing additional information.
          example: Operation completed successfully
        data:
          $ref: '#/components/schemas/default_sender'
      required:
        - http_code
        - response_code
        - response_msg
        - data
paths:
  /v3/default-senders:
    post:
      summary: Create Default Sender
      operationId: create-default-sender
      description: >-
        Creates a new default sender configuration to automate the selection of
        compliant SenderIDs.

        By configuring a default sender you no longer need to define the
        `sender_id` string when sending SMS messages. The default sender will be
        picked up automatically.


        For more information on Sender IDs, please refer to [What is a Sender ID
        or Sender
        Number?](https://help.clicksend.com/article/4kgj7krx00-what-is-a-sender-id-or-sender-number)
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                country_code:
                  type: string
                  description: >-
                    The country code of the recipient. Must be a valid ISO
                    3166-1 alpha-2 country code.
                  example: AU
                product_type:
                  type: string
                  description: >-
                    The type of product for the assignment. Support for
                    additional types coming soon.
                  enum:
                    - SMS
                default_sender_strategies:
                  type: array
                  description: >-
                    Array detailing sender strategies. Must contain exactly 1
                    element. Multiple strategies support coming soon.
                  minItems: 1
                  maxItems: 1
                  items:
                    type: object
                    properties:
                      sender_type:
                        type: string
                        enum:
                          - alpha_tag
                          - 10DLC
                          - tollfree
                          - own_number
                          - shortcode
                          - longcode
                          - shared_longcode
                        description: The type of sender for this strategy.
                      sender_id:
                        type: string
                        description: >
                          Unique identifier for the sender. Format varies based
                          on `sender_type`:

                          - `shortcode`: Numeric, 3-8 digits.

                          - `longcode`, `tollfree`, `10DLC`, `own_number`: 2-15
                          digits, may include `+` prefix.

                          - `alpha_tag`: 3-11 alphanumeric characters, must
                          include at least one letter or `+`.

                          - `shared_longcode`: Can be null or empty string.


                          > **Important:** The `sender_id` must be in valid
                          format, owned, and has ready to use status for the
                          corresponding `sender_type`.
                      sender_country_code:
                        type: string
                        description: >
                          The country code of the sender, using the ISO 3166-1
                          alpha-2 format (e.g., "US").


                          This field is required in the following cases:

                          - When `sender_type` is `own_number`, `longcode`,
                          `tollfree`, or `10DLC`

                          - When the `sender_id` follows the US/Canada number
                          format (starts with `+1`)


                          For all other cases, this field is optional.
                      note:
                        type: string
                        description: >-
                          Optional note providing additional context about the
                          sender strategy.
                        maxLength: 200
                    required:
                      - sender_type
                      - sender_id
              required:
                - country_code
                - product_type
                - default_sender_strategies
              example:
                country_code: AU
                product_type: SMS
                default_sender_strategies:
                  - sender_id: ClickSend
                    sender_type: alpha_tag
                    note: This is a test default sender
      security:
        - basicAuth: []
      parameters:
        - name: Content-Type
          in: header
          schema:
            type: string
          example: application/json
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create-default-sender'
              example:
                http_code: 200
                response_code: SUCCESS
                response_msg: Operation completed successfully
                data:
                  id: f99872cc-11a6-48ba-a9f2-bcfb6dd1e3d4
                  user_id: 123456
                  subaccount_id: 45678
                  country_code: AU
                  product_type: SMS
                  default_sender_strategies:
                    - sender_type: alpha_tag
                      sender_id: ClickSend
                      priority: 1
                      status: ENABLED
                      note: This is a test default sender
                  status: ENABLED
                  created_timestamp: '2021-08-02T00:00:00Z'
                  updated_timestamp: '2021-08-02T00:00:00Z'
        '400':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default_sender_error'
      x-codeSamples:
        - lang: curl
          source: |-
            curl --include \
                 --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
                 --request POST \
                 --header "Content-Type: application/json" \
                 --data-binary "    {
                    \"country_code\": \"AU\",
                    \"product_type\": \"SMS\",
                    \"default_sender_strategies\": [
                        {
                            \"sender_id\": \"ClickSend\",
                            \"sender_type\": \"alpha_tag\",
                            \"note\": \"This is a test default sender\"
                        }
                    ]
                }" \
            'https://rest.clicksend.com/v3/senders/default-senders'
    get:
      summary: Get List of Default Senders
      operationId: get-default-senders-list
      description: Retrieve a list of default senders for the current user
      security:
        - basicAuth: []
      parameters:
        - name: Content-Type
          in: header
          schema:
            type: string
          example: application/json
        - name: offset
          in: query
          schema:
            type: string
          required: false
          description: Page (offset) to be used for pagination
        - name: per_page
          in: query
          schema:
            type: integer
            default: 10
            minimum: 1
            maximum: 500
          required: false
          description: Size of the page in pagination
        - name: sort_by
          in: query
          schema:
            type: string
            default: created_timestamp
          required: false
          description: Parameter to sort the results by
        - name: sort_direction
          in: query
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
          required: false
          description: Direction of sorting
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get-default-senders-list'
              example:
                http_code: 200
                response_code: SUCCESS
                response_msg: Operation completed successfully
                data:
                  data:
                    - id: f99872cc-11a6-48ba-a9f2-bcfb6dd1e3d4
                      user_id: 123456
                      subaccount_id: 45678
                      country_code: AU
                      product_type: SMS
                      default_sender_strategies:
                        - sender_type: alpha_tag
                          sender_id: ClickSend
                          priority: 1
                          status: ENABLED
                          note: This is a test default sender
                      status: ENABLED
                      created_timestamp: '2021-08-02T00:00:00Z'
                      updated_timestamp: '2021-08-02T00:00:00Z'
                  per_page: 1
                  self_page_url: >-
                    https://api.clicksend.com/v4/sender_assignment_settings?offset=f99872cc-11a6-48ba-a9f2-bcfb6dd1e3d4#8fa5ebc2-777b-45db-a448-ec76a40d4384&per_page=1
                  next_page_url: >-
                    https://api.clicksend.com/v4/sender_assignment_settings?offset=f99872cc-11a6-48ba-a9f2-bcfb6dd1e3d4#8fa5ebc2-777b-45db-a448-ec76a40d4384&per_page=1
      x-codeSamples:
        - lang: curl
          source: >-
            curl --include \
                 --request GET \
                 --header "Content-Type: application/json" \
                 --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
            'https://rest.clicksend.com/v3/senders/default-senders?offset=f99872cc-11a6-48ba-a9f2-bcfb6dd1e3d4%238fa5ebc2-777b-45db-a448-ec76a40d4384&per_page=1&sort_by=created_timestamp&sort_direction=asc'
  /v3/default-senders/{default_sender_id}:
    patch:
      summary: Update Default Sender
      operationId: update-default-sender
      description: >-
        Updates the details of an existing default sender configuration.


        For more information on Sender IDs, please refer to [What is a Sender ID
        or Sender
        Number?](https://help.clicksend.com/article/4kgj7krx00-what-is-a-sender-id-or-sender-number)
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                default_sender_strategies:
                  type: array
                  description: >-
                    Array detailing sender strategies. Must contain exactly 1
                    element. Multiple strategies support coming soon.
                  minItems: 1
                  maxItems: 1
                  items:
                    type: object
                    properties:
                      sender_type:
                        type: string
                        enum:
                          - alpha_tag
                          - 10DLC
                          - tollfree
                          - own_number
                          - shortcode
                          - longcode
                          - shared_longcode
                        description: The type of sender for this strategy.
                      sender_id:
                        type: string
                        description: >
                          Unique identifier for the sender. Format varies based
                          on `sender_type`:

                          - `shortcode`: Numeric, 3-8 digits.

                          - `longcode`, `tollfree`, `10DLC`, `own_number`: 2-15
                          digits, may include `+` prefix.

                          - `alpha_tag`: 3-11 alphanumeric characters, must
                          include at least one letter or `+`.

                          - `shared_longcode`: Can be null or empty string.


                          > **Important:** The `sender_id` must be in valid
                          format, owned, and has ready to use status for the
                          corresponding `sender_type`.
                      sender_country_code:
                        type: string
                        description: >
                          The country code of the sender, using the ISO 3166-1
                          alpha-2 format (e.g., "US").


                          This field is required in the following cases:

                          - When `sender_type` is `own_number`, `longcode`,
                          `tollfree`, or `10DLC`

                          - When the `sender_id` follows the US/Canada number
                          format (starts with `+1`)


                          For all other cases, this field is optional.
                      note:
                        type: string
                        description: >-
                          Optional note providing additional context about the
                          sender strategy.
                        maxLength: 200
                    required:
                      - sender_type
                      - sender_id
              required:
                - default_sender_strategies
              example:
                default_sender_strategies:
                  - sender_id: ClickSend
                    sender_type: alpha_tag
                    note: This is a test default sender
      security:
        - basicAuth: []
      parameters:
        - name: Content-Type
          in: header
          schema:
            type: string
          example: application/json
        - name: default_sender_id
          in: path
          required: true
          schema:
            type: string
          description: The ID of the default sender to update
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/update-default-sender'
              example:
                http_code: 200
                response_code: SUCCESS
                response_msg: Operation completed successfully
                data:
                  id: f99872cc-11a6-48ba-a9f2-bcfb6dd1e3d4
                  user_id: 123456
                  subaccount_id: 45678
                  country_code: AU
                  product_type: SMS
                  default_sender_strategies:
                    - sender_type: alpha_tag
                      sender_id: ClickSend
                      priority: 1
                      status: ENABLED
                      note: This is a test default sender
                  status: ENABLED
                  created_timestamp: '2021-08-02T00:00:00Z'
                  updated_timestamp: '2021-08-02T00:00:00Z'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default_sender_error'
      x-codeSamples:
        - lang: curl
          source: >-
            curl --include \
                 --request PATCH \
                 --header "Content-Type: application/json" \
                 --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
                 --data-binary "{
              \"default_sender_strategies\": [
                {
                  \"sender_id\": \"ClickSend\",
                  \"sender_type\": \"alpha_tag\",
                  \"note\": \"This is a test default sender\"
                }
              ]
            }" \

            'https://rest.clicksend.com/v3/senders/default-senders/{default_sender_id}'
    get:
      summary: Get Default Sender Details
      operationId: get-default-sender-details
      description: >-
        Retrieve detailed information about a specific default sender
        configuration
      security:
        - basicAuth: []
      parameters:
        - name: Content-Type
          in: header
          schema:
            type: string
          example: application/json
        - name: default_sender_id
          in: path
          schema:
            type: string
          required: true
          description: The ID of the default sender to retrieve
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get-default-sender-details'
              example:
                http_code: 200
                response_code: SUCCESS
                response_msg: Operation completed successfully
                data:
                  id: f99872cc-11a6-48ba-a9f2-bcfb6dd1e3d4
                  user_id: 123456
                  subaccount_id: 45678
                  country_code: AU
                  product_type: SMS
                  default_sender_strategies:
                    - sender_type: alpha_tag
                      sender_id: ClickSend
                      priority: 1
                      status: ENABLED
                      note: This is a test default sender
                  status: ENABLED
                  created_timestamp: '2021-08-02T00:00:00Z'
                  updated_timestamp: '2021-08-02T00:00:00Z'
      x-codeSamples:
        - lang: curl
          source: >-
            curl --include \
                 --request GET \
                 --header "Content-Type: application/json" \
                 --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
            'https://rest.clicksend.com/v3/senders/default-senders/{default_sender_id}'
    delete:
      summary: Delete Default Sender
      operationId: delete-default-sender
      description: >-
        Removes a specified default sender setting. 

        If you don't configure a default sender and leave the `sender_id` string
        blank when sending an SMS,

        Smart Assign will pick the best suitable, compliant, available SenderID
        for you.
      security:
        - basicAuth: []
      parameters:
        - name: Content-Type
          in: header
          schema:
            type: string
          example: application/json
        - name: default_sender_id
          in: path
          schema:
            type: string
          required: true
          description: The ID of the default sender to delete
      responses:
        '204':
          description: Successful response (No Content)
      x-codeSamples:
        - lang: curl
          source: >-
            curl --include \
                 --request DELETE \
                 --header "Content-Type: application/json" \
                 --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
            'https://rest.clicksend.com/v3/senders/default-senders/{default_sender_id}'
  /v3/senders/compliant-sender-types:
    get:
      summary: List Compliant Sender Types
      operationId: list-compliant-sender-types
      description: Retrieves the list of compliant sender types for specific countries
      security:
        - basicAuth: []
      parameters:
        - in: query
          name: filter[product_type]
          required: true
          schema:
            type: string
            enum:
              - SMS
          description: Type of the product
          example: SMS
        - in: query
          name: filter[country_code][{index}]
          required: false
          schema:
            type: array
            items:
              type: string
            maxItems: 98
          description: >
            Array of recipient country codes (ISO 3166-1 alpha-2).

            If not specified, will get all compliant sender types for all
            countries.

            Replace `{index}` with the appropriate index value.


            <small>Example:</small>

            <small><code style="color:
            #424242;">filter[country_code][0]=US&filter[country_code][1]=AU</code></small>
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  http_code:
                    type: integer
                    description: HTTP status code of the response
                  response_code:
                    type: string
                    description: Code indicating the result of the response
                  response_msg:
                    type: string
                    description: Message providing additional information
                  data:
                    type: object
                    properties:
                      data:
                        type: array
                        items:
                          type: object
                          properties:
                            recipient_country_code:
                              type: string
                              pattern: ^[A-Z]{2}$
                              description: ISO 3166-1 alpha-2 formatted country code
                            blocked_sender_types:
                              type: array
                              items:
                                type: string
                              description: >-
                                List of blocked sender types in recipient
                                country
                            allowed_sender_types:
                              type: array
                              items:
                                type: object
                                properties:
                                  sender_type:
                                    type: string
                                    enum:
                                      - alpha_tag
                                      - 10DLC
                                      - tollfree
                                      - own_number
                                      - shortcode
                                      - longcode
                                      - shared_longcode
                                    description: Type of sender
                                  allowed_sender_countries:
                                    type: object
                                    properties:
                                      global:
                                        type: boolean
                                        description: >-
                                          Whether this sender type is allowed
                                          sending from any country
                                      country_codes:
                                        type: array
                                        items:
                                          type: string
                                        description: >-
                                          List of ISO 3166-1 alpha-2 formatted
                                          country codes
                                    required:
                                      - global
                                required:
                                  - sender_type
                                  - allowed_sender_countries
                          required:
                            - recipient_country_code
                            - blocked_sender_types
                            - allowed_sender_types
                        minItems: 1
                    required:
                      - data
                required:
                  - http_code
                  - response_code
                  - response_msg
                  - data
              example:
                http_code: 200
                response_code: SUCCESS
                response_msg: Compliant sender types retrieved successfully
                data:
                  data:
                    - recipient_country_code: AU
                      blocked_sender_types:
                        - tollfree
                        - 10DLC
                      allowed_sender_types:
                        - sender_type: longcode
                          allowed_sender_countries:
                            global: false
                            country_codes:
                              - AU
                              - US
                              - GB
                        - sender_type: alpha_tag
                          allowed_sender_countries:
                            global: true
                    - recipient_country_code: US
                      blocked_sender_types:
                        - own_number
                      allowed_sender_types:
                        - sender_type: 10DLC
                          allowed_sender_countries:
                            global: false
                            country_codes:
                              - US
                              - CA
      x-codeSamples:
        - lang: curl
          source: >
            curl --include \
                 --request GET \
                 --header "Content-Type: application/json" \
                 --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
            'https://rest.clicksend.com/v3/senders/compliant-sender-types?filter[product_type]=SMS&filter[country_code][0]=AU&filter[country_code][1]=US'
