Contact Cards

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 (or update) 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 on a specific chat to actually prompt the recipient to save your name and photo.

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 for the full endpoint specification.

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"),
})

Creating a card for a phone number that already has one returns error 2014. Use the update endpoint instead.

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. See the Retrieve Contact Card API reference.

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. See the Update Contact Card API reference.

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.

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.
• 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 -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 for the full cadence and behavior notes.

• Sharing Contact Card — push the configured card into an iMessage chat
• Error 2012 — contact card not found
• Error 2014 — contact card already exists
• API Reference: Contact Card