> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blujay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Name and Photo Sharing

> Set the iMessage name and photo your Blujay phone numbers offer to people who don't have them saved.

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`](https://docs.blujay.io/errors/feature-not-enabled).

## Read what a number shares

```bash curl theme={null}
curl https://api.blujay.io/v1/phone-numbers/phone_abc123/contact-card \
  -H "Authorization: Bearer blu_your_api_key"
```

```json Response (200) theme={null}
{
  "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.

**1. Upload the photo**

Create an attachment and `PUT` the file to its `upload_url`, as on [Media](https://docs.blujay.io/messaging/media.md).

```bash curl theme={null}
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}'
```

**2. Set the profile**

```bash curl theme={null}
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"}'
```

```json Response (200) theme={null}
{
  "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"
}
```

**3. 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](mailto: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.

```json Change the name, keep the photo theme={null}
{ "first_name": "Acme", "last_name": "Sales" }
```

```json Remove the photo theme={null}
{ "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](https://docs.blujay.io/messaging/contact-cards.md) 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`](https://docs.blujay.io/errors/feature-not-enabled) | The number is a Free Plan number. Dedicated numbers only. |
| `400` [`VALIDATION_ERROR`](https://docs.blujay.io/errors/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`](https://docs.blujay.io/errors/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`](https://docs.blujay.io/errors/attachment-not-ready) | The photo's file hasn't finished uploading. `PUT` the file to the `upload_url`, then retry. |
| `413` [`ATTACHMENT_TOO_LARGE`](https://docs.blujay.io/errors/attachment-too-large) | The photo is over 25 MiB. |
| `415` [`UNSUPPORTED_ATTACHMENT_TYPE`](https://docs.blujay.io/errors/unsupported-attachment-type) | The attachment isn't a JPEG or PNG. |
| `503` [`PHONE_NUMBER_UNAVAILABLE`](https://docs.blujay.io/errors/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

> [card] [Phone numbers and limits](https://docs.blujay.io/phone-numbers.md)
>
> List your numbers and read their live limits and health.

> [card] [Contact cards](https://docs.blujay.io/messaging/contact-cards.md)
>
> Share your details with SMS, RCS and Android recipients too.

> [card] [Media](https://docs.blujay.io/messaging/media.md)
>
> Upload the photo you set here.

> [card] [Group Chats](https://docs.blujay.io/messaging/group-chats.md#set-a-group-photo)
>
> Set the photo a group chat shows.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.