Name and Photo Sharing

When one of your numbers texts someone who doesn’t have it saved, iMessage can offer them a name and photo for it, the same “Share name and photo” prompt a person gets from a new iPhone contact. Set it once per number so your first messages arrive with a face and a name instead of a bare number. Your own (dedicated) numbers only; Free Plan numbers return 400 FEATURE_NOT_ENABLED.

Read what a number shares

curl

curl https://api.blujay.io/v1/phone-numbers/phone_abc123/contact-card \
  -H "Authorization: Bearer blu_your_api_key"

Response (200)

{
  "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:00.000Z"
  },
  "trace_id": "trc_5b7d9f1a3c2e",
  "timestamp": "2026-10-22T17:00:01.000Z"
}

Blujay asks the number for its live state on every read, so expect the call to take a second or two.

`status`	Meaning
`not_set`	The number shares no name and photo.
`applying`	A change was accepted and the number is finishing it. Read again in about 15 seconds.
`active`	The name and photo are in place.
`unavailable`	The number can’t report its state right now. Retry later.

photo is null when the number has no photo (iMessage shows the name’s initials). photo.download_url returns the current photo as a 512 by 512 PNG; send it with your API key like any other request.

Set the name and photo

Upload the photo first, then set the profile. Any JPEG or PNG up to 25 MiB works; Blujay center-crops it to a square and resizes it for iMessage, so send the original.

Upload the photo

Create an attachment and PUT the file to its upload_url, as on Media.

curl

curl -X POST https://api.blujay.io/v1/attachments \
  -H "Authorization: Bearer blu_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"filename":"acme.jpg","content_type":"image/jpeg","size_bytes":184233}'

Set the profile

curl

curl -X PUT https://api.blujay.io/v1/phone-numbers/phone_abc123/contact-card \
  -H "Authorization: Bearer blu_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Acme","last_name":"Support","avatar_attachment_id":"att_abc123"}'

Response (200)

{
  "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:00.000Z"
  },
  "trace_id": "trc_6b2d9e0f1a3c",
  "timestamp": "2026-10-22T17:00:01.000Z"
}

Check the result

PUT waits up to about 3 seconds for the number to publish the change. Usually it does: you get 200 with status: "active", and you’re done.Sometimes Apple is slow to take a change. Then you get 202 with status: "applying". The number keeps going on its own, so don’t send the PUT again. Read GET .../contact-card about 15 seconds later; status: "active" confirms it. If it still says applying after 15 minutes, email support@blujay.io with the trace_id.

PUT replaces the name: first_name is required and last_name is blank when you leave it out. The photo works differently: leave avatar_attachment_id out to keep the current photo, or send null to remove it so iMessage shows initials.

Change the name, keep the photo

{ "first_name": "Acme", "last_name": "Sales" }

Remove the photo

{ "first_name": "Acme", "last_name": "Support", "avatar_attachment_id": null }

Turn it off

DELETE /v1/phone-numbers/{phone_number_id}/contact-card stops the number from offering a name and photo. It returns 202 with the profile, and status becomes not_set once the number confirms.

What recipients see

The prompt appears on iPhones, in iMessage chats only. SMS and RCS recipients and Android phones never see it. To give them your details, send a contact card instead.
Blujay offers your card automatically with your first message in each chat, and again once a day while you keep messaging, so people see your current name and photo. There is nothing to call.
After you change the card, the new version goes out with your next message in each chat. If you change it several times in a row, an iPhone may show an earlier version until the next daily refresh, so settle on the final card before a large send.
People who saved the number as a contact keep their own card; nothing you set overwrites it.
The same name and photo appear in Number Settings in the Blujay app. Changing it in either place changes it everywhere.

Errors

Error	When
`400` `FEATURE_NOT_ENABLED`	The number is a Free Plan number. Dedicated numbers only.
`400` `VALIDATION_ERROR`	`first_name` is missing or over 80 characters, the body has an unknown field, or the photo could not be processed.
`404` `NOT_FOUND`	The number or the attachment isn’t in your workspace, or the number was replaced. `GET .../photo` also returns it when the number has no photo.
`409` `ATTACHMENT_NOT_READY`	The photo’s file hasn’t finished uploading. `PUT` the file to the `upload_url`, then retry.
`413` `ATTACHMENT_TOO_LARGE`	The photo is over 25 MiB.
`415` `UNSUPPORTED_ATTACHMENT_TYPE`	The attachment isn’t a JPEG or PNG.
`503` `PHONE_NUMBER_UNAVAILABLE`	The number is busy with another change, isn’t set up yet, or didn’t answer. Wait for `Retry-After`, then read `GET .../contact-card` before sending the change again: if the number applied it after all, the read says so.

Next steps

Phone numbers and limits

List your numbers and read their live limits and health.

Contact cards

Share your details with SMS, RCS and Android recipients too.

Media

Upload the photo you set here.

Group Chats

Set the photo a group chat shows.

​Read what a number shares

​Set the name and photo

​Turn it off

​What recipients see

​Errors

​Next steps

Phone numbers and limits

Contact cards

Media

Group Chats

Read what a number shares

Set the name and photo

Turn it off

What recipients see

Errors

Next steps