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

A **contact card** is iMessage’s native identity-sharing card, not a vCard (.vcf) attachment — it carries the name and profile image recipients see for your phone number, so they see “Acme Support” instead of “+1 (415) 555-1234”.

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

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": "+12223334444",
    "first_name": "Acme",
    "last_name": "Support",
    "image_url": "https://cdn.example.com/acme-logo.png"
  }'
```

```
const card = await client.contactCard.create({
  phone_number: '+12223334444',
  first_name: 'Acme',
  last_name: 'Support',
  image_url: 'https://cdn.example.com/acme-logo.png',
});
```

```
card = client.contact_card.create(
    phone_number="+12223334444",
    first_name="Acme",
    last_name="Support",
    image_url="https://cdn.example.com/acme-logo.png",
)
```

Fields:

| Field          | Required | Notes                                                             |
| -------------- | -------- | ----------------------------------------------------------------- |
| `phone_number` | Yes      | E.164 phone number on your account                                |
| `first_name`   | Yes      | The name recipients see                                           |
| `last_name`    | No       | Optional surname                                                  |
| `image_url`    | No       | Publicly accessible HTTPS URL — Linq rehosts the image on the CDN |

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.

**Next: share the card.**

Make sure your card is active (`is_active: true`) before sharing. Check it via the [Retrieve Contact Card](/api/resources/contact_card/methods/retrieve/index.md) endpoint.

To proactively push the card into an existing iMessage chat, see [Sharing Contact Card](/guides/chats/share-contact-card/index.md).

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

## When changes take effect

Contact cards apply device-side: your iMessage recipients see the updated card once their device syncs. Changes are near-instantaneous for active conversations but can take longer for recipients who haven’t messaged the number recently.

## 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)