Skip to content
Miss Blue
Create your free account

Reference

Numbers

The lines your project holds. The Mac behind each line remains our implementation detail.

GET/v1/numbers

Your project's numbers, with the name each has been given.

The Mac behind a number is never named. Which machine holds a line is our problem, and telling you would make it yours. availability says whether a number can send right now: { "status": "available" }, or { "status": "unavailable", "message": … } with a sentence written to be shown to your own users as it is. It is unavailable exactly when a send made now would be queued rather than sent — sends are still accepted, and go out when it is back.

curl -X GET https://api.missblue.dev/v1/numbers \
  -H "Authorization: Bearer $MISS_BLUE_KEY"

Response

{
  "total": 1,
  "data": [{
    "id": "8f14e45f-ceea-467a-9a1b-1b1e5f9e2c3d",
    "handle": "+16465550142",
    "label": "Main support",
    "service": "imessage",
    "project_id": "e3b7c534-7e5d-4669-b90a-5b617bfe77f0",
    "disabled": false,
    "simulated": false,
    "availability": { "status": "available" },
    "shared": false,
    "created_at": "2026-08-23T09:12:04Z"
  }]
}
GET/v1/numbers/{id}

Pull one number and its project and organization context.

curl -X GET https://api.missblue.dev/v1/numbers/8f14e45f-ceea-467a-9a1b-1b1e5f9e2c3d \
  -H "Authorization: Bearer $MISS_BLUE_KEY"

Response

{
  "number": {
    "id": "8f14e45f-ceea-467a-9a1b-1b1e5f9e2c3d",
    "handle": "+16465550142",
    "label": "Main support",
    "service": "imessage",
    "project_id": "e3b7c534-7e5d-4669-b90a-5b617bfe77f0",
    "disabled": false,
    "simulated": false,
    "availability": { "status": "available" },
    "shared": false,
    "created_at": "2026-08-23T09:12:04Z"
  },
  "project_name": "Client Support",
  "workspace_id": "3480fdd8-2ef3-4edd-9949-bf78b4cd3e35",
  "workspace_name": "Acme Agency"
}
POST/v1/numbers/{id}/label

Give a number a name.

So a thread says it arrived on Main support rather than +1 646 555 0142. Coming back to a conversation days later, the digits do not tell you which line you used.

labelstringEmpty or absent clears it back to the bare handle.
curl -X POST https://api.missblue.dev/v1/numbers/8f14e45f-ceea-467a-9a1b-1b1e5f9e2c3d/label \
  -H "Authorization: Bearer $MISS_BLUE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Main support"
  }'

Response

{
  "id": "8f14e45f-ceea-467a-9a1b-1b1e5f9e2c3d",
  "handle": "+16465550142",
  "label": "Main support",
  "service": "imessage",
  "project_id": "e3b7c534-7e5d-4669-b90a-5b617bfe77f0",
  "disabled": false,
  "simulated": false,
  "availability": { "status": "available" },
  "shared": false,
  "created_at": "2026-08-23T09:12:04Z"
}
GET/v1/numbers/{selector}/call-forwarding

Pull the currently confirmed call-forwarding destination and latest request.

forwarding_number changes only after staff confirms the carrier update. A pending destination appears under latest_request without pretending it is already active.

curl -X GET https://api.missblue.dev/v1/numbers/8f14e45f-ceea-467a-9a1b-1b1e5f9e2c3d/call-forwarding \
  -H "Authorization: Bearer $MISS_BLUE_KEY"

Response

{
  "number_id": "8f14e45f-ceea-467a-9a1b-1b1e5f9e2c3d",
  "number": "+16465550142",
  "forwarding_number": "+14155550100",
  "eligible": true,
  "eligibility_reason": null,
  "monthly_limit": 2,
  "requests_used_this_month": 1,
  "requests_remaining_this_month": 1,
  "latest_request": {
    "id": "927c4759-fb1a-43c4-9a39-acde90645fe0",
    "number_id": "8f14e45f-ceea-467a-9a1b-1b1e5f9e2c3d",
    "forward_to": "+14155550100",
    "status": "completed",
    "rejection_reason": null,
    "created_at": "2026-09-03T16:00:00Z",
    "updated_at": "2026-09-03T16:30:00Z",
    "completed_at": "2026-09-03T16:30:00Z"
  }
}
  • 400The path is neither a UUID nor a canonical E.164 number.
  • 404The selected number is outside this project.
POST/v1/numbers/{selector}/call-forwarding

Request a new call-forwarding destination.

The source in the path and forward_to must be canonical E.164 phone numbers. Staff complete the carrier change within 2–3 business days. Each number may request two changes per calendar month and have one open request at a time.

forward_to*E.164 stringThe destination: +, a non-zero country code, and 7–15 digits total.
curl -X POST https://api.missblue.dev/v1/numbers/8f14e45f-ceea-467a-9a1b-1b1e5f9e2c3d/call-forwarding \
  -H "Authorization: Bearer $MISS_BLUE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "forward_to": "+14155550100"
  }'

Response

{
  "id": "927c4759-fb1a-43c4-9a39-acde90645fe0",
  "number_id": "8f14e45f-ceea-467a-9a1b-1b1e5f9e2c3d",
  "forward_to": "+14155550100",
  "status": "pending",
  "rejection_reason": null,
  "created_at": "2026-09-03T16:00:00Z",
  "updated_at": "2026-09-03T16:00:00Z",
  "completed_at": null
}
  • 400The source or destination is not canonical E.164, or both are the same.
  • 404The selected number is outside this project.
  • 409This number already has a pending or processing request.
  • 429This number already requested two changes in the current calendar month.
GET/v1/numbers/{id}/name-photo

Pull this number's current Messages Name & Photo Sharing profile.

This is the Apple Account-wide outbound identity recipients may be offered, not a local Contacts card. photo_base64 is a bounded preview and has_photo remains authoritative. sharing_enabled says whether it is offered at all (to the number's contacts); Miss Blue keeps it on. Once a name and photo are saved here, saved is what was saved and in_sync whether the number still holds exactly that (photo_sha256 is the fingerprint of the exact image it holds). If it was changed outside Miss Blue, it is put back from what was saved, restored_at says when, and the project's people get an email. A new number starts with a name and photo Miss Blue chose (saved.is_default), and saved.verified_at says when a test message last proved the saved name and photo reach people.

curl -X GET https://api.missblue.dev/v1/numbers/8f14e45f-ceea-467a-9a1b-1b1e5f9e2c3d/name-photo \
  -H "Authorization: Bearer $MISS_BLUE_KEY"

Response

{
  "first_name": "Blue",
  "last_name": "Lover",
  "has_photo": true,
  "photo_mime_type": "image/jpeg",
  "photo_base64": "/9j/4AAQSkZJRg…",
  "photo_sha256": "53d37af3e156b59a0c7ed129912a7ff8c4b29de3acd0bca2b702b030d70bcd53",
  "sharing_enabled": true,
  "saved": {
    "first_name": "Blue",
    "last_name": "Lover",
    "has_photo": true,
    "photo_attachment_id": "88de9745-30e0-4b93-bfcb-dbb7f3325dde",
    "saved_at": "2026-10-01T17:10:55Z",
    "is_default": false
  },
  "in_sync": true
}
  • 403The number is shared or its Apple Account has more than one number.
  • 404The number is outside this project.
PUT/v1/numbers/{id}/name-photo

Update and verify the number's Messages name and photo.

Upload a JPEG or PNG first. To remove the photo, omit photo_attachment_id and set remove_photo to true. Success is returned only after an independent Messages readback matches the requested name and image. Saving also turns sharing on, for the number's contacts.

curl -X PUT https://api.missblue.dev/v1/numbers/8f14e45f-ceea-467a-9a1b-1b1e5f9e2c3d/name-photo \
  -H "Authorization: Bearer $MISS_BLUE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Blue",
    "last_name": "Lover",
    "photo_attachment_id": "88de9745-30e0-4b93-bfcb-dbb7f3325dde",
    "remove_photo": false
  }'

Response

{
  "first_name": "Blue",
  "last_name": "Lover",
  "has_photo": true,
  "photo_mime_type": "image/jpeg",
  "photo_base64": "/9j/4AAQSkZJRg…",
  "photo_sha256": "53d37af3e156b59a0c7ed129912a7ff8c4b29de3acd0bca2b702b030d70bcd53",
  "sharing_enabled": true,
  "saved": {
    "first_name": "Blue",
    "last_name": "Lover",
    "has_photo": true,
    "photo_attachment_id": "88de9745-30e0-4b93-bfcb-dbb7f3325dde",
    "saved_at": "2026-10-01T17:10:55Z"
  },
  "in_sync": true
}
GET/v1/numbers/{id}/service-status?handle={handle}

Pull live iMessage and FaceTime registration for a recipient.

Each service is registered, not_registered, or unknown. Unknown is an inconclusive Apple lookup and is never turned into a negative answer.

handle*stringThe E.164 phone number or Apple ID email to check.
curl -X GET https://api.missblue.dev/v1/numbers/8f14e45f-ceea-467a-9a1b-1b1e5f9e2c3d/service-status?handle=%2B15163128403 \
  -H "Authorization: Bearer $MISS_BLUE_KEY"

Response

{
  "handle": "+15163128403",
  "imessage": "registered",
  "facetime": "registered",
  "checked_at": "2026-08-28T10:04:00Z"
}
POST/v1/numbers/{id}/service-status

Run the same live service lookup with a JSON request.

curl -X POST https://api.missblue.dev/v1/numbers/8f14e45f-ceea-467a-9a1b-1b1e5f9e2c3d/service-status \
  -H "Authorization: Bearer $MISS_BLUE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "handle": "+15163128403"
  }'

Response

{
  "handle": "+15163128403",
  "imessage": "registered",
  "facetime": "registered",
  "checked_at": "2026-08-28T10:04:00Z"
}
NextCampaignsAnnouncements, scheduled messages, lists, tags, and automations created entirely through the API, including multi-step sequences with waits, reply conditions and messages personalized from each contact's name and custom fields.