# Contact Card

## Get contact cards

`contact_card.retrieve(ContactCardRetrieveParams**kwargs)  -> ContactCardRetrieveResponse`

**get** `/v3/contact_card`

Returns the contact card for a specific phone number, or all contact cards for the
authenticated partner if no `phone_number` is provided.

### Parameters

- `phone_number: Optional[str]`

  E.164 phone number to filter by. If omitted, all my cards for the partner are returned.

### Returns

- `class ContactCardRetrieveResponse: …`

  - `contact_cards: List[ContactCard]`

    - `first_name: str`

    - `is_active: bool`

    - `phone_number: str`

    - `image_url: Optional[str]`

    - `last_name: Optional[str]`

### Example

```python
import os
from linq import LinqAPIV3

client = LinqAPIV3(
    api_key=os.environ.get("LINQ_API_V3_API_KEY"),  # This is the default and can be omitted
)
contact_card = client.contact_card.retrieve()
print(contact_card.contact_cards)
```

#### Response

```json
{
  "contact_cards": [
    {
      "phone_number": "+15551234567",
      "first_name": "John",
      "last_name": "Doe",
      "image_url": "https://cdn.linqapp.com/contact-card/example.jpg",
      "is_active": true
    }
  ]
}
```

## Setup contact card

`contact_card.create(ContactCardCreateParams**kwargs)  -> SetContactCard`

**post** `/v3/contact_card`

Creates a contact card for a phone number. This endpoint is intended for initial, one-time setup only.

If setup does not complete, the response is `500` (`2022`) — call this endpoint again.

If the upstream write is rate-limited, the response is `503` (`4004`) instead. Setup
did not complete and the card is not active — wait before retrying, because repeated
attempts extend the rate limit.

**Note:** once a card is active, this endpoint returns `409` (`2014`) so an existing
card is never overwritten by accident. Use `PATCH /v3/contact_card` to change it.

### Parameters

- `first_name: str`

  First name for the contact card. Required.

- `phone_number: str`

  E.164 phone number to associate the contact card with

- `image_url: Optional[str]`

  Profile image URL for the contact card.

- `last_name: Optional[str]`

  Last name for the contact card. Optional.

### Returns

- `class SetContactCard: …`

  - `first_name: str`

    First name on the contact card

  - `is_active: bool`

    Whether the contact card was successfully applied to the device

  - `phone_number: str`

    The phone number the contact card is associated with

  - `image_url: Optional[str]`

    Image URL on the contact card

  - `last_name: Optional[str]`

    Last name on the contact card

### Example

```python
import os
from linq import LinqAPIV3

client = LinqAPIV3(
    api_key=os.environ.get("LINQ_API_V3_API_KEY"),  # This is the default and can be omitted
)
set_contact_card = client.contact_card.create(
    first_name="Acme",
    phone_number="+15551234567",
    image_url="https://cdn.linqapp.com/contact-card/example.jpg",
    last_name="Support",
)
print(set_contact_card.first_name)
```

#### Response

```json
{
  "phone_number": "+15551234567",
  "first_name": "John",
  "last_name": "Doe",
  "image_url": "https://cdn.linqapp.com/contact-card/example.jpg",
  "is_active": true
}
```

## Update contact card

`contact_card.update(ContactCardUpdateParams**kwargs)  -> SetContactCard`

**patch** `/v3/contact_card`

Partially updates the contact card for a phone number.

Fetches the current contact card and merges the provided fields.
Only fields present in the request body are updated; omitted fields retain their existing values.

If the update does not complete, the response is `500` (`2022`) — call this endpoint again.

If the upstream write is rate-limited, the response is `503` (`4004`) instead. The
update did not reach the line, so the card is left not active — wait before retrying,
because repeated attempts extend the rate limit.

### Parameters

- `phone_number: str`

  E.164 phone number of the contact card to update

- `first_name: Optional[str]`

  Updated first name. If omitted, the existing value is kept.

- `image_url: Optional[str]`

  Updated profile image URL. If omitted, the existing image is kept.

- `last_name: Optional[str]`

  Updated last name. If omitted, the existing value is kept.

### Returns

- `class SetContactCard: …`

  - `first_name: str`

    First name on the contact card

  - `is_active: bool`

    Whether the contact card was successfully applied to the device

  - `phone_number: str`

    The phone number the contact card is associated with

  - `image_url: Optional[str]`

    Image URL on the contact card

  - `last_name: Optional[str]`

    Last name on the contact card

### Example

```python
import os
from linq import LinqAPIV3

client = LinqAPIV3(
    api_key=os.environ.get("LINQ_API_V3_API_KEY"),  # This is the default and can be omitted
)
set_contact_card = client.contact_card.update(
    phone_number="+15551234567",
    first_name="John",
    image_url="https://cdn.linqapp.com/contact-card/example.jpg",
    last_name="Doe",
)
print(set_contact_card.first_name)
```

#### Response

```json
{
  "phone_number": "+15551234567",
  "first_name": "John",
  "last_name": "Doe",
  "image_url": "https://cdn.linqapp.com/contact-card/example.jpg",
  "is_active": true
}
```

## Domain Types

### Set Contact Card

- `class SetContactCard: …`

  - `first_name: str`

    First name on the contact card

  - `is_active: bool`

    Whether the contact card was successfully applied to the device

  - `phone_number: str`

    The phone number the contact card is associated with

  - `image_url: Optional[str]`

    Image URL on the contact card

  - `last_name: Optional[str]`

    Last name on the contact card

### Contact Card Retrieve Response

- `class ContactCardRetrieveResponse: …`

  - `contact_cards: List[ContactCard]`

    - `first_name: str`

    - `is_active: bool`

    - `phone_number: str`

    - `image_url: Optional[str]`

    - `last_name: Optional[str]`