---
title: Name & Photo Sharing | Sendblue Docs
description: Configure and share an iMessage Name & Photo profile for a Sendblue number
---

Use the Contact Sharing API to configure the name and photo shown when you message people from a Sendblue number. You can also check the current profile, request that it be shared with a specific conversation, or remove it.

Name & Photo Sharing is an iMessage feature. It is separate from sending a downloadable [VCF contact card](/guides/contact-card/index.md).

**Base URL:** `https://api.sendblue.com/api/v2/contact-sharing`

---

## Create or Update a Profile

```
POST /api/v2/contact-sharing/profile
```

### Request Body

| Parameter    | Type    | Required | Description                                                                   |
| ------------ | ------- | -------- | ----------------------------------------------------------------------------- |
| `fromNumber` | string  | Yes      | Your Sendblue number in E.164 format                                          |
| `firstName`  | string  | No       | First name to set. Send an empty string to clear it.                          |
| `lastName`   | string  | No       | Last name to set. Send an empty string to clear it.                           |
| `photoUrl`   | string  | No       | Public direct URL of the JPEG or PNG profile photo to set                     |
| `clearPhoto` | boolean | No       | Set to `true` to clear the current photo. Cannot be combined with `photoUrl`. |

Include at least one of `firstName`, `lastName`, `photoUrl`, or `clearPhoto: true`.

### Example Request

Terminal window

```
curl -X POST "https://api.sendblue.com/api/v2/contact-sharing/profile" \
  -H "sb-api-key-id: YOUR_API_KEY" \
  -H "sb-api-secret-key: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "fromNumber": "+14155551234",
    "firstName": "Jane",
    "lastName": "Smith",
    "photoUrl": "https://example.com/team/jane-smith.jpg"
  }'
```

When an active profile already exists, fields omitted from the request remain unchanged. For example, this request updates only the first name:

Terminal window

```
curl -X POST "https://api.sendblue.com/api/v2/contact-sharing/profile" \
  -H "sb-api-key-id: YOUR_API_KEY" \
  -H "sb-api-secret-key: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "fromNumber": "+14155551234",
    "firstName": "Janet"
  }'
```

If sharing is disabled, the request creates a new profile from the fields you provide and enables sharing.

### Success Response (200)

```
{
  "status": "OK",
  "data": {
    "hasProfile": true,
    "sharingEnabled": true,
    "firstName": "Jane",
    "lastName": "Smith",
    "displayName": "Jane Smith",
    "hasPhoto": true
  }
}
```

`200 OK` confirms that Sendblue accepted the update. Applying the profile may continue after the response, so do not retry only because the change is not visible immediately.

The response reflects the fields submitted with the request. After a partial update, an omitted field may appear as `null` or `false` in this response even though its existing value remains unchanged. Use [Get Profile State](#get-profile-state) to read the current profile, or subscribe to the [`contact_profile` webhook](/getting-started/webhooks#contact-profile-webhook/index.md) to receive the final result.

---

## Get Profile State

Read the current Name & Photo Sharing profile for a Sendblue number.

```
GET /api/v2/contact-sharing/state
```

### Query Parameters

| Parameter    | Type   | Required | Description                          |
| ------------ | ------ | -------- | ------------------------------------ |
| `fromNumber` | string | Yes      | Your Sendblue number in E.164 format |

### Example Request

Terminal window

```
curl "https://api.sendblue.com/api/v2/contact-sharing/state?fromNumber=%2B14155551234" \
  -H "sb-api-key-id: YOUR_API_KEY" \
  -H "sb-api-secret-key: YOUR_API_SECRET"
```

### Success Response (200)

```
{
  "status": "OK",
  "data": {
    "hasProfile": true,
    "sharingEnabled": true,
    "firstName": "Jane",
    "lastName": "Smith",
    "displayName": "Jane Smith",
    "hasPhoto": true,
    "publishRecordPresent": true
  }
}
```

| Field                  | Type            | Description                                                                                             |
| ---------------------- | --------------- | ------------------------------------------------------------------------------------------------------- |
| `hasProfile`           | boolean         | Whether a name or photo is configured                                                                   |
| `sharingEnabled`       | boolean         | Whether Name & Photo Sharing is enabled                                                                 |
| `firstName`            | string or null  | Current first name                                                                                      |
| `lastName`             | string or null  | Current last name                                                                                       |
| `displayName`          | string or null  | Current combined display name                                                                           |
| `hasPhoto`             | boolean         | Whether a profile photo is configured                                                                   |
| `publishRecordPresent` | boolean or null | Whether the profile is published and available to share. May be `null` when this status is unavailable. |

---

## Share a Profile With One Chat

Request that the number’s published Name & Photo profile be shared with one existing direct iMessage conversation. This endpoint does not send a text message.

```
POST /api/v2/contact-sharing/share
```

Before calling this endpoint:

- Configure the profile and confirm `publishRecordPresent: true`.
- Send at least one iMessage from `fromNumber` to `toNumber` so the direct conversation exists.

Group conversations and SMS conversations are not supported.

### Request Body

| Parameter    | Type   | Required | Description                                                            |
| ------------ | ------ | -------- | ---------------------------------------------------------------------- |
| `fromNumber` | string | Yes      | Your Sendblue number in E.164 format                                   |
| `toNumber`   | string | Yes      | Recipient of an existing direct iMessage conversation, in E.164 format |

### Example Request

Terminal window

```
curl -X POST "https://api.sendblue.com/api/v2/contact-sharing/share" \
  -H "sb-api-key-id: YOUR_API_KEY" \
  -H "sb-api-secret-key: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "fromNumber": "+14155551234",
    "toNumber": "+14155559876"
  }'
```

### Success Response (200)

```
{
  "status": "OK",
  "data": {
    "fromNumber": "+14155551234",
    "toNumber": "+14155559876",
    "requested": true,
    "deduplicated": false,
    "requestedAt": "2026-08-24T15:00:00.000Z",
    "cooldownUntil": "2026-08-25T15:00:00.000Z",
    "cooldownPersisted": true
  }
}
```

| Field               | Type    | Description                                                            |
| ------------------- | ------- | ---------------------------------------------------------------------- |
| `requested`         | boolean | `true` when a new share was requested                                  |
| `deduplicated`      | boolean | `true` when the same chat was already handled within the last 24 hours |
| `requestedAt`       | string  | ISO 8601 time associated with the share request                        |
| `cooldownUntil`     | string  | ISO 8601 time when a new share can be requested for this chat          |
| `cooldownPersisted` | boolean | Whether the 24-hour deduplication window was saved                     |

You can call the endpoint again at any time. Sendblue avoids duplicate requests for the same chat for 24 hours and returns `requested: false` with `deduplicated: true`.

A successful response confirms the sender-side share request. It does not confirm when the recipient sees or accepts the profile.

### Share Errors

Error responses use the standard body shown under [Errors](#errors). When available, a machine-readable `code` is also included.

| HTTP Status | Description                                                                                        |
| ----------- | -------------------------------------------------------------------------------------------------- |
| 400         | Missing or invalid phone numbers                                                                   |
| 409         | The profile is not ready, the conversation does not exist, or no prior outbound iMessage was found |
| 422         | The conversation is not a supported direct iMessage chat                                           |
| 502         | iMessage returned an invalid result                                                                |
| 503         | The Sendblue number is temporarily unavailable                                                     |
| 504         | The share request timed out                                                                        |

---

## Delete a Profile

Disable Name & Photo Sharing and remove the profile from a Sendblue number.

```
DELETE /api/v2/contact-sharing/profile
```

### Request Body

| Parameter    | Type   | Required | Description                          |
| ------------ | ------ | -------- | ------------------------------------ |
| `fromNumber` | string | Yes      | Your Sendblue number in E.164 format |

### Example Request

Terminal window

```
curl -X DELETE "https://api.sendblue.com/api/v2/contact-sharing/profile" \
  -H "sb-api-key-id: YOUR_API_KEY" \
  -H "sb-api-secret-key: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "fromNumber": "+14155551234"
  }'
```

### Success Response (200)

```
{
  "status": "OK",
  "data": {
    "hasProfile": false,
    "sharingEnabled": false
  }
}
```

---

## Errors

| HTTP Status | Description                                    |
| ----------- | ---------------------------------------------- |
| 400         | Missing, invalid, or conflicting parameters    |
| 401         | Invalid or missing API credentials             |
| 403         | Your account does not own `fromNumber`         |
| 404         | No active Sendblue number was found            |
| 500         | The request could not be accepted              |
| 503         | The Sendblue number is temporarily unavailable |

```
{
  "status": "ERROR",
  "message": "Description of what went wrong"
}
```

## Notes

- `photoUrl` must be a publicly accessible direct image URL.
- Use an empty string to clear `firstName` or `lastName`, `clearPhoto: true` to remove only the photo, and `DELETE /profile` to remove the full profile.
- Profile availability and display timing are controlled by iMessage and may vary by recipient device.
