# Share a contact card

Sends the line's saved name and photo into an existing 1:1 conversation, so Messages on the recipient's side offers to update the contact. Apple decides when the recipient sees it; it usually appears with the next message in that thread.

`POST /share-contact-card`

### Request body

- `lineId` (string (UUID v4), required) — The line whose card to share. The line must already have a card from POST /set-contact-card.

- `destination` (string, required) — The recipient — a phone number (any common format, normalised to E.164) or an iMessage email address. An iMessage conversation between the line and this destination must already exist; send a message first if it does not.

> **The conversation must already exist**
>
> Sharing goes into a chat, not to a number. If the line has never exchanged a message with the destination you get `404 CHAT_NOT_FOUND`. Send one message with `/send-api-message` first, then share.

> **SHARED means the line accepted it**
>
> `confirmation: LINE_ACCEPTED` is exactly that — Messages on the line took the send. The API cannot see whether the recipient's device displayed the card, so there is no “delivered” state and none is implied.

### Status codes

- **200** — SHARED — the line accepted the send.
- **400** — Bad lineId or destination.
- **401** — Missing or invalid API key.
- **403** — Trial account, or `LINE_NOT_ELIGIBLE`.
- **404** — `CHAT_NOT_FOUND` — no conversation with the destination on this line.
- **409** — `NO_CONTACT_CARD` — set one first; or the line is not ready (same codes as set).
- **429** — Rate limit exceeded.
- **502** — `SHARE_REJECTED` — the line refused the share.
- **503** — `LINE_OFFLINE` — nothing was shared; retry shortly.
- **504** — `SHARE_TIMEOUT` — INDETERMINATE; the card may have gone out.

> **Idempotency and resharing**
>
> The same line, destination and card revision within a short window is one share; a repeat replays the first result with `deduped: true`. Updating the card changes its revision, so share-after-update always sends. An `INDETERMINATE` result _is_ cached, so a blind retry after a timeout does not send a second card — pass a new `Idempotency-Key` once the recipient confirms nothing arrived.

**Request — Share**

```bash
curl -X POST https://api.tryprojectblue.com/share-contact-card \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lineId": "a3f8c2d1-b4e9-4f2a-c8d3-e1f0a2b3c4d5",
    "destination": "+15551234567"
  }'
```

**Request — Share · JavaScript**

```javascript
// Run on your server. Keep your API key private.
const response = await fetch("https://api.tryprojectblue.com/share-contact-card", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.PB_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "lineId": "a3f8c2d1-b4e9-4f2a-c8d3-e1f0a2b3c4d5",
    "destination": "+15551234567"
  })
});
const data = await response.json();
if (!response.ok) throw new Error(JSON.stringify(data));
console.log(data);
```

**Request — Share · Python**

```python
import os
import requests

response = requests.request(
    "POST",
    "https://api.tryprojectblue.com/share-contact-card",
    headers={
        "Authorization": "Bearer " + os.environ["PB_API_KEY"],
        "Content-Type": "application/json"
    },
    json={"lineId": "a3f8c2d1-b4e9-4f2a-c8d3-e1f0a2b3c4d5", "destination": "+15551234567"},
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

**Request — Reshare**

```bash
curl -X POST https://api.tryprojectblue.com/share-contact-card \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reshare-2026-10-13-rivera-group" \
  -d '{
    "lineId": "a3f8c2d1-b4e9-4f2a-c8d3-e1f0a2b3c4d5",
    "destination": "+15551234567"
  }'
```

**Request — Reshare · JavaScript**

```javascript
// Run on your server. Keep your API key private.
const response = await fetch("https://api.tryprojectblue.com/share-contact-card", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.PB_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "reshare-2026-10-13-rivera-group"
  },
  body: JSON.stringify({
    "lineId": "a3f8c2d1-b4e9-4f2a-c8d3-e1f0a2b3c4d5",
    "destination": "+15551234567"
  })
});
const data = await response.json();
if (!response.ok) throw new Error(JSON.stringify(data));
console.log(data);
```

**Request — Reshare · Python**

```python
import os
import requests

response = requests.request(
    "POST",
    "https://api.tryprojectblue.com/share-contact-card",
    headers={
        "Authorization": "Bearer " + os.environ["PB_API_KEY"],
        "Content-Type": "application/json",
        "Idempotency-Key": "reshare-2026-10-13-rivera-group"
    },
    json={"lineId": "a3f8c2d1-b4e9-4f2a-c8d3-e1f0a2b3c4d5", "destination": "+15551234567"},
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

**Response — 200 SHARED**

```json
{
  "status": "SHARED",
  "lineId": "a3f8c2d1-b4e9-4f2a-c8d3-e1f0a2b3c4d5",
  "destination": "+15551234567",
  "chatGuid": "iMessage;-;+15551234567",
  "confirmation": "LINE_ACCEPTED",
  "contactCard": {
    "cardId": "cmm7p3x9a0001s6ryh2k4d8nq",
    "firstName": "Jamie",
    "lastName": "Rivera Realty",
    "imageUrl": "https://…/contact-poster-images/api/user-42/line-84/3f9c…e1.jpg",
    "hasPhoto": true,
    "appliedToLine": true,
    "updatedAt": "2026-10-13T17:04:12.118Z"
  },
  "line": { "readiness": "READY", "serverVersion": "2.2.0" },
  "note": "The line accepted the share. Apple controls when the recipient sees the name and photo; it usually appears on the next message in that conversation.",
  "error_code": null,
  "error_message": null
}
```

**Response — 404 — no chat**

```json
{
  "status": "FAILED",
  "error_code": "CHAT_NOT_FOUND",
  "error_message": "No iMessage conversation with +15551234567 exists on this line. Send a message to the destination first, then share.",
  "lineId": "a3f8c2d1-b4e9-4f2a-c8d3-e1f0a2b3c4d5",
  "destination": "+15551234567"
}
```

**Response — 409 — no card**

```json
{
  "status": "FAILED",
  "error_code": "NO_CONTACT_CARD",
  "error_message": "This line has no contact card. Set one with POST /set-contact-card first."
}
```

**Response — 504 INDETERMINATE**

```json
{
  "status": "INDETERMINATE",
  "lineId": "a3f8c2d1-b4e9-4f2a-c8d3-e1f0a2b3c4d5",
  "destination": "+15551234567",
  "chatGuid": "iMessage;-;+15551234567",
  "error_code": "SHARE_TIMEOUT",
  "error_message": "The line did not confirm the share within 15s. The card may still have been sent; do not assume either way. Retry with a new Idempotency-Key only if the recipient confirms they did not receive it."
}
```