Contact Sharing API

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

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

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

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.