# Get Contact Card

`POST /tools/contact-card`

Retrieve contact information as a vCard and get a presigned URL to download the file. Contact cards can be sent via MMS as a media file.

## Authentication

Send your API key in the `PINNACLE-API-KEY` header.

## Request body

Required.

Content type: `application/json`.

### Fields

- `id` — `string`. The unique identifier of the contact. This identifier is a string that always begins with the prefix `cc_`, for example: `cc_1234567890`.
- `options` — `object`, optional
- `options.expiresAt` — `string`, optional. Set an expiration date for your download URL in IS0 8610 format.

If this field is not provided, the expiration time is defaulted to one hour after retrieval.

### Example

```json
{
  "id": "cc_1234567890"
}
```

## Responses

### 200

Returns complete contact information.

Content type: `application/json`. Schema: `object`.

- `id` — `string`. The unique identifier of the contact. This identifier is a string that always begins with the prefix `cc_`, for example: `cc_1234567890`.
- `formattedName` — `string`. Full display name for the vCard.
- `name` — `object`. Structured name components.
- `name.familyName` — `string`, optional. Last name or surname.
- `name.givenName` — `string`, optional. First name or given name.
- `name.additionalNames` — `string[]`, optional. Middle names or additional names.
- `name.honorificPrefixes` — `string[]`, optional. Title prefixes like "Dr.", "Mr.", "Ms.".
- `name.honorificSuffixes` — `string[]`, optional. Title suffixes like "Jr.", "Sr.", "PhD".
- `nickname` — `string[]`, optional. Nicknames or aliases.
- `birthday` — `string`, optional. Birthday in ISO 8601 date format (YYYY-MM-DD).
- `addresses` — `VcardAddress[]`. Physical addresses.
- `addresses[].countryName` — `string`, optional. Country name.
- `addresses[].extendedAddress` — `string`, optional. Extended address information (apartment, suite, etc.).
- `addresses[].fulladdress` — `string`, optional. Complete formatted address as a single string.
- `addresses[].locality` — `string`, optional. City or locality.
- `addresses[].postalCode` — `string`, optional. ZIP code or postal code.
- `addresses[].postOfficeBox` — `string`, optional. P.O. Box number.
- `addresses[].region` — `string`, optional. State, province, or region.
- `addresses[].streetAddress` — `string`, optional. Street address or street name and number.
- `addresses[].type` — `string[]`, optional. Address type classifications.
- `url` — `string`, optional. Website URL.
- `phones` — `VcardPhone[]`. Phone numbers.
- `phones[].type` — `string[]`, optional. Phone number type classifications.
- `phones[].value` — `string`, optional. Phone number in any format.
- `emails` — `VcardEmail[]`. Email addresses.
- `emails[].type` — `string[]`, optional. Email address type classifications.
- `emails[].value` — `string`, optional. Email address.
- `timezone` — `string`, optional. Timezone (e.g., "America/New_York").
- `geo` — `object`, optional. Geographic coordinates.
- `geo.latitude` — `number`, optional. Latitude coordinate.
- `geo.longitude` — `number`, optional. Longitude coordinate.
- `title` — `string`, optional. Job title or position.
- `role` — `string`, optional. Role or function within the organization.
- `organization` — `object`, optional. Organization or company information.
- `organization.name` — `string`, optional. Company or organization name.
- `organization.units` — `string[]`, optional. Department or organizational units.
- `categories` — `string[]`, default: []. Categories or tags for organizing contacts.
- `note` — `string`, optional. Additional notes or comments.
- `revision` — `string`. ISO 8601 timestamp of last vCard update.
- `file` — `object`. File associated to the contact.
- `file.url` — `string`. Presigned URL to download the contact card.
- `file.metadata` — `object`. Additional information about the download URL.
- `file.metadata.expiresAt` — `string`. When the download URL expires in ISO 8601 format.

Null indicates that it is permanent.

Example:

```json
{
  "id": "cc_1234567890",
  "formattedName": "Porter",
  "name": {
    "familyName": "Porter",
    "givenName": "Liam",
    "additionalNames": [
      "Liam Porter"
    ],
    "honorificPrefixes": [
      "Mr"
    ],
    "honorificSuffixes": []
  },
  "addresses": [],
  "phones": [],
  "emails": [],
  "categories": [],
  "revision": "2025-08-15T18:35:42.538+00:00",
  "file": {
    "url": "https://server.pinnacle.sh//storage/v1/example",
    "metadata": {
      "expiresAt": null
    }
  }
}
```

### 400

Validation failed. The payload has missing required fields and/or invalid types.

See https://zod.dev/error-formatting for more information.

Content type: `application/json`. Schema: `object`.

- `description` — `string`. Human-readable summary of validation failures.
- `errors` — `object`. Structured dictionary of issues containing two main sections:
- `errors`: Array of global validation errors not tied to specific fields
- `properties`: Object mapping field names to their specific validation errors, where each field contains an `errors` array

Example:

```json
{
  "description": "✖ Invalid input: expected string, received number\n  → at example_field",
  "errors": {
    "errors": [
      "Unrecognized key: 'extraKey'"
    ],
    "properties": {
      "example_field": {
        "errors": [
          "Invalid input: expected string, received NaN"
        ]
      }
    }
  }
}
```

### 401

The request lacks valid authentication credentials or the provided credentials are invalid.

Ensure you're including a valid API key in the request headers and that your account has the necessary permissions to access this endpoint.

Content type: `application/json`. Schema: `object`.

- `error` — `string`. Human-readable description of the error that occurred, corresponding to the HTTP status code.

Example:

```json
{
  "error": "Invalid API key."
}
```

### 403

Your subscription does not include access to this feature.

This occurs when attempting to use functionality that requires a higher subscription tier.
Please upgrade your subscription to access this feature.

Content type: `application/json`. Schema: `object`.

- `error` — `string`. Human-readable description of the error that occurred, corresponding to the HTTP status code.

Example:

```json
{
  "error": "Your subscription does not include access to this feature."
}
```

### 500

An unexpected error occurred on Pinnacle's servers while processing your request.

If this error persists, please contact support with the request details.

Content type: `application/json`. Schema: `object`.

- `error` — `string`. Human-readable description of the error that occurred, corresponding to the HTTP status code.

Example:

```json
{
  "error": "An unexpected error occurred while processing your request."
}
```

## SDK examples

### TypeScript

```typescript
import { PinnacleClient } from "rcs-js";

const client = new PinnacleClient({
  apiKey: process.env.PINNACLE_API_KEY!,
});

await client.tools.contactCard.get({
    id: "cc_1234567890"
});
```

### Python

```python
import os
from rcs import Pinnacle

client = Pinnacle(
    api_key=os.environ["PINNACLE_API_KEY"],
)

client.tools.contact_card.get(
    id="cc_1234567890",
)
```

### Ruby

```ruby
require "rcs"

client = Pinnacle::Client.new(
  api_key: ENV.fetch("PINNACLE_API_KEY")
)

client.tools.contact_card.get(id: "cc_1234567890")
```

## Machine-readable schema

[OpenAPI 3.1 JSON](https://docs.pinnacle.sh/openapi.json)