NAV
bash javascript php python

Info

Welcome to the Wavo Platform API reference.

Introduction

The Wavo Platform provides a modern REST API.

Requests support standard HTTP methods (GET, POST, PUT, DELETE). The API responses are JSON objects using standard HTTP status codes.

Authentication

User authentication is achieved through a Bearer token used in request header.

The user should generate an access token through the Wavo app, third-party integration settings.

This token authenticates the user and applies authorization logic to the API requests, fetching the appropriate data.

API Rate Limits

Wavo enforces API rate limits for its REST APIs.

Exceeding any rate limits will result in a status code of 429 (Too Many Requests). Rate limits are per user. There are the following rate limits:

These limits are independent e.g. in the same 60 seconds period, you could make 10 contact search requests and 60 clients requests. The specific rate limits are subject to change

Campaigns

APIs for managing campaigns.

Display a listing of campaigns


Requires authentication Return all campaigns accessible by a user. If used by an agency with white-label dashboard subscription, an optional client_id parameter can be defined to return the campaigns of a specific client.

Example request:

curl -X GET \
    -G "https://app.wavo.co/api/v1/campaigns?client_id=ah83445df46as5432mga" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Authorization: Bearer {token}"
const url = new URL(
    "https://app.wavo.co/api/v1/campaigns"
);

let params = {
    "client_id": "ah83445df46as5432mga",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": "Bearer {token}",
};

fetch(url, {
    method: "GET",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));

$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://app.wavo.co/api/v1/campaigns',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Authorization' => 'Bearer {token}',
        ],
        'query' => [
            'client_id' => 'ah83445df46as5432mga',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://app.wavo.co/api/v1/campaigns'
params = {
  'client_id': 'ah83445df46as5432mga'
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {token}'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()

Example response (200):

{
    "data": [
        {
            "id": "g6eq5ko37veynd8yj2w0",
            "name": "Spencer, Moore and Cremin 13",
            "timezone": "US\/Mountain",
            "status": "DRAFT",
            "created_at": 1597996642,
            "client": {
                "id": "nk68rdmpwv87oz05291y",
                "name": "Spencer, Moore and Cremin",
                "max_emails": 3,
                "created_at": 1597996642
            }
        },
        {
            "id": "yeowg4z070ok7vpd1682",
            "name": "Weissnat Ltd 9",
            "timezone": "US\/Mountain",
            "status": "DRAFT",
            "created_at": 1597996642,
            "client": {
                "id": "xkrdlm37w6djo8enp6zq",
                "name": "Weissnat Ltd",
                "max_emails": 3,
                "created_at": 1597996642
            }
        }
    ]
}

HTTP Request

GET api/v1/campaigns

Query Parameters

Parameter Status Description
client_id optional The id of a client.

Create a new campaign


Requires authentication Create a new campaign for a client.

Example request:

curl -X POST \
    "https://app.wavo.co/api/v1/campaigns" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Authorization: Bearer {token}" \
    -d '{"name":"consequuntur","client_id":"4a83445df46as5432mga","timezone":"US\/Mountain"}'
const url = new URL(
    "https://app.wavo.co/api/v1/campaigns"
);

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": "Bearer {token}",
};

let body = {
    "name": "consequuntur",
    "client_id": "4a83445df46as5432mga",
    "timezone": "US\/Mountain"
}

fetch(url, {
    method: "POST",
    headers: headers,
    body: body
})
    .then(response => response.json())
    .then(json => console.log(json));

$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://app.wavo.co/api/v1/campaigns',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Authorization' => 'Bearer {token}',
        ],
        'json' => [
            'name' => 'consequuntur',
            'client_id' => '4a83445df46as5432mga',
            'timezone' => 'US/Mountain',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://app.wavo.co/api/v1/campaigns'
payload = {
    "name": "consequuntur",
    "client_id": "4a83445df46as5432mga",
    "timezone": "US\/Mountain"
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {token}'
}
response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Example response (201):

{
    "data": {
        "id": "3ry94qv278e57gmxj1k8",
        "name": "Kreiger Ltd 15",
        "timezone": "US\/Mountain",
        "status": "DRAFT",
        "created_at": 1597996642,
        "client": {
            "id": "vl8re092o921w745jmpk",
            "name": "Kreiger Ltd",
            "max_emails": 3,
            "created_at": 1597996642
        }
    }
}

HTTP Request

POST api/v1/campaigns

Body Parameters

Parameter Type Status Description
name string required The campaign name.
client_id string required The id of the client.
timezone string required The timezone that the campaign's schedule should use.

Clients

APIs for managing clients.

Display a user's accessible clients


Requires authentication This will return an array of 1 or more clients (for users on white-label dashboard subscription).

Example request:

curl -X GET \
    -G "https://app.wavo.co/api/v1/clients" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Authorization: Bearer {token}"
const url = new URL(
    "https://app.wavo.co/api/v1/clients"
);

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": "Bearer {token}",
};

fetch(url, {
    method: "GET",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));

$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://app.wavo.co/api/v1/clients',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Authorization' => 'Bearer {token}',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://app.wavo.co/api/v1/clients'
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {token}'
}
response = requests.request('GET', url, headers=headers)
response.json()

Example response (200):

{
    "data": [
        {
            "id": "nq1m5d3po4j6o86jze4l",
            "name": "Carter-Marvin",
            "max_emails": 3,
            "created_at": 1597996642
        },
        {
            "id": "xv6jqlk4wej5g53dm1p2",
            "name": "Block PLC",
            "max_emails": 3,
            "created_at": 1597996642
        }
    ]
}

HTTP Request

GET api/v1/clients

Create a new client


Requires authentication Add a new client to the user's agency

Example request:

curl -X POST \
    "https://app.wavo.co/api/v1/clients" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Authorization: Bearer {token}" \
    -d '{"name":"Thompson LLC","max_emails":3}'
const url = new URL(
    "https://app.wavo.co/api/v1/clients"
);

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": "Bearer {token}",
};

let body = {
    "name": "Thompson LLC",
    "max_emails": 3
}

fetch(url, {
    method: "POST",
    headers: headers,
    body: body
})
    .then(response => response.json())
    .then(json => console.log(json));

$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://app.wavo.co/api/v1/clients',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Authorization' => 'Bearer {token}',
        ],
        'json' => [
            'name' => 'Thompson LLC',
            'max_emails' => 3,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://app.wavo.co/api/v1/clients'
payload = {
    "name": "Thompson LLC",
    "max_emails": 3
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {token}'
}
response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Example response (201):

{
    "data": {
        "id": "l8re092o9qv7w745jmpk",
        "name": "Thompson LLC",
        "max_emails": 3,
        "created_at": 1580411327
    }
}

HTTP Request

POST api/v1/clients

Body Parameters

Parameter Type Status Description
name string required The client name or title.
max_emails integer required The amount of max emails the client can add manually.

Display a client's users


Requires authentication Show all active users of a client as well as pending user invitations, with their assigned roles.

Example request:

curl -X GET \
    -G "https://app.wavo.co/api/v1/clients/a83445df46as5432mga/users" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Authorization: Bearer {token}"
const url = new URL(
    "https://app.wavo.co/api/v1/clients/a83445df46as5432mga/users"
);

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": "Bearer {token}",
};

fetch(url, {
    method: "GET",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));

$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://app.wavo.co/api/v1/clients/a83445df46as5432mga/users',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Authorization' => 'Bearer {token}',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://app.wavo.co/api/v1/clients/a83445df46as5432mga/users'
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {token}'
}
response = requests.request('GET', url, headers=headers)
response.json()

Example response (200):

{
    "data": {
        "users": [
            {
                "name": "Mike Jones",
                "email": "mike@wavo.co",
                "created_at": 1580412998,
                "roles": [
                    "view_campaigns"
                ]
            },
            {
                "name": "Bill Scott",
                "email": "bill@wavo.co",
                "created_at": 1580412998,
                "roles": [
                    "view_campaigns",
                    "create_campaigns"
                ]
            }
        ],
        "invitations": [
            {
                "email": "mike1@wavo.co",
                "created_at": 1580412998,
                "roles": [
                    "create_campaigns",
                    "export_data",
                    "view_campaigns"
                ]
            }
        ]
    }
}

HTTP Request

GET api/v1/clients/{client_id}/users

URL Parameters

Parameter Status Description
client_id required The id of a client.

Add a new client user


Requires authentication Add a new user to a client. Specify the user's email address and the roles he should have. Available roles are:

Example request:

curl -X POST \
    "https://app.wavo.co/api/v1/clients/a83445df46as5432mga/users" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Authorization: Bearer {token}" \
    -d '{"email":"mike@wavo.co","view_campaigns":true,"create_campaigns":true,"export_campaigns":true}'
const url = new URL(
    "https://app.wavo.co/api/v1/clients/a83445df46as5432mga/users"
);

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": "Bearer {token}",
};

let body = {
    "email": "mike@wavo.co",
    "view_campaigns": true,
    "create_campaigns": true,
    "export_campaigns": true
}

fetch(url, {
    method: "POST",
    headers: headers,
    body: body
})
    .then(response => response.json())
    .then(json => console.log(json));

$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://app.wavo.co/api/v1/clients/a83445df46as5432mga/users',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Authorization' => 'Bearer {token}',
        ],
        'json' => [
            'email' => 'mike@wavo.co',
            'view_campaigns' => true,
            'create_campaigns' => true,
            'export_campaigns' => true,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://app.wavo.co/api/v1/clients/a83445df46as5432mga/users'
payload = {
    "email": "mike@wavo.co",
    "view_campaigns": true,
    "create_campaigns": true,
    "export_campaigns": true
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {token}'
}
response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Example response (200):

{
    "message": "An invitation was sent to mike@wavo.co"
}

HTTP Request

POST api/v1/clients/{client_id}/users

URL Parameters

Parameter Status Description
client_id required The id of a client.

Body Parameters

Parameter Type Status Description
email string required The email address of the user.
view_campaigns boolean optional Whether the user will be able to view campaigns.
create_campaigns boolean optional Whether the user will be able to create new campaigns.
export_campaigns boolean optional Whether the user will be able export campaign contacts.

Update a client user


Requires authentication Update a client user's roles. Can update roles of active users or user invitations. Available roles are:

Example request:

curl -X PUT \
    "https://app.wavo.co/api/v1/clients/a83445df46as5432mga/users" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Authorization: Bearer {token}" \
    -d '{"email":"mike@wavo.co","view_campaigns":false,"create_campaigns":false,"export_campaigns":true}'
const url = new URL(
    "https://app.wavo.co/api/v1/clients/a83445df46as5432mga/users"
);

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": "Bearer {token}",
};

let body = {
    "email": "mike@wavo.co",
    "view_campaigns": false,
    "create_campaigns": false,
    "export_campaigns": true
}

fetch(url, {
    method: "PUT",
    headers: headers,
    body: body
})
    .then(response => response.json())
    .then(json => console.log(json));

$client = new \GuzzleHttp\Client();
$response = $client->put(
    'https://app.wavo.co/api/v1/clients/a83445df46as5432mga/users',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Authorization' => 'Bearer {token}',
        ],
        'json' => [
            'email' => 'mike@wavo.co',
            'view_campaigns' => false,
            'create_campaigns' => false,
            'export_campaigns' => true,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://app.wavo.co/api/v1/clients/a83445df46as5432mga/users'
payload = {
    "email": "mike@wavo.co",
    "view_campaigns": false,
    "create_campaigns": false,
    "export_campaigns": true
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {token}'
}
response = requests.request('PUT', url, headers=headers, json=payload)
response.json()

Example response (200):

{
    "message": "Success. Updated user roles."
}

HTTP Request

PUT api/v1/clients/{client_id}/users

URL Parameters

Parameter Status Description
client_id required The id of a client.

Body Parameters

Parameter Type Status Description
email string required The email address of the user.
view_campaigns boolean optional Whether the user will be able to view campaigns.
create_campaigns boolean optional Whether the user will be able to create new campaigns.
export_campaigns boolean optional Whether the user will be able export campaign contacts.

Delete a client user


Requires authentication Remove a user from a client.

Example request:

curl -X DELETE \
    "https://app.wavo.co/api/v1/clients/a83445df46as5432mga/users?email=mike%40wavo.co" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Authorization: Bearer {token}"
const url = new URL(
    "https://app.wavo.co/api/v1/clients/a83445df46as5432mga/users"
);

let params = {
    "email": "mike@wavo.co",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": "Bearer {token}",
};

fetch(url, {
    method: "DELETE",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));

$client = new \GuzzleHttp\Client();
$response = $client->delete(
    'https://app.wavo.co/api/v1/clients/a83445df46as5432mga/users',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Authorization' => 'Bearer {token}',
        ],
        'query' => [
            'email' => 'mike@wavo.co',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://app.wavo.co/api/v1/clients/a83445df46as5432mga/users'
params = {
  'email': 'mike@wavo.co'
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {token}'
}
response = requests.request('DELETE', url, headers=headers, params=params)
response.json()

Example response (204):

{}

HTTP Request

DELETE api/v1/clients/{client_id}/users

URL Parameters

Parameter Status Description
client_id required The id of a client.

Query Parameters

Parameter Status Description
email required The email address of the user.

Contacts

APIs for managing contacts.

Create a new contact


Requires authentication A new contact can be attached to an existing campaign. As such the campaign_id is required

Example request:

curl -X POST \
    "https://app.wavo.co/api/v1/contacts" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Authorization: Bearer {token}" \
    -d '{"campaign_id":"fkjtf4390kfgu8903nsk","email":"illo","first_name":"dicta","last_name":"commodi","company":"beatae","industry":"non","website":"nulla","title":"dolorem","phone":"molestiae","address":"voluptatum","city":"ut","state":"impedit","country":"vitae","custom_merge_fields":{"fav color": "green", "sport": "climbing", "os": "Windows NT 4.0"}}'
const url = new URL(
    "https://app.wavo.co/api/v1/contacts"
);

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": "Bearer {token}",
};

let body = {
    "campaign_id": "fkjtf4390kfgu8903nsk",
    "email": "illo",
    "first_name": "dicta",
    "last_name": "commodi",
    "company": "beatae",
    "industry": "non",
    "website": "nulla",
    "title": "dolorem",
    "phone": "molestiae",
    "address": "voluptatum",
    "city": "ut",
    "state": "impedit",
    "country": "vitae",
    "custom_merge_fields": {
        "fav color": "green", 
        "sport": "climbing", 
        "os": "Windows NT 4.0"
    }
}

fetch(url, {
    method: "POST",
    headers: headers,
    body: body
})
    .then(response => response.json())
    .then(json => console.log(json));

$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://app.wavo.co/api/v1/contacts',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Authorization' => 'Bearer {token}',
        ],
        'json' => [
            'campaign_id' => 'fkjtf4390kfgu8903nsk',
            'email' => 'illo',
            'first_name' => 'dicta',
            'last_name' => 'commodi',
            'company' => 'beatae',
            'industry' => 'non',
            'website' => 'nulla',
            'title' => 'dolorem',
            'phone' => 'molestiae',
            'address' => 'voluptatum',
            'city' => 'ut',
            'state' => 'impedit',
            'country' => 'vitae',
            'custom_merge_fields' => [
                "fav color" => "green", 
                "sport" => "climbing", 
                "os" => "Windows NT 4.0",
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://app.wavo.co/api/v1/contacts'
payload = {
    "campaign_id": "fkjtf4390kfgu8903nsk",
    "email": "illo",
    "first_name": "dicta",
    "last_name": "commodi",
    "company": "beatae",
    "industry": "non",
    "website": "nulla",
    "title": "dolorem",
    "phone": "molestiae",
    "address": "voluptatum",
    "city": "ut",
    "state": "impedit",
    "country": "vitae",
    "custom_merge_fields": {
        "fav color": "green", 
        "sport": "climbing", 
        "os": "Windows NT 4.0"
    }
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {token}'
}
response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Example response (201):

{
    "data": [
        {
            "id": "we52o4rv130mz1qxyzk8pmljd",
            "email": "aditya.kohler@example.org",
            "first_name": "Aditya",
            "last_name": "Kohler",
            "company": "Gerlach, Ziemann and Reilly",
            "industry": "Nonprofit Organization Management",
            "website": "kunde.com",
            "title": "Ms.",
            "phone": "219-959-5166",
            "address": "41164 Osvaldo Row",
            "city": "Baileyborough",
            "state": "New Hampshire",
            "country": "US",
            "custom_merge_fields": {
                "fav color": "purple",
                "sport": "running",
                "os": "Windows NT 5.0"
            },
            "timezone": "US\/Mountain",
            "status": "OK",
            "interest": null,
            "emails_sent": 0,
            "created_at": 1579888600,
            "campaign": {
                "id": "fkjtf4390kfgu8903nsk",
                "name": "Grady-Runolfsson 16",
                "timezone": "US\/Mountain",
                "status": "DRAFT",
                "created_at": 1579888600,
                "client": {
                    "id": "a83445df46as5432mga",
                    "name": "Grady-Runolfsson",
                    "created_at": 1579888600
                }
            }
        }
    ]
}

HTTP Request

POST api/v1/contacts

Body Parameters

Parameter Type Status Description
campaign_id string required The id of the campaign.
email string required The email address of the contact.
first_name string optional The first name of the contact.
last_name string optional The last name of contact.
company string optional The company of the contact.
industry string optional The industry of the contact.
website string optional The website of the contact.
title string optional The job title of the contact.
phone string optional The phone of the contact.
address string optional The address of the contact.
city string optional The city of the contact.
state string optional The state of the contact.
country string optional The country of the contact.
custom_merge_fields[] array optional An array of merge data to be used in email messages.

Display a contact


Requires authentication Find a contact by id and display its details.

Example request:

curl -X GET \
    -G "https://app.wavo.co/api/v1/contacts/we52o4rv130mz1qxyzk8pmljd" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Authorization: Bearer {token}"
const url = new URL(
    "https://app.wavo.co/api/v1/contacts/we52o4rv130mz1qxyzk8pmljd"
);

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": "Bearer {token}",
};

fetch(url, {
    method: "GET",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));

$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://app.wavo.co/api/v1/contacts/we52o4rv130mz1qxyzk8pmljd',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Authorization' => 'Bearer {token}',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://app.wavo.co/api/v1/contacts/we52o4rv130mz1qxyzk8pmljd'
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {token}'
}
response = requests.request('GET', url, headers=headers)
response.json()

Example response (200):

{
    "data": {
        "id": "we52o4rv130mz1qxyzk8pmljd",
        "email": "aditya.kohler@example.org",
        "first_name": "Aditya",
        "last_name": "Kohler",
        "company": "Gerlach, Ziemann and Reilly",
        "industry": "Nonprofit Organization Management",
        "website": "kunde.com",
        "title": "Ms.",
        "phone": "219-959-5166",
        "address": "41164 Osvaldo Row",
        "city": "Baileyborough",
        "state": "New Hampshire",
        "country": "US",
        "custom_merge_fields": {
            "fav color": "purple",
            "sport": "running",
            "os": "Windows NT 5.0"
        },
        "timezone": "US\/Mountain",
        "status": "OK",
        "interest": null,
        "emails_sent": 0,
        "created_at": 1579888600,
        "campaign": {
            "id": "fkjtf4390kfgu8903nsk",
            "name": "Grady-Runolfsson 16",
            "timezone": "US\/Mountain",
            "status": "DRAFT",
            "created_at": 1579888600,
            "client": {
                "id": "a83445df46as5432mga",
                "name": "Grady-Runolfsson",
                "created_at": 1579888600
            }
        }
    }
}

HTTP Request

GET api/v1/contacts/{contact_id}

URL Parameters

Parameter Status Description
contact_id required The id of the contact.

Display a listing of contacts


Requires authentication Return all contacts of a campaign.

Example request:

curl -X GET \
    -G "https://app.wavo.co/api/v1/campaigns/fkjtf4390kfgu8903nsk/contacts?status=replied&interest=positive&emails_sent=3&limit=2&offset=0" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Authorization: Bearer {token}"
const url = new URL(
    "https://app.wavo.co/api/v1/campaigns/fkjtf4390kfgu8903nsk/contacts"
);

let params = {
    "status": "replied",
    "interest": "positive",
    "emails_sent": "3",
    "limit": "2",
    "offset": "0",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": "Bearer {token}",
};

fetch(url, {
    method: "GET",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));

$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://app.wavo.co/api/v1/campaigns/fkjtf4390kfgu8903nsk/contacts',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Authorization' => 'Bearer {token}',
        ],
        'query' => [
            'status' => 'replied',
            'interest' => 'positive',
            'emails_sent' => '3',
            'limit' => '2',
            'offset' => '0',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://app.wavo.co/api/v1/campaigns/fkjtf4390kfgu8903nsk/contacts'
params = {
  'status': 'replied',
  'interest': 'positive',
  'emails_sent': '3',
  'limit': '2',
  'offset': '0'
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {token}'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()

Example response (200):

{
    "data": [
        {
            "id": "j5ropgvndm6l1v0z7lwe9481y",
            "email": "corwin.velda@example.com",
            "first_name": "Vincent",
            "last_name": "Kemmer",
            "company": "Hartmann, Lockman and Thompson",
            "industry": "Luxury Goods & Jewelry",
            "website": "mosciski.com",
            "title": "Mr.",
            "phone": "1-213-895-2923",
            "address": "6166 Jakubowski Cliff Suite 605",
            "city": "Port Reidville",
            "state": "North Carolina",
            "country": "US",
            "custom_merge_fields": {
                "fav color": "teal",
                "sport": "tennis",
                "os": "Windows NT 6.2"
            },
            "timezone": "US\/Mountain",
            "status": "OK",
            "interest": null,
            "emails_sent": 1,
            "created_at": 1579888424
        },
        {
            "id": "ny4j2vd8k56248q1wzgeo9r3p",
            "email": "mschowalter@example.com",
            "first_name": "Jacquelyn",
            "last_name": "Okuneva",
            "company": "Armstrong, Ferry and Nolan",
            "industry": "Design",
            "website": "sanford.com",
            "title": "Prof.",
            "phone": "(828) 344-5044 x05539",
            "address": "1971 Colten Ways",
            "city": "Batzland",
            "state": "Kansas",
            "country": "US",
            "custom_merge_fields": {
                "fav color": "silver",
                "sport": "tennis",
                "os": "Windows 95"
            },
            "timezone": "US\/Mountain",
            "status": "REPLIED",
            "interest": "POSITIVE",
            "emails_sent": 2,
            "created_at": 1579888424
        }
    ]
}

HTTP Request

GET api/v1/campaigns/{campaign_id}/contacts

URL Parameters

Parameter Status Description
campaign_id required The id of a campaign.

Query Parameters

Parameter Status Description
status optional Get contacts of a specific status. Can be one of: ok, replied, unsubscribed, bounced, autoreplied, missing-data, stopped.
interest optional Get contacts that have a specific interest level. Can be one of: unmarked, positive, neutral, negative.
emails_sent optional Get contacts that have been contacted a specific number of times.
limit optional The number of objects to return. Defaults to 100. Maximum 500.
offset optional The zero-based offset for the default object sorting.

Search for contacts


Requires authentication Find contacts of a specific email address.

Example request:

curl -X GET \
    -G "https://app.wavo.co/api/v1/contacts?email=aditya.kohler%40example.org&client_id=a83445df46as5432mga&campaign_id=fkjtf4390kfgu8903nsk" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Authorization: Bearer {token}"
const url = new URL(
    "https://app.wavo.co/api/v1/contacts"
);

let params = {
    "email": "aditya.kohler@example.org",
    "client_id": "a83445df46as5432mga",
    "campaign_id": "fkjtf4390kfgu8903nsk",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": "Bearer {token}",
};

fetch(url, {
    method: "GET",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));

$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://app.wavo.co/api/v1/contacts',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Authorization' => 'Bearer {token}',
        ],
        'query' => [
            'email' => 'aditya.kohler@example.org',
            'client_id' => 'a83445df46as5432mga',
            'campaign_id' => 'fkjtf4390kfgu8903nsk',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://app.wavo.co/api/v1/contacts'
params = {
  'email': 'aditya.kohler@example.org',
  'client_id': 'a83445df46as5432mga',
  'campaign_id': 'fkjtf4390kfgu8903nsk'
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {token}'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()

Example response (200):

{
    "data": [
        {
            "id": "we52o4rv130mz1qxyzk8pmljd",
            "email": "aditya.kohler@example.org",
            "first_name": "Aditya",
            "last_name": "Kohler",
            "company": "Gerlach, Ziemann and Reilly",
            "industry": "Nonprofit Organization Management",
            "website": "kunde.com",
            "title": "Ms.",
            "phone": "219-959-5166",
            "address": "41164 Osvaldo Row",
            "city": "Baileyborough",
            "state": "New Hampshire",
            "country": "US",
            "custom_merge_fields": {
                "fav color": "purple",
                "sport": "running",
                "os": "Windows NT 5.0"
            },
            "timezone": "US\/Mountain",
            "status": "OK",
            "interest": null,
            "emails_sent": 0,
            "created_at": 1579888600,
            "campaign": {
                "id": "fkjtf4390kfgu8903nsk",
                "name": "Grady-Runolfsson 16",
                "timezone": "US\/Mountain",
                "status": "DRAFT",
                "created_at": 1579888600,
                "client": {
                    "id": "a83445df46as5432mga",
                    "name": "Grady-Runolfsson",
                    "created_at": 1579888600
                }
            }
        }
    ]
}

HTTP Request

GET api/v1/contacts

Query Parameters

Parameter Status Description
email required The email address we are searching for.
client_id optional The id of a client.
campaign_id optional The id of a campaign.

Email Messages

APIs for managing email messages.

Display a listing of a campaign's replies.


Requires authentication Return all email message replies of a campaign.

Example request:

curl -X GET \
    -G "https://app.wavo.co/api/v1/campaigns/fkjtf4390kfgu8903nsk/replies?limit=2&offset=0" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Authorization: Bearer {token}"
const url = new URL(
    "https://app.wavo.co/api/v1/campaigns/fkjtf4390kfgu8903nsk/replies"
);

let params = {
    "limit": "2",
    "offset": "0",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": "Bearer {token}",
};

fetch(url, {
    method: "GET",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));

$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://app.wavo.co/api/v1/campaigns/fkjtf4390kfgu8903nsk/replies',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Authorization' => 'Bearer {token}',
        ],
        'query' => [
            'limit' => '2',
            'offset' => '0',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://app.wavo.co/api/v1/campaigns/fkjtf4390kfgu8903nsk/replies'
params = {
  'limit': '2',
  'offset': '0'
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {token}'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()

Example response (200):

{
    "data": [
        {
            "id": "2dpkq21yvjn4r530y56gzwlm3e08ox",
            "thread_id": "l12zpqxdn36mwrog08e5mwrkj",
            "contact_id": "83jm7zlgve0nlzq4d15orxywn",
            "from_email": "john.jacksom@example.com",
            "to_email": "corwin.velda@example.com",
            "from_name": "John Jackson",
            "to_name": "Corwin Velda",
            "submitted_at": 1597066351,
            "created_at": 1597066376,
            "subject": "Re: Test message subject",
            "snippet": "Short Message Body...",
            "message_body": "Message body text...",
            "message_raw": "Raw Message text with html tags..."
        },
        {
            "id": "66lgem812pz0w7y6g9yoj3nr4kvqdx",
            "thread_id": "rdle34wnjy94qj6m178p0gz5v",
            "contact_id": "8j5orm17lnqgpkqvg9pk4z3ew",
            "from_email": "ella.jones@example.com",
            "to_email": "corwin.velda@example.com",
            "from_name": "Ella Jones",
            "to_name": "Corwin Velda",
            "submitted_at": 1597066351,
            "created_at": 1597066376,
            "subject": "Re: Test message subject",
            "snippet": "Short Message Body...",
            "message_body": "Message body text...",
            "message_raw": "Raw Message text with html tags..."
        }
    ]
}

HTTP Request

GET api/v1/campaigns/{campaign_id}/replies

URL Parameters

Parameter Status Description
campaign_id required The id of a campaign.

Query Parameters

Parameter Status Description
limit optional The number of objects to return. Defaults to 10. Maximum 20.
offset optional The zero-based offset for the default object sorting.

Display a listing of a contact's replies.


Requires authentication Return all email message replies of a contact.

Example request:

curl -X GET \
    -G "https://app.wavo.co/api/v1/contacts/83jm7zlgve0nlzq4d15orxywn/replies" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Authorization: Bearer {token}"
const url = new URL(
    "https://app.wavo.co/api/v1/contacts/83jm7zlgve0nlzq4d15orxywn/replies"
);

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": "Bearer {token}",
};

fetch(url, {
    method: "GET",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));

$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://app.wavo.co/api/v1/contacts/83jm7zlgve0nlzq4d15orxywn/replies',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Authorization' => 'Bearer {token}',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://app.wavo.co/api/v1/contacts/83jm7zlgve0nlzq4d15orxywn/replies'
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {token}'
}
response = requests.request('GET', url, headers=headers)
response.json()

Example response (200):

{
    "data": [
        {
            "id": "2dpkq21yvjn4r530y56gzwlm3e08ox",
            "thread_id": "l12zpqxdn36mwrog08e5mwrkj",
            "contact_id": "83jm7zlgve0nlzq4d15orxywn",
            "from_email": "john.jacksom@example.com",
            "to_email": "corwin.velda@example.com",
            "from_name": "John Jackson",
            "to_name": "Corwin Velda",
            "submitted_at": 1597066351,
            "created_at": 1597066376,
            "subject": "Re: Test message subject",
            "snippet": "Short Message Body...",
            "message_body": "Message body text...",
            "message_raw": "Raw Message text with html tags..."
        },
        {
            "id": "rgr8yd4lkzvp05dw29nxe1w62m3qoj",
            "thread_id": "l12zpqxdn36mwrog08e5mwrkj",
            "contact_id": "83jm7zlgve0nlzq4d15orxywn",
            "from_email": "john.jacksom@example.com",
            "to_email": "corwin.velda@example.com",
            "from_name": "John Jackson",
            "to_name": "Corwin Velda",
            "submitted_at": 1597066499,
            "created_at": 1597066528,
            "subject": "Re: Test message subject",
            "snippet": "Short Message Body...",
            "message_body": "Message body text...",
            "message_raw": "Raw Message text with html tags..."
        }
    ]
}

HTTP Request

GET api/v1/contacts/{contact_id}/replies

URL Parameters

Parameter Status Description
contact_id required The id of a contact.

Display an email thread.


Requires authentication Return an email thread with all its messages.

Example request:

curl -X GET \
    -G "https://app.wavo.co/api/v1/email-threads/rdle34wnjy94qj6m178p0gz5v" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Authorization: Bearer {token}"
const url = new URL(
    "https://app.wavo.co/api/v1/email-threads/rdle34wnjy94qj6m178p0gz5v"
);

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": "Bearer {token}",
};

fetch(url, {
    method: "GET",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));

$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://app.wavo.co/api/v1/email-threads/rdle34wnjy94qj6m178p0gz5v',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Authorization' => 'Bearer {token}',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://app.wavo.co/api/v1/email-threads/rdle34wnjy94qj6m178p0gz5v'
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {token}'
}
response = requests.request('GET', url, headers=headers)
response.json()

Example response (200):

{
    "data": {
        "id": "rdle34wnjy94qj6m178p0gz5v",
        "campaign_id": "jxv8qkeml4ml1g69y3w5",
        "contact_id": "8j5orm17lnqgpkqvg9pk4z3ew",
        "email_messages": [
            {
                "id": "2dpkq21yvjn4r530y56gzwlm3e08ox",
                "thread_id": "l12zpqxdn36mwrog08e5mwrkj",
                "contact_id": "83jm7zlgve0nlzq4d15orxywn",
                "from_email": "corwin.velda@example.com",
                "to_email": "ella.jones@example.com",
                "from_name": "Corwin Velda",
                "to_name": "Ella Jones",
                "submitted_at": 1597066219,
                "created_at": 1597066208,
                "subject": "Test message subject",
                "snippet": "Short Message Body...",
                "message_body": "Message body text...",
                "message_raw": "Raw Message text with html tags..."
            },
            {
                "id": "66lgem812pz0w7y6g9yoj3nr4kvqdx",
                "thread_id": "rdle34wnjy94qj6m178p0gz5v",
                "contact_id": "8j5orm17lnqgpkqvg9pk4z3ew",
                "from_email": "ella.jones@example.com",
                "to_email": "corwin.velda@example.com",
                "from_name": "Ella Jones",
                "to_name": "Corwin Velda",
                "submitted_at": 1597066351,
                "created_at": 1597066376,
                "subject": "Re: Test message subject",
                "snippet": "Short Message Body...",
                "message_body": "Message body text...",
                "message_raw": "Raw Message text with html tags..."
            }
        ]
    }
}

HTTP Request

GET api/v1/email-threads/{email_thread_id}

URL Parameters

Parameter Status Description
email_thread_id required The id of the email thread.

Suppression

APIs for managing suppression list.

Add new email address to suppression list


Requires authentication This will add new email addresses to a client's suppression list. Any contacts matching these emails, will be set as unsubscribed.

Example request:

curl -X POST \
    "https://app.wavo.co/api/v1/suppressions/emails" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Authorization: Bearer {token}" \
    -d '{"client_id":"a83445df46as5432mga","emails":["alicia.hammes@example.com", "douglas.herman@example.com"]}'
const url = new URL(
    "https://app.wavo.co/api/v1/suppressions/emails"
);

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": "Bearer {token}",
};

let body = {
    "client_id": "a83445df46as5432mga",
    "emails": [
        "alicia.hammes@example.com", 
        "douglas.herman@example.com"
    ]
}

fetch(url, {
    method: "POST",
    headers: headers,
    body: body
})
    .then(response => response.json())
    .then(json => console.log(json));

$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://app.wavo.co/api/v1/suppressions/emails',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Authorization' => 'Bearer {token}',
        ],
        'json' => [
            'client_id' => 'a83445df46as5432mga',
            'emails' => [
                "alicia.hammes@example.com",
                "douglas.herman@example.com"
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://app.wavo.co/api/v1/suppressions/emails'
payload = {
    "client_id": "a83445df46as5432mga",
    "emails": [
        "alicia.hammes@example.com",
        "douglas.herman@example.com"
    ]
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {token}'
}
response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Example response (201):

{
    "data": [
        "alicia.hammes@example.com",
        "douglas.herman@example.com"
    ]
}

HTTP Request

POST api/v1/suppressions/emails

Body Parameters

Parameter Type Status Description
client_id string required The id of a client.
emails[] array required An array of emails that should be put on client's suppression list.

Add new domain address to suppression list


Requires authentication This will add new domains to a client's suppression list. Any contacts matching these domains, will be set as unsubscribed.

Example request:

curl -X POST \
    "https://app.wavo.co/api/v1/suppressions/domains" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Authorization: Bearer {token}" \
    -d '{"client_id":"a83445df46as5432mga","domains":["domain1.com", "domain2.com"]}'
const url = new URL(
    "https://app.wavo.co/api/v1/suppressions/domains"
);

let headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": "Bearer {token}",
};

let body = {
    "client_id": "a83445df46as5432mga",
    "domains": [
        "domain1.com",
        "domain2.com"
    ]
}

fetch(url, {
    method: "POST",
    headers: headers,
    body: body
})
    .then(response => response.json())
    .then(json => console.log(json));

$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://app.wavo.co/api/v1/suppressions/domains',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'Authorization' => 'Bearer {token}',
        ],
        'json' => [
            'client_id' => 'a83445df46as5432mga',
            'domains' => [
                "domain1.com",
                "domain2.com"
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import requests
import json

url = 'https://app.wavo.co/api/v1/suppressions/domains'
payload = {
    "client_id": "a83445df46as5432mga",
    "domains": [
        "domain1.com",
        "domain2.com"
    ]
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {token}'
}
response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Example response (201):

{
    "data": [
        "domain1.com",
        "domain2.com"
    ]
}

HTTP Request

POST api/v1/suppressions/domains

Body Parameters

Parameter Type Status Description
client_id string required The id of a client.
domains[] array required An array of domains that should be put on client's suppression list.