curl --request DELETE \
--url https://api.blujay.io/v1/phone-numbers/{phone_number_id} \
--header 'Authorization: Bearer <token>'const options = {method: 'DELETE', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.blujay.io/v1/phone-numbers/{phone_number_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.blujay.io/v1/phone-numbers/{phone_number_id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.delete(url, headers=headers)
print(response.text)package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.blujay.io/v1/phone-numbers/{phone_number_id}"
req, _ := http.NewRequest("DELETE", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}require 'uri'
require 'net/http'
url = URI("https://api.blujay.io/v1/phone-numbers/{phone_number_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Delete.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.blujay.io/v1/phone-numbers/{phone_number_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "DELETE",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}{
"status": "success",
"trace_id": "trc_8f2a1c0e4b7d",
"timestamp": "2026-10-14T17:01:00.000Z",
"data": {
"phone_number_id": "phone_abc123",
"display_number": "+15555550100",
"status": "active",
"line_type": "outbound",
"access_type": "shared",
"send_status": {
"allowed": true,
"reason": "<string>",
"reason_code": "sender_retired"
},
"capabilities": {
"messaging": {
"outbound": true,
"inbound": true,
"media_attachments": true,
"link_parts": true
},
"voice": {
"outbound_ready": true,
"inbound_forwarding_ready": true
}
},
"outbound_policy": {
"inbound_first": true,
"first_message_links_allowed": true,
"follow_up_links_allowed": true,
"daily_total_enforced": true
},
"released_at": "2023-11-07T05:31:56Z",
"quiet_until": "2023-11-07T05:31:56Z",
"label": "Support line",
"health_status": {
"status": "healthy",
"score": 98,
"as_of": "2026-10-14T17:01:00.000Z",
"freshness": "fresh"
},
"limits": {
"new_contacts": {
"used_today": 1,
"limit_per_day": 1,
"remaining_today": 1,
"reset_at": "2026-10-14T17:01:00.000Z"
},
"daily": {
"used_today": 1,
"guideline": 1,
"remaining_to_guideline": 1,
"enforced": true
}
},
"queue": {
"pending": 1,
"capacity": 1,
"remaining": 1
}
},
"client_request_id": "<string>"
}{
"status": "error",
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "<string>",
"type": "validation",
"http_status": 400,
"retryable": true,
"doc_url": "<string>",
"details": [
{}
],
"retry_after": 2,
"reset_at": "2026-10-14T17:01:00.000Z"
},
"trace_id": "trc_8f2a1c0e4b7d",
"timestamp": "2026-10-14T17:01:00.000Z",
"client_request_id": "<string>"
}{
"status": "error",
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "<string>",
"type": "validation",
"http_status": 400,
"retryable": true,
"doc_url": "<string>",
"details": [
{}
],
"retry_after": 2,
"reset_at": "2026-10-14T17:01:00.000Z"
},
"trace_id": "trc_8f2a1c0e4b7d",
"timestamp": "2026-10-14T17:01:00.000Z",
"client_request_id": "<string>"
}{
"status": "error",
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "<string>",
"type": "validation",
"http_status": 400,
"retryable": true,
"doc_url": "<string>",
"details": [
{}
],
"retry_after": 2,
"reset_at": "2026-10-14T17:01:00.000Z"
},
"trace_id": "trc_8f2a1c0e4b7d",
"timestamp": "2026-10-14T17:01:00.000Z",
"client_request_id": "<string>"
}{
"status": "error",
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "<string>",
"type": "validation",
"http_status": 400,
"retryable": true,
"doc_url": "<string>",
"details": [
{}
],
"retry_after": 2,
"reset_at": "2026-10-14T17:01:00.000Z"
},
"trace_id": "trc_8f2a1c0e4b7d",
"timestamp": "2026-10-14T17:01:00.000Z",
"client_request_id": "<string>"
}{
"status": "error",
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "<string>",
"type": "validation",
"http_status": 400,
"retryable": true,
"doc_url": "<string>",
"details": [
{}
],
"retry_after": 2,
"reset_at": "2026-10-14T17:01:00.000Z"
},
"trace_id": "trc_8f2a1c0e4b7d",
"timestamp": "2026-10-14T17:01:00.000Z",
"client_request_id": "<string>"
}Release a phone number (reseller partners)
Reseller partner admin keys only, with Blujay-Workspace naming the customer. Releases a number you assigned into its quiet period (30 days unless agreed otherwise). Until quiet_until the customer keeps its history and still receives on the number, but can’t send from it; queued and scheduled texts on it wait instead of sending. Then the number retires. Releasing a number that is already released returns it unchanged. The customer’s webhooks receive phone_number.released and phone_number.status_updated. Any other credential gets 404.
curl --request DELETE \
--url https://api.blujay.io/v1/phone-numbers/{phone_number_id} \
--header 'Authorization: Bearer <token>'const options = {method: 'DELETE', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.blujay.io/v1/phone-numbers/{phone_number_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.blujay.io/v1/phone-numbers/{phone_number_id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.delete(url, headers=headers)
print(response.text)package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.blujay.io/v1/phone-numbers/{phone_number_id}"
req, _ := http.NewRequest("DELETE", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}require 'uri'
require 'net/http'
url = URI("https://api.blujay.io/v1/phone-numbers/{phone_number_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Delete.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.blujay.io/v1/phone-numbers/{phone_number_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "DELETE",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}{
"status": "success",
"trace_id": "trc_8f2a1c0e4b7d",
"timestamp": "2026-10-14T17:01:00.000Z",
"data": {
"phone_number_id": "phone_abc123",
"display_number": "+15555550100",
"status": "active",
"line_type": "outbound",
"access_type": "shared",
"send_status": {
"allowed": true,
"reason": "<string>",
"reason_code": "sender_retired"
},
"capabilities": {
"messaging": {
"outbound": true,
"inbound": true,
"media_attachments": true,
"link_parts": true
},
"voice": {
"outbound_ready": true,
"inbound_forwarding_ready": true
}
},
"outbound_policy": {
"inbound_first": true,
"first_message_links_allowed": true,
"follow_up_links_allowed": true,
"daily_total_enforced": true
},
"released_at": "2023-11-07T05:31:56Z",
"quiet_until": "2023-11-07T05:31:56Z",
"label": "Support line",
"health_status": {
"status": "healthy",
"score": 98,
"as_of": "2026-10-14T17:01:00.000Z",
"freshness": "fresh"
},
"limits": {
"new_contacts": {
"used_today": 1,
"limit_per_day": 1,
"remaining_today": 1,
"reset_at": "2026-10-14T17:01:00.000Z"
},
"daily": {
"used_today": 1,
"guideline": 1,
"remaining_to_guideline": 1,
"enforced": true
}
},
"queue": {
"pending": 1,
"capacity": 1,
"remaining": 1
}
},
"client_request_id": "<string>"
}{
"status": "error",
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "<string>",
"type": "validation",
"http_status": 400,
"retryable": true,
"doc_url": "<string>",
"details": [
{}
],
"retry_after": 2,
"reset_at": "2026-10-14T17:01:00.000Z"
},
"trace_id": "trc_8f2a1c0e4b7d",
"timestamp": "2026-10-14T17:01:00.000Z",
"client_request_id": "<string>"
}{
"status": "error",
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "<string>",
"type": "validation",
"http_status": 400,
"retryable": true,
"doc_url": "<string>",
"details": [
{}
],
"retry_after": 2,
"reset_at": "2026-10-14T17:01:00.000Z"
},
"trace_id": "trc_8f2a1c0e4b7d",
"timestamp": "2026-10-14T17:01:00.000Z",
"client_request_id": "<string>"
}{
"status": "error",
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "<string>",
"type": "validation",
"http_status": 400,
"retryable": true,
"doc_url": "<string>",
"details": [
{}
],
"retry_after": 2,
"reset_at": "2026-10-14T17:01:00.000Z"
},
"trace_id": "trc_8f2a1c0e4b7d",
"timestamp": "2026-10-14T17:01:00.000Z",
"client_request_id": "<string>"
}{
"status": "error",
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "<string>",
"type": "validation",
"http_status": 400,
"retryable": true,
"doc_url": "<string>",
"details": [
{}
],
"retry_after": 2,
"reset_at": "2026-10-14T17:01:00.000Z"
},
"trace_id": "trc_8f2a1c0e4b7d",
"timestamp": "2026-10-14T17:01:00.000Z",
"client_request_id": "<string>"
}{
"status": "error",
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "<string>",
"type": "validation",
"http_status": 400,
"retryable": true,
"doc_url": "<string>",
"details": [
{}
],
"retry_after": 2,
"reset_at": "2026-10-14T17:01:00.000Z"
},
"trace_id": "trc_8f2a1c0e4b7d",
"timestamp": "2026-10-14T17:01:00.000Z",
"client_request_id": "<string>"
}Authorizations
Your workspace API key, sent as Authorization: Bearer blu_.... Workspace admins can find it in the Blujay app under API.
An API key has full access to your workspace and works on every endpoint. There is no test mode: every key sends real messages and changes real data, so keep it secret and use it only from your server.
Each API key can make 600 read requests and 120 write requests per minute, plus 60 attachment requests per minute. Over a limit you get 429 RATE_LIMIT_EXCEEDED with Retry-After.
Reseller partner keys. A partner key acts for one of the partner's customers when the request names it in the Blujay-Workspace header (the customer's workspace_ ID). Without the header it reaches only /v1/partner/* and /v1/me. Each customer gets the limits above for each partner key, and all of a partner's requests together get ten times those limits; a 429 says which in error.details[0].scope (partner_customer or partner). A messaging key can read anything for a customer and change chats, messages, contacts, attachments and vCards; everything else needs an admin key (403 PARTNER_ROLE_FORBIDDEN). Paused or closing customers can be read but not changed (409 CUSTOMER_PAUSED or CUSTOMER_CLOSING). Any other workspace ID in the header returns 404 NOT_FOUND; using the header with any other credential returns 400 WORKSPACE_HEADER_NOT_ALLOWED.
Path Parameters
^phone_[A-Za-z0-9_-]+$"phone_abc123"
Response
The released number, with released_at and quiet_until.
Wraps every successful response. The result is in data.
success ^trc_[A-Za-z0-9_-]+$"trc_8f2a1c0e4b7d"
"2026-10-14T17:01:00.000Z"
A Blujay number in your workspace and what it can do right now. Numbers on the Shared Free Plan omit health, limits, queue and calling readiness.
Show child attributes
Show child attributes
Your X-Request-ID header value, echoed back when you send one. Not included on the send responses (POST /v1/chats and POST /v1/chats/{chat_id}/messages); keep your own mapping from your request ID to the returned message ID there.