---
title: "Get Contact Card"
method: POST
path: "/tools/contact-card"
tags: ["tools > contactCard"]
---

# Get Contact Card

`POST /tools/contact-card`

## Request

- Base URL: `https://api.pinnacle.sh`
- URL: `https://api.pinnacle.sh/tools/contact-card`
- Auth: API key in header `PINNACLE-API-KEY`

Retrieve contact information as a vCard and get a presigned URL to download the file. Contact cards can be sent [via MMS](/api-reference/messages/send-mms) as a media file.

## Request body

- GetVCardSchema
  - `id` string, required: The unique identifier of the contact. This identifier is a string that always begins with the prefix `cc_`, for example: `cc_1234567890`.
  - `options` GetVCardSchemaOptions
    - `expiresAt` string: Set an expiration date for your download URL in IS0 8610 format. <br> If this field is not provided, the expiration time is defaulted to one hour after retrieval.

## Response `200`

Returns complete contact information.

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

## Other responses

- `400`: Validation failed. The payload has missing required fields and/or invalid types. <br> See https://zod.dev/error-formatting for more information.
- `401`: The request lacks valid authentication credentials or the provided credentials are invalid. <br> Ensure you're including a valid API key in the request headers and that your account has the necessary permissions to access this endpoint.
- `403`: Your subscription does not include access to this feature. <br> This occurs when attempting to use functionality that requires a higher subscription tier. Please upgrade your subscription to access this feature.
- `500`: An unexpected error occurred on Pinnacle's servers while processing your request. <br> If this error persists, please contact support with the request details.

---

[API](https://skmtc.dev/pinnacle/apis/pinnacle-2.md) - [All operations](https://skmtc.dev/pinnacle/apis/pinnacle-2/llms.txt) - [OpenAPI document](https://skmtc.dev/pinnacle/apis/pinnacle-2/revisions/45416dadab79?raw)