---
title: Contact Cards | API Docs
description: Set, retrieve, update, and share the contact card recipients see for your phone numbers.
---

Contact Card lets you set and share your contact information (name and profile photo) with chat participants via iMessage Name and Photo Sharing.

Use `POST /v3/contact_card` to create or update a card for a phone number. Use `PATCH /v3/contact_card` to update an existing active card. Use `GET /v3/contact_card` to retrieve the active card(s) for your partner account.

**Sharing behavior:** Sharing may not take effect in every chat due to limitations outside our control. We recommend calling the share endpoint once per day, after the first outbound activity.

A contact card is **not** a vCard (.vcf) attachment — it’s iMessage’s native identity card, so recipients see “Acme Support” in place of “+1 (415) 555-1234”.

Working with contact cards is a **two-step flow**:

1. **Configure once per phone number** — [create](#create-a-contact-card) (or [update](#update-a-contact-card)) the card on your sending number. This sets the identity but does **not** push it into any chat.
2. **Share into each chat** — [call the share endpoint](#share-a-contact-card) on a specific chat to actually prompt the recipient to save your name and photo.

## Create a contact card

Create a contact card and apply it to one of your phone numbers. The card is stored in an inactive state first; once successfully applied it activates and `is_active` returns `true`. See the [Create Contact Card API reference](/api/resources/contact_card/methods/create/index.md) for the full endpoint specification.

- [cURL](#tab-panel-40)
- [TypeScript](#tab-panel-41)
- [Python](#tab-panel-42)
- [Go](#tab-panel-43)

Terminal window

```
curl -X POST https://api.linqapp.com/api/partner/v3/contact_card \
  -H "Authorization: Bearer $LINQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "phone_number": "+15551234567",
      "first_name": "Acme",
      "last_name": "Support",
      "image_url": "https://cdn.linqapp.com/contact-card/example.jpg"
    }'
```

```
await client.contactCard.create({
  phone_number: "+15551234567",
  first_name: "Acme",
  last_name: "Support",
  image_url: "https://cdn.linqapp.com/contact-card/example.jpg",
});
```

```
client.contactCard.create(
    phone_number="+15551234567",
    first_name="Acme",
    last_name="Support",
    image_url="https://cdn.linqapp.com/contact-card/example.jpg",
)
```

```
client.ContactCard.Create(context.TODO(), linq.ContactCardNewParams{
  PhoneNumber: linq.F("+15551234567"),
  FirstName: linq.F("Acme"),
  LastName: linq.F("Support"),
  ImageUrl: linq.F("https://cdn.linqapp.com/contact-card/example.jpg"),
})
```

| Field          | Required | Type     | Description                                                                                   |
| -------------- | -------- | -------- | --------------------------------------------------------------------------------------------- |
| `phone_number` | Yes      | `string` | E.164 phone number to associate the contact card with                                         |
| `first_name`   | Yes      | `string` | First name for the contact card. Required.                                                    |
| `last_name`    | No       | `string` | Last name for the contact card. Optional.                                                     |
| `image_url`    | No       | `string` | URL of the profile image to rehost on the CDN. Only re-uploaded when a new value is provided. |

Creating a card for a phone number that already has one returns [error `2014`](/error/codes/2xxx/2014/index.md). Use the update endpoint instead.

**Creating a card does not share it.**

Creating only configures the card on your phone number — recipients won’t see anything yet. To actually prompt them to save your name and photo, [call the share endpoint](#share-a-contact-card) on each chat after the first outbound message.

Confirm the card activated (`is_active: true`) via the [Retrieve Contact Card](/api/resources/contact_card/methods/retrieve/index.md) endpoint before sharing.

## Retrieve contact cards

Retrieve every card on your account, or filter to a single phone number with the `phone_number` query parameter. If no card exists for the queried number, the endpoint returns [error `2012`](/error/codes/2xxx/2012/index.md). See the [Retrieve Contact Card API reference](/api/resources/contact_card/methods/retrieve/index.md).

## Update a contact card

Partially update the active card for a phone number — omitted fields retain their existing values. An active card must already exist, otherwise the request returns [error `2012`](/error/codes/2xxx/2012/index.md). See the [Update Contact Card API reference](/api/resources/contact_card/methods/update/index.md).

## Share a contact card

Configuring a card is **not** the same as showing it to a recipient. Your card lives on your phone number until you push it into a chat with the share endpoint — a separate API call against `POST /v3/chats/{chatId}/share_contact_card`. See the [Share Contact Card API reference](/api/resources/chats/methods/share_contact_card/index.md).

**Before calling share, make sure:**

- A contact card exists for the chat’s `from` number, with `is_active: true`. If not, the API returns [error `2012`](/error/codes/2xxx/2012/index.md).
- The chat is an **iMessage** conversation — sharing has no effect on RCS or SMS chats.
- There is at least one prior **outbound message** in the chat.

* [cURL](#tab-panel-36)
* [TypeScript](#tab-panel-37)
* [Python](#tab-panel-38)
* [Go](#tab-panel-39)

Terminal window

```
curl -X POST https://api.linqapp.com/api/partner/v3/chats/{chatId}/share_contact_card \
  -H "Authorization: Bearer $LINQ_API_KEY"
```

```
await client.chats.shareContactCard({chatId});
```

```
client.chats.share_contact_card({chat_id})
```

```
client.Chats.ShareContactCard(context.TODO(), {chatId})
```

The endpoint takes no request body — the card associated with the chat’s `from` phone number is shared automatically. There’s no confirmation the recipient saved it, so it’s safe to call **once per day** after the first outbound message in that chat.

See [Sharing Contact Card](/guides/chats/share-contact-card/index.md) for the full cadence and behavior notes.

## Related

- [Sharing Contact Card](/guides/chats/share-contact-card/index.md) — push the configured card into an iMessage chat
- [Error 2012 — contact card not found](/error/codes/2xxx/2012/index.md)
- [Error 2014 — contact card already exists](/error/codes/2xxx/2014/index.md)
- [API Reference: Contact Card](/api/resources/contact_card/index.md)