I/O Docs: API Documentation

OAuth 2.0 Flow: Select OAuth 2.0 Flow

Existing Client Credentials: Manual Input

API Key:

App/Key: Select Application Key Manually provide key information

Shared Secret:

Client ID:

Client Secret: Authorize

Client ID: Get Access Token

Client ID:

Client Secret:

---

Username:

Password: Get Access Token

Client ID:

Client Secret: Get Access Token

Authorization Code: Get Access Token

Access Token:

Username:

Password:

Username:

Binary Security Token:

Username:

Password:

• Contacts

  • List Methods
  • Expand Methods

  • GET Get All Contacts /api/v1/contacts

    List all contacts in the user's account

    Parameter	Value	Type	Description
    type		string	type parameter determines the results returned.type can be basic,standard or all

  • POST Create A New Contact /api/v1/contacts

    Create a contact in VR

    Parameter	Value	Type	Description
    email		string	email address of the contact to be created
    First Name		string	First Name of the contact to be created
    Last Name		string	Last Name of the contact to be created

  • GET Search Contacts /api/v1/contacts

    Read A Contact

    Parameter	Value	Type	Description
    type		string	type parameter determines the results returned.type can be basic,standard or all
    email		string	email address to search contacts by

  • PUT Update Contact /api/v1/contacts/:contact_id

    Update List

    Parameter	Value	Type	Description
    :contact_id		string	id of contact to be updated
    first_name		string	First name of the contact
    last_name		string	Last name of the contact

  • DELETE Delete Contact /api/v1/contacts/:contact_id

    Delete Contact

    Parameter	Value	Type	Description
    :contact_id		string	id of contact to be delete

  • GET Read Contact /api/v1/contacts/:id

    Read Contact

    Parameter	Value	Type	Description
    :id		string	id of contact to be delete

  • GET Contact : Member Lists /api/v1/contacts/:id/lists

    Lists the contact is a part of

    Parameter	Value	Type	Description
    :id		string	id of contact

  • GET Contact : Targeted Messages /api/v1/contacts/:id/messages

    Lists the messages sent to the contact

    Parameter	Value	Type	Description
    :id		string	id of contact

• Lists

  • List Methods
  • Expand Methods

  • POST Create Lists /api/v1/lists

    Create List

    Parameter	Value	Type	Description
    name		string	name of the list to be created
    is_public		string	creating public vs private lists

  • DELETE Delete Lists /api/v1/lists/:list_id

    Delete List

    Parameter	Value	Type	Description
    :list_id		string	list id to be deleted

  • GET Read List /api/v1/lists/:list_id

    Retrieve details about a list

    Parameter	Value	Type	Description
    :list_id		string	list id to be deleted

  • GET Get All Lists /api/v1/lists

    Return all lists for a given user

    Parameter	Value	Type	Description
    type		string	type parameter determines the results returned.type can be basic,standard or all

  • GET Targeted Messages /api/v1/lists/:list_id/messages

    Get all messages that was sent to the given list

    Parameter	Value	Type	Description
    :list_id		string	list id to be deleted
    type		string	type parameter determines the results returned.type can be basic,standard or all

  • GET Lists:Member Contacts /api/v1/lists/:list_id/contacts

    Get the contacts that are a part of the given list

    Parameter	Value	Type	Description
    :list_id		string	list id to be deleted
    type		string	type parameter determines the results returned.type can be basic,standard or all

• Emails

  • List Methods
  • Expand Methods

  • POST Create Email /api/v1/messages/emails

    Create Email

    Parameter	Value	Type	Description
    from_address		string	from address to send the campaign from
    from_label		string	from label to send the campaign from
    reply_to		string	reply to address for the email campaign
    subject		string	subject of the email campaign
    message		string	message content of the email campaign
    unsubscribe_message		string	unsubscribe message, required for compliance purposes

  • DELETE Delete Email /api/v1/messages/emails/:email_id

    Delete Email

    Parameter	Value	Type	Description
    :email_id		string	email id to be deleted
    from_label		string	from label to send the campaign from
    reply_to		string	reply to address for the email campaign
    subject		string	subject of the email campaign
    message		string	message content of the email campaign
    unsubscribe_message		string	unsubscribe message, required for compliance purposes

  • GET List All Emails /api/v1/messages

    Retrieve details about an email

    Parameter	Value	Type	Description
    :type		string	controls the details about lists that are returned

  • GET Read Email /api/v1/messages/emails/:email_id

    Retrieve details about an email

    Parameter	Value	Type	Description
    :email_id		string	email id to be deleted

  • POST Launch Email /api/v1/messages/emails/:email_id

    Send or schedule an email campaign

    Parameter	Value	Type	Description
    :email_id		string	email id to be deleted
    lists		array	Array of list ids to send the email to. Maximum of 50 list ids allowed
    scheduled_at		string	Optional date flag to schedule the email campaign to be sent on a specific day

  • POST Launch Test Email /api/v1/messages/emails/:email_id/test

    Send a test email campaign

    Parameter	Value	Type	Description
    :email_id		string	email id to be deleted
    default_test_recipient_emails	True False	boolean	boolean flag to indicate if the test email should use saved email addresses or not
    recipients		array	Array of email address. Maximum of 8 allowed.

  • POST Email: Get Summary Stats /api/v1/messages/emails/:email_id/stats

    Send a test email campaign

    Parameter	Value	Type	Description
    email_id		string	email id to be deleted

  • GET Email: Targeted Lists /api/v1/messages/emails/:email_id/lists

    Retrieve lists to which the given email was sent

    Parameter	Value	Type	Description
    :email_id		string	email id to be deleted

• Social Posts

  • List Methods
  • Expand Methods

  • GET Social Posts: Get Summary Stats /api/v1/messages/social_posts/:socialpost_id/lists

    Retrieve lists to which the given email was sent

    Parameter	Value	Type	Description
    :socialpost_id		string	socialpost id to be get stats on

• Contacts

  • List Methods
  • Expand Methods

  • POST Create A New Contact /api/v1/contacts

    This API creates a contact in VerticalResponse. 'email' is a required field. If the contact does not exist already, a new contact is created in the master list in VerticalResponse.

    Parameter	Value	Type	Description
    email		string	email address of the contact to be created
    first_name		string	First Name of the contact to be created
    last_name		string	Last Name of the contact to be created

  • PUT Update Contact /api/v1/contacts/:contact_id

    Update a contact in VerticalResponse.Cannot update the contact's email.Other attributes including custom fields values can be updated.No fields are required but atleast one is required for the update to work.

    Parameter	Value	Type	Description
    :contact_id		string	id of the contact to be updated
    first_name		string	First name of the contact
    last_name		string	Last name of the contact

  • GET Get All Contacts /api/v1/contacts

    List all contacts in the user's VerticalResponse account. All contacts in the master list are returned.

    Parameter	Value	Type	Description
    type		string	type parameter determines the results returned.type can be basic,standard or all

  • GET Contacts:Summary Stats /api/v1/contacts/:contact_id/stats

    This API returns summary stats of a particular contact.Details about the number of emails sent, number of opens, clicks etc will be returned.

    Parameter	Value	Type	Description
    contact_id		string	id of the contact. Required to retrieve stats for the given contact
    type		string	type parameter determines the results returned.type can be basic,standard or all

  • GET Search Contacts /api/v1/contacts

    This API allows to search for contacts. Currently contacts can be searched by email and created_at date.

    Parameter	Value	Type	Description
    type		string	type parameter determines the results returned.type can be basic,standard or all
    email		string	email address to search contacts by

  • GET List Inactive Contacts /api/v1/contacts

    This API returns contacts that are non mailable. This includes contacts that are on hold, bounced or unsubscribed.

    Parameter	Value	Type	Description
    type		string	type parameter determines the results returned.type can be basic,standard or all
    status		string	status of the contacts to filter by. status can be inactive,bounced or unsubscribed.

  • GET List All Contact Attributes /api/v1/contacts/fields

    This API returns all the attributes a VR contact has. This includes all of VR's standard fields as well as custom fields set up by user.

    Parameter	Value	Type	Description
    type		string	type parameter determines the results returned.type can be basic,standard or all

  • GET Read Contact /api/v1/contacts/:id

    This API prodvides details about an individual contact.

    Parameter	Value	Type	Description
    :id		string	id of contact to get more details.
    type		string	type parameter determines the results returned.type can be basic,standard or all

  • GET Contact : Member Lists /api/v1/contacts/:id/lists

    This API returns all the lists that a particular contact is a member of. Attributes of the list are returned

    Parameter	Value	Type	Description
    :id		string	id of the contact.Required to retrieve the lists the contact is a member of.
    type		string	type parameter determines the results returned.type can be basic,standard or all

  • GET Contact : Targeted Messages /api/v1/contacts/:id/messages

    This API returns all the messages (emails and social posts) sent to a particular contact. Attributes of message are returned as per the type parameter.

    Parameter	Value	Type	Description
    :id		string	id of the contact . Required to retrieve the messages sent to the contact.

  • DELETE Delete Contact /api/v1/contacts/:contact_id

    This API deletes the given contact.

    Parameter	Value	Type	Description
    :contact_id		string	id of contact to be deleted

• Lists

  • List Methods
  • Expand Methods

  • POST Create List /api/v1/lists

    This API creates a list in VerticalResponse.A list is a collection of contacts.Name is a required field to create a list.

    Parameter	Value	Type	Description
    name		string	name of the list to be created
    is_public		string	Privacy status of the list. Contacts cannot see private lists in unsubscribe preferences.

  • PUT Update List /api/v1/lists/:list_id

    This API upates the attributes of a list. Accepted parameters are name and is_public.

    Parameter	Value	Type	Description
    :list_id		string	list id to add the contact to
    name		string	name of the list to be created
    is_public		string	Privacy status of the list. Contacts cannot see private lists in unsubscribe preferences.

  • POST Add Contact to a List /api/v1/lists/:list_id/contacts

    This API adds an existing contact to the given list.If the contact does not exist, then a new contact is created and added to the given list.

    Parameter	Value	Type	Description
    :list_id		string	list id to add the contact to
    email		string	email address of the contact to be added to list. If contact does not exist in VR, a new contact will be created and added to list

  • GET Read List /api/v1/lists/:list_id

    This API retrieve details about a given list.The attributes returned depend on the type parameter.

    Parameter	Value	Type	Description
    :list_id		string	id of the list to get more details.
    type		string	type parameter determines the results returned.type can be basic,standard or all

  • GET Get All Lists /api/v1/lists

    This API returns all lists a VR user has.

    Parameter	Value	Type	Description
    type		string	type parameter determines the results returned.type can be basic,standard or all

  • GET List:Summary Stats /api/v1/lists/:list_id/stats

    This API returns summary stats for a given list.Summary stats include size and reach of lists and number of contacts that bounced, unsubscribed or are on hold.

    Parameter	Value	Type	Description
    list_id		string	id of the list. Required to retrieve the summary stats for the list.

  • GET Targeted Messages /api/v1/lists/:list_id/messages

    This API retrieves all the messages that were sent to the given list.

    Parameter	Value	Type	Description
    :list_id		string	id of the list. Required to retrieve messages sent to this list.
    type		string	type parameter determines the results returned.type can be basic,standard or all

  • GET Lists:Member Contacts /api/v1/lists/:list_id/contacts

    The API returns all the contacts that are members of the given list.

    Parameter	Value	Type	Description
    :list_id		string	id of the list. Required to retreive contacts that are a part of this list.
    type		string	type parameter determines the results returned.type can be basic,standard or all

  • DELETE Delete Lists /api/v1/lists/:list_id

    This API deletes a given list. The contacts in this list are not deleted and are part of the master list.

    Parameter	Value	Type	Description
    :list_id		string	id of the list to be deleted

  • DELETE Remove Contact from List /api/v1/lists/:list_id/contacts/:contact_id

    This API removes a Contact from a List.The contact will not be deleted from VR

    Parameter	Value	Type	Description
    :list_id		string	id of the list from which the contact will be removed.
    :contact_id		string	id of the contact to be removed from the list

• Messages

  • List Methods
  • Expand Methods

  • GET List Messages /api/v1/messages

    This API returns all messages sent by a user. Messages include email campaign and social posts.

    Parameter	Value	Type	Description
    type		string	type parameter determines the results returned.type can be basic,standard or all

  • GET Messages:Find /api/v1/messages

    Search messages by emails, social_posts, status of the message , created,scheduled and sent timestamps.

    Parameter	Value	Type	Description
    type		string	type parameter determines the results returned.type can be basic,standard or all
    message_type		string	message_type parameter is used to filter messages by emails or social posts.Accepted values are 'email' or 'social_post'
    status		string	status parameter is used to filter messages by the state they are in.Accepted values are 'draft', 'delivered' or 'scheduled'
    created_since		string	Timestamp when the message was created. The accepted format is yyyy-mm-dd
    created_until		string	created_since and created_until are used to specify a date range to search messages by the date when they were created.
    scheduled_since		string	Timestamp when the message was scheduled to be delivered.
    scheduled_until		string	scheduled_since and scheduled_until are used to specify a date range to search messages by the date when they were scheduled to be delivered.
    sent_since		string	Timestamp when the message was sent to its intended recipients
    sent_until		string	scheduled_since and scheduled_until are used to specify a date range to search messages by the date when they were sent.

• Emails

  • List Methods
  • Expand Methods

  • POST Create Email /api/v1/messages/emails

    This API is used to create an email. Both HTML and text emails can be created.

    Parameter	Value	Type	Description
    from_address		string	from address from which to send the email campaign from
    from_label		string	from label for the email campaign.
    reply_to		string	reply to address for the email campaign
    subject		string	subject of the email campaign
    message		string	content of the email campaign
    company		string	Company name of the business. Required for compliance purposes.
    street_address		string	street address of the sender. Required for compliance purposes.
    locality		string	City of the sender. Part of the sender's postal address.
    region		string	State of the sender.Part of the sender's postal address.
    postal_code		string	postal code of the sender. Part of the sender's postal address.
    unsubscribe_message		string	unsubscribe message, required for compliance purposes

  • PUT Update Email /api/v1/messages/emails/:email_id

    This API updates a given email.All attributes of an email can be updated.The unsubscribe_message cannot be null and should include the unsusbcribe link.

    Parameter	Value	Type	Description
    from_address		string	from address from which to send the email campaign from
    from_label		string	from label of the email campaign.
    reply_to		string	reply to address for the email campaign
    subject		string	subject of the email campaign
    message		string	content of the email campaign
    street_address		string	street address of the sender. Required for compliance purposes.
    locality		string	City of the sender. Part of the sender's postal address.
    region		string	State of the sender.Part of the sender's postal address.
    postal_code		string	postal code of the sender. Part of the sender's postal address.
    unsubscribe_message		string	unsubscribe message, required for compliance purposes

  • POST Launch Email /api/v1/messages/emails/:email_id

    This API is used to send or schedule an email campaign

    Parameter	Value	Type	Description
    :email_id		string	id of the email. Required to launch the given email.
    lists		array	Array of list ids to send the email to. Maximum of 50 list ids allowed
    scheduled_at		string	Optional date flag to schedule the email campaign to be sent on a specific day

  • POST Launch Test Email /api/v1/messages/emails/:email_id/test

    This API is used to send a test email campaign.If default_test_recipient_emails is checked, then email addresses stored in the VR web application for sending test emails will be used.

    Parameter	Value	Type	Description
    :email_id		string	id of the email. Required to launch a test.
    default_test_recipient_emails	True False	boolean	boolean flag to indicate if the test email should use saved email addresses or not
    recipients		string	Array of email address. Maximum of 8 allowed.

  • GET List Emails /api/v1/messages

    This API returns all emails returned by a VR user.

    Parameter	Value	Type	Description
    type		string	type parameter determines the results returned.type can be basic,standard or all
    message_type		string	message_type parameter is used to filter messages by emails or social posts.Accepted values are 'email' or 'social_post'

  • POST Unschedule Email /api/v1/messages/emails/:email_id/unschedule

    The API is used to unschedule an email campaign. Only emails in scheduled status can be unscheduled.

    Parameter	Value	Type	Description
    :email_id		string	id of the email. Required to unschedule the email.

  • GET Read Email /api/v1/messages/emails/:email_id

    This API is used to retrieve details about a given email

    Parameter	Value	Type	Description
    :email_id		string	id of the email to get more details
    type		string	type parameter determines the results returned.type can be basic,standard or all

  • GET Email: Get Summary Stats /api/v1/messages/emails/:email_id/stats

    This API returns summary stats for a given email.This includes opens, open_rate,clicks,click_rate, bounces, unsubscribes, unqiue clicks etc.

    Parameter	Value	Type	Description
    :email_id		string	id of the email. Required to retrieve summary stats.
    type		string	type parameter determines the results returned.type can be basic,standard or all

  • GET Email: Targeted Lists /api/v1/messages/emails/:email_id/lists

    This API returns all lists to which the given email was sent

    Parameter	Value	Type	Description
    :email_id		string	id of the email. This is required to retrieve lists to which the email was sent to.
    type		string	type parameter determines the results returned.type can be basic,standard or all

  • DELETE Delete Email /api/v1/messages/emails/:email_id

    The API is used to delete an email

    Parameter	Value	Type	Description
    :email_id		string	id of the email to be deleted

• Custom Fields

  • List Methods
  • Expand Methods

  • POST Create Custom Field /api/v1/custom_fields

    VR allows 20 custom fields per account. This API is used to create a Custom Field

    Parameter	Value	Type	Description
    name		string	name of the custom field to be created

  • PUT Update Custom Field /api/v1/custom_fields/:custom_field_name

    This API is used to update the name of the given custom field

    Parameter	Value	Type	Description
    :custom_field_name		string	custom field to be updated
    name		string	name of the new custom field to be updated

  • GET List all Custom Fields /api/v1/custom_fields

    This API lists all the custom fields for the user

  • DELETE Delete Custom Field /api/v1/custom_fields/:custom_field_name

    This API is used to delete a particular custom field. Doing so will also remove this as an attibute for a contact.

    Parameter	Value	Type	Description
    :custom_field_name		string	custom field name to be deleted

• Social Posts

  • List Methods
  • Expand Methods

  • GET List Social Posts /api/v1/messages

    This API returns all social posts sent by a VR user.

    Parameter	Value	Type	Description
    type		string	type parameter determines the results returned.type can be basic,standard or all
    message_type		string	message_type parameter is used to filter messages by emails or social posts.Accepted values are 'email' or 'social_post'

  • GET Social Posts: Get Summary Stats /api/v1/messages/social_posts/:socialpost_id/stats

    This API returns all stats for the given social post

    Parameter	Value	Type	Description
    :socialpost_id		string	id of the social post. This is required to retrieve summary stats for the social post.