ResellerHQ
Log inTry the sandbox free
GuidesAPI reference
Numbers

Renew a number

POST
/v1/numbers/{id}/renew

Adds time to the end of the rental and charges your wallet.

Authorization

apiKey
headerAuthorizationBearer <token>

An API key from the Developers page. rhq_test_ keys reach the sandbox, rhq_live_ keys the live side.

Path Parameters

id*string

Header Parameters

Idempotency-Key?string

A value unique to this request, such as a UUID. A retry with the same key within 24 hours returns the first outcome instead of running again.

Length8 <= length <= 200

Request Body

application/json
  1. body
Default{}
duration?string

How long to add. Defaults to the number's renewDuration

Value in"12h""1d""7d""30d""180d""365d"

Response Body

Success

application/json
  1. response

Success

id*string
number*string

Digits only, as issued by the carrier

country*string

ISO 3166-1 alpha-2 country code, for example US or GB

Match^[A-Z]{2}$
product*string

any_service receives SMS from anyone; single_service is locked to one sender

Value in"any_service""single_service"
service*|

The one service a single_service number receives from

status*string
Value in"active""expired""cancelled"
customerId*|

The customer this was bought for, if any

orderId*string
nickname*string|null
startsAt*string

ISO 8601 timestamp

Formatdate-time
endsAt*string

ISO 8601 timestamp

Formatdate-time
autoRenew*boolean

Whether it is extended shortly before it ends

renewDuration*string

How long each automatic renewal adds

Value in"12h""1d""7d""30d""180d""365d"
unitPrice*integer

Price of one rental period, in minor units

customerPrice*|

A price per renewal fixed for the customer on this number alone, in their list's currency. It beats their contract and list. Null when there is none

paidTotal*integer

Everything charged for this number so far, in minor units

messageCount*integer
cancellableFrom*|

While the provider still holds a new number, the earliest it may be cancelled. Null when there is no wait left to name, or the number is no longer active

createdAt*string

ISO 8601 timestamp

Formatdate-time
curl -X POST "https://example.com/v1/numbers/num_01K6XJ4Q8ZT3M9R5V2B7WDHNCA/renew" \  -H "Idempotency-Key: 2f1c9a52-7d0e-4a8e-9a53-0c1f6f3f2b11" \  -H "Content-Type: application/json" \  -d '{}'
{  "id": "num_01K6XJ4Q8ZT3M9R5V2B7WDHNCA",  "number": "15550100002",  "country": "US",  "product": "any_service",  "service": null,  "status": "active",  "customerId": "cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA",  "orderId": "ord_01K6XJ4Q8ZT3M9R5V2B7WDHNCA",  "nickname": "Support line",  "startsAt": "2026-10-07T11:04:31.000Z",  "endsAt": "2026-11-06T11:04:31.000Z",  "autoRenew": true,  "renewDuration": "30d",  "unitPrice": 1200,  "customerPrice": null,  "paidTotal": 1200,  "messageCount": 3,  "cancellableFrom": null,  "createdAt": "2026-10-07T11:04:31.000Z"}

Update a number PATCH

Change the nickname, the renewal settings or the price fixed for the customer. Fields you leave out stay as they are.

Cancel a number POST

Only possible before the number has received a message, and not before `cancellableFrom` while the provider still holds a new number (5 minutes for most).