VipeCloud API v3.1

1. Overview
2. Authentication

Endpoints

1. Users (GET/POST/PUT)
2. Contacts (POST/GET)
3. Custom Fields (GET)
4. Contact Lists (POST/GET)
5. User Reputation (GET)
6. Log Completed Task (POST)
7. Email Templates (POST/PUT/GET)
8. Files (POST/GET)
9. Emails (POST)
10. Tags (POST/GET/DELETE)
11. User Merge Tags (POST/GET)
12. AutoResponders (POST/GET)
13. Series Templates (POST/GET)
14. Series Template Steps (POST/GET)
15. Social Accounts (GET)
16. Social Post (POST/GET/DELETE)
17. Social Group Post (POST/GET/DELETE)
18. Text Templates (POST/GET)
19. Texts (POST)
20. Unsubscribes (POST)
21. Stories (POST/GET)
22. Social Connect (POST)
23. Social Account Groups (POST/GET)
24. Zoom Background (POST)

Overview

What can VipeCloud's API do for you?

• Connect proprietary or other 3rd party systems to VipeCloud

General Information

• Your account must gain authorization to use the VipeCloud API. Email support@vipecloud.com to request authorization
• All requests must by made from HTTPS
• All data sent should be JSON encoded (all data received will be JSON encoded)
• Base URL for these functions: https://v.vipecloud.com/api/v3.1
• API usage is currently throttled at 10 calls per 2 seconds per user

Interested in receiving webhooks?

• Learn about our webhooks API: Webhooks v1.0

Responses

• 200 for success
• 422 for incorrect post
• 500 which is most likely a VipeCloud error

Authentication

Authorization is a Basic header of a base64 encoded concatenation of your VipeCloud user email and an active user API Key. API keys are managed in the Setup section of your VipeCloud account.

Sample PHP curl header to add to your POST

<?php

$auth = base64_encode($user_email.":".$api_key);
curl_setopt($curl, CURLOPT_HTTPHEADER, array("Authorization: Basic $auth", "Accept: application/json"));

?>

Users (GET / POST / PUT)

GET all active users within your account

GET /users

The response to this GET will be a list of the currently active VipeCloud users in your account. Users displayed are based on the visibility permission of the authenticated user. For example, an Admin user will see all your account users, a Manager will see their team members, and a Member will only see themselves.

{ 
  [
    { 
      "first_name"  : "Wiley", 
      "last_name"  : "Coyote", 
      "email"  : "wiley.coyote@acme.com",
      "phone"  : "123-456-7890",
      "company_name" : "Acme",
      "api_keys" : ["123456XYZ"],
      "user_role" : 'Admin'
    },
    {
      ...
    }
  ]
}

POST create a new user

NOTE: this endpoint is in beta and requires invite-only access

POST /users

Only authenticated Admin users can use this endpoint.

Attribute	type	required	description
first_name	string	yes	First name.
last_name	string	yes	Last name.
email	string	yes	Email address (this is the email the user will send email from).
phone	string	yes	Phone office.
company_name	string	yes	Company name.
user_role	enum (Admin,Manager,Member)	yes	The role the new user will have within your account.

Sample post body:

{ 
  "first_name"  : "Wiley", 
  "last_name"  : "Coyote", 
  "email"  : "wiley.coyote@acme.com",
  "phone"  : "123-456-7890",
  "company_name" : "Acme",
  "user_role" : 'Member'
}

Sample 200 response:

{ 
  "first_name"  : "Wiley", 
  "last_name"  : "Coyote", 
  "email"  : "wiley.coyote@acme.com",
  "phone"  : "123-456-7890",
  "company_name" : "Acme",
  "user_role" : 'Member',
  "api_keys" : ["123456XYZ"] //save this to authenticate directly into this user's account
}

PUT update a user

NOTE: this endpoint is in beta and requires invite-only access

PUT /users

Attribute	type	required	description
first_name	string	no	First name.
last_name	string	no	Last name.
email	string	no	Email address (this is the email the user will send email from).
phone	string	no	Phone office.
company_name	no	yes	Company name.
user_role	enum (Admin,Manager,Member)	no	The role the new user will have within your account.

Sample body:

{ 
  "first_name"  : "Elmer" 
}

Sample 200 response:

{ 
  "first_name"  : "Elmer", 
  "last_name"  : "Coyote", 
  "email"  : "wiley.coyote@acme.com",
  "phone"  : "123-456-7890",
  "company_name" : "Acme",
  "user_role" : 'Member',
  "api_keys" : ["123456XYZ"] //save this to authenticate directly into this user's account
}

Contacts (POST / GET)

Create new / update existing Contacts in VipeCloud

POST /contacts(/:id)

When POSTing to /contacts, the body can either be an individual contact record or an array of contact records. If you are updating existing contacts, it is recommended that you include a contacts_master_id parameter for the contact. If not, the system will search for existing contacts based on the unique setting for your contact email address (account-wide, per user, or none). If submitting an array of contact records to create or update, first_name and email are always required.

You can, optionally, include a "contact_lists" parameter to your contact POST body. If you do, we will assume the contact_list_ids you submit represent the ENTIRETY of the contact lists the contact should be a part of. We will compare your POSTed contact_list_ids to any existing contact_lists for the contact. If the contact is part of contact lists not in your POST they will be removed from the list. And if contacts in your POST are not on the list they will be added. To remove a contact from ALL contact lists they are on, submit "0" as the contact_list_id (e.g. contact_lists : ["0"]).

Sample post body below.

{ 
   "first_name" : "Road", //required
   "last_name" : "Runner", 
   "email" : "email", //email or mobile_phone required
   "title" : "Evader",
   "website" : "www.acme.com", 
   "work_phone" : "1234567890", 
   "mobile_phone" : "1234567891", //email or mobile_phone required
   "direct_phone" : "1234567892", 
   "phone" : "1234567893", 
   "company_name" : "Acme", 
   "address1" : "123 Acme Street", 
   "address2" : "", 
   "city" : "Disneyland", 
   "state" : "CA", 
   "zip" : "12345", 
   "country" : "USA", 
   "unsubscribe" : 0,
   "personal_linkedin_url" : "https://www.linkedin.com/...",
   "personal_twitter_url" : "https://www.twitter.com/...",
   "personal_facebook_url" : "https://www.facebook.com/...",
   "tags" : ["Speedy"], 
   "verify" : 0, //if this is 1 AND you are an enterprise user AND this user has less than 10K verifications this month, we will verify the contact's email address on import
   "custom_fields" : [ //an array of the custom fields. Key value is the custom field id.
      id : "value" 
   ],
   "contact_lists" : [ //an array of contact_list_ids.
      "0" => 123,
      "1" => 1234
   ],
   "add_to_contact_lists" : [ 123, 1234 ], //optional parameter that accepts an array of contact_list_ids to add the contact directly to a set of lists (the user must own the contact list)
   "remove_from_contact_lists" : [ 12345, 12346 ] //optional parameter that accepts an array of contact_list_ids to remove the contact directly from a set of lists (the user must own the contact list)
}

GET Contacts

GET /contacts(/:id)

If no id, returns an array of the contacts for the authenticated user. If id, returns the details for a contact. If you only require certain contact parameters, append them (comma-separated) as a "to_get" parameter:

E.g. GET /contacts/123?to_get=contacts_master_id,first_name 

Full contact record:

{ 
  [
    { 
     "contacts_master_id" : 123,
     "first_name" : "Road", 
     "last_name" : "Runner", 
     "email" : "email", 
     "title" : "Evader",
     "website" : "www.acme.com", 
     "work_phone" : "1234567890", 
     "mobile_phone" : "1234567891", 
     "direct_phone" : "1234567892", 
     "phone" : "1234567893", 
     "company_name" : "Acme", 
     "address1" : "123 Acme Street", 
     "address2" : "", 
     "city" : "Disneyland", 
     "state" : "CA", 
     "zip" : "12345", 
     "country" : "USA", 
     "personal_linkedin_url" : "https://www.linkedin.com/...",
     "personal_twitter_url" : "https://www.twitter.com/...",
     "personal_facebook_url" : "https://www.facebook.com/...",
     "tags" : ["Speedy"],
     "contact_lists" : [
        "0" => [
            "contact_list_id" : 123,
            "contact_list_name" : "First list"
        ]
     ]
    },
    {
    ...
    }
  ]
}

Custom Fields (GET)

Get your account's custom fields.

GET account custom fields

GET /custom_fields

The response to this GET will be an array of your account custom fields.

{ 
  [
    {
      "id" : 1, //the custom field id
      "item_type" : "contact",
      "field_type" : "Text", //can be any of the input field types VipeCloud supports
      "field_name" : "My Custom Field",
      "options" : "", //will only have values for dropdowns and picklists. Will be an array of your options 
    }
  ]
}

Contact Lists (POST / GET)

Create new / update existing Contact List in VipeCloud

POST /contact_lists(/:id)

If creating a new list, a list name must be present. Creating an "empty" list - a list with a list_name and no contacts is allowed.

When POSTing contacts to an existing list, we will assume the contacts you submit represent the ENTIRETY of the contact list. We will compare your POSTed contacts to any existing contacts on the list. If contacts on the list are not in your POST they will be removed from the list. And if contacts in your POST are not on the list they will be added.

Note that VipeCloud will not add contacts that have unsubscribed from any user in your account, bounced, or have an email which has verified as undeliverable.

When submitting contacts include the contacts_master_id of the contact record.

{ 
 "contact_list_name" : "My First List", //required if creating a new list. Will overwrite existing name if "id" provided
 "contacts" : [
    {
      "contacts_master_id" : 123
    },
    {
      ...
    }
 ]
}

The response to this POST will be a status of success or error. On success the contact_list_id will be included in addition to a count of successful emails added to the list and a list of emails that were not added, with a message detailing why the contact wasn't added.

{
  "status" : "success",
  "contact_list_id" : 123,
  "contacts_added" : 123,
  "contacts_not_added": [
    {
      "contacts_master_id": 123,
      "message":"Contact unsubscribed."
    },
    {
      ...
    }
  ]
}

GET list of existing Contact Lists a user has in VipeCloud

GET /contact_lists(/:id)

Returns an individual record or array of the lists that a user has in VipeCloud. Optionally add the parameter hide_system_lists to the url to remove system lists from the result (e.g. /contact_lists?hide_system_lists=1)

{ 
  [
    {  
      "contact_list_id" : "123",
      "contact_list_name" : "New Customers",  
      "create_date" : "2014-09-03 08:30:39",
      "active_count": 16 //note that bounces, unsubscribes, and verified undeliverable contacts are automatically removed
      "source" : "upload_csv"
    },
    {
    ...
    }
  ]
}

User Reputation (GET)

Access a user's email sending reputation in VipeCloud. Note that if a user's email sending reputation drops below 70, they are not allowed to send email for 21 days. This is designed to protect your domain and ability to deliver email, as well as ours.

GET a user's email reputation

GET /user_reputation

The response to this GET will be an integer between 0 and 100.

{ 
  "reputation" : 100
}

Log Completed Task (POST)

POST /tasks

Body params

{
  "contact_email" : "road.runner@acme.com", //required and used to identify the contact
  "subject" : "Started Trial", //required
  "activity_type" : "their_activity", //required. Can be their_activity or your_activity
  "details" : "Created trial via website", 
  "contact_tags" : ["BusinessTrial","Annual"], //VipeCloud will create a contact if it doesn't exist. Values must be array
  "source" : "Website signup", //free form
  "company_tags" : ["BusinessTrial","Annual"] //VipeCloud will create a company if it doesn't exist. Values must be array
}

Sample response

{
    "status": "success",
    "contact_tags": "BusinessTrial,Annual",
    "contact_email": "road.runner@acme.com",
    "contact_first_name": "Road",
    "contact_company": "Acme"
}

Email Templates (POST / PUT / GET)

If you are migrating from another email sending provider and more email templates than you can manually transfer over, you can import them using the /email_templates endpoint. You can also edit your email templates with a PUT.

POST Template

POST /email_templates

Body params

{
  "title" : "My Email Template", //required and used to identify the contact
  "subject" : "My Email Subject", //required
  "copy" : "Hi there, this is my email template copy....", //required. HTML is allowed.
  "landing_page" : 1, //optional, can be a 1 or a 0. If a 1 we will respond with a link to the landing page
  "email_template_id" : 123, //optional, can be used to update one of your existing email templates
}

Sample response

{
    "status": "success",
    "email_template_id": 123,
    "landing_page": "link goes here" //only if you enable a landing page for the email template
}

PUT Template

PUT /email_templates/:id

Body params

{
  "title" : "My Email Template", //optional
  "subject" : "My Email Subject", //optional
  "copy" : "Hi there, this is my email template copy....", //optional. HTML is allowed.
  "landing_page" : 1, //optional, can be a 1 or a 0. If a 1 we will respond with a link to the landing page
}

Sample response

{
    "status": "success",
    "email_template_id": 123,
    "landing_page": "link goes here" //only if you enable a landing page for the email template
}

GET Template(s)

GET /email_templates

GET a list of your email templates, search for an email template by title, or a get specific template by id. If no email template is found, the response will be code 422 with the message "No template was found."

A note on access: in the API we only return email templates owned by the user. We do not return email templates the user can access via Shared With Me.

Sample responses

GET /email_templates
{ 
  [
    "0" : [
      "email_template_id" : 123
      "title" : "This is my title",
      "update_date" : 2020-01-05 04:00:11
    ]
  ]
}

GET /email_templates?query=title
{ 
  [
    "0" : [
      "email_template_id" : 123
      "title" : "This is my title",
      "update_date" : 2020-01-05 04:00:11
    ]
  ]
}

GET /email_templates/123
{ 
  "email_template_id" : 123
  "title" : "This is my title",
  "subject" : "This is my subject",
  "copy" : "<div>html of your email template here</div>"
}

Files (POST / GET)

Add, update, and retrieve files from your user accounts. If you are migrating from another system and have more files than you can manually transfer over (images, videos, documents, etc.), you can import them using the /files endpoint.

POST File(s)

POST /files(/:id)

Sample body when creating a new file

{
  "file_url" : "https://www.linktofile.com", //required
  "file_name" : "My File", //required
  "thumb_url" : "https://whatever.com" //required if importing a video
}

Sample response

{
    "status": "success",
    "id" : "123",
    "download_link": "link goes here",
    "trackable_link": "link goes here" //this is a trackable VipeCloud link
    "thumb_url": "link goes here" //only included for video file uploads
}

Sample body when updating an existing file (e.g. POST to /files/123 ). You can update the file_name or tag_ids associated with a file.

{
  "file_name" : "My File",
  "tag_ids" : ["1","2"]
}

Sample response

{
    "id": "123",
    "file_name" : "My File",
    "download_link": "link goes here",
    "trackable_link": "link goes here" //this is a trackable VipeCloud link
    "create_date": "2020-01-28 23:03:23", 
    "tag_ids" : ["1","2"]
}

GET File

GET /files(/:id)

Retrieve files by id or search your account for files by file_name (url encoded) or tag_id. Responses are limited to a maximum of 50 files. If no file is found, the response will be code 422 with the message "No file was found."

Sample response to get file by id. GET /files/123

{ 
    "id": "123",
    "file_name" : "My File",
    "download_link": "link goes here",
    "trackable_link": "link goes here" //this is a trackable VipeCloud link
    "create_date": "2020-01-28 23:03:23", 
    "tag_ids" : ["1","2"]
}

Sample response to get files by file_name (url encoded) or tag_id. Array of files is returned. GET /files?file_name=My%20File or /files?tag_id=1

{ 
    [
      "id": "123",
      "file_name" : "My File",
      "download_link": "link goes here",
      "trackable_link": "link goes here" //this is a trackable VipeCloud link
      "create_date": "2020-01-28 23:03:23", 
      "tag_ids" : ["1","2"]
    ],...
}

Emails (POST)

Send emails via a POST.

POST Email(s)

POST /emails

Attribute	type	required	description
emails	string	yes or contact_list_id	Comma or semicolon separated string of emails.
cc_emails	string	no	Comma or semicolon separated string of emails.
contact_list_id	integer	yes or emails	Required param if sending to contact list. Include emails OR contact_list_id.
subject	string	yes or email_template_id	Required if no email_template_id.
message	string	yes or email_template_id	Required if no email_template_id.
email_template_id	integer	yes or subject and message	Send email to email template. Replaces requirement for subject and message.
filters	array	no	Filter contacts within a contact list at the time of send. If you include the filters parameter our system will create a new, system-generated list based on which contacts meet your filters within the contact_list_id that is also submitted. Each group of filters within the filters array must include a field_type (standard or custom), id (if standard a slug, if custom the custom_field_id), an operator (accepted values include equals, less_than, greater_than, less_than_or_equal_to, or greater_than_or_equal_to), and a value. Contacts that meet all filters within any of the filter groups will be added to the system-generated list.
test_filters	boolean	no	Will test your filters and NOT send the email. Will return the number of contacts in your original list and after your filters have been applied.
filtered_list_name	string	no	Optional name of the filterd contact list created
schedule_data	array	no	The schedule_data array requires four keys: scheduled_date (string formmated as YYYY-MM-DD), hour (string, no leading 0), min (string, no leading 0), and ampm (string).

Sample body.

{
  "emails":"roadrunner@acme.com",
  "cc_emails":"wile.e.coyote@acme.com",
  "contact_list_id": 12345,
  "email_template_id": 67890,
  "filters":[
    "0" : [
      "0" : [
        "field_type" : "standard",
        "id" : "first_name", 
        "operator" : "equals",
        "value" : "Wiley"
      ],
      "1" : [
        "field_type" : "custom",
        "id" : "123", 
        "operator" : "greater_than",
        "value" : "1000"
      ]
    ]
  ],
  "test_filters" : true,
  "schedule_data" : [
      "scheduled_date" : "2020-06-30",
      "hour" : "12",
      "min" : "15",
      "ampm" : "pm"
  ]
}

Sample 200 responses:

Post Type	Response
Specific emails	{"emails":[{"email":"roadrunner@acme.com","status":"correct"},{"email":"wile.e.coyote@acme.com","status":"correct"}]}
Contact list	{"emails":"queue"}
Test filters	{"original_list_contacts": 100, "filtered_list_contacts" : 15, "view_filtered_contacts" : link_to_system_generated_contact_list }
Scheduled email	{"emails":"scheduled"}

Sample 422 responses:

Sample response messages
No filters submitted.
You don't have access to that contact list.
No contacts in contact list, so not processing email.
You don't have access to that email template.
All filters are required to have field_type, id, operator, and value parameters.
ABCXYZ is not a valid contact standard field.
ABCXYZ is not a valid operator.

Tags (POST / GET / DELETE)

Create, update, retrieve, and delete tags for your users. Tags utilized via the API can be attributed to files.

POST Tag(s)

POST /tags(/:id)

Sample body when creating a new tag

{
  "tag_name" : "My Tag Name", //required
}

Sample response

{
    "status": "success",
    "tag_id" : "123"
}

Sample body when updating an existing tag (e.g. POST to /tags/123 ). You can update the tag_name.

{
  "tag_name" : "My Tag Name 2", //required
}

Sample response

{
    "status": "success",
    "tag_id" : "123",
    "tag_name" : "My Tag Name 2"
}

GET Tag

GET /tags(/:id)

Retrieve tags by id or as a group. If no tag is found, the response will be code 422 with the message "No tag was found."

Sample response to get tag by id. GET /tags/123

{     
    "tag_id" : "123",
    "tag_name" : "My Tag Name 2"
}

Sample response to get tags with no id. Array of tags is returned. GET /tags

{ 
    [
      "id": "123",
      "tag_name" : "My Tag Name 2"
    ],...
}

DELETE Tag

DLETE /tags/:id

Delete tag by id. If no tag is found, the response will be code 422 with the message "No tag was found."

Sample response to delete tag by id. DELETE /tags/123

{     
    "status" : "success
}

User Merge Tags (POST / GET)

Update and retrieve user_merge_tags from your user accounts. Create the user_merge_tag for the account in your parent user account.

POST User Merge Tag

POST /user_merge_tags(/:id)

Sample body when updating a merge tag value.

{
  "value" : "New Value"
}

Sample response

{
    "id": "123",
    "merge_tag" : "%YOUR_USER_MERGE_TAG%",
    "value" : "New Value"
}

GET User Merge Tags

GET /user_merge_tags(/:id)

Retrieve user merge tags by id or retrieve a list of all user_merge_tags in your account.

Sample response to get user_merge_tag by id. GET /user_merge_tags/123

{ 
    "id": "123",
    "merge_tag" : "%YOUR_USER_MERGE_TAG%",
    "value" : "New Value"
}

Sample response to get all user merge tags. GET /user_merge_tags

{ 
    [
      "id": "123",
      "merge_tag" : "%YOUR_USER_MERGE_TAG%",
      "value" : "New Value"
    ],...
}

AutoResponders (POST / GET)

Create, update, and retrieve AutoResponders from your user accounts.

POST AutoResponder

Attribute	type	required	description
contact_list_id	integer	yes	Contact list id
template_type	enum	yes	"email" or "series"
template_id	integer	yes	The id of the email or series template
trigger	enum	yes	"contact" or "recurring" or "custom_field" Trigger details: - If "contact" must also include "delay_days", "delay_hours", and "delay_min" parameters. May also include "contact_trigger_hours" (1/0), "contact_trigger_from_hour" (1-12), "contact_trigger_from_min" (0-59), "contact_trigger_from_ampm" (am/pm), "contact_trigger_to_hour" (1-12), "contact_trigger_to_min" (0-59), "contact_trigger_to_ampm" (am/pm) - If "recurring" must also include "day", "hour", "min", and "ampm" parameters (no leading 0's). Optionally "weekday_only" can be set to "on". - If "custom_field" must also include "custom_field_id", "hour", "min", and "ampm" parameters.

POST /autoresponders(/:id)

Sample body when creating an AutoResponder.

{
    "contact_list_id" : 123,
    "template_type" : "email",
    "template_id" : 123,
    "trigger" : "contact",
    "delay_days" : 0,
    "delay_hours" : 0,
    "delay_min" : 0
}

GET AutoResponders

GET /autoresponders(/:id)

Retrieve autoresponders by id or retrieve a list of all autoresponders in the user's account.

Sample response to get autoresponders by id. GET /autoresponders/123

{ 
    "id" : 123,
    "contact_list_id" : 123,
    "contact_list_name" : "My contact list",
    "template_type" : "email",
    "template_id" : 123,
    "template_title" : "My email template",
    "trigger" : "contact",
    "delay_days" : 0,
    "delay_hours" : 0,
    "delay_min" : 0,
    "schedule_data" : null,
    "weekday_only" : null
}

Sample response to get all autoresponders. GET /autoresponders

{ 
    [
      "id" : 123,
      "contact_list_id" : 123,
      "contact_list_name" : "My contact list",
      "template_type" : "email",
      "template_id" : 123,
      "template_title" : "My email template",
      "trigger" : "contact",
      "delay_days" : 0,
      "delay_hours" : 0,
      "delay_min" : 0,
      "schedule_data" : null,
      "weekday_only" : null
    ],...
}

Series Templates (POST / GET)

Create, update, and retrieve Series Templates from your user accounts. Use in conjunction with the /series_template_steps endpoint.

POST Series Template

Attribute	type	required	description
title	string	yes	The title of your series template
steps	array	yes	Array of series step ids
cancel_all_inbound	boolean	no	Optionally set a flag to cancel following steps of a series if the user receives an inbound email from the series recipient. This requires the user to have connected their inbox to VipeCloud to work.

POST /series_templates(/:id)

Sample body when creating an Series Template.

{
    "title" : "My Series Template",
    "steps" : ["123","124","125"]
}

GET Series Templates

GET /series_templates(/:id)

Retrieve series templates by id or retrieve a list of all series templates in the user's account.

Sample response to get series templates by id. GET /series_templates/123

{ 
    "id" : 123,
    "title" : "My Series Template",
    "update_date" : "2019-07-24 23:00:31"
}

Sample response to get all series templates. GET /series_templates

{ 
    [
      "id" : 123,
      "title" : "My Series Template",
      "update_date" : "2019-07-24 23:00:31"
    ],...
}

Series Template Steps (POST / GET)

Create, update, and retrieve Series Template Steps from your user accounts. Use in conjunction with the /series_templates endpoint.

POST Series Template Step

Attribute	type	required	description
delay_days	integer	yes	The number of days to delay this step after the prior step. Note that the first step in a series template will always have the delay days set to 0, regardless of this value.
email_template_id	integer	yes	Email template id
series_template_id	integer	no	Note the system will automatically assign this value when the series template step id is included in a POST to /series_templates. IMPORTANT: a series template step can only be associated with ONE series template.
action	string	no	This value will ALWAYS be set to "send a new email" for series template steps created via the API.
hour	integer	no	Optionally set the hour of the day this step will process. Disregarded for the first step. No leading zero.
min	integer	no	Optionally set the minute of the hour this step will process. Disregarded for the first step. No leading zero.
ampm	enum "am" or "pm"	no	Optionally set the am or pm of the day this step will process. Disregarded for the first step. NOTE to set the time for the step to process EACH of the hour, min, and ampm parameters need to be set.
weekday	boolean	no	Optionally set the step to only process on a weekday.

POST /series_template_steps(/:id)

Sample body when creating a Series Template Step. NOTE - if you UPDATE a series template step ALREADY associated with a series template you must ALSO update the series template to save the step changes.

{
    "delay_days" : 7,
    "email_template_id" : 123,
    "hour" : 12,
    "min" : 0,
    "ampm" : "pm",
    "weekday" : true
}

GET Series Template Steps

GET /series_template_steps(/:id)

Retrieve series template steps by id, by series_template_id, or retrieve a list of all series template steps in the user's account.

Sample response to get series template steps by id. GET /series_template_steps/123 or /series_template_steps?series_template_id=123

{ 
    "id" : 123,
    "series_template_id" : 123,
    "delay_days" : 7,
    "action" : "send a new email",
    "email_template_id" : 123,
    "weekday" : true,
    "hour" : 12,
    "min" : 0,
    "ampm" : "pm"
}

Sample response to get all series template steps. GET /series_template_steps

{ 
    [
      "id" : 123,
      "series_template_id" : 123,
      "delay_days" : 7,
      "action" : "send a new email",
      "email_template_id" : 123,
      "weekday" : true,
      "hour" : 12,
      "min" : 0,
      "ampm" : "pm"
    ],...
}

Social Accounts (GET)

Retrieve a user's connected social accounts.

GET account custom fields

GET /social_accounts(/:id)

The response to this GET will be an array of the user's social accounts or the details of a single account.

{ 
  [
    {
      "id" : 1, //the custom field id
      "slug" => "facebook", //lowercase string of the social network
      "account_name" => "Page - VipeCloud", //the name the user has given this social account
      "status" => "", //no status means the account is in good standing. Status of "authorized" is a Facebook group that has been authorized to connect by the user in VipeCloud, but has not yet had the VipeCloud app added to the Facebook group.
      "create_date" => "2020-03-22 16:45:37"
    }
  ]
}

Social Post (POST / GET / DELETE)

Create, update, retrieve, and delete social posts for your users.

POST Social Post

Attribute	type	required	description
social_account_id	integer	yes	The id for the social account of the user to make the post.
comment_data	array	yes	The comment_data array can support three keys: comment (string), images (array of URL strings), and link (string). It is required to have at least one of the comment or the images keys in your post.
schedule_data	array	yes	The schedule_data array requires four keys: scheduled_date (string, formatted YYYY-MM-DD), hour (string, no leading zero), min (string, no leading zero), and ampm (string).

POST /social_post(/:id)

Sample body when creating a Social Post.

{
    "social_account_id" : 123,
    "comment_data" : [
        "comment" : "Hello World!",
        "images" : ["https://www.imagehere.com/my_png.png"],
        "link" : ""
    ],
    "schedule_data" : [
        "scheduled_date" : "2020-03-23",
        "hour" : "5",
        "min" : "0",
        "ampm" : "pm"
    ]
}

GET Social Post

GET /social_post(/:id)

Retrieve the most recent 50 social posts or a single social post by id.

{ 
    [
      {
        "social_account_id" : 123,
        "comment_data" : [
            "comment" : "Hello World!",
            "images" : [],
            "link" : ""
        ],
        "schedule_data" : [
            "scheduled_date" : "2020-03-23",
            "hour" : "5",
            "min" : "0",
            "ampm" : "pm"
        ]
      }
    ]
}

DELETE Social Post

DELETE /social_post/:id

Delete a social post by id.

{ 
    "status" : "success"
}

Social Group Post (POST / GET / DELETE)

Create, update, retrieve, and delete social group posts for groups of your users' social accounts.

POST Social Group Post

Attribute	type	required	description
social_group_id	integer	yes	The id for the social group of the user to make the post.
comment_data	array	yes	The comment_data array can support three keys: comment (string), images (array of URL strings), and link (string). It is required to have at least one of the comment or the images keys in your post.
schedule_data	array	yes	The schedule_data array requires four keys: scheduled_date (string, formatted YYYY-MM-DD), hour (string, no leading zero), min (string, no leading zero), and ampm (string).

POST /social_group_post(/:id)

Sample body when creating a Social Group Post.

{
    "social_group_id" : 123,
    "comment_data" : [
        "comment" : "Hello World!",
        "images" : ["https://www.imagehere.com/my_png.png"],
        "link" : ""
    ],
    "schedule_data" : [
        "scheduled_date" : "2020-03-23",
        "hour" : "5",
        "min" : "0",
        "ampm" : "pm"
    ]
}

GET Social Group Post

GET /social_group_post(/:id)

Retrieve the most recent 50 social group posts or a single social group post by id.

{ 
    [
      {
        "social_group_id" : 123,
        "comment_data" : [
            "comment" : "Hello World!",
            "images" : [],
            "link" : ""
        ],
        "account_data" : [
            "group_ids" : ["1"],
            "account_ids" : ["1"]
        ]
        "schedule_data" : [
            "scheduled_date" : "2020-03-23",
            "hour" : "5",
            "min" : "0",
            "ampm" : "pm"
        ]
      }
    ]
}

DELETE Social Group Post

DELETE /social_group_post/:id

Delete a social group post by id.

{ 
    "status" : "success"
}

Text Templates (POST / GET)

If you are migrating from another text sending provider and have more text templates than you can manually transfer over, you can import them using the /text_templates endpoint.

POST /text_templates

Body params

{
  "title" : "My Text Template", //required and used to identify the contact
  "message" : "Hi there, this is my text template mesage....", //required. HTML is *not* allowed.
  "images" : ["https://imageurl1.com","https://imageurl2.com"], //optional, array of image urls
  "text_template_id" : 123, //optional, can be used to update one of your existing text templates
}

Sample response

{
    "status": "success",
    "text_template_id": 123
}

GET Templates(s)

GET /text_templates

GET a list of your text templates, search for an text template by title, or a get specific template by id. If no template is found, the response will be code 422 with the message "No template was found."

A note on access: in the API we only return text templates owned by the user. We do not return email templates the user can access via Shared With Me.

Sample responses

GET /text_templates
{ 
  [
    "0" : [
      "text_template_id" : 123
      "title" : "This is my title",
      "update_date" : 2020-01-05 04:00:11
    ]
  ]
}

GET /text_templates?query=title
{ 
  [
    "0" : [
      "text_template_id" : 123
      "title" : "This is my title",
      "update_date" : 2020-01-05 04:00:11
    ]
  ]
}

GET /text_templates/123
{ 
  "text_template_id" : 123
  "title" : "This is my title",
  "message" : "text of your text template here",
  "images" : ["https://imageurl1.com","https://imageurl2.com"], //array of image urls
}

Texts (POST)

Send texts via a POST.

POST Text(s)

POST /texts

Attribute	type	required	description
contacts_master_id	integer	yes or contact_list_id	The id of the contact you are texting
contact_list_id	integer	yes or contacts_master_id	Required param if sending to contact list. Include contacts_master_id OR contact_list_id.
message	string	yes or email_template_id	Required if no text_template_id.
text_template_id	integer	yes or message	Send text with text template. Replaces requirement for message.
filters	array	no	Filter contacts within a contact list at the time of send. If you include the filters parameter our system will create a new, system-generated list based on which contacts meet your filters within the contact_list_id that is also submitted. Each group of filters within the filters array must include a field_type (standard or custom), id (if standard a slug, if custom the custom_field_id), an operator (accepted values include equals, less_than, greater_than, less_than_or_equal_to, or greater_than_or_equal_to), and a value. Contacts that meet all filters within any of the filter groups will be added to the system-generated list.
test_filters	boolean	no	Will test your filters and NOT send the text. Will return the number of contacts in your original list and after your filters have been applied.
filtered_list_name	string	no	Optional name of the filterd contact list created
schedule_data	array	no	The schedule_data array requires four keys: scheduled_date (string formmated as YYYY-MM-DD), hour (string, no leading 0), min (string, no leading 0), and ampm (string).

Sample body.

{
  "contact_list_id": 12345,
  "text_template_id": 67890,
  "filters":[
    "0" : [
      "0" : [
        "field_type" : "standard",
        "id" : "first_name", 
        "operator" : "equals",
        "value" : "Wiley"
      ],
      "1" : [
        "field_type" : "custom",
        "id" : "123", 
        "operator" : "greater_than",
        "value" : "1000"
      ]
    ]
  ],
  "test_filters" : true,
  "schedule_data" : [
      "scheduled_date" : "2020-06-30",
      "hour" : "12",
      "min" : "15",
      "ampm" : "pm"
  ]
}

Sample 200 responses:

Post Type	Response
Specific contact	{"contact":{"contacts_master_id":"123","status":"correct"}}
Contact list	{"texts":"queue"}
Test filters	{"original_list_contacts": 100, "filtered_list_contacts" : 15, "view_filtered_contacts" : link_to_system_generated_contact_list }
Scheduled email	{"texts":"scheduled"}

Sample 422 responses:

Sample response messages
No filters submitted.
You don't have access to that contact list.
No contacts in contact list, so not processing text.
You don't have access to that text template.
All filters are required to have field_type, id, operator, and value parameters.
ABCXYZ is not a valid contact standard field.
ABCXYZ is not a valid operator.

Unsubscribes (POST)

Manually add unsubscribed email addresses for a user via a POST.

POST Unsubscribe

POST /unsubscribes

Attribute	type	required	description
email	string	yes	The email address to add to the unsubscribe list for this user.

Sample body.

{
  "email": "wiley.e.coyote@acme.com"
}

Sample 200 response below. Note that if an email is already unsubscribed for this user the response will still be a 200 but the status will say 'already_unsubscribed'.

{
  "email": "wiley.e.coyote@acme.com",
  "status": "success"
}

Stories (POST / GET)

Create, update, and retrieve Stories for your users.

POST /stories/:id

A note on chapters: when sending a POST to a Story, the chapter order is defined by your submitted array of chapters. If you are updating a Story, any previously existing Story chapters not included in your POST will be deleted.

Story Attribute	type	required	description
id	integer	yes if updating, no if creating new	The id of the story.
title	string	yes	The title of your story. Text string.
description	string	yes	The description for your story. HTML allowed. Empty value also allowed.
call_to_action	string	yes	The call to action for your story. HTML allowed. Empty value also allowed (though not suggested).
bg_music	integer	no	The id of the music track.
chapters	array	yes	Your story chapters. See Chapter Attributes below.
update_video	integer	no	Set to 1 if you want to encode the story as a video.

Chapter Attribute	type	required	description
id	integer	yes if updating, no if creating new	The id of the chapter.
type	string	yes	Supported values are file:image or vcvideo.
img_src	string	yes	Link to image or video thumbnail.
display_length	float	yes	Length of time to display this chapter. E.g. 5 or 5.2
asset_key	string	yes if type is vcvideo	The asset_key of the VipeCloud hosted video.

Sample POST body

{
  'title' : 'API Story',
  'description' : 'API story description',
  'call_to_action' : 'Click me now!',
  'chapters' => [
    [
      'type' => 'file:image',
      'img_src' => 'https:\/\/c.vipecloud.com\/view_file\/a91tm36w6nco80844c8cwwk004rxx007kf24g',
      'display_length' => 5
    ]
  ]
}

Sample response

{
    'id' : 123
    'title' : 'API Story',
    'description' : 'API story description',
    'call_to_action' : 'Click me now!',
    'story_key' : 'ABCDEF12345',
    'video_url' : 'https://v.vipecloud.com/vf/story_video/ABCDEF12345.mp4',
    'bg_music' : 0,
    'chapters' : [
      [
        'chapter_order' : 1,
        'chapter_data' : [
          'type' : 'file:image',
          'img_src' : 'https://myimageurl.com',
          'display_length' : 5
        ]
      ]
    ]
}

GET Stories

GET /stories/:id

GET a list of your Stories, search for a Story by title, or a get specific Story by id. If no story is found, the response will be code 422 with the message "No story was found."

A note on access: in the API we only return stories owned by the user. We do not return stories the user can access via Shared With Me.

Sample responses

GET /stories
{ 
  [
    "0" : [
      'id' : 123
      'title' : 'API Story',
      'description' : 'API story description',
      'call_to_action' : 'Click me now!'
      'story_key' : 'ABCDEF12345',
      'video_url' : 'https://v.vipecloud.com/vf/story_video/ABCDEF12345.mp4',
      'bg_music' : 0
    ]
  ]
}

GET /stories?query=story
{ 
  [
    "0" : [
      'id' : 123
      'title' : 'API Story',
      'description' : 'API story description',
      'call_to_action' : 'Click me now!',
      'story_key' : 'ABCDEF12345',
      'video_url' : 'https://v.vipecloud.com/vf/story_video/ABCDEF12345.mp4',
      'bg_music' : 0
    ]
  ]
}

GET /stories/123
{ 
  'id' : 123
  'title' : 'API Story',
  'description' : 'API story description',
  'call_to_action' : 'Click me now!',
  'story_key' : 'ABCDEF12345',
  'video_url' : 'https://v.vipecloud.com/vf/story_video/ABCDEF12345.mp4',
  'bg_music' : 0,
  'chapters' : [
    [
      'chapter_order' : 1,
      'chapter_data' : [
        'type' : 'file:image',
        'img_src' : 'https://myimageurl.com',
        'display_length' : 5
      ]
    ]
  ]
}

Social Connect (POST)

Invite people to authorize you to post to their social accounts on their behalf. The workflow presented here is to 1) send an email notification to a contact to invite them to authorize their social account. 2) They receive the email with the link and authorize. 3) You will receive a notification email upon completion (or failure) of authorization. In your notification there will be a link you can go to in order to select which account to connect.

NOTE: This can be used as first time authorization AND refreshing existing authorization.

POST Social Connect

POST /social_connect

Attribute	type	required	description
contacts_master_id	integer	yes OR first_name and email	The contact you want to authorize you to post on their behalf.
first_name	string	yes with email OR contacts_master_id	The first name of the contact.
email	string	yes with first_name OR contacts_master_id	The email of the contact.
social_network	string	yes	Only "facebook" is support at this time (by using "facebook", Instagram is by default also support).
email_template_id	integer	no	The email template to send to the contact for authorization. Must include a merge tag link of %SOCIAL_CONNECT_LINK%.
subject	string	no	In lieu of an email_template_id (or using our default template if email_template_id, subject, and message are not provide), this is the subject of the invite email.
message	string	no	In lieu of an email_template_id (or using our default template if email_template_id, subject, and message are not provide), this is the message of the invite email. Must include a merge tag link of %SOCIAL_CONNECT_LINK%.

Sample body.

{
  "first_name": "Bugs",
  "email" : "bugsbunny@acme.com",
  "social_network" : "facebook"
}

Sample 200 response below.

{
  "status": "success"
}

Social Account Groups (POST / GET)

Create, update, and retrieve Social Account Groups. Only works for Admin users.

POST /social_account_groups(/:id)

Attribute	type	required	description
id	integer	yes if updating, no if creating new	The id of the Social Account Group.
group_name	string	yes	The name of the Social Account Group.

Sample POST body

{
  'group_name' : 'All Social Accounts'
}

Sample response

{
    'id' : 123
    'group_name' : 'All Social Accounts',
    'create_date' : '2021-09-14 21:45:44'
}

GET Social Account Groups

GET /social_account_groups/:id

GET a list of your Social Account Groups, search for a Social Account Groups by name, or a get specific Social Account Groups by id. If no Social Account Groups is found, the response will be code 422 with the message "No Social Account Groups was found."

Sample responses

GET /social_account_groups
{ 
  [
    "0" : [
      'id' : 123
      'group_name' : 'All Social Accounts',
      'create_date' : '2021-09-14 21:45:44'
    ]
  ]
}

GET /social_account_groups?query=social
{ 
  [
    "0" : [
      'id' : 123
      'group_name' : 'All Social Accounts',
      'create_date' : '2021-09-14 21:45:44'
    ]
  ]
}

GET /social_account_groups/123
{ 
  'id' : 123
  'group_name' : 'All Social Accounts',
  'create_date' : '2021-09-14 21:45:44'
}

Zoom Background (POST)

Create and upload custom virtual backgrounds with a QR Code to your Zoom account.

NOTE: This endpoint is in BETA and requires invite only access.

POST Zoom Background

POST /zoom_background

Attribute	type	required	description
title	string	yes	The title of the image to add to your Zoom virtual background library.
action	enum (create_preview, upload_image_url)	yes	Which virtual background action is this endpoint taking?
image_url	string	yes	The image you want to use as your background. Will be cropped to 16x9 if it is not submitted in those dimensions.
url	string	no	The url destination for the QR Code.
url_location	enum (top-right (default), top-left, bottom-right, bottom-left)	yes if url parameter provided	The location of the QR Code on the image
text	array	no	An array of up to 3 strings for 3 rows of text (e.g. Your Name, Your Title, Your Company Name)
text_location	enum (top-right, top-left (default), bottom-right, bottom-left)	yes if text parameter provided	The location of your text on your image.
font_color	enum (white (default) or black)	yes if text parameter provided	The color of the text overlay.

Sample body.

{
  "title": "My First Background",
  "action" : "create_preview",
  "image_url" : "https://myimageurl.com", //a 16x9 image
  "url" : "https://vipecloud.com",
  "url_location" : "top-right"
}

Sample 200 response below.

{
  "status": "success",
  "background_url" : "https://vipecloud.com/your_zoom_virtual_background"
}