Volly Marketing Automation API

API Endpoint

https://api.vollyma.com/v1

API Integration

Our API is an HTTPS REST API which is hosted at the following base endpoint below. POST and PUT methods will accept JSON (application/json). There are two authentication methods available - OAuth and API key

API Key

https://api.vollyma.com/v1/:object

You will need to use the HTTP Authorization header to submit your API key with your request.

Authorization = Key :key
e.g. Authorization = Key 59b9e8a83d0f4266abc485e0237072b2

OAuth

You will need to send a POST request to get an OAuth token for authenticating follow-up API requests. Your POST request body will need to include your provided OAuth client id and OAuth client secret.

https://api.vollyma.com/oauth/token

body = {
  "client_id": :id,
  "client_secret": :secret
}
e.g. {
  "client_id": "1nb13wvt12CG54ab40hf",
  "client_secret": "wHe3t9b44X-uR1QGfLlsZtICBc3Nb2fGNJ9NvkaIa"
}

The response will include the access token and the token type. This token will be valid for 10 minutes, after which it won’t authenticate and you’ll have to request a new one.

{
    "access_token": "ayJraWWiOiJyWFlybi1ZVk521WI0eEhxbE9adzhD...J3KdQTBHGu5BeupIh8BQVPFMFIBa4zCGohsX4KGqsuiHk8AxbvFLf",
    "token_type": "Bearer"
}

Include the token in the HTTP Authorization header for your API request. Your OAuth client id will also be required as a header field.

https://api.vollyma.com/v1/:object

client_id = :id
Authorization = Bearer :token
e.g. client_id = "1nb13wvt12CG54ab40hf"
     Authorization = Bearer ayJraWWiOiJyWFlybi1ZVk521WI0eEhxbE9adzhD...J3KdQTBHGu5BeupIh8BQVPFMFIBa4zCGohsX4KGqsuiHk8AxbvFLf

If you do not have the authorization header properly set, you will receive a 401 Unauthorized response.

mTLS

To use mTLS authentication, the above OAuth authorization is required as well as a signed and encrypted payload. That payload should be set in a json body with a jwt key. All .key and .crt files are required before this functionality will be enabled.

https://api.vollyma.com/v1/:object

headers = {
  client_id: :id
  Authorization: Bearer :token
}

body = {
  "jwt": :payload
}


e.g. 
headers = {
  client_id: "1nb13wvt12CG54ab40hf"
  Authorization: Bearer ayJraWWiOiJyWFlybi1ZVk521WI0eEhxbE9adzhD...J3KdQTBHGu5BeupIh8BQVPFMFIBa4zCGohsX4KGqsuiHk8AxbvFLf
}
body = {
  "jwt": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIi...-5cAt3XESr09qrr8ltZgi1IktVHgVIQyCqDFd1IgKEIx1wDvHMl3N_GuFW8Uvq5q2OkrNuK6ee79xmEDtv4x1FV6hW5R4zyo2WTf1HO.DlbRUPw5xczU1FNlZ9uciA"
}

Leads ¶

GET ¶

GET https://api.vollyma.com/v1/leads?external=%7B%22source%22%3A%22source%22%2C%22id%22%3A12%7D

Responses200404

Headers

Content-Type: application/json

Body

{
  "id": "8461dbd128a303f5d26a968a761990bc",
  "status": "Open - Not Contacted",
  "attributes": {
    "product": "Purchase",
    "leadsource": "Web"
  },
  "agent": "vollysf@email.com",
  "recipient": {
    "email": "apitest@myvolly.com",
    "email2": "apitest@email.com",
    "firstname": "api",
    "lastname": "test",
    "address": {},
    "phones": {}
  },
  "external": {
    "source": "source",
    "id": "00Q61000002hAmUEAU",
  },
  "client": "25ca04b0565a11e5a8b78770bbc1b432",
  "created": "2015-09-17T21:49:40.311Z",
  "segmented": "2015-09-17T21:49:40.339Z",
  "segment": "f639053512fa433fa7cf0fbe91af6764",
  "updated": "2015-09-19T21:54:04.775Z",
  "step": "1a592f87733c47589a7c08f021e082f6"
}

Body

"Not found"

Get Lead - By External
GET`/leads{?external}`

Use this endpoint to query a lead using external information.

URI Parameters

HideShow

external: JSON (required) Example: %7B%22source%22%3A%22source%22%2C%22id%22%3A12%7D
Pass in a JSON object as the external query parameter which has a source and id field defined. These values should be the exact same as used when creating the lead. The external JSON object will be parsed and must be valid JSON.

GET ¶

GET https://api.vollyma.com/v1/leads/8461dbd128a303f5d26a968a761990bc

Responses200404

Headers

Content-Type: application/json

Body

{
  "id": "8461dbd128a303f5d26a968a761990bc",
  "status": "Open - Not Contacted",
  "attributes": {
    "product": "Purchase",
    "leadsource": "Web"
  },
  "agent": "vollysf@email.com",
  "recipient": {
    "email": "test1@email.com",
    "email2": "test2@email.com",
    "firstname": "api",
    "lastname": "test",
    "address": {},
    "phones": {}
  },
  "external": {
    "source": "source",
    "id": "00Q61000002hAmUEAU",
  },
  "client": "25ca04b0565a11e5a8b78770bbc1b432",
  "created": "2015-09-17T21:49:40.311Z",
  "segmented": "2015-09-17T21:49:40.339Z",
  "segment": "f639053512fa433fa7cf0fbe91af6764",
  "updated": "2015-09-19T21:54:04.775Z",
  "step": "1a592f87733c47589a7c08f021e082f6"
}

Body

"Not found"

Get Lead - By Id
GET`/leads/{id}`

Use this endpoint to query a lead using their Volly given lead id.

URI Parameters

HideShow

id: string (required) Example: 8461dbd128a303f5d26a968a761990bc
Lookup a lead by lead id.

GET ¶

GET https://api.vollyma.com/v1/leads/email/test1@email.com

Responses200404

Headers

Content-Type: application/json

Body

{
  "id": "8461dbd128a303f5d26a968a761990bc",
  "status": "Open - Not Contacted",
  "attributes": {
    "product": "Purchase",
    "leadsource": "Web"
  },
  "agent": "vollysf@email.com",
  "recipient": {
    "email": "test1@email.com",
    "email2": "test2@email.com",
    "firstname": "api",
    "lastname": "test",
    "address": {},
    "phones": {}
  },
  "external": {
    "source": "source",
    "id": "00Q61000002hAmUEAU",
  },
  "client": "25ca04b0565a11e5a8b78770bbc1b432",
  "created": "2015-09-17T21:49:40.311Z",
  "segmented": "2015-09-17T21:49:40.339Z",
  "segment": "f639053512fa433fa7cf0fbe91af6764",
  "updated": "2015-09-19T21:54:04.775Z",
  "step": "1a592f87733c47589a7c08f021e082f6"
}

Body

"Not found"

Get Lead - By E-mail
GET`/leads/email/{email}`

Use this endpoint to query a lead using an email address.

URI Parameters

HideShow

email: string (required) Example: test1@email.com
Lookup a lead by email address.

POST ¶

POST https://api.vollyma.com/v1/leads

Requestsexample 1

Headers

Content-Type: application/json

Body

{
  "status": "New",
  "attributes": {
    "leadsource": "Web",
    "product": "Purchase"
  },
  "agent": "jane.agent@email.com",
  "recipient": {
    "firstname": "John",
    "lastname": "Doe",
    "email": "john.doe@email.com",
    "email2": "jane.doe@email.com",
    "address": {
      "line1": "12345 Easy St.",
      "line2": "address2",
      "city": "Nowhere",
      "state": "AK",
      "zip": "12345"
    },
    "phones": {
      "home": "1234567890",
      "mobile": "0987654321",
      "work": "1234509876"
    },
    "sms": {
      "enabled": "true",
      "optin": "true",
      "optin_date": "2016",
      "optout_date": "2016",
      "phone": "0987654321"
    }
  },
  "external": {
    "source": "source",
    "id": "12345"
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "attributes": {
      "type": "object",
      "properties": {
        "leadsource": {
          "type": "string"
        },
        "product": {
          "type": "string"
        }
      },
      "required": [
        "leadsource"
      ]
    },
    "agent": {
      "type": "string",
      "description": "Agent's email address"
    },
    "recipient": {
      "type": "object",
      "properties": {
        "firstname": {
          "type": "string"
        },
        "lastname": {
          "type": "string"
        },
        "email": {
          "type": "string",
          "description": "Lead's email address"
        },
        "email2": {
          "type": "string",
          "description": "Optional secondary email to CC"
        },
        "address": {
          "type": "object",
          "properties": {
            "line1": {
              "type": "string"
            },
            "line2": {
              "type": "string"
            },
            "city": {
              "type": "string"
            },
            "state": {
              "type": "string"
            },
            "zip": {
              "type": "string"
            }
          }
        },
        "phones": {
          "type": "object",
          "properties": {
            "home": {
              "type": "string"
            },
            "mobile": {
              "type": "string"
            },
            "work": {
              "type": "string"
            }
          }
        },
        "sms": {
          "type": "object",
          "properties": {
            "enabled": {
              "type": "string"
            },
            "optin": {
              "type": "string"
            },
            "optin_date": {
              "type": "string",
              "description": "05-18T15:45:29.417Z"
            },
            "optout_date": {
              "type": "string",
              "description": "06-20T19:13:40.002Z"
            },
            "phone": {
              "type": "string"
            }
          }
        }
      },
      "required": [
        "email"
      ]
    },
    "external": {
      "type": "object",
      "properties": {
        "source": {
          "type": "string"
        },
        "id": {
          "type": "string"
        }
      },
      "required": [
        "source",
        "id"
      ]
    }
  },
  "required": [
    "status",
    "attributes",
    "agent",
    "recipient",
    "external"
  ]
}

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "c156953beae6cf6bb91b38ae560236bf"
}

Create/Update New Lead
POST`/leads`

POST JSON to this endpoint to insert a new lead into a drip campaign, setup by status. We will examine the status and attributes of the lead to determine which segment in the campaign this lead will receive messages from. If the status of the lead changes, any scheduled messages will be canceled, and the lead will be re-segmented.

It is important that when you are adding leads, you supply the external source and id of this lead. Typically, the source is a string identifying the system where the lead resides, and the id is a value which is unique to that system.

Note: POSTing will behave as an upsert if you supply a different source, id combination.

Optouts ¶

Lookup Optout ¶

GET https://api.vollyma.com/v1/optouts/test1@email.com

Responses200404

Headers

Content-Type: application/json

Body

{
  "email": "test1@email.com",
  "history": [
    {
      "type": "optout",
      "at": "2015-09-23T15:01:34.733Z",
      "from": "api"
    }
  ]
}

This response has no content.

Lookup Optout
GET`/optouts/{email}`

Use this object to query your optout database for an email address.

URI Parameters

HideShow

email: string (required) Example: test1@email.com
Lookup an optout by email address

GET Optouts Since ¶

GET https://api.vollyma.com/v1/optouts?since=2015-09-24T21:22:39.939Z

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "email": "test3@email.com",
    "history": [
      {
        "type": "optout",
        "at": "2015-09-23T15:01:44.737Z",
        "from": "api"
      }
    ]
  },
  {
    "email": "test2@email.com",
    "history": [
      {
        "type": "optout",
        "at": "2015-09-23T15:01:41.543Z",
        "from": "api"
      }
    ]
  },
  {
    "email": "test1@email.com",
    "history": [
      {
        "type": "optout",
        "at": "2015-09-23T15:01:34.733Z",
        "from": "api"
      }
    ]
  }
]

Get Optouts Since
GET`/optouts{?since}`

Use this object to query your optout database for all opt-outs since that date.

URI Parameters

HideShow

since: string (required) Example: 2015-09-24T21:22:39.939Z
Pass in a UTC date formatted as ISO 8601 (YYYY-MM-DDTHH:MM:SSZ) to retrieve all optouts that have occured since that date.

POST ¶

POST https://api.vollyma.com/v1/optouts

Requestsexample 1

Headers

Content-Type: application/json

Body

{
  "email": "im.an.optout@email.com"
}

Responses201

Headers

Location: /v1/optouts/im.an.optout@email.com

Add Optout
POST`/optouts`

Use this object to add an optout to your optout database. Any email that Volly attempts to send to an address in this database will be canceled.

Optins ¶

POST ¶

POST https://api.vollyma.com/v1/optins

Requestsexample 1

Headers

Content-Type: application/json

Body

{
  "email": "opt.me.back.in@email.com"
}

Responses201

Headers

Location: /v1/optins/opt.me.back.in@email.com

Add Optin
POST`/optins`

Use this object to optin an email address.

Groups ¶

Manipulate the groups associated with your account. Senders may be assigned to a specific group to inherit these values.

Groups Operations ¶

GET https://api.vollyma.com/v1/groups

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": "6e36a10c1bff2a7b73647a29ff178a7c",
    "name": "Volly",
    "email": "support@myvolly.com",
    "address": {
      "address1": "12345 Easy St.",
      "address2": "Suite 402",
      "city": "Overland Park",
      "state": "KS",
      "zip": "66213"
    },
    "phones": {},
    "updated": "2014-07-25T21:25:12.477Z"
  },
  {
    "id": "6e36a10c1bff2a7b73647a29ff19d289",
    "name": "Loan Officers",
    "phones": {},
    "active": true,
    "updated": "2014-08-07T20:51:17.494Z"
  }
]

Get Groups
GET`/groups`

Retrieve groups associated with your account.

POST https://api.vollyma.com/v1/groups

Requestsexample 1

Headers

Content-Type: application/json

Body

{
  "name": "Loan Officers",
  "email": "loanofficers@email.com",
  "address": {
    "address1": "12345 Easy St.",
    "address2": "address2",
    "city": "Nowhere",
    "state": "AK",
    "zip": "12345"
  },
  "active": true,
  "phones": {
    "main": "1234567890",
    "cell": "0987654321",
    "fax": "1234509876"
  },
  "signature": "<p>This is the group signature.</p>"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "email": {
      "type": "string"
    },
    "address": {
      "type": "object",
      "properties": {
        "address1": {
          "type": "string"
        },
        "address2": {
          "type": "string"
        },
        "city": {
          "type": "string"
        },
        "state": {
          "type": "string"
        },
        "zip": {
          "type": "string"
        }
      }
    },
    "active": {
      "type": "boolean"
    },
    "phones": {
      "type": "object",
      "properties": {
        "main": {
          "type": "string"
        },
        "cell": {
          "type": "string"
        },
        "fax": {
          "type": "string"
        }
      }
    },
    "signature": {
      "type": "string",
      "description": "HTML formatted group signature"
    }
  },
  "required": [
    "name"
  ]
}

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "c156953beae6cf6bb91b38ae56008d92"
}

Create New Group
POST`/groups`

POST JSON to this endpoint to create a new group.

Get/Edit Group ¶

GET https://api.vollyma.com/v1/groups/6e36a10c1bff2a7b73647a29ff19d289

Responses200404

Headers

Content-Type: application/json

Body

{
  "id": "6e36a10c1bff2a7b73647a29ff19d289",
  "name": "Loan Officers",
  "phones": {},
  "active": true,
  "updated": "2014-08-07T20:51:17.494Z"
}

This response has no content.

Get Group
GET`/groups/{id}`

Use this endpoint to query a group.

URI Parameters

HideShow

id: string (required) Example: 6e36a10c1bff2a7b73647a29ff19d289
The group ID

PUT https://api.vollyma.com/v1/groups/6e36a10c1bff2a7b73647a29ff19d289

Requestsexample 1

Headers

Content-Type: application/json

Body

{
  "name": "Loan Officers",
  "email": "loanofficers@email.com",
  "address": {
    "address1": "12345 Easy St.",
    "address2": "address2",
    "city": "Nowhere",
    "state": "AK",
    "zip": "12345"
  },
  "active": true,
  "phones": {
    "main": "1234567890",
    "cell": "0987654321",
    "fax": "1234509876"
  },
  "signature": "<p>This is the group signature.</p>"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "email": {
      "type": "string"
    },
    "address": {
      "type": "object",
      "properties": {
        "address1": {
          "type": "string"
        },
        "address2": {
          "type": "string"
        },
        "city": {
          "type": "string"
        },
        "state": {
          "type": "string"
        },
        "zip": {
          "type": "string"
        }
      }
    },
    "active": {
      "type": "boolean"
    },
    "phones": {
      "type": "object",
      "properties": {
        "main": {
          "type": "string"
        },
        "cell": {
          "type": "string"
        },
        "fax": {
          "type": "string"
        }
      }
    },
    "signature": {
      "type": "string",
      "description": "HTML formatted group signature"
    }
  },
  "required": [
    "name"
  ]
}

Responses200

Headers

Content-Type: application/json

Body

{
  "ok": true
}

Update Group
PUT`/groups/{id}`

Use this endpoint to update a group.

URI Parameters

HideShow

id: string (required) Example: 6e36a10c1bff2a7b73647a29ff19d289
The group ID

DELETE https://api.vollyma.com/v1/groups/6e36a10c1bff2a7b73647a29ff19d289

Responses200

Headers

Content-Type: application/json

Body

{
  "ok": true
}

Delete Group
DELETE`/groups/{id}`

Use this endpoint to delete a group.

URI Parameters

HideShow

id: string (required) Example: 6e36a10c1bff2a7b73647a29ff19d289
The group ID

Senders ¶

Manipulate the senders associated with your account. Senders must have a unique email address. When posting leads or setting up batch sends, the sender email address is used to pull template values which can be used in replacement variables.

Senders Operations ¶

GET https://api.vollyma.com/v1/senders

Responses200404

Headers

Content-Type: application/json

Body

[
  {
    "id": "6bfca41f0e83873e48ed6b37247c3d0c",
    "phones": {
      "main": "111-222-3333",
      "cell": "444-555-6666",
      "fax": "777-888-9999"
    },
    "group": "6e36a10c1bff2a7b79332a29ff19d289",
    "email": "senderone@email.com",
    "firstname": "Sender",
    "lastname": "One",
    "custom": {
      "NMLS": "54321",
      "brokersite id": "123456789",
      "title": "Mortgage Loan Originator"
    },
    "active": true,
    "inserted": "2014-08-22T17:48:01.034Z",
    "updated": "2015-06-15T18:57:40.585Z",
    "lastnotification": "2014-10-27T21:21:24.527Z",
    "aliases": [
      "Sender One",
      "One, Sender"
    ],
    "override": false
  },
  {
    "id": "6bfca41f0e87167e48ed6b3724aa0472",
    "phones": {
      "main": "816-888-8888",
      "cell": "",
      "fax": ""
    },
    "group": "6e36a10c1bff2a7b73647a29ff19d289",
    "firstname": "Sender",
    "lastname": "Two",
    "custom": {
      "NMLS": "12345"
    },
    "active": false,
    "updated": "2015-06-15T18:57:40.586Z",
    "email": "sendertwo@email.com",
    "aliases": [
      "Sender Two",
      "Two, Sender"
    ],
    "override": false,
    "inserted": "2015-06-15T18:57:00.000Z"
  }
]

This response has no content.

Get Senders
GET`/senders`

Retrieve senders associated with your account.

POST https://api.vollyma.com/v1/senders

Requestsexample 1

Headers

Content-Type: application/json

Body

{
  "email": "new.sender@email.com",
  "aliases": [
    "NewSender"
  ],
  "firstname": "New",
  "lastname": "Sender",
  "active": true,
  "group": "6e36a10c1bff2a7b12345a29ff19d289 | Loan Officers",
  "phones": {
    "main": "1234567890",
    "cell": "0987654321",
    "fax": "1234509876"
  },
  "override": false,
  "signature": "<p>This is an individual sender override signature.</p>"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "email": {
      "type": "string"
    },
    "aliases": {
      "type": "array"
    },
    "firstname": {
      "type": "string"
    },
    "lastname": {
      "type": "string"
    },
    "active": {
      "type": "boolean"
    },
    "group": {
      "type": "string",
      "description": "Can be Volly group id or group name"
    },
    "phones": {
      "type": "object",
      "properties": {
        "main": {
          "type": "string"
        },
        "cell": {
          "type": "string"
        },
        "fax": {
          "type": "string"
        }
      }
    },
    "override": {
      "type": "boolean",
      "description": "Set to 'true' to override the group signature"
    },
    "signature": {
      "type": "string",
      "description": "HTML formatted sender signature"
    }
  },
  "required": [
    "email",
    "firstname",
    "lastname"
  ]
}

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "c156953beae6cf6bb91b38ae5602871b"
}

Create New Sender
POST`/senders`

POST JSON to this endpoint to create a new sender.

Get Active Senders ¶

GET https://api.vollyma.com/v1/senders/active

Responses200

Headers

Content-Type: application/json

Body

[
  {
    "id": "6bfca41f0e83873e48ed6b37247c3d0c",
    "phones": {
      "main": "111-222-3333",
      "cell": "444-555-6666",
      "fax": "777-888-9999"
    },
    "group": "6e36a10c1bff2a7b79332a29ff19d289",
    "email": "senderone@email.com",
    "firstname": "Sender",
    "lastname": "One",
    "custom": {
      "NMLS": "54321",
      "brokersite id": "123456789",
      "title": "Mortgage Loan Originator"
    },
    "active": true,
    "inserted": "2014-08-22T17:48:01.034Z",
    "updated": "2015-06-15T18:57:40.585Z",
    "lastnotification": "2014-10-27T21:21:24.527Z",
    "aliases": [
      "Sender One",
      "One, Sender"
    ],
    "override": false
  }
]

Get Active Senders
GET`/senders/active`

User this query to get only the active senders in the account (active: true).

Get/Edit Sender ¶

GET https://api.vollyma.com/v1/senders/c156953beae6cf6bb91b38ae5602871b

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "c156953beae6cf6bb91b38ae5602871b",
  "inserted": "2015-09-23T15:48:42.034Z",
  "email": "new.sender@email.com",
  "aliases": [
    "NewSender"
  ],
  "firstname": "New",
  "lastname": "Sender",
  "active": true,
  "group": "6e36a10c1bff2a7b73647a29ff19d289",
  "phones": {
    "main": "1234567890",
    "cell": "0987654321",
    "fax": "1234509876"
  },
  "updated": "2015-09-23T15:51:45.036Z"
}

Get Sender
GET`/senders/{id}`

Use this endpoint to query a sender.

URI Parameters

HideShow

id: string (required) Example: c156953beae6cf6bb91b38ae5602871b
The sender ID

PUT https://api.vollyma.com/v1/senders/c156953beae6cf6bb91b38ae5602871b

Requestsexample 1

Headers

Content-Type: application/json

Body

{
  "email": "new.sender@email.com",
  "aliases": [
    "NewSender"
  ],
  "firstname": "New",
  "lastname": "Sender",
  "active": true,
  "group": "6e36a10c1bff2a7b12345a29ff19d289 | Loan Officers",
  "phones": {
    "main": "1234567890",
    "cell": "0987654321",
    "fax": "1234509876"
  },
  "override": false,
  "signature": "<p>This is an individual sender override signature.</p>"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "email": {
      "type": "string"
    },
    "aliases": {
      "type": "array"
    },
    "firstname": {
      "type": "string"
    },
    "lastname": {
      "type": "string"
    },
    "active": {
      "type": "boolean"
    },
    "group": {
      "type": "string",
      "description": "Can be Volly group id or group name"
    },
    "phones": {
      "type": "object",
      "properties": {
        "main": {
          "type": "string"
        },
        "cell": {
          "type": "string"
        },
        "fax": {
          "type": "string"
        }
      }
    },
    "override": {
      "type": "boolean",
      "description": "Set to 'true' to override the group signature"
    },
    "signature": {
      "type": "string",
      "description": "HTML formatted sender signature"
    }
  },
  "required": [
    "email",
    "firstname",
    "lastname"
  ]
}

Responses200

Headers

Content-Type: application/json

Body

{
  "ok": true
}

Update Sender
PUT`/senders/{id}`

Use this endpoint to update a sender.

URI Parameters

HideShow

id: string (required) Example: c156953beae6cf6bb91b38ae5602871b
The sender ID

DELETE https://api.vollyma.com/v1/senders/c156953beae6cf6bb91b38ae5602871b

Responses200

Headers

Content-Type: application/json

Body

{
  "ok": true
}

Delete Sender
DELETE`/senders/{id}`

Use this endpoint to delete a sender.

URI Parameters

HideShow

id: string (required) Example: c156953beae6cf6bb91b38ae5602871b
The sender ID

Direct Sends ¶

There are multiple ways to initiate a direct send.

POST ¶

POST https://api.vollyma.com/v1/send

Requestsexample 1

Headers

Content-Type: application/json

Body

{
  "message": "intro",
  "agent": "jane.agent@email.com",
  "lead": {
    "source": "velocify",
    "id": "29309023"
  },
  "skip_ping": true
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "This is the slugname of the message configured on Volly's platform"
    },
    "agent": {
      "type": "string"
    },
    "lead": {
      "type": "object",
      "properties": {
        "source": {
          "type": "string",
          "description": "This is the name of the external system.  Must be used in conjunction with ID below"
        },
        "id": {
          "type": "string",
          "description": "This is the lead ID in the external system.  Must be used in conjunction with source above"
        }
      },
      "required": [
        "source",
        "id"
      ]
    },
    "skip_ping": {
      "type": "boolean",
      "description": "Set to true to stop Volly's platform from calling back into the integrated system to check for status or agent changes"
    }
  },
  "required": [
    "message",
    "agent",
    "lead"
  ]
}

Responses202

This response has no content.

Direct Send with Integration
POST`/send`

Use this endpoint to direct send an e-mail when integrated with an external system.

URI Parameters

HideShow

key: string (optional) Example: e8062b295e224c4f8273daed1ab66a59
Your API key, required if the authorization header is not set.

POST https://api.vollyma.com/v1/send

Requestsexample 1

Headers

Content-Type: application/json

Body

{
  "message": "intro",
  "agent": "jane.agent@email.com",
  "lead/recipient": {
    "email": "john.doe@gmail.com",
    "email2": "jane.doe@gmail.com",
    "firstname": "John",
    "custom": {
      "favoritecolor": "Blue"
    }
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "This is the slugname of the message configured on Volly's platform"
    },
    "agent": {
      "type": "string"
    },
    "lead/recipient": {
      "type": "object",
      "properties": {
        "email": {
          "type": "string"
        },
        "email2": {
          "type": "string",
          "description": "Recipient only. Secondary email to CC"
        },
        "firstname": {
          "type": "string",
          "description": "Lead attributes can be flexed in if a direct send message uses them"
        },
        "custom": {
          "type": "object",
          "properties": {
            "favoritecolor": {
              "type": "string"
            }
          },
          "description": "Custom attributes can be flexed in if a direct send message uses them"
        }
      },
      "required": [
        "email"
      ]
    }
  },
  "required": [
    "message",
    "agent",
    "lead/recipient"
  ]
}

Responses202

This response has no content.

Direct Send E-mail Only
POST`/send`

Use this endpoint to direct send an e-mail.

URI Parameters

HideShow

key: string (optional) Example: e8062b295e224c4f8273daed1ab66a59
Your API key, required if the authorization header is not set.

Webhook Events ¶

Events ¶

This is not an API endpoint.

The following are webhook events and their JSON payloads that we can POST to a url you provide. This JSON will have information regarding the event that occured, and may be used to keep your systems up-to-date, or trigger other actions.

mTLS

If mTLS is enabled for the client, webhook event payloads will be signed and encrypted. The payload will be sent as a json body with a key jwt. A token endpoint url must be provided, as well as all required .key and .crt files, before this functionality will be enabled.

{
  "jwt": :payload
}

e.g.
{
  "jwt": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIi...-5cAt3XESr09qrr8ltZgi1IktVHgVIQyCqDFd1IgKEIx1wDvHMl3N_GuFW8Uvq5q2OkrNuK6ee79xmEDtv4x1FV6hW5R4zyo2WTf1HO.DlbRUPw5xczU1FNlZ9uciA"
}

Custom Variables ¶

If custom lead variables are used, they will be included in the following format:

custom: {
    loanamount: "$240,000.00"
  }

POST https://api.vollyma.com/v1/

Requestsexample 1

Headers

Content-Type: application/json

Body

{
  "at": "2016-05-18T15:45:29.417Z",
  "type": "email.queued",
  "email": "201282329088",
  "message": "Day 0 Message",
  "subject": "This is the email subject line",
  "lead": {
    "id": "f0fafb1637c34e51b603575be7afa551",
    "external": {
      "id": "1234",
      "source": "crm"
    }
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "at": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "email": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "subject": {
      "type": "string"
    },
    "lead": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "This refers to the lead ID on Volly's platform"
        },
        "external": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "This refers to the lead ID on your CRM system"
            },
            "source": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

Responses

email.queued
POST`/`

An email has been sent to our outbound mail queues.

POST https://api.vollyma.com/v1/

Requestsexample 1

Headers

Content-Type: application/json

Body

{
  "at": "2016-05-18T15:45:31.361Z",
  "type": "email.delivered",
  "email": "201282329088",
  "lead": {
    "id": "f0fafb1637c34e51b603575be7afa551",
    "external": {
      "id": "1234",
      "source": "crm"
    }
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "at": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "email": {
      "type": "string"
    },
    "lead": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "This refers to the lead ID on Volly's platform"
        },
        "external": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "This refers to the lead ID on your CRM system"
            },
            "source": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

Responses

email.delivered
POST`/`

An email was delivered to the recipients inbound servers. This does not indicate the email is in the inbox, but does indicate that we have done everything we can.

POST https://api.vollyma.com/v1/

Requestsexample 1

Headers

Content-Type: application/json

Body

{
  "at": "2016-05-18T16:00:14.169Z",
  "type": "email.opened",
  "email": "201282329088",
  "lead": {
    "id": "f0fafb1637c34e51b603575be7afa551",
    "external": {
      "id": "1234",
      "source": "crm"
    }
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "at": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "email": {
      "type": "string"
    },
    "lead": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "This refers to the lead ID on Volly's platform"
        },
        "external": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "This refers to the lead ID on your CRM system"
            },
            "source": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

Responses

email.opened
POST`/`

An email was opened. The client or recipient server downloaded our embedded tracking pixel. There is an option for only unique opened events.

POST https://api.vollyma.com/v1/

Requestsexample 1

Headers

Content-Type: application/json

Body

{
  "at": "2016-05-18T16:05:21.497Z",
  "type": "email.clicked",
  "email": "201282329088",
  "redirect": "http://app.vollyma.com/page/bdede430b79211e48c85034b0c695ed1/452a62d28bb14193ad1fcc523fb2dd0a?e=201282329088",
  "lead": {
    "id": "f0fafb1637c34e51b603575be7afa551",
    "external": {
      "id": "1234",
      "source": "crm"
    }
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "at": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "email": {
      "type": "string"
    },
    "redirect": {
      "type": "string"
    },
    "lead": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "This refers to the lead ID on Volly's platform"
        },
        "external": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "This refers to the lead ID on your CRM system"
            },
            "source": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

Responses

email.clicked
POST`/`

A URL within the email was clicked. There is an option for only unique clicked events.

POST https://api.vollyma.com/v1/

Requestsexample 1

Headers

Content-Type: application/json

Body

{
  "at": "2016-05-18T16:00:14.169Z",
  "type": "form.completed",
  "email": "201282329088",
  "message": "Thank You Survey",
  "body": {
    "Question One": "Answer One",
    "Question Two": "2"
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "at": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "email": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "body": {
      "type": "object",
      "properties": {
        "Question One": {
          "type": "string"
        },
        "Question Two": {
          "type": "string"
        }
      }
    }
  }
}

Responses

form.completed
POST`/`

A survey was completed.

POST https://api.vollyma.com/v1/

Requestsexample 1

Headers

Content-Type: application/json

Body

{
  "at": "2016-05-18T16:31:45.682Z",
  "type": "optout",
  "email": "20138672804",
  "address": "im.an.optout@email.com",
  "lead": {
    "id": "2d8e1fe74f9c426ab23e60913260439d",
    "external": {
      "id": "1234",
      "source": "crm"
    }
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "at": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "email": {
      "type": "string"
    },
    "address": {
      "type": "string"
    },
    "lead": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "This refers to the lead ID on Volly's platform"
        },
        "external": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "This refers to the lead ID on your CRM system"
            },
            "source": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

Responses

optout
POST`/`

An email address has either opted-out through our optout link, a hard bounce, or we caught a spam report message through a FBL.

POST https://api.vollyma.com/v1/

Requestsexample 1

Headers

Content-Type: application/json

Body

{
  "at": "2016-05-18T16:00:14.169Z",
  "type": "email.bounced",
  "email": "201282329088",
  "error": "5.1.1 (bad destination mailbox address) : smtp;550 5.1.1 User Unknown",
  "lead": {
    "id": "2d8e1fe74f9c426ab23e60913260439d",
    "external": {
      "id": "1234",
      "source": "crm"
    }
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "at": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "email": {
      "type": "string"
    },
    "error": {
      "type": "string"
    },
    "lead": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "This refers to the lead ID on Volly's platform"
        },
        "external": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "This refers to the lead ID on your CRM system"
            },
            "source": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

Responses

email.bounced
POST`/`

An email bounced and failed to send.

POST https://api.vollyma.com/v1/

Requestsexample 1

Headers

Content-Type: application/json

Body

{
  "at": "2016-05-18T16:00:14.169Z",
  "type": "email.errored.global",
  "email": "201282329088",
  "error": {
    "message": "Message did not send because \"recipient@myvolly.com\" is globally opted out.",
    "name": "PermanentError",
    "location": "check",
    "code": "optout",
    "resource": "global",
    "recipient": "recipient@myvolly.com",
    "agent": "agent@myvolly.com"
  },
  "lead": {
    "id": "2d8e1fe74f9c426ab23e60913260439d",
    "external": {
      "id": "1234",
      "source": "crm"
    }
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "at": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "email": {
      "type": "string"
    },
    "error": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "location": {
          "type": "string"
        },
        "code": {
          "type": "string"
        },
        "resource": {
          "type": "string"
        },
        "recipient": {
          "type": "string"
        },
        "agent": {
          "type": "string"
        }
      }
    },
    "lead": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "This refers to the lead ID on Volly's platform"
        },
        "external": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "This refers to the lead ID on your CRM system"
            },
            "source": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

Responses

email.errored.global
POST`/`

An email errored because the recipient is globally opted out and failed to send.

Text Events ¶

POST https://api.vollyma.com/v1/

Requestsexample 1

Headers

Content-Type: application/json

Body

{
  "at": "2016-05-18T16:00:14.169Z",
  "type": "text.queued",
  "to": "+12345678901",
  "lead": {
    "id": "2d8e1fe74f9c426ab23e60913260439d",
    "external": {
      "id": "1234",
      "source": "crm"
    }
  },
  "text": "This is an example text. Please talk to your LO for more info."
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "at": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "to": {
      "type": "string"
    },
    "lead": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "This refers to the lead ID on Volly's platform"
        },
        "external": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "This refers to the lead ID on your CRM system"
            },
            "source": {
              "type": "string"
            }
          }
        }
      }
    },
    "text": {
      "type": "string"
    }
  }
}

Responses

text.queued
POST`/`

A text message has been sent to twilio.

POST https://api.vollyma.com/v1/

Requestsexample 1

Headers

Content-Type: application/json

Body

{
  "at": "2016-05-18T16:00:14.169Z",
  "type": "text.reply.twilio",
  "from": "+12345678902",
  "lead": {
    "id": "2d8e1fe74f9c426ab23e60913260439d",
    "external": {
      "id": "1234",
      "source": "crm"
    }
  },
  "reply": "This is an example reply."
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "at": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "from": {
      "type": "string"
    },
    "lead": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "This refers to the lead ID on Volly's platform"
        },
        "external": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "This refers to the lead ID on your CRM system"
            },
            "source": {
              "type": "string"
            }
          }
        }
      }
    },
    "reply": {
      "type": "string"
    }
  }
}

Responses

text.reply
POST`/`

A text reply has been received from twilio.

POST https://api.vollyma.com/v1/

Requestsexample 1

Headers

Content-Type: application/json

Body

{
  "at": "2016-05-18T16:00:14.169Z",
  "type": "text.optout",
  "from": "+12345678902",
  "lead": {
    "id": "2d8e1fe74f9c426ab23e60913260439d",
    "external": {
      "id": "1234",
      "source": "crm"
    }
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "at": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "from": {
      "type": "string"
    },
    "lead": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "This refers to the lead ID on Volly's platform"
        },
        "external": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "This refers to the lead ID on your CRM system"
            },
            "source": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

Responses

text.optout
POST`/`

An optout text reply has been received from the lead.

POST https://api.vollyma.com/v1/

Requestsexample 1

Headers

Content-Type: application/json

Body

{
  "at": "2016-05-18T16:00:14.169Z",
  "type": "text.optin",
  "from": "+12345678902",
  "lead": {
    "id": "2d8e1fe74f9c426ab23e60913260439d",
    "external": {
      "id": "1234",
      "source": "crm"
    }
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "at": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "from": {
      "type": "string"
    },
    "lead": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "This refers to the lead ID on Volly's platform"
        },
        "external": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "This refers to the lead ID on your CRM system"
            },
            "source": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

Responses

text.optin
POST`/`

An optin text reply has been received from the lead.

Generated by aglio on 09 Jan 2025

API Endpoint

API Integration ¶

API Key ¶

OAuth ¶

mTLS ¶

Leads ¶

GET ¶

Headers

Body

Body

Get Lead - By ExternalGET/leads{?external}

GET ¶

Headers

Body

Body

Get Lead - By IdGET/leads/{id}

GET ¶

Headers

Body

Body

Get Lead - By E-mailGET/leads/email/{email}

POST ¶

Headers

Body

Schema

Headers

Body

Create/Update New LeadPOST/leads

Optouts ¶

Lookup Optout ¶

Headers

Body

Lookup OptoutGET/optouts/{email}

GET Optouts Since ¶

Headers

Body

Get Optouts SinceGET/optouts{?since}

POST ¶

Headers

Body

Headers

Add OptoutPOST/optouts

Optins ¶

POST ¶

Headers

Body

Headers

Add OptinPOST/optins

Groups ¶

Groups Operations ¶

Headers

Body

Get GroupsGET/groups

Headers

Body

Schema

Headers

Body

Create New GroupPOST/groups

Get/Edit Group ¶

Headers

Body

Get GroupGET/groups/{id}

Headers

Body

Schema

Headers

Body

Update GroupPUT/groups/{id}

Headers

Body

Delete GroupDELETE/groups/{id}

Senders ¶

Senders Operations ¶

Headers

Body

Get SendersGET/senders

Headers

Body

Schema

API Integration

API Key

OAuth

mTLS

Get Lead - By External
GET`/leads{?external}`

Get Lead - By Id
GET`/leads/{id}`

Get Lead - By E-mail
GET`/leads/email/{email}`

Create/Update New Lead
POST`/leads`

Lookup Optout
GET`/optouts/{email}`

Get Optouts Since
GET`/optouts{?since}`

Add Optout
POST`/optouts`

Add Optin
POST`/optins`

Get Groups
GET`/groups`

Create New Group
POST`/groups`

Get Group
GET`/groups/{id}`

Update Group
PUT`/groups/{id}`

Delete Group
DELETE`/groups/{id}`

Get Senders
GET`/senders`

Create New Sender
POST`/senders`

Get Active Senders
GET`/senders/active`

Get Sender
GET`/senders/{id}`

Update Sender
PUT`/senders/{id}`

Delete Sender
DELETE`/senders/{id}`

Direct Send with Integration
POST`/send`

Direct Send E-mail Only
POST`/send`

mTLS

email.queued
POST`/`

email.delivered
POST`/`

email.opened
POST`/`

email.clicked
POST`/`

form.completed
POST`/`

optout
POST`/`

email.bounced
POST`/`

email.errored.global
POST`/`