Own Numbers

Messaging

Sender IDs

Own Numbers

API endpoints for managing and verifying user-owned numbers as sender IDs for messaging services.

Download OpenAPI description

own-numbers.json

own-numbers.yaml

Servers

https://rest.clicksend.com/

List Own Numbers

Request

List own numbers.

Parameters

Parameter	In	Type	Required	Description
offset	query	uuid	false	Page(offset) to be used for pagination. Example: `offset=f99872cc-11a6-48ba-a9f2-bcfb6dd1e3d4#8fa5ebc2-777b-45db-a448-ec76a40d4384`
page_size	query	integer	false	Number of records per page. Default: 10. Range [1..500]
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` .
sort_by	query	string	false	Sort by parameter. Default: `created_timestamp`
sort_direction	query	string	false	Direction of sorting. Default: `asc`. Value must be in enum [`asc`, `desc`].

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...

Security

basicAuth

Headers

Content-Typestring

Example: application/json

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'

Responses

Successful response

Bodyapplication/json

own_numbersArray of objects(own_number)

The list of own numbers.

_metadataobject

The metadata.

Response

application/json

{
  "own_numbers": [
    { … }
  ],
  "_metadata": {
    "pagination": { … }
  }
}

Get Own Number Detail

Request

Get a specific own numbers.

Parameters

Parameter	In	Type	Required	Description
own_number_id	path	uuid	true	ID of the own number

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...

Security

basicAuth

Path

own_number_idstringrequired

Headers

Content-Typestring

Example: application/json

curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
     --request GET \

'https://rest.clicksend.com/v3/own-numbers/60b34fe9-1b45-43f8-b9ef-06b7fdb3a9f5'

Responses

Successful response

Bodyapplication/json

idstring(uuid)

The unique identifier for the record.

Example: "8fa5ebc2-777b-45db-a448-ec76a40d4384"

account_idstring(uuid)

The unique identifier for the account.

Example: "85edb794-ee6d-4a38-9f63-c5fa8acf0d79"

workspace_idstring(uuid)

The unique identifier for the workspace.

Example: "85edb794-ee6d-4a38-9f63-c5fa8acf0d79"

user_idstring(uuid)

The unique identifier for the user.

Example: "85edb794-ee6d-4a38-9f63-c5fa8acf0d79"

phone_numberstring

The user's phone number.

Example: "+61412345678"

countrystring

The country code of the phone number.

Example: "AU"

labelstring

A label for the phone number.

Example: "My phone number"

statusstring

The status of the phone number.

Example: "APPROVED"

verified_timestampstring(date-time)

The timestamp when the phone number was verified.

Example: "2023-08-31T12:00:00Z"

is_nearing_expirationboolean

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_timestampstring(date-time)

The timestamp when the record was created.

Example: "2023-08-25T08:00:00Z"

updated_timestampstring(date-time)

The timestamp when the record was last updated.

Example: "2023-08-25T08:30:00Z"

Response

application/json

{
  "id": "8fa5ebc2-777b-45db-a448-ec76a40d4384",
  "account_id": "85edb794-ee6d-4a38-9f63-c5fa8acf0d79",
  "workspace_id": "85edb794-ee6d-4a38-9f63-c5fa8acf0d79",
  "user_id": "85edb794-ee6d-4a38-9f63-c5fa8acf0d79",
  "phone_number": "+61412345678",
  "country": "AU",
  "label": "My phone number",
  "status": "APPROVED",
  "verified_timestamp": "2023-08-31T12:00:00Z",
  "is_nearing_expiration": true,
  "created_timestamp": "2023-08-25T08:00:00Z",
  "updated_timestamp": "2023-08-25T08:30:00Z"
}

Update Own Number

Request

Update details of a specific own numbers.

Parameters

Parameter	In	Type	Required	Description
own_number_id	path	uuid	true	ID of the own number

Properties

Name	Type	Required	Restrictions	Description
label	string	false	none	Custom label for phone number. Length must be between 1 - 200 characters.

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...

Path

own_number_idstringrequired

Body

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'

Responses

Successful response

Bodyapplication/json

idstring(uuid)

The unique identifier for the record.

Example: "8fa5ebc2-777b-45db-a448-ec76a40d4384"

account_idstring(uuid)

The unique identifier for the account.

Example: "85edb794-ee6d-4a38-9f63-c5fa8acf0d79"

workspace_idstring(uuid)

The unique identifier for the workspace.

Example: "85edb794-ee6d-4a38-9f63-c5fa8acf0d79"

user_idstring(uuid)

The unique identifier for the user.

Example: "85edb794-ee6d-4a38-9f63-c5fa8acf0d79"

phone_numberstring

The user's phone number.

Example: "+61412345678"

countrystring

The country code of the phone number.

Example: "AU"

labelstring

A label for the phone number.

Example: "My phone number"

statusstring

The status of the phone number.

Example: "APPROVED"

verified_timestampstring(date-time)

The timestamp when the phone number was verified.

Example: "2023-08-31T12:00:00Z"

is_nearing_expirationboolean

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_timestampstring(date-time)

The timestamp when the record was created.

Example: "2023-08-25T08:00:00Z"

updated_timestampstring(date-time)

The timestamp when the record was last updated.

Example: "2023-08-25T08:30:00Z"

Response

application/json

{
  "id": "8fa5ebc2-777b-45db-a448-ec76a40d4384",
  "account_id": "85edb794-ee6d-4a38-9f63-c5fa8acf0d79",
  "workspace_id": "85edb794-ee6d-4a38-9f63-c5fa8acf0d79",
  "user_id": "85edb794-ee6d-4a38-9f63-c5fa8acf0d79",
  "phone_number": "+61412345678",
  "country": "AU",
  "label": "My phone number",
  "status": "APPROVED",
  "verified_timestamp": "2023-08-31T12:00:00Z",
  "is_nearing_expiration": true,
  "created_timestamp": "2023-08-25T08:00:00Z",
  "updated_timestamp": "2023-08-25T08:30:00Z"
}

Delete Own Number

Request

Delete a specific own numbers.

Parameters

Parameter	In	Type	Required	Description
own_number_id	path	uuid	true	ID of the own number

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...

Security

basicAuth

Path

own_number_idstringrequired

Headers

Content-Typestring

Example: application/json

curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
     --request DELETE \

'https://rest.clicksend.com/v3/own-numbers/60b34fe9-1b45-43f8-b9ef-06b7fdb3a9f5'

Responses

Successful response

Bodyapplication/json

idstring(uuid)

The unique identifier for the record.

Example: "8fa5ebc2-777b-45db-a448-ec76a40d4384"

account_idstring(uuid)

The unique identifier for the account.

Example: "85edb794-ee6d-4a38-9f63-c5fa8acf0d79"

workspace_idstring(uuid)

The unique identifier for the workspace.

Example: "85edb794-ee6d-4a38-9f63-c5fa8acf0d79"

user_idstring(uuid)

The unique identifier for the user.

Example: "85edb794-ee6d-4a38-9f63-c5fa8acf0d79"

phone_numberstring

The user's phone number.

Example: "+61412345678"

countrystring

The country code of the phone number.

Example: "AU"

labelstring

A label for the phone number.

Example: "My phone number"

statusstring

The status of the phone number.

Example: "APPROVED"

verified_timestampstring(date-time)

The timestamp when the phone number was verified.

Example: "2023-08-31T12:00:00Z"

is_nearing_expirationboolean

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_timestampstring(date-time)

The timestamp when the record was created.

Example: "2023-08-25T08:00:00Z"

updated_timestampstring(date-time)

The timestamp when the record was last updated.

Example: "2023-08-25T08:30:00Z"

Response

application/json

{
  "id": "8fa5ebc2-777b-45db-a448-ec76a40d4384",
  "account_id": "85edb794-ee6d-4a38-9f63-c5fa8acf0d79",
  "workspace_id": "85edb794-ee6d-4a38-9f63-c5fa8acf0d79",
  "user_id": "85edb794-ee6d-4a38-9f63-c5fa8acf0d79",
  "phone_number": "+61412345678",
  "country": "AU",
  "label": "My phone number",
  "status": "APPROVED",
  "verified_timestamp": "2023-08-31T12:00:00Z",
  "is_nearing_expiration": true,
  "created_timestamp": "2023-08-25T08:00:00Z",
  "updated_timestamp": "2023-08-25T08:30:00Z"
}

Request Own Number Verification OTP

Request

Request to generate own number verification OTP

Properties

Name	Type	Required	Restrictions	Description
label	string	false	none	Custom label for phone number. Length must be between 1 - 200 characters.
phone_number	string	true	none	Phone number.
country	string	false	none	Country code.

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...

Security

basicAuth

Headers

Content-Typestring

Example: application/json

Bodyapplication/json

labelstring

Example: "My phone number"

phone_numberstring

Example: "+61412345678"

countrystring

Example: "AU"

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'

Responses

Successful response

Bodyapplication/json

idstring

The ID of the verification request.

Example: "db630385-cb76-457d-8f16-76df1b394257"

own_number_idstring

The ID of the own number.

Example: "db630385-cb76-457d-8f16-76df1b394257"

statusstring

The status of the verification request.

Example: "APPROVED"

expires_timestampstring

The expiration timestamp of the verification request.

Example: "2023-08-31T12:00:00Z"

remaining_attemptsnumber

The number of remaining attempts.

Example: 2

created_timestampstring

The creation timestamp of the verification request.

Example: "2023-08-25T08:00:00Z"

updated_timestampstring

The last update timestamp of the verification request.

Example: "2023-08-25T08:10:00Z"

Response

application/json

{
  "id": "db630385-cb76-457d-8f16-76df1b394257",
  "own_number_id": "db630385-cb76-457d-8f16-76df1b394257",
  "status": "APPROVED",
  "expires_timestamp": "2023-08-31T12:00:00Z",
  "remaining_attempts": 2,
  "created_timestamp": "2023-08-25T08:00:00Z",
  "updated_timestamp": "2023-08-25T08:10:00Z"
}

Verify Own Number OTP

Request

Request to verify an OTP for Own Number verification

Parameters

Parameter	In	Type	Required	Description
verification_id	path	uuid	true	ID of the Own Number verification

Properties

Name	Type	Required	Restrictions	Description
code	string	true	none	OTP code. Length must be 6 characters
phone_number	string	true	none	Phone number.
country	string	false	none	Country code.

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...

Security

basicAuth

Path

verification_idstringrequired

Headers

Content-Typestring

Example: application/json

Bodyapplication/json

countrystring

Example: "AU"

phone_numberstring

Example: "+61437887111"

codestring

Example: "428312"

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'

Responses

Successful response

Bodyapplication/json

idstring

The ID of the verification request.

Example: "db630385-cb76-457d-8f16-76df1b394257"

own_number_idstring

The ID of the own number.

Example: "db630385-cb76-457d-8f16-76df1b394257"

statusstring

The status of the verification request.

Example: "APPROVED"

expires_timestampstring

The expiration timestamp of the verification request.

Example: "2023-08-31T12:00:00Z"

remaining_attemptsnumber

The number of remaining attempts.

Example: 1

created_timestampstring

The creation timestamp of the verification request.

Example: "2023-08-25T08:00:00Z"

updated_timestampstring

The last update timestamp of the verification request.

Example: "2023-08-25T08:15:00Z"

Response

application/json

{
  "id": "db630385-cb76-457d-8f16-76df1b394257",
  "own_number_id": "db630385-cb76-457d-8f16-76df1b394257",
  "status": "APPROVED",
  "expires_timestamp": "2023-08-31T12:00:00Z",
  "remaining_attempts": 1,
  "created_timestamp": "2023-08-25T08:00:00Z",
  "updated_timestamp": "2023-08-25T08:15:00Z"
}

Own Numbers

List Own Numbers

Request

Parameters

Responses

Was this helpful?

Get Own Number Detail

Request

Parameters

Responses

Was this helpful?

Update Own Number

Request

Parameters

Properties

Responses

Was this helpful?

Delete Own Number

Request

Parameters

Responses

Was this helpful?

Request Own Number Verification OTP

Request

Properties

Responses

Was this helpful?

Verify Own Number OTP

Request

Parameters

Properties

Responses

Was this helpful?