{
"status": "success",
"data": {
"phone_number_id": "phone_abc123",
"status": "active",
"first_name": "Acme",
"last_name": "Support",
"display_name": "Acme Support",
"photo": {
"download_url": "/v1/phone-numbers/phone_abc123/contact-card/photo",
"content_type": "image/png"
},
"updated_at": "2026-10-22T17:00:01.000Z"
},
"trace_id": "trc_8f2a1c0e4b7d",
"timestamp": "2026-10-22T17:00:02.000Z"
}{
"status": "success",
"data": {
"phone_number_id": "phone_abc123",
"status": "applying",
"first_name": "Acme",
"last_name": "Support",
"display_name": "Acme Support",
"photo": {
"download_url": "/v1/phone-numbers/phone_abc123/contact-card/photo",
"content_type": "image/png"
},
"updated_at": "2026-10-22T17:00:00.000Z"
},
"trace_id": "trc_8f2a1c0e4b7d",
"timestamp": "2026-10-22T17:00:01.000Z"
}{
"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>"
}{
"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": "PHONE_NUMBER_UNAVAILABLE",
"message": "This service is temporarily unavailable",
"type": "phone_number",
"http_status": 503,
"retryable": true,
"doc_url": "https://docs.blujay.io/errors/phone-number-unavailable",
"details": [],
"retry_after": 30
},
"trace_id": "trc_8f2a1c0e4b7d",
"timestamp": "2026-10-14T00:00:00.000Z"
}Set a number's iMessage name and photo
Sets the iMessage name and photo for one of your dedicated numbers. Upload the photo first with POST /v1/attachments (JPEG or PNG, up to 25 MiB); Blujay center-crops it to a square and resizes it for iMessage. PUT replaces the name. Omit avatar_attachment_id to keep the current photo, or send null to remove it so iMessage shows the number’s initials.
PUT waits up to about 3 seconds for the number to publish the change. Usually it does, and you get 200 with status: active. If Apple is slow to take the change, you get 202 with status: applying; the number keeps going on its own, and GET .../contact-card about 15 seconds later reports active. There is no need to send the change again. The response confirms the number accepted the change, not that anyone has seen it yet. Blujay offers the card automatically with your next message in each iMessage chat and refreshes it once a day, so there is nothing to call. If you change it several times in a row, an iPhone may show an earlier version until the next daily refresh. People who saved the number as a contact keep their own card.
Refusals: Free Plan numbers 400 FEATURE_NOT_ENABLED; a photo that isn’t JPEG or PNG 415 UNSUPPORTED_ATTACHMENT_TYPE; a photo still uploading 409 ATTACHMENT_NOT_READY; a number that is busy with another change, not set up, or not reachable 503 PHONE_NUMBER_UNAVAILABLE with Retry-After. After a 503, read GET .../contact-card before retrying: if the number applied the change after all, the read reports it.
{
"status": "success",
"data": {
"phone_number_id": "phone_abc123",
"status": "active",
"first_name": "Acme",
"last_name": "Support",
"display_name": "Acme Support",
"photo": {
"download_url": "/v1/phone-numbers/phone_abc123/contact-card/photo",
"content_type": "image/png"
},
"updated_at": "2026-10-22T17:00:01.000Z"
},
"trace_id": "trc_8f2a1c0e4b7d",
"timestamp": "2026-10-22T17:00:02.000Z"
}{
"status": "success",
"data": {
"phone_number_id": "phone_abc123",
"status": "applying",
"first_name": "Acme",
"last_name": "Support",
"display_name": "Acme Support",
"photo": {
"download_url": "/v1/phone-numbers/phone_abc123/contact-card/photo",
"content_type": "image/png"
},
"updated_at": "2026-10-22T17:00:00.000Z"
},
"trace_id": "trc_8f2a1c0e4b7d",
"timestamp": "2026-10-22T17:00:01.000Z"
}{
"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>"
}{
"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": "PHONE_NUMBER_UNAVAILABLE",
"message": "This service is temporarily unavailable",
"type": "phone_number",
"http_status": 503,
"retryable": true,
"doc_url": "https://docs.blujay.io/errors/phone-number-unavailable",
"details": [],
"retry_after": 30
},
"trace_id": "trc_8f2a1c0e4b7d",
"timestamp": "2026-10-14T00:00:00.000Z"
}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"
Body
The iMessage name and photo to set on a dedicated number. PUT replaces the name. Omit avatar_attachment_id to keep the current photo; send null to remove it.
1 - 80"Acme"
Optional. Blank when omitted.
80"Support"
A ready JPEG or PNG attachment from POST /v1/attachments, up to 25 MiB. Blujay center-crops it to a square and resizes it to 512 by 512 for iMessage. null removes the photo.
^att_[A-Za-z0-9_-]+$"att_abc123"
Response
The number published the change. status is active.
Wraps every successful response. The result is in data.
success ^trc_[A-Za-z0-9_-]+$"trc_8f2a1c0e4b7d"
"2026-10-14T17:01:00.000Z"
The iMessage name and photo a dedicated number offers to people who don't have it saved.
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.