> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.pinnacle.sh/v-2/api-reference/tools/get-contact-card/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pinnacle.sh/_mcp/server. # Get Contact Card POST https://api.pinnacle.sh/tools/contact-card Content-Type: application/json 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. Reference: https://docs.pinnacle.sh/api-reference/tools/get-contact-card ## Authentication - `PINNACLE-API-KEY` header (required) — API Key authentication via header ## Request ### Body (application/json) This endpoint expects a 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, optional) ## Response ### 200 Returns complete contact information. - `addresses` (list of vCardAddressSchema, required) — Physical addresses. - `categories` (list of string, required) — Categories or tags for organizing contacts. - `emails` (list of vCardEmailSchema, required) — Email addresses. - `file` (VCardDataFile, required) — File associated to the contact. - `formattedName` (string, required) — Full display name for the vCard. - `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`. - `name` (VCardResName, required) — Structured name components. - `phones` (list of vCardPhoneSchema, required) — Phone numbers. - `revision` (string, required) — ISO 8601 timestamp of last vCard update. - `birthday` (string, optional, nullable) — Birthday in ISO 8601 date format (YYYY-MM-DD). - `geo` (VCardResGeo, optional, nullable) — Geographic coordinates. - `nickname` (list of string, optional) — Nicknames or aliases. - `note` (string, optional, nullable) — Additional notes or comments. - `organization` (VCardResOrganization, optional) — Organization or company information. - `role` (string, optional, nullable) — Role or function within the organization. - `timezone` (string, optional, nullable) — Timezone (e.g., "America/New_York"). - `title` (string, optional, nullable) — Job title or position. - `url` (string, optional, nullable) — Website URL. ## Errors ### 400 Bad Request Error Validation failed. The payload has missing required fields and/or invalid types. See [https://zod.dev/error-formatting](https://zod.dev/error-formatting) for more information. - `description` (string, required) — Human-readable summary of validation failures. - `errors` (ZodErrorErrors, required) — 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 ### 401 Unauthorized Error 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. - `error` (string, required) — Human-readable description of the error that occurred, corresponding to the HTTP status code. ### 403 Forbidden Error 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. - `error` (string, required) — Human-readable description of the error that occurred, corresponding to the HTTP status code. ### 500 Internal Server Error An unexpected error occurred on Pinnacle's servers while processing your request. If this error persists, please contact support with the request details. - `error` (string, required) — Human-readable description of the error that occurred, corresponding to the HTTP status code. ## Types ### GetVCardSchemaOptions - `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. ### vCardAddressSchema - `countryName` (string, optional) — Country name. - `extendedAddress` (string, optional) — Extended address information (apartment, suite, etc.). - `fulladdress` (string, optional) — Complete formatted address as a single string. - `locality` (string, optional) — City or locality. - `postalCode` (string, optional) — ZIP code or postal code. - `postOfficeBox` (string, optional) — P.O. Box number. - `region` (string, optional) — State, province, or region. - `streetAddress` (string, optional) — Street address or street name and number. - `type` (list of enum, optional) — Address type classifications. - Allowed values: `DOM`, `INTL`, `POSTAL`, `PARCEL`, `HOME`, `WORK`, `PREF` ### vCardEmailSchema - `type` (list of enum, optional) — Email address type classifications. - Allowed values: `PREF`, `INTERNET`, `X400`, `AOL`, `APPLELINK`, `ATTMAIL`, `CIS`, `EWORLD`, `IBMMAIL`, `MCIMAIL`, `POWERSHARE`, `PRODIGY`, `TLX` - `value` (string, optional) — Email address. ### VCardDataFile File associated to the contact. - `url` (string, required) — Presigned URL to download the contact card. - `metadata` (VCardDataFileMetadata, required) — Additional information about the download URL. ### VCardResName Structured name components. - `familyName` (string, optional) — Last name or surname. - `givenName` (string, optional) — First name or given name. - `additionalNames` (list of string, optional) — Middle names or additional names. - `honorificPrefixes` (list of string, optional) — Title prefixes like "Dr.", "Mr.", "Ms.". - `honorificSuffixes` (list of string, optional) — Title suffixes like "Jr.", "Sr.", "PhD". ### vCardPhoneSchema - `type` (list of enum, optional) — Phone number type classifications. - Allowed values: `PREF`, `WORK`, `HOME`, `VOICE`, `FAX`, `MSG`, `CELL`, `PAGER`, `BBS`, `MODEM`, `CAR`, `ISDN`, `VIDEO` - `value` (string, optional) — Phone number in any format. ### VCardResGeo Geographic coordinates. - `latitude` (double, optional) — Latitude coordinate. - `longitude` (double, optional) — Longitude coordinate. ### VCardResOrganization Organization or company information. - `name` (string, optional) — Company or organization name. - `units` (list of string, optional) — Department or organizational units. ### ZodErrorErrors 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 ### VCardDataFileMetadata Additional information about the download URL. - `expiresAt` (string, required, nullable) — When the download URL expires in ISO 8601 format. Null indicates that it is permanent. ## Examples **Request** ```json { "id": "cc_1234567890" } ``` **Response** ```json { "addresses": [], "categories": [], "emails": [], "file": { "url": "https://server.pinnacle.sh//storage/v1/example", "metadata": { "expiresAt": null } }, "formattedName": "Porter", "id": "cc_1234567890", "name": { "familyName": "Porter", "givenName": "Liam", "additionalNames": [ "Liam Porter" ], "honorificPrefixes": [ "Mr" ], "honorificSuffixes": [] }, "phones": [], "revision": "2025-08-15T18:35:42.538+00:00" } ``` **SDK Code** ```python Contact Card import requests url = "https://api.pinnacle.sh/tools/contact-card" payload = { "id": "cc_1234567890" } headers = { "PINNACLE-API-KEY": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Contact Card const url = 'https://api.pinnacle.sh/tools/contact-card'; const options = { method: 'POST', headers: {'PINNACLE-API-KEY': '', 'Content-Type': 'application/json'}, body: '{"id":"cc_1234567890"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Contact Card package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.pinnacle.sh/tools/contact-card" payload := strings.NewReader("{\n \"id\": \"cc_1234567890\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("PINNACLE-API-KEY", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Contact Card require 'uri' require 'net/http' url = URI("https://api.pinnacle.sh/tools/contact-card") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["PINNACLE-API-KEY"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"id\": \"cc_1234567890\"\n}" response = http.request(request) puts response.read_body ``` ```java Contact Card import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.pinnacle.sh/tools/contact-card") .header("PINNACLE-API-KEY", "") .header("Content-Type", "application/json") .body("{\n \"id\": \"cc_1234567890\"\n}") .asString(); ``` ```php Contact Card request('POST', 'https://api.pinnacle.sh/tools/contact-card', [ 'body' => '{ "id": "cc_1234567890" }', 'headers' => [ 'Content-Type' => 'application/json', 'PINNACLE-API-KEY' => '', ], ]); echo $response->getBody(); ``` ```csharp Contact Card using RestSharp; var client = new RestClient("https://api.pinnacle.sh/tools/contact-card"); var request = new RestRequest(Method.POST); request.AddHeader("PINNACLE-API-KEY", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"id\": \"cc_1234567890\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Contact Card import Foundation let headers = [ "PINNACLE-API-KEY": "", "Content-Type": "application/json" ] let parameters = ["id": "cc_1234567890"] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.pinnacle.sh/tools/contact-card")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` > One API for RCS, iMessage, MMS, and SMS. Build, test, and scale every channel — send your first message in minutes, not weeks.