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.

Webhook Testing

To further help developers test Mav’s outbound integrations we have a testing tool which sends dummy data (specific to the selected playbook) to your webhook. You can access the testing tool by going to this link while signed in.