Contact Cards

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 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": "+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. 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 endpoint.

To proactively push the card into an existing iMessage chat, see Sharing Contact Card.

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

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

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 — push the configured card into an iMessage chat
• Error 2012 — contact card not found
• Error 2014 — contact card already exists
• API Reference: Contact Card