openapi: 3.0.0
info:
  title: Own Numbers
  description: >-
    API endpoints for managing and verifying user-owned numbers as sender IDs
    for messaging services.
servers:
  - url: https://rest.clicksend.com
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
  schemas:
    own_number:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier for the record.
          example: 8fa5ebc2-777b-45db-a448-ec76a40d4384
        account_id:
          type: string
          format: uuid
          description: The unique identifier for the account.
          example: 85edb794-ee6d-4a38-9f63-c5fa8acf0d79
        workspace_id:
          type: string
          format: uuid
          description: The unique identifier for the workspace.
          example: 85edb794-ee6d-4a38-9f63-c5fa8acf0d79
        user_id:
          type: string
          format: uuid
          description: The unique identifier for the user.
          example: 85edb794-ee6d-4a38-9f63-c5fa8acf0d79
        phone_number:
          type: string
          description: The user's phone number.
          example: '+61412345678'
        country:
          type: string
          description: The country code of the phone number.
          example: AU
        label:
          type: string
          description: A label for the phone number.
          example: My phone number
        status:
          type: string
          description: The status of the phone number.
          example: APPROVED
        verified_timestamp:
          type: string
          format: date-time
          description: The timestamp when the phone number was verified.
          example: '2023-08-31T12:00:00Z'
        is_nearing_expiration:
          type: boolean
          description: >-
            Indicates whether the phone number verification is nearing its
            expiration date:

            - **true:** The verification was completed more than 11 months ago
            and will expire soon. You should re-verify your phone number to
            maintain uninterrupted service.

            - **false:** The verification is still valid and not approaching
            expiration.
          example: true
        created_timestamp:
          type: string
          format: date-time
          description: The timestamp when the record was created.
          example: '2023-08-25T08:00:00Z'
        updated_timestamp:
          type: string
          format: date-time
          description: The timestamp when the record was last updated.
          example: '2023-08-25T08:30:00Z'
    list-own-numbers:
      type: object
      properties:
        own_numbers:
          type: array
          description: The list of own numbers.
          items:
            $ref: '#/components/schemas/own_number'
        _metadata:
          type: object
          description: The metadata.
          properties:
            pagination:
              type: object
              properties:
                self:
                  type: string
                  description: The URL of the current page.
                  example: >-
                    https://rest.clicksend.com/v3/own-numbers?offset=f99872cc-11a6-48ba-a9f2-bcfb6dd1e3d4#8fa5ebc2-777b-45db-a448-ec76a40d4384&page_size=10
                next:
                  type: string
                  description: The URL of the next page.
                  example: >-
                    https://rest.clicksend.com/v3/own-numbers?offset=f99872cc-11a6-48ba-a9f2-bcfb6dd1e3d4#8fa5ebc2-777b-45db-a448-ec76a40d4384&page_size=10
                page_size:
                  type: integer
                  description: The number of items returned per page.
                  example: 10
    request-own-number-verification-otp:
      type: object
      properties:
        id:
          type: string
          description: The ID of the verification request.
          example: db630385-cb76-457d-8f16-76df1b394257
        own_number_id:
          type: string
          description: The ID of the own number.
          example: db630385-cb76-457d-8f16-76df1b394257
        status:
          type: string
          description: The status of the verification request.
          example: APPROVED
        expires_timestamp:
          type: string
          description: The expiration timestamp of the verification request.
          example: '2023-08-31T12:00:00Z'
        remaining_attempts:
          type: number
          description: The number of remaining attempts.
          example: 2
        created_timestamp:
          type: string
          description: The creation timestamp of the verification request.
          example: '2023-08-25T08:00:00Z'
        updated_timestamp:
          type: string
          description: The last update timestamp of the verification request.
          example: '2023-08-25T08:10:00Z'
    verify-own-number-otp:
      type: object
      properties:
        id:
          type: string
          description: The ID of the verification request.
          example: db630385-cb76-457d-8f16-76df1b394257
        own_number_id:
          type: string
          description: The ID of the own number.
          example: db630385-cb76-457d-8f16-76df1b394257
        status:
          type: string
          description: The status of the verification request.
          example: APPROVED
        expires_timestamp:
          type: string
          description: The expiration timestamp of the verification request.
          example: '2023-08-31T12:00:00Z'
        remaining_attempts:
          type: number
          description: The number of remaining attempts.
          example: 1
        created_timestamp:
          type: string
          description: The creation timestamp of the verification request.
          example: '2023-08-25T08:00:00Z'
        updated_timestamp:
          type: string
          description: The last update timestamp of the verification request.
          example: '2023-08-25T08:15:00Z'
paths:
  /v3/own-numbers:
    get:
      summary: List Own Numbers
      operationId: list-own-numbers
      description: "_List own numbers._\n\n### Parameters\n\n| Parameter | In | Type | Required | Description |\n| --- | --- | --- | --- | --- |\n| offset | query | uuid | false | Page(offset) to be used for pagination. Example:\_`offset=f99872cc-11a6-48ba-a9f2-bcfb6dd1e3d4#8fa5ebc2-777b-45db-a448-ec76a40d4384` |\n| page_size | query | integer | false | Number of records per page. Default: 10. Range \\[1..500\\] |\n| filter\\[status\\]\\[\\] | query | string | false | Filter by statuses. Value must be in enum \\[`PENDING`,\_`APPROVED`,\_`REJECTED`\\]. For example:\_`filter[status][0]=PENDING&filter[status][1]=APPROVED`\_. |\n| sort_by | query | string | false | Sort by parameter. Default:\_`created_timestamp` |\n| sort_direction | query | string | false | Direction of sorting. Default:\_`asc`. Value must be in enum \\[`asc`,\_`desc`\\]. |\n\nRefer to\_[Status Codes](/#status-codes)\_for definitions of HTTP status code responses.\n\n\_This endpoint requires authentication,\_[more info...](https://developers.clicksend.com/docs/rest/v3/#authentication)"
      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/list-own-numbers'
      x-codeSamples:
        - lang: curl
          source: >-
            curl --include \
                 --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
                 --request GET \

            'https://rest.clicksend.com/v3/own-numbers?page_size=50&filter[status][0]=PENDING&filter[status][1]=APPROVED&sort_by=created_timestamp&sort_direction=asc'
  /v3/own-numbers/{own_number_id}:
    get:
      summary: Get Own Number Detail
      operationId: get-own-number-detail
      description: "_Get a specific own numbers._\n\n### Parameters\n\n| Parameter | In | Type | Required | Description |\n| --- | --- | --- | --- | --- |\n| own_number_id | path | uuid | true | ID of the own number |\n\nRefer to\_[Status Codes](/#status-codes)\_for definitions of HTTP status code responses.\n\nThis endpoint requires authentication,\_[more info...](https://developers.clicksend.com/docs/rest/v3/#authentication)"
      security:
        - basicAuth: []
      parameters:
        - name: Content-Type
          in: header
          schema:
            type: string
          example: application/json
        - name: own_number_id
          in: path
          schema:
            type: string
          required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/own_number'
      x-codeSamples:
        - lang: curl
          source: >-
            curl --include \
                 --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
                 --request GET \

            'https://rest.clicksend.com/v3/own-numbers/60b34fe9-1b45-43f8-b9ef-06b7fdb3a9f5'
    patch:
      summary: Update Own Number
      operationId: update-own-number
      description: "_Update details of a specific own numbers._\n\n### Parameters\n\n| Parameter | In | Type | Required | Description |\n| --- | --- | --- | --- | --- |\n| own_number_id | path | uuid | true | ID of the own number |\n\n### Properties\n\n| Name | Type | Required | Restrictions | Description |\n| --- | --- | --- | --- | --- |\n| label | string | false | none | Custom label for phone number. Length must be between 1 - 200 characters. |\n\nRefer to\_[Status Codes](/#status-codes)\_for definitions of HTTP status code responses.\n\nThis endpoint requires authentication,\_[more info...](https://developers.clicksend.com/docs/rest/v3/#authentication)"
      requestBody:
        content: {}
      parameters:
        - name: own_number_id
          in: path
          schema:
            type: string
          required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/own_number'
      x-codeSamples:
        - lang: curl
          source: >-
            curl --include \
                 --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
                 --request PATCH \
                 --data-binary "    {
                    \"label\": \"My phone number\"
                }" \

            'https://rest.clicksend.com/v3/own-numbers/60b34fe9-1b45-43f8-b9ef-06b7fdb3a9f5'
    delete:
      summary: Delete Own Number
      operationId: delete-own-number
      description: "_Delete a specific own numbers._\n\n### Parameters\n\n| Parameter | In | Type | Required | Description |\n| --- | --- | --- | --- | --- |\n| own_number_id | path | uuid | true | ID of the own number |\n\nRefer to\_[Status Codes](/#status-codes)\_for definitions of HTTP status code responses.\n\nThis endpoint requires authentication,\_[more info...](https://developers.clicksend.com/docs/rest/v3/#authentication)"
      security:
        - basicAuth: []
      parameters:
        - name: Content-Type
          in: header
          schema:
            type: string
          example: application/json
        - name: own_number_id
          in: path
          schema:
            type: string
          required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/own_number'
      x-codeSamples:
        - lang: curl
          source: >-
            curl --include \
                 --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
                 --request DELETE \

            'https://rest.clicksend.com/v3/own-numbers/60b34fe9-1b45-43f8-b9ef-06b7fdb3a9f5'
  /v3/own-numbers/verifications:
    post:
      summary: Request Own Number Verification OTP
      operationId: request-own-number-verification-otp
      description: "_Request to generate own number verification OTP_\n\n### Properties\n\n| Name | Type | Required | Restrictions | Description |\n| --- | --- | --- | --- | --- |\n| label | string | false | none | Custom label for phone number. Length must be between 1 - 200 characters. |\n| phone_number | string | true | none | Phone number. |\n| country | string | false | none | Country code. |\n\nRefer to\_[Status Codes](/#status-codes)\_for definitions of HTTP status code responses.\n\nThis endpoint requires authentication,\_[more info...](https://developers.clicksend.com/docs/rest/v3/#authentication)"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                label:
                  type: string
                phone_number:
                  type: string
                country:
                  type: string
              example:
                label: My phone number
                phone_number: '+61412345678'
                country: AU
      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/request-own-number-verification-otp'
      x-codeSamples:
        - lang: curl
          source: |-
            curl --include \
                 --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
                 --request POST \
                 --data-binary "    {
                    \"label\": \"My phone number\",
                    \"phone_number\": \"+61412345678\",
                    \"country\": \"AU\"
                }" \

            'https://rest.clicksend.com/v3/own-numbers/verifications'
  /v3/own-numbers/verifications/{verification_id}/verify:
    post:
      summary: Verify Own Number OTP
      operationId: verify-own-number-otp
      description: "_Request to verify an OTP for Own Number verification_\n\n### Parameters\n\n| Parameter | In | Type | Required | Description |\n| --- | --- | --- | --- | --- |\n| verification_id | path | uuid | true | ID of the Own Number verification |\n\n### Properties\n\n| Name | Type | Required | Restrictions | Description |\n| --- | --- | --- | --- | --- |\n| code | string | true | none | OTP code. Length must be 6 characters |\n| phone_number | string | true | none | Phone number. |\n| country | string | false | none | Country code. |\n\nRefer to\_[Status Codes](/#status-codes)\_for definitions of HTTP status code responses.\n\nThis endpoint requires authentication,\_[more info...](https://developers.clicksend.com/docs/rest/v3/#authentication)"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                country:
                  type: string
                phone_number:
                  type: string
                code:
                  type: string
              example:
                country: AU
                phone_number: '+61437887111'
                code: '428312'
      security:
        - basicAuth: []
      parameters:
        - name: Content-Type
          in: header
          schema:
            type: string
          example: application/json
        - name: verification_id
          in: path
          schema:
            type: string
          required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/verify-own-number-otp'
      x-codeSamples:
        - lang: curl
          source: >-
            curl --include \
                 --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
                 --request POST \
                 --data-binary "    {
                    \"code\": \"428312\",
                    \"phone_number\": \"+61437887111\",
                    \"country\": \"AU\"
                }" \

            'https://rest.clicksend.com/v3/own-numbers/verifications/e9bcb7cc-d42b-47cd-ad1f-8677307d4040/verify'
