API Documentation
Overview
Mav’s API is available to all customers on a paid subscription. Customers use Mav’s API to customize many things to their business or sales operations. Here are a few examples:
Programmatically trigger Mav playbooks based on internal events. Such as CRM status change, lead delivery, or any other custom event.
Programmatically customize runtime settings for a Mav Playbook. Such as agent name, partner name or topic for following up.
Programmatically pass additional information about the lead. Enable Mav to dynamically verify information vs asking for information for the first time.
Subscribe to opt-in / opt-out status to store and keep TCPA compliance internally.
Subscribe to outcomes. Examples can be qualified, unqualified, scheduled, or call back requests.
Store information Mav collects on the lead in your own CRM or internal data warehouse.
And much more…
Mav API is split between two categories. Inbound (triggering Mav playbooks to run) and Outbound(subscribing to events that Mav generates).
The Inbound API is a set of RESTful APIs.
The Outbound is a set of Activities (Events, and Outcomes) you can subscribe to via webhooks.
To best understand how to integrate with Mav, let's start by defining a few important features and aspects of what makes Mav work.
Playbooks
One of the most important aspects of Mav are Playbooks. Playbooks are similar to the sales playbooks you give to your team, but Mav robotically runs them. Playbooks hold the logic and instructions for the data you’re capturing and the outcome you're trying to accomplish.
For example, if you’re running a qualification playbook the logic for the questions Mav asks and the accepted responses will be included in the playbook.
Right now, playbooks are co-authored between you and our internal team to ensure quality. Once a playbook is published in your account you will have access to add your leads, dynamically customize it, and run API calls against it.
Playbook Activities
Playbook activities are predefined activities that happen over the course of the SMS experience with your leads. Activities have two categories: Events and Outcomes.
Events are general activities that are agnostic to the playbook type. For example: started, opted_in, stopped, completed, etc.
Outcomes are specific outcomes that a lead may achieve by interacting with Mav. For example: qualified, unqualified, call back requested, scheduled, etc.
Plays
Plays are the specific instance of a playbook being run on a lead. Each time a lead is added to a playbook it creates a “Play” referencing that playbook run.
Plays can be in one of these four states:
Running - This means the playbook is currently active.
Stopped - This means the playbook is currently active.
Has Outcome - This means the lead has reached a playbook outcome.
Opted Out - This means the lead has opted out of messaging.
Getting Started with Mav’s Inbound API
Authentication
To work with our Inbound API you will need to have access to your account API Key. This can be accessed via the Settings page on the Mav dashboard. If you need help accessing your API key please contact our support team.
In your API request headers please supply both of these keys and values:
Authorization: xxxxxxxapi_keyxxxxx
Accept: application/json
Click below to read our Inbound API docs directly from Postman.
Getting Started with Mav’s Outbound API
Mav’s outbound API consists of subscribing to either event or outcome activity. Activity subscriptions are optional. You can choose to subscribe to one, many or all of the available activities (events and outcomes) your playbook supports.
Event activities are available across all playbooks and they include the following:
started — when Mav sends out the first message to the lead
interested — when a lead expresses interest and opts-in to messaging
stopped — when a playbook is stopped (either manually or during an opt-out)
completed — when a playbook has reached an outcome
reengagement_sent — when Mav sends a smart re-engagement to a lead
talk_to_human — when Mav would like to talk to a human
party_line_lead_attempted — when Mav attempts to call the lead for a party line
party_line_lead_answered — when the lead picks up the party line call from Mav
party_line_rep_attempted — when Mav attempts to call the rep for a party line
party_line_rep_unsuccessful — when Mav is unable to join the lead and rep for a party line
catch_all_level1 — when a lead hits CatchAll Level 1
catch_all_level2 — when a lead hits CatchAll Level 2
catch_all_level3 — when a lead hits CatchAll Level 3
Outcome activities are specific to your playbook. To give you an example, a typical Mortgage qualification playbook will include these outcomes that are available for you to subscribe to:
party_line_completed — when the lead and the rep have successfully been connected via a party line
callback_requested — when the lead has requested a call back
textback_requested — when the lead has requested a text back
unqualified — when the lead is unqualified
opted_out — when the lead opts out of messaging
Both events and outcomes will post a similar parameters to your supplied URL endpoint and you can expect to see the following parameters for each:
activity_type — event or outcome
activity_label — name of event or outcome
activity_play_id — Mav ID of the this specific play
activity_note — summary of activity
activity_created_at — timestamp of activity
lead_id — Mav lead ID
lead_first_name — lead first name
lead_last_name — lead last name
lead_email — lead email
lead_opted_out — opt out status
lead_created_at — timestamp creation date for lead
lead_additional_info — array of additional information that is specific to your playbook.
lead_originators
origin — source name
key — unique ID of originator source
Note: lead_orginators can be the same data you passed on the inbound call. This can be used to match a lead in your system and update the record.