Skip to content
clearance.rest

Update the metadata of a number

PATCH
/numbers/items/{id}
curl --request PATCH \
  --url https://api.clearance.rest/numbers/items/example \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "metadata": { "additionalProperty": "example" } }'

JSON Merge Patch (RFC 7396) on the project-scoped metadata. Send If-Match: "<metadata_version>" to update only when the version still matches; otherwise the response is 412 metadata_version_mismatch and error.details.current_version holds the current version.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

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

Resource id.

Header Parameters

Section titled “Header Parameters”
If-Match
string

Metadata version from the last read (the metadata_version field or the ETag header), for example "3". The update fails with 412 and error.details.current_version when it no longer matches; * matches any version. Without the header the update is unconditional.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

JSON Merge Patch (RFC 7396) of the metadata: keys set to null are removed, arrays are replaced.

object
metadata
required

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

object
key
additional properties
Examplegenerated
{
  "metadata": {
    "additionalProperty": "example"
  }
}

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
Example
{
  "success": true,
  "item": {
    "type": "temporary",
    "status": "ACTIVE"
  }
}

400

Section titled “400”

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
}

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
}

412

Section titled “412”

Default Response

Media typeapplication/json

The If-Match version does not match the current metadata version.

object
success
required
boolean
error
required
object
code
required
string
Allowed values: metadata_version_mismatch
message
required
string
details
required
object
current_version
required

The current metadata_version; read the resource again and retry.

integer
>= -9007199254740991 <= 9007199254740991
Example
{
  "success": false,
  "error": {
    "code": "metadata_version_mismatch"
  }
}

413

Section titled “413”

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
}