Contacts
Contents
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.
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 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 |
| state | 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
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
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
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 |
| status |
| type=standard |
|---|
| first_name |
| last_name |
| status |
| birthdate |
| gender |
| marital_status |
| company |
| title |
| website |
| street_address |
| extended_address |
| city |
| state |
| 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
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
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
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
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
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
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
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 |
|---|
| 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
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/
Method
POST
Sample Request
Sample Response
Status API Response
