Create Contact API V2¶

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; String	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; Object	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; Array of Objects	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
`email`	Optional; Array of Objects	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; Array of Objects	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; Array of Objects	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."
}