(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.data-privacy-src= 'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-TT9ZP96');

Knowledge Base

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 NameOptional/Mandatory; DatatypeDescription
x-api-keyMandatory; AlphanumericAuthentication Key for your account to access API service. Unique Alphanumeric Key can be reset under your Account->API Settings. Case-sensitive.
actionMandatory; StringExplains the action for this API Request. Value is Case-Insensitive.
nameMandatoryName of the contact.
name:first-nameOptional, Mandatory if the last-name is blank; StringFirst name of the contact.
name:last-nameOptional, Mandatory if the first-name is blank; StringLast name of the contact.
name:suffixOptional; StringName suffix of the contact.
organizationOptional; StringOrganization or company name. Accepts any text.
titleOptional; StringTitle for the person in the contact. Accepts any text.
photo-urlOptional; StringURL of the contact photo. Supports PNG, GIF, and JPEG file types.
noteOptional; StringNotes. Accepts any text.
phoneOptional; StringPhone(s) of the contact. Max phones supported: 4
phone:numberOptional; StringPhone number.
phone:labelOptional; StringLabel for the phone. Available labels:

Work
Home
Mobile
Fax
Pager
Main
Other
emailOptional; StringEmail(s) of the contact. Max emails supported: 4
email:idOptional; StringEmail address.
email:labelOptional; StringLabel for the email. Available labels:

Work
Home
physical-addressOptional; StringPhysical address(es) of the contact. Max physical addresses supported: 4
physical-address:addressOptional; StringPhysical address.
physical-address:labelOptional; StringLabel for the physical address. Available labels:

Work
Home
websiteOptional; StringWebsite URL(s) of the contact. Max website URLs supported: 4
website:urlOptional; StringWebsite URL.
website:labelOptional; StringCustom label for the website URL. Characters > 100 will be truncated.

Response Parameters

Param NamePresenceDescription
statusError Response“failure” 
error-codeError ResponseError code associated with the error.
error-infoError ResponseError 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."
}
Go to Top