{
  "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"
          },
          "notified_timestamp": {
            "type": "string",
            "nullable": true,
            "description": "The timestamp when the user was last notified about this number, if applicable.",
            "example": null
          },
          "is_nearing_expiration": {
            "type": "boolean",
            "description": "Indicates whether the phone number verification is nearing its expiration date:\n- **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.\n- **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...](/#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 \\\n     --header \"Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==\"  \\\n     --request GET \\\n\n'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...](/#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 \\\n     --header \"Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==\"  \\\n     --request GET \\\n\n'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...](/#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 \\\n     --header \"Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==\"  \\\n     --request PATCH \\\n     --data-binary \"    {\n        \\\"label\\\": \\\"My phone number\\\"\n    }\" \\\n\n'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...](/#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 \\\n     --header \"Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==\"  \\\n     --request DELETE \\\n\n'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...](/#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 \\\n     --header \"Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==\"  \\\n     --request POST \\\n     --data-binary \"    {\n        \\\"label\\\": \\\"My phone number\\\",\n        \\\"phone_number\\\": \\\"+61412345678\\\",\n        \\\"country\\\": \\\"AU\\\"\n    }\" \\\n\n'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...](/#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 \\\n     --header \"Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==\"  \\\n     --request POST \\\n     --data-binary \"    {\n        \\\"code\\\": \\\"428312\\\",\n        \\\"phone_number\\\": \\\"+61437887111\\\",\n        \\\"country\\\": \\\"AU\\\"\n    }\" \\\n\n'https://rest.clicksend.com/v3/own-numbers/verifications/e9bcb7cc-d42b-47cd-ad1f-8677307d4040/verify'"
          }
        ]
      }
    }
  }
}