Name & Photo Sharing

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.

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

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:

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 to read the current profile, or subscribe to the contact_profile webhook 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

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

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. 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

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.