---
title: Contact Sharing API | Sendblue Docs
description: Configure Name & Photo Sharing profiles for your Sendblue numbers
---

Configure Name & Photo Sharing profiles on your Sendblue numbers. When enabled, recipients see your contact card (name, photo, display name) when they receive messages.

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

---

## Get Profile State

Check whether a phone number has a Name & Photo Sharing profile configured.

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

### Query Parameters

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

### Example Request

Terminal window

```
curl -X GET "https://api.sendblue.co/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,
    "firstName": "Jane",
    "lastName": "Smith",
    "displayName": "Jane at Acme"
  }
}
```

### Response Schema

| Field         | Type           | Description                               |
| ------------- | -------------- | ----------------------------------------- |
| `hasProfile`  | boolean        | `true` if name & photo sharing is active  |
| `firstName`   | string \| null | First name configured on the profile      |
| `lastName`    | string \| null | Last name configured on the profile       |
| `displayName` | string \| null | Optional display name shown to recipients |

---

## Create or Update Profile

Set up a Name & Photo Sharing profile on a phone number. If a profile exists, it will be overwritten.

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

### Request Body

| Parameter     | Type   | Required | Description                                            |
| ------------- | ------ | -------- | ------------------------------------------------------ |
| `fromNumber`  | string | Yes      | Your Sendblue number (E.164 format)                    |
| `firstName`   | string | Yes      | First name displayed on the contact card               |
| `lastName`    | string | Yes      | Last name displayed on the contact card                |
| `photoUrl`    | string | Yes      | Public URL to profile photo (JPEG or PNG)              |
| `displayName` | string | No       | Optional display name shown alongside the contact card |

### Example Request

Terminal window

```
curl -X POST "https://api.sendblue.co/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",
    "displayName": "Jane at Acme"
  }'
```

### Success Response (200)

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

---

## Delete Profile

Remove the Name & Photo Sharing profile from a phone number.

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

### Request Body

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

### Example Request

Terminal window

```
curl -X DELETE "https://api.sendblue.co/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
  }
}
```

---

## Error Responses

| HTTP Status | Description                                                |
| ----------- | ---------------------------------------------------------- |
| 400         | Missing or invalid parameters                              |
| 401         | Invalid or missing API credentials                         |
| 403         | Your account does not own this phone number                |
| 404         | No active Sendblue number found for the given `fromNumber` |
| 500         | Operation failed on the device (see `message` for details) |
| 503         | The phone number’s device is temporarily unavailable       |

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

---

## Notes

- **Photo requirements**: `photoUrl` must be a publicly accessible direct link to an image. The image is downloaded and applied to the device at the time of request. If unreachable or invalid, the request fails with a 500 error.

- **Propagation**: After creating or updating a profile, the name and photo will be shared with contacts on subsequent iMessage conversations. Existing conversations may take some time to reflect the update.

- **Rate of change**: Frequent updates are supported, but each update fully replaces the previous one.