List numbers
GET
The numbers you hold or have held, newest first.
apiKeyheader
AuthorizationBearer <token>An API key from the Developers page. rhq_test_ keys reach the sandbox, rhq_live_ keys the live side.
limit?integerHow many to return
Range
1 <= value <= 100Default
25cursor?stringnextCursor from the previous page
status?stringValue in
"active""expired""cancelled"customerId?stringcountry?stringISO 3166-1 alpha-2 country code, for example US or GB
Match
^[A-Z]{2}$autoRenew?stringtrue or false
q?stringDigits to look for anywhere in the number, for example its last four
Length
length <= 40Success
application/json- response
Success
data*array<>nextCursor*|Pass as cursor for the next page. null on the last page
total*integerHow many match across every page
Range
0 <= valuecurl -X GET "https://example.com/v1/numbers?customerId=cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA&country=US"{ "data": [ { "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, "createdAt": "2026-10-07T11:04:31.000Z" } ], "nextCursor": null, "total": 1}