Table of Contents
Synopsis
This API function creates a contact defined in the JSON. The response will return a vCard file for download. Contact details like contact name, organization name/title, note, photo, phone number, email address, physical address, and websites may be provided.
- A contact must have some data added in the request.
- The first and last names of the contact are required in the contact. The first and last names can only contain alphanumeric, space “ “ and period “.” characters. The request will fail if the first and last names are not included or if they contain special characters. The rest of the contact information is optional and can be empty.
- Up to four phone numbers, four email addresses, four physical addresses, and four websites are supported in the contact. The request will pass and the message will be sent, ignoring the rest of the options passed in the contact, if the limit is exceeded.
- Currently the labels “work” and “home” are supported for the phone number, email address, and physical address labels in the vCard. Additionally the labels “mobile”, “fax”, “pager”, “main”, and “other” are supported for the phone number labels only. If any other labels are used, then the request will fail and no message will be sent. If no label is added, then the default label “work” is used.
- Currently custom labels are supported for website labels in the vCard. If no label is added, then the default label “homepage” is used. There is a total limit of 100 characters per website label. Any characters > 100 will be truncated in the vCard.
- The photo URL in the contact supports gif, jpg, and png image file types. If the photo validation fails, then the request will fail.
Request: JSON
curl -X POST \
-H "x-api-key: API_KEY" \
-H "content-type: application/json" -d '
{
"action": "createcontact",
"name": {
"first-name": "FIRST_NAME",
"last-name": "LAST_NAME",
"suffix": "NAME_SUFFIX"
},
"organization": "ORGANIZATION_NAME",
"title": "ORGANIZATION_TITLE",
"photo-url": "PROFILE_PHOTO_URL",
"note": "CONTACT_NOTE",
"phone": [
{
"number": "PHONE_NUMBER",
"label": "PHONE_NUMBER_LABEL"
},
...
],
"email": [
{
"id": "EMAIL_ADDRESS",
"label": "EMAIL_ADDRESS_LABEL"
},
...
],
"physical-address": [
{
"address": "PHYSICAL_ADDRESS",
"label": "PHYSICAL_ADDRESS_LABEL"
},
...
],
"website": [
{
"url": "WEBSITE_URL",
"label": "WEBSITE_URL_LABEL"
},
...
]
}' \
"API_ENDPOINT_URL"
Success Response: JSON
Output the vCard file to download (.vcf file)
Content-type: text/vcard; charset=utf-8;
Content-Disposition: inline; filename=contact.vcf;
BEGIN:VCARD
ORG:ORGANIZATION_NAME
TITLE:ORGANIZATION_TITLE
PHOTO;TYPE=JPEG;ENCODING=BASE64:PHOTO_URL_TO_BASE64
NOTE:CONTACT_NOTE
TEL;PHONE_NUMBER_LABEL;:PHONE_NUMBER
EMAIL;EMAIL_ADDRESS_LABEL;:EMAIL_ADDRESS
ADR;PHYSICAL_ADDRESS_LABEL;:PHYSICAL_ADDRESS
item1.URL:WEBSITE_URL
item1.X-ABLabel:WEBSITE_URL_LABEL
N:LAST_NAME;FIRST_NAME;;;NAME_SUFFIX
END:VCARD
Failure Response: JSON
{
"status": "failure",
"error-code": "ERROR_CODE",
"error-info": "ERROR_INFO",
}
Request Parameters
Param Name | Optional/Mandatory; Datatype | Description |
x-api-key | Mandatory; Alphanumeric | Authentication Key for your account to access API service. Unique Alphanumeric Key can be reset under your Account->API Settings. Case-sensitive. |
action | Mandatory; String | Explains the action for this API Request. Value is Case-Insensitive. |
name | Mandatory | Name of the contact. |
name:first-name | Optional, Mandatory if the last-name is blank; String | First name of the contact. |
name:last-name | Optional, Mandatory if the first-name is blank; String | Last name of the contact. |
name:suffix | Optional; String | Name suffix of the contact. |
organization | Optional; String | Organization or company name. Accepts any text. |
title | Optional; String | Title for the person in the contact. Accepts any text. |
photo-url | Optional; String | URL of the contact photo. Supports PNG, GIF, and JPEG file types. |
note | Optional; String | Notes. Accepts any text. |
phone | Optional; String | Phone(s) of the contact. Max phones supported: 4 |
phone:number | Optional; String | Phone number. |
phone:label | Optional; String | Label for the phone. Available labels: Work Home Mobile Fax Pager Main Other |
Optional; String | Email(s) of the contact. Max emails supported: 4 | |
email:id | Optional; String | Email address. |
email:label | Optional; String | Label for the email. Available labels: Work Home |
physical-address | Optional; String | Physical address(es) of the contact. Max physical addresses supported: 4 |
physical-address:address | Optional; String | Physical address. |
physical-address:label | Optional; String | Label for the physical address. Available labels: Work Home |
website | Optional; String | Website URL(s) of the contact. Max website URLs supported: 4 |
website:url | Optional; String | Website URL. |
website:label | Optional; String | Custom label for the website URL. Characters > 100 will be truncated. |
Response Parameters
Param Name | Presence | Description |
status | Error Response | “failure” |
error-code | Error Response | Error code associated with the error. |
error-info | Error Response | Error message explaining the error code. |
Request Example: JSON
curl -X POST \
-H "x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "content-type: application/json" -d '
{
"action": "createcontact",
"name": {
"first-name": "John",
"last-name": "Appleseed",
"suffix": "Jr."
},
"organization": "Dunder Mifflin",
"title": "Account Manager",
"photo-url": "https://dundermifflinco.com/johnappleseedjr.png",
"note": "Manage account campaigns.",
"phone": [
{
"number": "10000000000",
"label": "Work"
}
],
"email": [
{
"id": "fake.email@email.com",
"label": "Work"
}
],
"physical-address": [
{
"address": "Fake Address",
"label": "Work"
}
],
"website": [
{
"url": "https://www.dundermifflinco.com/",
"label": "Dunder Mifflin"
}
]
}' \
"API_ENDPOINT_URL"
Response Example: Success
Output the vCard file to download (.vcf file)
Content-type: text/vcard; charset=utf-8;
Content-Disposition: inline; filename=contact.vcf;
BEGIN:VCARD
ORG:Dunder Mifflin
TITLE:Account Manager
PHOTO;TYPE=JPEG;ENCODING=BASE64:/9j/4AAQSkZJRgABAQEASABIAAD/4gxYSUNDX1BST0ZJTEUAAQEAAAxITGlubwIQAABtbnRyUkdCIFhZWiAHzgACAAkABgAxAABhY3NwTVNGVAAAAABJRUMgc1JHQgAAAAAAAAAAAAAAAAAA9tYAAQAAAADTLUhQICAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABFjcHJ0AAABUAAAADNkZXNjAAABhAAAAGx3dHB0AAAB8AAAABRia3B0AAACBAAAABRyWFlaAAACGAAAABRnWFlaAAACLAAAABRiWFlaAAACQAAAABRkbW5kAAACVAAAAHBkbWRkAAACxAAAAIh2dWVkAAADTAAAAIZ2aWV3AAAD1AAAACRsdW1pAAAD+AAAABRtZWFzAAAEDAAAACR0ZWNoAAAEMAAAAAxyVFJDAAAEPAAACAxnVFJDAAAEPAAACAxiVFJDAAAEPAAACAx0ZXh0AA....
NOTE:Manage account campaigns.
TEL;WORK;:10000000000
EMAIL;WORK;:fake.email@email.com
ADR;WORK;:Fake Address
item1.URL:https://www.dundermifflinco.com/
item1.X-ABLabel:Dunder Mifflin
N:Appleseed;John;;;Jr.
END:VCARD
Response Example: Failure
{
"status": "failure",
"error-code": "E1515",
"error-info": "The first or last name for the vCard is required."
}