Skip to content
Project BlueDocs
Popular pages
Guides / Getting startedQuickstartGet an API key, send your first message, and confirm delivery.API reference / MessagesPOSTSend a messageSend iMessage or SMS, with media, voice memos, and message effects./send-api-messageGuides / IntegrationsWebhooksReceive message and call events at your own endpoint.Guides / Getting startedAuthenticationCreate an API key and authenticate requests with a bearer token.AI tools / AI toolsMCP server & skillConnect Claude, Codex, Cursor, and other AI tools to Project Blue.
↑ ↓ Navigate↵ Openesc Close
Dashboard
For AI agents
View as Markdown

Get a contact card

Returns the card Project Blue stored for the line and, read live, what Messages on the line currently holds. This is the source of truth after an INDETERMINATE set and the way to notice a card someone changed on the Mac by hand.

GET/get-contact-cardBearer token

Query parameters

lineIdstring (UUID v4)Required
The line to read. Use a lineId returned from GET /get-lines.

The line object

readiness"READY" | "OFFLINE" | "UNSUPPORTED_SERVER" | "PRIVATE_API_DISABLED" | "HELPER_DISCONNECTED" | "NOT_REGISTERED" | "LINE_NOT_ELIGIBLE"Required
Whether the line can take contact-card calls right now, checked live on every request. Anything other than READY also appears as an error_code on the write endpoints.
serverVersionstring | nullRequired
BlueBubbles version the line is running. Contact cards need 2.2.0 or newer.
namestring | nullRequired
The name Messages on the line currently holds, read live. null when the line could not be read.
hasPhotoboolean | nullRequired
Whether Messages on the line currently holds a photo.
state"APPLIED" | "MISMATCH" | "NOT_SET" | "UNMANAGED" | "UNAVAILABLE"Required
How the live card compares with the stored one. APPLIED matches; MISMATCH means someone changed it on the Mac or a set did not finish; NOT_SET has no card anywhere; UNMANAGED has a card on the Mac that was never set through Project Blue; UNAVAILABLE means the line could not be read.

When the live card matches the stored one, appliedToLine on the stored card is set to true; when it does not, it is cleared. Reading is always 200 — a line that cannot be reached reports state: UNAVAILABLE with the readiness reason rather than an error.

API reference