Contacts

Contents

Overview

Create a Contact

Update a Contact

Delete a Contact

Read Details about a Contact

Contacts: Summary Stats

List all Contacts

Search Contacts

List Inactive Contacts

List Active Contacts

Contacts in Lists

Messages sent to a contact

List all Contact fields

Create Contacts in Batch

Overview

VerticalResponse helps users create and send great email campaigns. We make contact and list management easy, allowing users to create contacts, group them into meaningful lists, and use these lists to send targeted email campaigns. VR's REST API can be used to create, update, delete and list contacts for a given account. The contacts API also allows the user to get details of the lists a contact belongs to, messages sent to the contact, etc. In addition to standard contact fields, VerticalResponse provides 20 custom fields. These fields can be used to add additional details for each contact. The Contact API’s can be used to create new contacts with both standard and custom fields.

Create

The Contact Create API creates a new contact in the specific list ID, if specified, as well as the Master List. The create API can also be called without using lists, in which case the contact will be created in the master list alone. The user can then add the contact to a list at a later time. The API accepts all the standard parameters as request attributes for a contact. Email is the only required attribute. Other contact attributes are optional.

URL

https://vrapi.verticalresponse.com/api/v1/lists/:id/contacts

https://vrapi.verticalresponse.com/api/v1/contacts

Method

POST

Field Name Description Rules
email Email address of the contact required to create a contact
first_name First name of the contact optional
last_name Last name of the contact optional
birthdate Birthdate of the contact optional
gender Gender of the contact optional
marital_status Marital status of the contact optional
company Company the contact represents optional
title Title the contact holds in their company optional
website website address of the contact optional
street_address Street address of contact optional
extended_address Extended address of contact optional
city City of contact's address
optional
region State of contact's address. optional
postal_code Postal code of contact's address
optional
country Country of contact's address
optional
home_phone Home phone of contact
optional
mobile_phone Mobile phone number of contact
optional
work_phone Work phone number of contact
optional
fax Fax number of contact
optional

The Contact Create API is quite powerful, and can also be used to create custom fields while creating a contact. If a user would like to use custom fields in addition to the standard fields that VR provides, they can do so by using the Contact API or the Custom Fields: Create API. If using the Contacts: Create API, the user can specify the new custom field along with the value to assign to a particular user in the request. On success, the API returns the URI of the created contact. This URI can then be followed for other contact operations, like Read, Delete, Update etc.

Errors

If the email address is invalid, not present or already exists, the API returns an error. If any of the optional fields do not exist or is invalid, the API returns an error.

Sample Request

This API creates a contact in the user's master list as no list id is specified in the request URL

Creating Contacts with a Custom Field

Update

This API updates a contact provided the attributes of a contact to update. The email address of a contact cannot be updated. All other standard and custom fields can be updated using the API. On success, the API returns the URI of the contact. The attributes that are used in the create API can be updated.On success the API returns the URI of the contact updated.

Error

If the contact does not exist, the API will return an error. If the standard or custom attributes are invalid, the API will return an error. Attempting to update a contact’s email address will return an error.

URL

https://vrapi.verticalresponse.com/api/v1/contact/:id

Method

PUT

Sample Request

Delete

The contact delete API deletes a given contact from the user’s account. This API deletes a contact from the master list and all other lists the contact is a part of. On success the API returns a success code and message. VR maintains unsubscribes if a contact is deleted. So if the deleted contact is re-added, VR will maintain the unsubscribe.

URL

https://vrapi.verticalresponse.com/api/v1/contacts/:id

Method

DELETE

Sample Request

Read

The read API provides details about an individual contact. The API returns the contact’s attributes based on the type attribute. Type attribute can be set to basic, standard or all. Depending on the attribute different results are returned.

Attributes Description
Contact attributes Contact's attributes depending on the type parameter
optin_status optin status refers to the status of the contact’s membership status. Contacts choose to subscribe to emails by explicity opting in.Contacts might also have unsubscribed or bounced. The different values this attribute could have are optin, bounced or unsubscribed.
messageable

The messageable flag indicates whether the contact is mailable. If a developer wants to check whether a contact is mailable, this is the flag to look for.

status

The status attribute refers to the contact's mailable status. It can be "mailable","bounced","unsubscribed".If "mailable" the contact will receive all the email campaigns sent to them.

messages Messages URI that contains the messages that were sent to the contact.
lists Lists URI that contains the lists the contact is a part of.

The contact attributes returned depend on the type attribute. Type takes in basic, standard and all as attributes.

type=basic
first_name
last_name
email
status
type=standard
first_name
last_name
email
status
birthdate
gender
marital_status
company
title
website
street_address
extended_address
city
region
postal_code
country
home_phone
mobile_phone
work_phone
fax

type = all

This will return all the standard fields plus any custom fields that the user has.

The type parameter is a standard feature for GET requests across the API’s. This way the developer has more control over the data that is returned. The READ API also provides more details about a particular contact like the lists they are a part of, the messages sent to the contact etc. These additional details are returned as URI, which can then be subsequently used to get the details. In addition the API also returns details about the contact’s optin status and the contact’s messagable status.

URL

https://vrapi.verticalresponse.com/api/v1/contacts/:id

Method

GET

Sample Request

Contacts:Stats

The contacts summary statistics API will return details of the contact's interactions with messages sent to them. The API accepts an optional type parameter which takes the values "basic","standard" or "all". All the three values return the same attributes in this case. The following attributes are returned for each contact

Attribute Description
total_sent Total number of emails sent to contact
opens Total number of emails opened by the contact
clicks Number of clicks by the contact
bounces Hard bounces by the contact
facebook_shares Number of times the contact has shared an email on facebook
twitter_shares Number of times the contact has shared an email on twitter

URL

https://vrapi.verticalresponse.com/api/v1/contacts/<contact_id>/stats

Method

GET

Sample Request

Sample Response

Contacts :List

The contacts list API returns all contacts in a given list. The contact’s attributes along with its URI will be returned. The attributes returned would depend on the request parameter type. The type parameter will accept as input one of “basic, standard or all” values. To see what basic, standard and all parameters return, check the Contact: Read section. The type value is optional. If no type value is passed in, the attributes pertaining to basic mode will be returned.On success, a list of contacts present in the given list is returned.

Error

If the list does not exist, the API returns an error.

URL

https://vrapi.verticalresponse.com/api/v1/lists/:id/contacts

Method 

GET

Sample Request

Sample Response

Find

The find API lets users find a contact within a specific list or in the user’s account by email address, created date. The API currently only supports full strings in search and no wild cards. To search by created date, users can input a date range using the created_since and created_until parameters. If there is no created_since, the API assumes the user’s account creation date.If there is no created_until the API assumes current date.If more than one search attribute is used, the query will be considered an AND query and only data that matches all search criteria will be returned. If no data matches the search criteria, an empty items array is returned.

Success

The contacts that match the search criteria are returned. The data returned can be controlled by setting the type attribute to basic,standard or all. For more details on the data returned by the type attribute check the Contact:Read section.

Error

If the date range for search is not valid, the API returns an error.

If parameters that are not searchable are used in the search, the API simply lists all the contacts in the user’s account or given list.

URL

https://vrapi.verticalresponse.com/api/v1/contacts (or)

https://vrapi.verticalresponse.com/api/v1/lists/<listid>/contacts

Method

GET

Sample Request

Sample Response

List Inactive Contacts - Unsubscribes and Bounces

The find API can be used to list inactive contacts and filter by the type of inactive contacts. In the VR system bounced and unsubscribed contacts constitute inactive contacts. The  status parameter can be used to filter inactive contacts or specifically search for "unsubscribed" and "bounced".

Success

The contacts that match the search criteria are returned. The data returned can be controlled by setting the type attribute to basic,standard or all. For more details on the data returned by the type attribute check the Contact:Read section.

Error

If any value other than "inactive", "bounced" or "unsusbcribed" is provided, the API will return an error.

URL

https://vrapi.verticalresponse.com/api/v1/contacts (or)

https://vrapi.verticalresponse.com/api/v1/lists/<listid>/contacts

Method

GET

Sample Request

List All Bounced Contacts

Sample Response

List Active Contacts

Just like the inactive contacts, the find API can also be used to list all active contacts in a particular VR account. Active contacts are those which are mailable and can receive email campaigns you send. They have a status of "mailable" in the VR system . The  status parameter can be used to filter active contacts .

Success

Only active , mailable contacts are returned. The attributes of contacts returned can be controlled by setting the type attribute to basic,standard or all. For more details on the data returned by the type attribute check the Contact:Read section.

Error

If any value other than "active" "inactive", "bounced" or "unsusbcribed" is provided, the API will return an error.

URL

https://vrapi.verticalresponse.com/api/v1/contacts (or)

https://vrapi.verticalresponse.com/api/v1/lists/<listid>/contacts

Method

GET

Sample Request

Sample Response

Contacts : Member Lists

This API returns all the lists the given contact is a member of. The API returns the details of the list the contact is a part of. Like other GET calls, this also takes the type parameter. Depending on the type parameter, the API will return the list attributes. For a list of attributes that are returned for lists, check the section on Lists. The “All Contacts” list will always be returned since every contact is present in the master list. On success the API returns the URI and other attributes of the list that the user is a part of.

Error

The API returns an error if the contact id is invalid or if a value other than basic,standard,all is passed in for type.

URL

https://vrapi.verticalresponse.com/api/v1/contacts/:id/lists

Method 

GET

Sample Request

Sample Response

Contact: Targeted Messages

The API returns all the emails that were sent to the given contact. Like other GET calls, this API accepts a type parameter with basic, standard, all values. The type parameter determines the attributes of emails to return.  For details about the email attributes that are returned based on the type parameter, check the Messages section. The messages regardless of their state, (sent, scheduled, draft) will be returned.

For emails that are in draft state, the sent date will be null. For emails that are scheduled, scheduled_at will have the appropriate date and sent_at will be null. The messages are returned in the order of most recently sent.The API will return all the messages sent/scheduled to the contact regardless of which lists they are a part of when the API is called.

Success

An array of messages sent to the user are returned. If no messages are sent, then an empty items array is returned.

URL

https://vrapi.verticalresponse.com/api/v1/contacts/<contact_id>/messages 

Method

GET

Sample Request

Sample Response

List All Contact Fields

This API returns the attribute names of contacts. These include the standard fields that VR provides as well as custom fields that users create. The API accepts a type parameter that takes in “standard” or “all” values and returns the standard contact fields and standard + custom fields respectively. This API can be used while mapping fields between two systems like Salesforce and VR. Type is optional and is “all” by default.

Type Value = Standard
email
first_name
last_name
company
website
title
address 1
address 2
city 2
state
postal code
country
work
home
mobile
fax
birthdate
marital status
gender

Type = all

Standard fields + custom fields.

URL

https://vrapi.verticalresponse.com/api/v1/contacts/fields

Method

 GET

Sample Request

Sample Response

Contacts Create: Batch

This API is used to create contacts in batch. The batch contact create is an extension of the contact create API. The API accepts as input an array of contact objects. Email address is the only required field. The API also accepts custom fields and their corresponding values similar to the contact create API.

Note: If contacts that already exist are provided as input with any of their attributes changed the contact will be updated with the new details. The status API will return the number of contacts updated along with the number of contacts added.

Note 2: The API does not update attributes that have a blank or no value. Only the changed attributes will be updated. The API allows up to 10000 contacts to be created.

Depending on the subscription plan each user is limited to a certain number of users in their account. Free users can manage up to 1000 contacts. If the batch contact create API is called to createmore than 1000 contacts for a free user ,the API will return an error with details on the number of contacts over limit. The user can upgrade to a paid plan to start managing additional contacts. The users can also delete contacts to make space for the new ones.

Difference

There is one difference between the contacts create API and batch create API. The batch create API will only accept custom fields if they already exist in the user’s account. If custom fields that don’t exist are passed in, the API will not create them and will return an error.

Success

The API will always return success along with a status URL. This status URL when called will return the status of the batch create process. The status API returns the following details.

Attributes Description
processed Number of contacts processed by the API
updated Number of contacts updated
created Number of contacts created
invalid Number and email addresses of unsubscribed contacts in the request
unsubscribed Number and email addresses of unsubscribed contacts in the request
bounced Number and email addresses of bounced contacts in the request
nonmailable Number and email addresses of non mailable contacts in the request
on_hold

Number and email addresses of contacts in request

Errors

The batch API supports partial success scenarios. If one among the list of contacts to be created has invalid request parameters, it will not affect the creation of other contacts. The results of the number of contacts created and not created can be obtained from the status URL.

URL

https://vrapi.verticalresponse.com/api/v1/lists/ contacts

Method

POST

Sample Request

Sample Response

Status API Response