ContactDrive API v1

Welcome ninjas, hackers, and those mid-sprint! For developers looking to integrate ContactDrive with other services, we offer a public RESTful API. (Note: as with all of ContactDrive, the API is currently in beta. Please, be gentle... and let us know if anything breaks.)

Zapier

Before you go about building a custom integration with ContactDrive, we just want to be sure you know about our integration with Zapier. Zapier is a web-based tool that makes it easy to automate tasks between web apps.

With Zapier, you can easily plug ContactDrive into any workflow involving hundreds of apps, including web forms, email marketing, social media, customer support, Google Sheets, and more. Here's a handy overview.

To integrate ContactDrive with Zapier, first setup a free Zapier account, then contact us to let us know the email address you are using on Zapier. We'll then share our private Zap with you.

Base URL

All URLs referenced in the documentation have the following base:

https://api.contactdrive.app/api/v1

Authentication

A valid API token is required to access all resources via the API. Users can obtain their personal token from the My Profile menu item. Just click on the Integrations tab and generate an API token.

There are two ways to pass a token to the API successfully. First, an API token can be appended to the URL using the parameter apiKey. An example request might look like:

https://api.contactdrive.app/api/v1/contacts?apiKey=XXX

Also, a token can be added to the request header using the key "apiKey".

Note: Users with access to multiple accounts will need to generate a separate API token for each account.

Resources

The ContactDrive API allows you to create, update, delete and retrieve contact data for your account. Currently the only object supported is contacts, however we plan to add future objects for transactions, tasks, and other contact-related information.

All API responses are returned in JSON.

Create or Update a Contact

Include a data paramenter in the body of the request with any fields for the contact listed below.

Example request

POST https://api.contactdrive.app/api/v1/contacts?apiKey=XXX

Body:

Parameters

• apiKey: The authenticated user's API token, retrieved from My Profile. Alternatively, can be added to the request header.

Required Fields

All POST requests must have some combination of ContactDrive contact ID, firstName, lastName and/or at least one email address.

How We Check for Duplicates

If a ContactDrive system ID is passed via the body attribute "id", then the POST request will update that resource.

If a name only is provided, ContactDrive will look for matching contacts with that name and update the first matching contact found.

If an email only is provided, then ContactDrive will look for matching contacts with that email and update the first matching contact found.

However, for the most accurate updates (other than passing a ContactDrive resource ID), if both a name and an email address are provided, then ContactDrive will match on both fields. This ensures that couples who share an email address (or event staff who reuse email addresses for registration) don't get accidentally updated.

Attributes

• id
  • String
  • Contact's system ID in ContactDrive
  • The fastest and most accurate field to pass for updating existing contacts
• firstName
  • String
  • Contact's first name
• lastName
  • String
  • Contact's last name
• emails:
  • Array
  • Contact's email addresses, if any
  • emails contains an array of objects, each object representing a single email address
  • Child attributes:
    • type
      • String
      • The type of email address
      • Value must be "Home", "Work", or "Other" (case sensitive)
    • address
      • String
      • Contact's email address
    • isPrimary
      • Boolean
      • True if this is the contact's primary email address. Default is false
      • Value must be true or false
• prefix
  • String
  • Contact's name prefix
  • Value must be "Mr.", "Mrs.", "Ms.", "Miss", or "Dr."
• middleName
  • String
  • Contact's middle name
• suffix
  • String
  • Contact's name suffix (i.e. Jr., Ph.D., M.D., III, etc)
• nickname
  • String
  • Contact's nickname
• fullname
  • String
  • Contact's full or mailing name
• gender
  • String
  • Contact's gender
  • Value must be "Male" or "Female"
• transactionTotal
  • Number
  • Sum of contributions, sales, or other transactions representing the value of this contact
• phones
  • Array
  • Contact's phone numbers, if any
  • phones contains an array of objects, each object representing a single phone number
  • Child attributes:
    • type
      • String
      • The type of phone number
      • Value must be "Mobile", "Home", "Work", or "Other" (case sensitive)
    • number
      • String
      • Contact's phone number
    • isPrimary
      • Boolean
      • True if this is the contact's primary phone number. Default is false
      • Value must be true or false
• addresses
  • Array
  • Contact's street or mailing addresses, if any
  • addresses contains an array of objects, each object representing a single address
  • Child attributes:
    • type
      • String
      • The type of email address
      • Value must be "Home", "Work", or "Other" (case sensitive)
    • street
      • String
      • The street address or P.O. Box of the address
    • city
      • String
      • The city name of the address
    • state
      • String
      • The state or province of the address
      • Value must be an all caps, two-letter state abbreviation (e.g. "AL","AK","AZ", etc)
    • zip
      • String
      • The ZIP or postal code of the address
    • country
      • String
      • The country of the address
• websites
  • Array
  • Contact's associated websites and social media links, if any
  • websites contains an array of objects, each object representing a single website
  • Child attributes:
    • name
      • String
      • The display name of the website (e.g. "Facebook", "Homepage", "Blog")
    • URL
      • String
      • The URL of the website
• organizations
  • Array
  • Contact's associated companies and organizations, if any
  • organizations contains an array of objects, each object representing a single company or organization
  • Child attributes:
    • name
      • String
      • The name of the organization
    • jobTitle
      • String
      • The contact's job title or role at this organization
    • isCurrent
      • Boolean
      • True if the contact is currently at this organization
      • Value must be true or false
• tags
  • Array
  • Tags associated with a contact, if any
  • tags contains an array of strings, each string representing a single tag
• customFields
  • Object
  • Data for custom fields defined by an organization specific to this contact
  • customFields is a object containing key-value pairs of fields pre-defined for this specific organization.
  • Each key in the custom fields object must match the Slug for a field pre-defined for the organization. Custom fields can be viewed, created and updated in the ContactDrive application under Account Settings > Custom Fields. (Note: only admins can create, edit, or delete custom fields.)

Response Codes

We do our best to provide accurate and useful response codes to all API calls. Here's the most common:

• 200: "Contact successfully created!"
• 400: "This request does not match ContactDrive's data schema. Please re-map your fields."
• 401: "Invalid API key."
• 404: "No contacts found."

TODO: ADD EXAMPLE RESPONSE

Retrieve a Contact

Example request

GET https://api.contactdrive.app/api/v1/contacts?apiKey=XXX&id=YYY

Parameters

• apiKey: The authenticated user's API token, retrieved from My Profile
• id: The unique ID for the contact you would like to retrieve

Response Codes

We do our best to provide accurate and useful response codes to all API calls. Here's the most common:

• 200: Success!
• 401: "Invalid API key."
• 400: "This request does not match ContactDrive's data schema. Please re-map your fields."
• 404: "No contacts found."

TODO: ADD EXAMPLE RESPONSE

Delete a Contact

Example request

DELETE https://api.contactdrive.app/api/v1/contacts?apiKey=XXX&id=YYY

Parameters

• apiKey: The authenticated user's API token, retrieved from My Profile
• id: The unique ID for the contact you would like to delete

Response Codes

We do our best to provide accurate and useful response codes to all API calls. Here's the most common:

• 200: "Contact removed!"
• 401: "Invalid API key."
• 403: "DELETE calls must have an id (and only an id) in the request body in the correct format (String)."
• 404: "Can't delete a non-existent contact."

TODO: ADD EXAMPLE RESPONSE

List All Contacts

If you submit a GET request to the contacts endpoint without an id specified, it will return a JSON document with all of the contacts in your organization.

Example request

GET https://api.contactdrive.app/api/v1/contacts?apiKey=XXX

Parameters

• apiKey: The authenticated user's API token, retrieved from My Profile

Response Codes

We do our best to provide accurate and useful response codes to all API calls. Here's the most common:

• 200: Success!
• 400: "This request does not match ContactDrive's data schema. Please re-map your fields."
• 401: "Invalid API key."
• 404: "No contacts found."