Skip to content
clearance.rest

Release a number

POST
/numbers/items/{id}/release
curl --request POST \
  --url https://api.clearance.rest/numbers/items/example/release \
  --header 'X-API-Key: <X-API-Key>'

Temporary numbers: released before any SMS arrived, the rental price is credited back. Monthly numbers: returned and no longer renewed. Device numbers: disconnected from the project.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string
>= 1 characters

Resource id.

Responses

Section titled “Responses”

200

Section titled “200”

Default Response

Media typeapplication/json
object
success
required
boolean
item
required

A number of the project with its status and metadata.

object
id
required
string
phone_number
required
string
type
required
string
Allowed values: temporary monthly device
status
required
string
Allowed values: ACTIVE OFFLINE SIM_REMOVED MOVED RELEASED EXPIRED UNASSIGNED
status_reason
required
string | null
country
required
string | null
capabilities
required
Any of:
object
key
additional properties
boolean
assigned_at
required
Any of:

UTC timestamp (ISO 8601).

string
ended_at
required
Any of:

UTC timestamp (ISO 8601).

string
expires_at
required
Any of:

UTC timestamp (ISO 8601).

string
renews_at
required
Any of:

UTC timestamp (ISO 8601).

string
released_reason
required
string | null
created_at
required

UTC timestamp (ISO 8601).

string
updated_at
required

UTC timestamp (ISO 8601).

string
temporary
required
Any of:
object
service
required
string | null
operator
required
string | null
first_sms_at
required
Any of:

UTC timestamp (ISO 8601).

string
device
required
Any of:
object
carrier_name
required
string | null
present
required
boolean
verified_at
required
Any of:

UTC timestamp (ISO 8601).

string
last_seen_at
required
Any of:

UTC timestamp (ISO 8601).

string
online
required
boolean
metadata
required
Any of:

Free-form JSON object (at most 16 KB, 5 levels deep, keys up to 64 characters).

object
key
additional properties
metadata_version
required

Increases on every change; use it in If-Match.

integer
>= -9007199254740991 <= 9007199254740991
refunded
required

USD credited back to the balance (a temporary number released before any SMS arrived).

number
Example
{
  "success": true,
  "item": {
    "type": "temporary",
    "status": "ACTIVE"
  }
}

401

Section titled “401”

Default Response

Media typeapplication/json

Error envelope returned by every JSON endpoint.

object
success
required
boolean
error
required
object
code
required

Machine-readable error code (snake_case).

string
message
required

Human-readable message.

string
details

Extra context for the error.

object
key
additional properties
Example
{
  "success": false
}

403

Section titled “403”

Default Response

Media typeapplication/json

Error envelope returned by every JSON endpoint.

object
success
required
boolean
error
required
object
code
required

Machine-readable error code (snake_case).

string
message
required

Human-readable message.

string
details

Extra context for the error.

object
key
additional properties
Example
{
  "success": false
}

404

Section titled “404”

Default Response

Media typeapplication/json

Error envelope returned by every JSON endpoint.

object
success
required
boolean
error
required
object
code
required

Machine-readable error code (snake_case).

string
message
required

Human-readable message.

string
details

Extra context for the error.

object
key
additional properties
Example
{
  "success": false
}

409

Section titled “409”

Default Response

Media typeapplication/json

Error envelope returned by every JSON endpoint.

object
success
required
boolean
error
required
object
code
required

Machine-readable error code (snake_case).

string
message
required

Human-readable message.

string
details

Extra context for the error.

object
key
additional properties
Example
{
  "success": false
}

502

Section titled “502”

Default Response

Media typeapplication/json

Error envelope returned by every JSON endpoint.

object
success
required
boolean
error
required
object
code
required

Machine-readable error code (snake_case).

string
message
required

Human-readable message.

string
details

Extra context for the error.

object
key
additional properties
Example
{
  "success": false
}

503

Section titled “503”

Default Response

Media typeapplication/json

Error envelope returned by every JSON endpoint.

object
success
required
boolean
error
required
object
code
required

Machine-readable error code (snake_case).

string
message
required

Human-readable message.

string
details

Extra context for the error.

object
key
additional properties
Example
{
  "success": false
}