> 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/upsert-contact-card/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pinnacle.sh/_mcp/server. # Upsert Contact Card POST https://api.pinnacle.sh/tools/contact-card/upsert Content-Type: application/json Create a new contact card or updates an existing one with full vCard data. Contact cards can be sent [via MMS](/api-reference/messages/send-mms) as a media file. Reference: https://docs.pinnacle.sh/api-reference/tools/upsert-contact-card ## Authentication - `PINNACLE-API-KEY` header (required) — API Key authentication via header ## Request ### Body (application/json) This endpoint expects a vCardSchema. - `formattedName` (string, required) — Full display name for the vCard. - `name` (VCardSchemaName, required) — Structured name components. - `id` (string, optional) — The unique identifier of the contact. This identifier is a string that always begins with the prefix `cc_`, for example: `cc_1234567890`. - `nickname` (list of string, optional) — Nicknames or aliases. - `birthday` (string, optional, nullable) — Birthday in ISO 8601 date format (YYYY-MM-DD). - `addresses` (list of vCardAddressSchema, optional) — Physical addresses. - `url` (string, optional, nullable) — Website URL. - `phones` (list of vCardPhoneSchema, optional) — Phone numbers. - `emails` (list of vCardEmailSchema, optional) — Email addresses. - `timezone` (string, optional, nullable) — Timezone (e.g., "America/New_York"). - `geo` (VCardSchemaGeo, optional, nullable) — Geographic coordinates. - `title` (string, optional, nullable) — Job title or position. - `role` (string, optional, nullable) — Role or function within the organization. - `organization` (VCardSchemaOrganization, optional) — Organization or company information. - `categories` (list of string, optional) — Categories or tags for organizing contacts. - `note` (string, optional, nullable) — Additional notes or comments. - `photo` (string, optional, nullable) — Contact's photo ## Response ### 200 Successfully created/updated contact card. - `id` (string, optional) — The unique identifier of the contact. This identifier is a string that always begins with the prefix `cc_`, for example: `cc_1234567890`. - `downloadUrl` (string, optional) — Presigned download url to download vCard data. This link will expire in one hour. ## 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 ### VCardSchemaName 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". ### 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` ### 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. ### 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. ### VCardSchemaGeo Geographic coordinates. - `latitude` (double, optional) — Latitude coordinate. - `longitude` (double, optional) — Longitude coordinate. ### VCardSchemaOrganization 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 ## Examples **Request** ```json { "formattedName": "Jane Smith", "name": { "familyName": "Smith", "givenName": "Jane", "additionalNames": [ "A." ], "honorificPrefixes": [ "Dr." ], "honorificSuffixes": [ "PhD" ] }, "id": "cc_1234567890", "nickname": [ "Janie" ], "birthday": "1990-02-15", "addresses": [ { "countryName": "USA", "extendedAddress": "Apt. 4B", "locality": "Anytown", "postalCode": "90210", "postOfficeBox": "PO Box 123", "region": "CA", "streetAddress": "123 Main St", "type": [ "HOME", "PREF" ] } ], "url": "https://app.pinnacle.sh", "phones": [ { "type": [ "CELL" ], "value": "+15551234567" } ], "emails": [ { "type": [ "INTERNET" ], "value": "jane.smith@example.com" } ], "timezone": "America/Los_Angeles", "geo": { "latitude": 34.0522, "longitude": -118.2437 }, "title": "Engineer", "role": "Developer", "organization": { "name": "Acme Co", "units": [ "Engineering", "R&D" ] }, "categories": [ "Friend", "Colleague" ], "note": "Test contact entry", "photo": "https://fastly.picsum.photos/id/853/200/200.jpg?hmac=f4LF-tVBBnJb9PQAVEO8GCTGWgLUnxQLw44rUofE6mQ" } ``` **Response** ```json { "id": "cc_1234567890", "downloadUrl": "https://files.short.ly/vcard/def456.vcf" } ``` **SDK Code** ```python Upserted Contact Card import requests url = "https://api.pinnacle.sh/tools/contact-card/upsert" payload = { "formattedName": "Jane Smith", "name": { "familyName": "Smith", "givenName": "Jane", "additionalNames": ["A."], "honorificPrefixes": ["Dr."], "honorificSuffixes": ["PhD"] }, "id": "cc_1234567890", "nickname": ["Janie"], "birthday": "1990-02-15", "addresses": [ { "countryName": "USA", "extendedAddress": "Apt. 4B", "locality": "Anytown", "postalCode": "90210", "postOfficeBox": "PO Box 123", "region": "CA", "streetAddress": "123 Main St", "type": ["HOME", "PREF"] } ], "url": "https://app.pinnacle.sh", "phones": [ { "type": ["CELL"], "value": "+15551234567" } ], "emails": [ { "type": ["INTERNET"], "value": "jane.smith@example.com" } ], "timezone": "America/Los_Angeles", "geo": { "latitude": 34.0522, "longitude": -118.2437 }, "title": "Engineer", "role": "Developer", "organization": { "name": "Acme Co", "units": ["Engineering", "R&D"] }, "categories": ["Friend", "Colleague"], "note": "Test contact entry", "photo": "https://fastly.picsum.photos/id/853/200/200.jpg?hmac=f4LF-tVBBnJb9PQAVEO8GCTGWgLUnxQLw44rUofE6mQ" } headers = { "PINNACLE-API-KEY": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Upserted Contact Card const url = 'https://api.pinnacle.sh/tools/contact-card/upsert'; const options = { method: 'POST', headers: {'PINNACLE-API-KEY': '', 'Content-Type': 'application/json'}, body: '{"formattedName":"Jane Smith","name":{"familyName":"Smith","givenName":"Jane","additionalNames":["A."],"honorificPrefixes":["Dr."],"honorificSuffixes":["PhD"]},"id":"cc_1234567890","nickname":["Janie"],"birthday":"1990-02-15","addresses":[{"countryName":"USA","extendedAddress":"Apt. 4B","locality":"Anytown","postalCode":"90210","postOfficeBox":"PO Box 123","region":"CA","streetAddress":"123 Main St","type":["HOME","PREF"]}],"url":"https://app.pinnacle.sh","phones":[{"type":["CELL"],"value":"+15551234567"}],"emails":[{"type":["INTERNET"],"value":"jane.smith@example.com"}],"timezone":"America/Los_Angeles","geo":{"latitude":34.0522,"longitude":-118.2437},"title":"Engineer","role":"Developer","organization":{"name":"Acme Co","units":["Engineering","R&D"]},"categories":["Friend","Colleague"],"note":"Test contact entry","photo":"https://fastly.picsum.photos/id/853/200/200.jpg?hmac=f4LF-tVBBnJb9PQAVEO8GCTGWgLUnxQLw44rUofE6mQ"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Upserted Contact Card package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.pinnacle.sh/tools/contact-card/upsert" payload := strings.NewReader("{\n \"formattedName\": \"Jane Smith\",\n \"name\": {\n \"familyName\": \"Smith\",\n \"givenName\": \"Jane\",\n \"additionalNames\": [\n \"A.\"\n ],\n \"honorificPrefixes\": [\n \"Dr.\"\n ],\n \"honorificSuffixes\": [\n \"PhD\"\n ]\n },\n \"id\": \"cc_1234567890\",\n \"nickname\": [\n \"Janie\"\n ],\n \"birthday\": \"1990-02-15\",\n \"addresses\": [\n {\n \"countryName\": \"USA\",\n \"extendedAddress\": \"Apt. 4B\",\n \"locality\": \"Anytown\",\n \"postalCode\": \"90210\",\n \"postOfficeBox\": \"PO Box 123\",\n \"region\": \"CA\",\n \"streetAddress\": \"123 Main St\",\n \"type\": [\n \"HOME\",\n \"PREF\"\n ]\n }\n ],\n \"url\": \"https://app.pinnacle.sh\",\n \"phones\": [\n {\n \"type\": [\n \"CELL\"\n ],\n \"value\": \"+15551234567\"\n }\n ],\n \"emails\": [\n {\n \"type\": [\n \"INTERNET\"\n ],\n \"value\": \"jane.smith@example.com\"\n }\n ],\n \"timezone\": \"America/Los_Angeles\",\n \"geo\": {\n \"latitude\": 34.0522,\n \"longitude\": -118.2437\n },\n \"title\": \"Engineer\",\n \"role\": \"Developer\",\n \"organization\": {\n \"name\": \"Acme Co\",\n \"units\": [\n \"Engineering\",\n \"R&D\"\n ]\n },\n \"categories\": [\n \"Friend\",\n \"Colleague\"\n ],\n \"note\": \"Test contact entry\",\n \"photo\": \"https://fastly.picsum.photos/id/853/200/200.jpg?hmac=f4LF-tVBBnJb9PQAVEO8GCTGWgLUnxQLw44rUofE6mQ\"\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 Upserted Contact Card require 'uri' require 'net/http' url = URI("https://api.pinnacle.sh/tools/contact-card/upsert") 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 \"formattedName\": \"Jane Smith\",\n \"name\": {\n \"familyName\": \"Smith\",\n \"givenName\": \"Jane\",\n \"additionalNames\": [\n \"A.\"\n ],\n \"honorificPrefixes\": [\n \"Dr.\"\n ],\n \"honorificSuffixes\": [\n \"PhD\"\n ]\n },\n \"id\": \"cc_1234567890\",\n \"nickname\": [\n \"Janie\"\n ],\n \"birthday\": \"1990-02-15\",\n \"addresses\": [\n {\n \"countryName\": \"USA\",\n \"extendedAddress\": \"Apt. 4B\",\n \"locality\": \"Anytown\",\n \"postalCode\": \"90210\",\n \"postOfficeBox\": \"PO Box 123\",\n \"region\": \"CA\",\n \"streetAddress\": \"123 Main St\",\n \"type\": [\n \"HOME\",\n \"PREF\"\n ]\n }\n ],\n \"url\": \"https://app.pinnacle.sh\",\n \"phones\": [\n {\n \"type\": [\n \"CELL\"\n ],\n \"value\": \"+15551234567\"\n }\n ],\n \"emails\": [\n {\n \"type\": [\n \"INTERNET\"\n ],\n \"value\": \"jane.smith@example.com\"\n }\n ],\n \"timezone\": \"America/Los_Angeles\",\n \"geo\": {\n \"latitude\": 34.0522,\n \"longitude\": -118.2437\n },\n \"title\": \"Engineer\",\n \"role\": \"Developer\",\n \"organization\": {\n \"name\": \"Acme Co\",\n \"units\": [\n \"Engineering\",\n \"R&D\"\n ]\n },\n \"categories\": [\n \"Friend\",\n \"Colleague\"\n ],\n \"note\": \"Test contact entry\",\n \"photo\": \"https://fastly.picsum.photos/id/853/200/200.jpg?hmac=f4LF-tVBBnJb9PQAVEO8GCTGWgLUnxQLw44rUofE6mQ\"\n}" response = http.request(request) puts response.read_body ``` ```java Upserted 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/upsert") .header("PINNACLE-API-KEY", "") .header("Content-Type", "application/json") .body("{\n \"formattedName\": \"Jane Smith\",\n \"name\": {\n \"familyName\": \"Smith\",\n \"givenName\": \"Jane\",\n \"additionalNames\": [\n \"A.\"\n ],\n \"honorificPrefixes\": [\n \"Dr.\"\n ],\n \"honorificSuffixes\": [\n \"PhD\"\n ]\n },\n \"id\": \"cc_1234567890\",\n \"nickname\": [\n \"Janie\"\n ],\n \"birthday\": \"1990-02-15\",\n \"addresses\": [\n {\n \"countryName\": \"USA\",\n \"extendedAddress\": \"Apt. 4B\",\n \"locality\": \"Anytown\",\n \"postalCode\": \"90210\",\n \"postOfficeBox\": \"PO Box 123\",\n \"region\": \"CA\",\n \"streetAddress\": \"123 Main St\",\n \"type\": [\n \"HOME\",\n \"PREF\"\n ]\n }\n ],\n \"url\": \"https://app.pinnacle.sh\",\n \"phones\": [\n {\n \"type\": [\n \"CELL\"\n ],\n \"value\": \"+15551234567\"\n }\n ],\n \"emails\": [\n {\n \"type\": [\n \"INTERNET\"\n ],\n \"value\": \"jane.smith@example.com\"\n }\n ],\n \"timezone\": \"America/Los_Angeles\",\n \"geo\": {\n \"latitude\": 34.0522,\n \"longitude\": -118.2437\n },\n \"title\": \"Engineer\",\n \"role\": \"Developer\",\n \"organization\": {\n \"name\": \"Acme Co\",\n \"units\": [\n \"Engineering\",\n \"R&D\"\n ]\n },\n \"categories\": [\n \"Friend\",\n \"Colleague\"\n ],\n \"note\": \"Test contact entry\",\n \"photo\": \"https://fastly.picsum.photos/id/853/200/200.jpg?hmac=f4LF-tVBBnJb9PQAVEO8GCTGWgLUnxQLw44rUofE6mQ\"\n}") .asString(); ``` ```php Upserted Contact Card request('POST', 'https://api.pinnacle.sh/tools/contact-card/upsert', [ 'body' => '{ "formattedName": "Jane Smith", "name": { "familyName": "Smith", "givenName": "Jane", "additionalNames": [ "A." ], "honorificPrefixes": [ "Dr." ], "honorificSuffixes": [ "PhD" ] }, "id": "cc_1234567890", "nickname": [ "Janie" ], "birthday": "1990-02-15", "addresses": [ { "countryName": "USA", "extendedAddress": "Apt. 4B", "locality": "Anytown", "postalCode": "90210", "postOfficeBox": "PO Box 123", "region": "CA", "streetAddress": "123 Main St", "type": [ "HOME", "PREF" ] } ], "url": "https://app.pinnacle.sh", "phones": [ { "type": [ "CELL" ], "value": "+15551234567" } ], "emails": [ { "type": [ "INTERNET" ], "value": "jane.smith@example.com" } ], "timezone": "America/Los_Angeles", "geo": { "latitude": 34.0522, "longitude": -118.2437 }, "title": "Engineer", "role": "Developer", "organization": { "name": "Acme Co", "units": [ "Engineering", "R&D" ] }, "categories": [ "Friend", "Colleague" ], "note": "Test contact entry", "photo": "https://fastly.picsum.photos/id/853/200/200.jpg?hmac=f4LF-tVBBnJb9PQAVEO8GCTGWgLUnxQLw44rUofE6mQ" }', 'headers' => [ 'Content-Type' => 'application/json', 'PINNACLE-API-KEY' => '', ], ]); echo $response->getBody(); ``` ```csharp Upserted Contact Card using RestSharp; var client = new RestClient("https://api.pinnacle.sh/tools/contact-card/upsert"); var request = new RestRequest(Method.POST); request.AddHeader("PINNACLE-API-KEY", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"formattedName\": \"Jane Smith\",\n \"name\": {\n \"familyName\": \"Smith\",\n \"givenName\": \"Jane\",\n \"additionalNames\": [\n \"A.\"\n ],\n \"honorificPrefixes\": [\n \"Dr.\"\n ],\n \"honorificSuffixes\": [\n \"PhD\"\n ]\n },\n \"id\": \"cc_1234567890\",\n \"nickname\": [\n \"Janie\"\n ],\n \"birthday\": \"1990-02-15\",\n \"addresses\": [\n {\n \"countryName\": \"USA\",\n \"extendedAddress\": \"Apt. 4B\",\n \"locality\": \"Anytown\",\n \"postalCode\": \"90210\",\n \"postOfficeBox\": \"PO Box 123\",\n \"region\": \"CA\",\n \"streetAddress\": \"123 Main St\",\n \"type\": [\n \"HOME\",\n \"PREF\"\n ]\n }\n ],\n \"url\": \"https://app.pinnacle.sh\",\n \"phones\": [\n {\n \"type\": [\n \"CELL\"\n ],\n \"value\": \"+15551234567\"\n }\n ],\n \"emails\": [\n {\n \"type\": [\n \"INTERNET\"\n ],\n \"value\": \"jane.smith@example.com\"\n }\n ],\n \"timezone\": \"America/Los_Angeles\",\n \"geo\": {\n \"latitude\": 34.0522,\n \"longitude\": -118.2437\n },\n \"title\": \"Engineer\",\n \"role\": \"Developer\",\n \"organization\": {\n \"name\": \"Acme Co\",\n \"units\": [\n \"Engineering\",\n \"R&D\"\n ]\n },\n \"categories\": [\n \"Friend\",\n \"Colleague\"\n ],\n \"note\": \"Test contact entry\",\n \"photo\": \"https://fastly.picsum.photos/id/853/200/200.jpg?hmac=f4LF-tVBBnJb9PQAVEO8GCTGWgLUnxQLw44rUofE6mQ\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Upserted Contact Card import Foundation let headers = [ "PINNACLE-API-KEY": "", "Content-Type": "application/json" ] let parameters = [ "formattedName": "Jane Smith", "name": [ "familyName": "Smith", "givenName": "Jane", "additionalNames": ["A."], "honorificPrefixes": ["Dr."], "honorificSuffixes": ["PhD"] ], "id": "cc_1234567890", "nickname": ["Janie"], "birthday": "1990-02-15", "addresses": [ [ "countryName": "USA", "extendedAddress": "Apt. 4B", "locality": "Anytown", "postalCode": "90210", "postOfficeBox": "PO Box 123", "region": "CA", "streetAddress": "123 Main St", "type": ["HOME", "PREF"] ] ], "url": "https://app.pinnacle.sh", "phones": [ [ "type": ["CELL"], "value": "+15551234567" ] ], "emails": [ [ "type": ["INTERNET"], "value": "jane.smith@example.com" ] ], "timezone": "America/Los_Angeles", "geo": [ "latitude": 34.0522, "longitude": -118.2437 ], "title": "Engineer", "role": "Developer", "organization": [ "name": "Acme Co", "units": ["Engineering", "R&D"] ], "categories": ["Friend", "Colleague"], "note": "Test contact entry", "photo": "https://fastly.picsum.photos/id/853/200/200.jpg?hmac=f4LF-tVBBnJb9PQAVEO8GCTGWgLUnxQLw44rUofE6mQ" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.pinnacle.sh/tools/contact-card/upsert")! 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.