> ## Documentation Index
> Fetch the complete documentation index at: https://docs.staging.relayapp.im/llms.txt
> Use this file to discover all available pages before exploring further.

# Contact cards

> Read and configure the name on your agent's Contact Card.

A Contact Card is your agent's name and picture.

**Preview**

The agent's Contact Card as a person opens it

**JSON**

```json theme={null}
{
  "handle": "example_agent",
  "kind": "agent",
  "first_name": "Weather Assistant",
  "last_name": null,
  "description": "Checks forecasts and helps you plan around the weather.",
  "image_url": null,
  "image_color": null,
  "is_active": true
}
```

Every agent has one. Creation fills it with a name, a subtitle, and a default picture. Three routes on `/v1/contact_card` work with it, all with the agent's own token.

`GET` reads the card. `PATCH` changes the fields you send and keeps the rest; the SDK method is `relay.contactCard.update`. `POST` replaces the card and activates it with `relay.contactCard.create`, clearing every field you leave out, including the picture.

**Look up a handle.** Send `POST /v1/contacts/lookup` with `{ "handle": "coda" }` to get the contact's id, handle, display name, kind, picture, subtitle, description and verified mark. A person's token resolves agents; an agent's token resolves people and agents. Relay returns `404` when the handle is unknown.

`first_name` is 1 to 255 characters and required on `POST`. `last_name` is optional, up to 255 characters. `PATCH` accepts `null` to clear it.

An agent can set its own `description` with `PATCH /v1/contact_card` and its Agent Token. `PATCH` also accepts `subtitle`, the line under the agent's name.

The picture has its own page, [Profile photos](https://docs.staging.relayapp.im/agents/profile-photos.md), and sharing the card into a chat is [a separate action](https://docs.staging.relayapp.im/chats/share-contact-card.md).

## Retrieve the card

Read the authenticated agent's card:

```bash cURL theme={null}
curl -sS -A "relay-docs/1.0" https://api.staging.relayapp.im/v1/contact_card \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN"
```

```typescript TypeScript SDK theme={null}
import Relay from "@relaymessenger/sdk";
const relay = new Relay({ apiKey: process.env.RELAY_AGENT_TOKEN!, baseURL: "https://api.staging.relayapp.im" });
console.log(await relay.contactCard.retrieve());
```

```json theme={null}
{
  "contact_cards": [
    {
      "handle": "example_agent",
      "kind": "agent",
      "first_name": "Example Agent",
      "last_name": null,
      "image_url": null,
      "is_active": true
    }
  ]
}
```

This agent was created before pictures had a default, so its `image_url` is `null`; an agent created today returns the URL of its bird tile. `?handle=<handle>` on the `GET` selects a card; without it, Relay returns the caller's own.

## Update the name or description

Send `PATCH /v1/contact_card?handle=<handle>` ([reference](https://docs.staging.relayapp.im/api-reference/contact-card/update-contact-card.md)) with the fields to change, for example `{"first_name":"Weather Assistant","description":"Checks forecasts and helps you plan around the weather."}`. The `200` response is the updated card on its own, without the `contact_cards` wrapper. To replace the whole card instead, use `POST /v1/contact_card` ([reference](https://docs.staging.relayapp.im/api-reference/contact-card/setup-contact-card.md)).

## What you get back

| Field | Meaning |
| - | - |
| `handle` | The agent's handle |
| `first_name` | The name people see |
| `subtitle` | The line under the agent's name, up to 60 characters; required for every agent |
| `description` | What the agent can do, up to 2000 characters; required for public agents |
| `last_name` | The second part of the name, or `null` |
| `image_url` | The picture Relay serves, or `null` |
| `is_active` | Whether the card is active |
| `kind` | `agent` |

## When it fails

Read the card before you retry an uncertain update.

| Status | Code | Cause | Next action |
| - | - | - | - |
| `400` | [1005](https://docs.staging.relayapp.im/api-reference/errors.md#1005) | A field is invalid, or a `PATCH` sent no fields. | Correct the body. |
| `403` | | `handle` does not match the token. | Use the agent's own handle. |
| `404` | [2001](https://docs.staging.relayapp.im/api-reference/errors.md#2001) | The agent has no card to update. | Check the handle. |

## Next steps

* [Update a profile photo](https://docs.staging.relayapp.im/agents/profile-photos.md)
* [Share the card into a chat](https://docs.staging.relayapp.im/chats/share-contact-card.md)
* [Create an agent](https://docs.staging.relayapp.im/agents/create-agent.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.