NAV
javascript

Welcome

Welcome to Happy Grasshopper's API reference!

This page will help you get started with our API. We hope to get you up and running as soon as possible!

Happy Grasshopper provides this simple REST API to allows developers to integrate their applications with ours.

Please keep in mind that our API is in active development and and new features will be added periodically while keeping backwards compatible.

API Endpoint

Our API Endpoint URLs have the following structure:

https://api.happygrasshopper.com/v2/resource/{variable}

Authentication

Every Happy Grasshopper user has the ability to generate and revoke API keys (Personal Access Tokens) inside their account. These keys can be generated in the V2 API section of your Account Settings under the Integrations tab.

The generated api key is required in each request as an Authorization header.

Example: Authorization: Bearer <api_key>

The Happy Grasshopper API is available via HTTPS only. This ensures that all data transmitted is encrypted.

API keys allow their bearer much of the same functionality as a user's login credentials, therefore API keys should be handled as securely as passwords.

Authorization

API keys have the same access levels as the user whom the key belongs to.

Happy Grasshopper provides 3 access levels:

Requests and Responses

Happy Grasshopper API uses JSON encoded data for it's requests and responses. We recommend sending the Content-Type: application/json header with all requests.

Example POST/PUT Request: {"first_name": "Gus",}

Example Response: {"id": 1, "first_name": "Gus"}

Request Context

By default, API requests are assumed to be in the context of the user who owns the API key. However, Admin and Manager users have the ability to perform all resource actions in the context of other users. A Manager can only access it's team's users. Admins have access to all users.

The context query parameter is used to apply context to requests. The value of the context parameter can either be a user's id, email or an identifier mapped to the request's API key.

Example GET: /v2/users?context=<user_identifier>

Or, if you would like to include it in a POST/PUT request body...

Example POST/PUT: {"context": <user_identifier>, ...}

This will scope a request to the identified user.

Please keep in mind that you can only make requests in the context of users whom you have permission to access.

Dates

The date format used in all date and time responses is yyyy-mm-dd hh:mm:ss. Please note that dates and times are always expressed in UTC.

Response Codes

On success for newly created resources, the response code will be a 201 Created. On all other responses, the response code should be a 200 OK response.

Any other response code is most likely an error.

Pagination

Example:

{
   "total": 50,
   "per_page": 25,
   "current_page": 1,
   "last_page": 2,
   "next_page_url": "https://api.happygrasshopper.com/v2/resource?page=2",
   "prev_page_url": null,
   "from": 1,
   "to": 25,
   "data":[
        {
            // Resource Object
        },
        {
            // Resource Object
        }
   ]
}

Some endpoints return a paginated collection to prevent overloading the client with potentially hundreds of resources in a single response. Paginated responses are returned in ascending order by

An example of a paginated response object is provided in the examples section of this page.

Endpoints that return paginated response are paged using the page query parameter.

Example GET: /v2/resource?page=2

By default, 25 resources are returned per page. You can increase the number of resources returned using the per_page query parameter.

Example GET: /v2/resource?per_page=10

A paginated response structure is:

Support

Please feel free to reach out to us at support@happygrasshopper.com with any questions you may have.

We're always more than happy to help!

Audiences

Index

Request:

var settings = {
    "url": "https://api.happygrasshopper.com/v2/audiences",
    "method": "GET",
    "headers": {
        "Accept": "application/json",
        "Authorization":"Bearer <api_key>"
    }
}

$.ajax(settings).done(function (response) {
    console.log(response);
});

Response: The user object and all audiences available to that user.

{
    "user": {
        "id": 1,
        "email": "gus@happygrasshopper.com",
        "first_name": "Gus",
        "last_name": "Grasshopper",
        "phone": "1234567890",
        "created": "2016-06-13 13:32:43",
        "modified": "2017-11-05 01:05:51"
    },
    "audiences": [
        {
            "id": 1,
            "name": "Sphere",
            "description": "Sphere",
            "first_touch_subject": "Quick question for you",
            "allow_first_touch": true,
            "first_touch_message": "I just added you to my address book. Would you mind replying to this email so that I know that I entered your contact information correctly? I want to make sure we stay in touch.<br \/>\n<br \/>\nHave an amazing day!",
            "created": "2016-11-14 10:35:23",
            "modified": "2016-11-14 15:59:03"
        },
        ...
    ]
}

Display a collection of audiences.

HTTP Request

GET v2/audiences

HEAD v2/audiences

Query Parameters

Parameter Status Description
context optional The identifier of the user who's audiences you would like returned. See Request Context.

Contact Tags

Index

Request:

var settings = {
    "url": "https://api.happygrasshopper.com/v2/contacts/{contact}/tags",
    "method": "GET",
    "headers": {
        "Accept": "application/json",
        "Authorization":"Bearer <api_key>"
    }
}

$.ajax(settings).done(function (response) {
    console.log(response);
});

Response: The contact object and all tags attached to the contact.

{
    "contact": {
        // Contact Object
    },
    "tags": [
        // Contact's Tags
        {
            "id": 1,
            "tag": "Tag 1",
            "email": "randomstring1@go.happygrasshopper.com",
            "type": "team",
            "created": "2016-02-08 21:35:07",
            "modified": "2016-02-08 21:35:07"
        },
        {
            "id": 2,
            "tag": "Tag 2",
            "email": "randomstring2@go.happygrasshopper.com",
            "type": "team",
            "created": "2017-11-06 18:12:28",
            "modified": "2017-11-06 18:12:28"
        },
        ...
    ]
}

Display a collection of a specified contact's tags.

HTTP Request

GET v2/contacts/{contact}/tags

HEAD v2/contacts/{contact}/tags

Route Variable

Variable Description
contact The contact's id or email. Remember - Route variables and query parameters should be url encoded.

Query Parameters

Parameter Status Description
context optional The identifier of the user who owns the contact. See Request Context.

Create

Request:

var settings = {
    "url": "https://api.happygrasshopper.com/v2/contacts/{contact}/tags",
    "method": "POST",
    "data": {
        "tags": "Happy,grasshopper, \"Remember, stay happy!\""
    },
    "headers": {
        "Accept": "application/json",
        "Content-Type":"application/json",
        "Authorization":"Bearer <api_key>"
    }
}

$.ajax(settings).done(function (response) {
    console.log(response);
});

Response: The contact object and the newly added tags.

{
    "contact": {
        // Contact Object
    },
    "tags": [ 
        // Newly Added Tags
        {
            "id": 1,
            "tag": "Happy",
            "email": "randomstring1@go.happygrasshopper.com",
            "type": "default",
            "created": "2017-11-07 18:49:19",
            "modified": "2017-11-07 18:49:19"
        },
        {
            "id": 2,
            "tag": "grasshopper",
            "email": "randomstring2@go.happygrasshopper.com",
            "type": "default",
            "created": "2017-11-07 18:49:19",
            "modified": "2017-11-07 18:49:19"
        },
        {
            "id": 3,
            "tag": "Remember, stay happy!",
            "email": "randomstring3@go.happygrasshopper.com",
            "type": "default",
            "created": "2017-11-07 18:49:19",
            "modified": "2017-11-07 18:49:19"
        }
    ]
}

Add a tag to a contact.

HTTP Request

POST v2/contacts/{contact}/tags

Route Variable

Variable Description
contact The contact's id or email. Remember - Route variables and query parameters should be url encoded.

Form Data

Parameter Type Status Description
tags string required A comma delimited string of tags. A tag with one or more commas in it's name should be enclosed in quotes.
type string optional For manager and team users, tags are created with a type of "team" by default. To create individual tags for managers or team users, "default" should be used as the type parameter.
context string optional The identifier of the user who owns the contact. See Request Context.

Delete

Request:

var settings = {
    "url": "https://api.happygrasshopper.com/v2/contacts/{contact}/tags/{tag?}",
    "method": "DELETE",
    "data": {
        "tags": "Happy, \"Remember, stay happy!\""
    },
    "headers": {
        "Accept": "application/json",
        "Content-Type":"application/json",
        "Authorization":"Bearer <api_key>"
    }
}

$.ajax(settings).done(function (response) {
    console.log(response);
});

Response: Requested tags and the status of the delete.

{
    "tags": [
        {
            "tag": "Happy",
            "deleted": true
        },
        {
            "tag": "Remember, stay happy!",
            "deleted": true
        }
    ]
}

Remove a tag from a contact.

HTTP Request

DELETE v2/contacts/{contact}/tags/{tag?}

Route Variable

Variable Description
contact The contact's id or email. Remember - Route variables and query parameters should be url encoded.
tag The id of a tag. This optional route variable should only be used in instances where you intend to detach a single tag from a contact, and you know that tag's id.

Form Data

Parameter Type Status Description
tags string optional A comma delimited string of tags. A tag with one or more commas in it's name should be enclosed in quotes.
context string optional The identifier of the user who owns the contact. See Request Context.

Contacts

Index

Request:

var settings = {
    "url": "https://api.happygrasshopper.com/v2/contacts",
    "method": "GET",
    "headers": {
        "Accept": "application/json",
        "Authorization":"Bearer <api_key>"
    }
}

$.ajax(settings).done(function (response) {
    console.log(response);
});

Response: A paginated collection of user contacts.

{
    "current_page": 1,
    "data": [
        {
            "id": 1,
            "unsubscribe": false,
            "invalid": false,
            "unsubscribe_date": null,
            "deleted": false,
            "email": "gus@happygrasshopper.com",
            "first_name": "Gus",
            "last_name": "Grasshopper",
            "phone": "1234567890",
            "created": "2017-02-22 02:55:24",
            "modified": "2017-09-27 01:21:17",
            "tags": [
                {
                    "id": 1,
                    "tag": "Happy Tag",
                    "email": "randomstring@go.happygrasshopper.com",
                    "type": "default",
                    "created": "2016-06-13 14:09:33",
                    "modified": "2016-06-13 14:09:33"
                }
            ],
            "user": {
                "id": 1,
                "email": "gus@happygrasshopper.com",
                "first_name": "Gus",
                "last_name": "Grasshopper",
                "phone": "1234567890",
                "created": "2016-06-13 13:32:43",
                "modified": "2017-11-05 01:05:51"
            },
            "audience": {
                "id": 1,
                "name": "Sphere",
                "description": "Sphere",
                "first_touch_subject": "Quick question for you",
                "allow_first_touch": true,
                "first_touch_message": "I just added you to my address book. Would you mind replying to this email so that I know that I entered your contact information correctly? I want to make sure we stay in touch.<br \/>\n<br \/>\nHave an amazing day!",
                "created": "2016-11-14 10:35:23",
                "modified": "2016-11-14 15:59:03"
            },
            "notes": [
                {
                    "id": 1,
                    "note": "This contact is happy!",
                    "date_time": "2017-10-20 14:20:37",
                    "created": "2017-10-20 14:20:37",
                    "modified": "2017-10-20 14:20:37"
                }
            ]
        },
        ...
    ],
    "from": 1,
    "last_page": 2,
    "next_page_url": "https://api.happygrasshopper.com/v2/contacts?page=2",
    "path": "https://api.happygrasshopper.com/v2/contacts",
    "per_page": 25,
    "prev_page_url": null,
    "to": 25,
    "total": 50
}

Display a paginated collection of contacts.

HTTP Request

GET v2/contacts

HEAD v2/contacts

Query Parameters

Parameter Status Description
email optional Limit results to only contacts with the specified email.
first_name optional Limit results to only contacts with the specified first name.
last_name optional Limit results to only contacts with the specified last name.
phone optional Limit results to only contacts with the specified phone number.
per_page optional The number of contacts returned per page.
created_before optional Limit results to only contacts created before a specified url encoded date.
Format: yyyy-mm-dd or yyyy-mm-dd hh:mm:ss.
created_after optional Limit results to only contacts created after a specified url encoded date.
Format: yyyy-mm-dd or yyyy-mm-dd hh:mm:ss.
updated_before optional Limit results to only contacts updated before a specified url encoded date.
Format: yyyy-mm-dd or yyyy-mm-dd hh:mm:ss.
updated_after optional Limit results to only contacts updated after a specified url encoded date.
Format: yyyy-mm-dd or yyyy-mm-dd hh:mm:ss.
context optional The identifier of the user whose contacts should be displayed. See Request Context.

Create

Create a contact.

Request:

var settings = {
    "url": "https://api.happygrasshopper.com/v2/contacts",
    "method": "POST",
    "data": {
        "email": "gus@happygrasshopper.com",
        "first_name": "Gus",
        "last_name": "Grasshopper",
        "phone": "1234567890",
        "audience": "Sphere",
        "unsubscribe": false,
        "tags": "Happy Tag",
        "notes": "This contact is happy!"
    },
    "headers": {
        "Accept": "application/json",
        "Content-Type":"application/json",
        "Authorization":"Bearer <api_key>"
    }
}

$.ajax(settings).done(function (response) {
    console.log(response);
});

Response: The newly created contact.

{
    "id": 1,
    "unsubscribe": false,
    "invalid": false,
    "unsubscribe_date": null,
    "deleted": false,
    "email": "gus@happygrasshopper.com",
    "first_name": "Gus",
    "last_name": "Grasshopper",
    "phone": "1234567890",
    "created": "2017-02-22 02:55:24",
    "modified": "2017-09-27 01:21:17",
    "tags": [
        {
            "id": 1,
            "tag": "Happy Tag",
            "email": "randomstring@go.happygrasshopper.com",
            "type": "default",
            "created": "2016-06-13 14:09:33",
            "modified": "2016-06-13 14:09:33"
        }
    ],
    "user": {
        "id": 1,
        "email": "gus@happygrasshopper.com",
        "first_name": "Gus",
        "last_name": "Grasshopper",
        "phone": "1234567890",
        "created": "2016-06-13 13:32:43",
        "modified": "2017-11-05 01:05:51"
    },
    "audience": {
        "id": 1,
        "name": "Sphere",
        "description": "Sphere",
        "first_touch_subject": "Quick question for you",
        "allow_first_touch": true,
        "first_touch_message": "I just added you to my address book. Would you mind replying to this email so that I know that I entered your contact information correctly? I want to make sure we stay in touch.<br \/>\n<br \/>\nHave an amazing day!",
        "created": "2016-11-14 10:35:23",
        "modified": "2016-11-14 15:59:03"
    },
    "notes": [
        {
            "id": 1,
            "note": "This contact is happy!",
            "date_time": "2017-10-20 14:20:37",
            "created": "2017-10-20 14:20:37",
            "modified": "2017-10-20 14:20:37"
        }
    ]
}

HTTP Request

POST v2/contacts

Form Data

Parameter Type Status Description
email email required The contact's email address.
Maximum: 255 characters
first_name string optional The contact's first name.
Maximum: 255 characters
last_name string optional The contact's last name.
Maximum: 255 characters
phone string optional The contact's phone number.
audience string optional The contact's audience. Should be one of the names of the audiences available to the user the contact is being created for.
Default: Uncategorized
unsubscribe boolean optional Only use true if the contact should be created as unsubscribed.
Default: false
tags string optional A comma delimited string of tags. A tag with one or more commas in it's name should be enclosed in quotes.
notes string optional A note that should be added to the contact.
context string optional The identifier of the user for whom the contact will be created. See Request Context.

Read

Request:

var settings = {
    "url": "https://api.happygrasshopper.com/v2/contacts/{contact}",
    "method": "GET",
    "headers": {
        "Accept": "application/json",
        "Authorization":"Bearer <api_key>"
    }
}

$.ajax(settings).done(function (response) {
    console.log(response);
});

Response: The requested contact.

{
    "id": 1,
    "unsubscribe": false,
    "invalid": false,
    "unsubscribe_date": null,
    "deleted": false,
    "email": "gus@happygrasshopper.com",
    "first_name": "Gus",
    "last_name": "Grasshopper",
    "phone": "1234567890",
    "created": "2017-02-22 02:55:24",
    "modified": "2017-09-27 01:21:17",
    "tags": [
        {
            "id": 1,
            "tag": "Happy Tag",
            "email": "randomstring@go.happygrasshopper.com",
            "type": "default",
            "created": "2016-06-13 14:09:33",
            "modified": "2016-06-13 14:09:33"
        }
    ],
    "user": {
        "id": 1,
        "email": "gus@happygrasshopper.com",
        "first_name": "Gus",
        "last_name": "Grasshopper",
        "phone": "1234567890",
        "created": "2016-06-13 13:32:43",
        "modified": "2017-11-05 01:05:51"
    },
    "audience": {
        "id": 1,
        "name": "Sphere",
        "description": "Sphere",
        "first_touch_subject": "Quick question for you",
        "allow_first_touch": true,
        "first_touch_message": "I just added you to my address book. Would you mind replying to this email so that I know that I entered your contact information correctly? I want to make sure we stay in touch.<br \/>\n<br \/>\nHave an amazing day!",
        "created": "2016-11-14 10:35:23",
        "modified": "2016-11-14 15:59:03"
    },
    "notes": [
        {
            "id": 1,
            "note": "This contact is happy!",
            "date_time": "2017-10-20 14:20:37",
            "created": "2017-10-20 14:20:37",
            "modified": "2017-10-20 14:20:37"
        }
    ]
}

Display a specified contact.

HTTP Request

GET v2/contacts/{contact}

HEAD v2/contacts/{contact}

Route Variable

Variable Description
contact The contact's id or email. Remember - Route variables and query parameters should be url encoded.

Query Parameters

Parameter Status Description
context optional The identifier of the user who owns the contact. See Request Context.

Update

Update a specified contact.

Request:

var settings = {
    "url": "https://api.happygrasshopper.com/v2/contacts/{contact}",
    "method": "PUT",
    "data": {
        "email": "gus.updated@happygrasshopper.com",
        "first_name": "Gustav",
        "last_name": "Frog",
        "phone": "1238675309",
        "audience": "Uncategorized",
        "unsubscribe": true,
        "tags": "Happier Tag",
        "notes": "This contact is even happier!"
    },
    "headers": {
        "Accept": "application/json",
        "Content-Type":"application/json",
        "Authorization":"Bearer <api_key>"
    }
}

$.ajax(settings).done(function (response) {
    console.log(response);
});
{
    "id": 1,
    "unsubscribe": true,
    "invalid": true,
    "unsubscribe_date": "2017-09-27 01:21:17",
    "deleted": false,
    "email": "gus.updated@happygrasshopper.com",
    "first_name": "Gustav",
    "last_name": "Frog",
    "phone": "1238675309",
    "created": "2017-02-22 02:55:24",
    "modified": "2017-09-27 01:21:17",
    "tags": [
        {
            "id": 1,
            "tag": "Happy Tag",
            "email": "randomstring@go.happygrasshopper.com",
            "type": "default",
            "created": "2016-06-13 14:09:33",
            "modified": "2016-06-13 14:09:33"
        },
        {
            "id": 2,
            "tag": "Happier Tag",
            "email": "randomstring@go.happygrasshopper.com",
            "type": "default",
            "created": "2016-06-13 14:09:33",
            "modified": "2016-06-13 14:09:33"
        }
    ],
    "user": {
        "id": 1,
        "email": "gus@happygrasshopper.com",
        "first_name": "Gus",
        "last_name": "Grasshopper",
        "phone": "1234567890",
        "created": "2016-06-13 13:32:43",
        "modified": "2017-11-05 01:05:51"
    },
    "audience": {
        "id": 7,
        "name": "Uncategorized",
        "description": "Uncategorized",
        "first_touch_subject": "",
        "allow_first_touch": false,
        "first_touch_message": "",
        "created": "2016-11-14 10:35:23",
        "modified": "2016-11-14 15:59:03"
    },
    "notes": [
        {
            "id": 1,
            "note": "This contact is happy!",
            "date_time": "2017-10-20 14:20:37",
            "created": "2017-10-20 14:20:37",
            "modified": "2017-10-20 14:20:37"
        },
        {
            "id": 1,
            "note": "This contact is even happier!",
            "date_time": "2017-10-21 14:20:37",
            "created": "2017-10-21 14:20:37",
            "modified": "2017-10-21 14:20:37"
        }
    ]
}

HTTP Request

PUT v2/contacts/{contact}

Route Variable

Variable Description
contact The contact's id or email. Remember - Route variables and query parameters should be url encoded.

Form Data

Parameter Type Status Description
email email optional The contact's email address.
Maximum: 255 characters
first_name string optional The contact's first name.
Maximum: 255 characters
last_name string optional The contact's last name.
Maximum: 255 characters
phone string optional The contact's phone number.
audience string optional The contact's audience. Should be one of the names of the audiences available to the user the contact belongs to.
Default: Uncategorized
unsubscribe boolean optional Only true if the contact should be unsubscribed.
Default: false
tags string optional A comma delimited string of tags that will be added to the contact. A tag with one or more commas in it's name should be enclosed in quotes.
notes string optional A note that should be added to the contact.
user string optional This parameter can only be used by users who have the ability to update the user who owns a contact (Admins and Managers).
context string optional The identifier of the user for whom the contact will be created. See Request Context.

Delete

Request:

var settings = {
    "url": "https://api.happygrasshopper.com/v2/contacts/{contact}",
    "method": "DELETE",
    "headers": {
        "Accept": "application/json",
        "Content-Type":"application/json",
        "Authorization":"Bearer <api_key>"
    }
}

$.ajax(settings).done(function (response) {
    console.log(response);
});

Response: true if the contact was successfully deleted.

{
    "success": true
}

Delete a specified contact.

HTTP Request

DELETE v2/contacts/{contact}

Route Variable

Variable Description
contact The contact's id or email. Remember - Route variables and query parameters should be url encoded.

Query Parameters

Parameter Status Description
context optional The identifier of the user who owns the contact. See Request Context.

Reports

Index

Request:

var settings = {
    "url": "https://api.happygrasshopper.com/v2/reports",
    "method": "GET",
    "headers": {
        "Accept": "application/json",
        "Authorization":"Bearer <api_key>"
    }
}

$.ajax(settings).done(function (response) {
    console.log(response);
});

Response: A paginated collection of user's reports.

{
    "current_page": 1,
    "data": [
        {
            "_id": "59e8cc0435713c211e5cbb12",
            "user_id": 75723,
            "contact_id": 8696044,
            "email": "Gus-no-fuss@rustedtruck.com",
            "message_id": "kit_030270ce-4e7a-4c3e-8474-c79dfaccd9d5",
            "type": "KIT",
            "type_id": 248,
            "provider": "happygrasshopper",
            "provider_message_id": "KIT:248",
            "provider_event_id": "6d0ea641-e032-4859-b539-f9068ff8744d",
            "event": 11,
            "event_name": "sent",
            "count": 1,
            "additional_data": {
                "kit_message_id": 1729,
                "kit_queue_id": 131165,
                "kit_sent_list_id": 248,
                "user_id": 75723,
                "send_once": true,
                "send_by_type": "Audience",
                "audience_id": 1,
                "send_to_all": false,
                "subject": "send once 24 sept",
                "signature_id": 14814,
                "send": "Schedule",
                "send_date": "2017-10-19",
                "send_time": "16:00:00",
                "verification_required": false,
                "verified": false,
                "verification_date": null,
                "alert_required": true,
                "alert_sent": "2017-10-16 07:00:04"
            },
            "timestamp": "2017-10-19 16:00:03",
            "created_at": "2017-10-19 16:00:03",
            "updated_at": "2017-10-19 16:00:03"
        },
    ...
    ],
    "from": 1,
    "last_page": 1,
    "next_page_url": null,
    "path": "https://api.happygrasshopper.com/v2/reports",
    "per_page": 25,
    "prev_page_url": null,
    "to": 23,
    "total": 23
}

Display a paginated collection of reports.

HTTP Request

GET v2/reports

HEAD v2/reports

Query Parameters

Parameter Status Description
contact_id optional id of contact who performed the event.
email optional The email of the contact who performed the report event.
type optional Type of report.
Options: BLAST, KIT, NEWSLETTER, FIRSTTOUCH.
type_id optional The id of the type of report.
event_name optional Name of the event that was performed by the contact.
Options: deferred, delivered, dropped, processed, click, open, spamreport, unsubscribe, reply, sent, soft_bounce, hard_bounce.
per_page optional The number of reports returned per page.
created_before optional Limit results to only reports created before a specified url encoded date.
Format: yyyy-mm-dd or yyyy-mm-dd hh:mm:ss.
created_after optional Limit results to only reports created after a specified url encoded date.
Format: yyyy-mm-dd or yyyy-mm-dd hh:mm:ss.
updated_before optional Limit results to only reports updated before a specified url encoded date.
Format: yyyy-mm-dd or yyyy-mm-dd hh:mm:ss.
updated_after optional Limit results to only reports updated after a specified url encoded date.
Format: yyyy-mm-dd or yyyy-mm-dd hh:mm:ss.
context optional The identifier of the user whose reports should be displayed. See Request Context.

Tags

Index

Display a paginated collection of tags.

Request:

var settings = {
    "url": "https://api.happygrasshopper.com/v2/tags",
    "method": "GET",
    "headers": {
        "Accept": "application/json",
        "Authorization":"Bearer <api_key>"
    }
}

$.ajax(settings).done(function (response) {
    console.log(response);
});

Response: Paginated collection of user's tags.

{
    "current_page": 1,
    "data": [
        {
            "id": 1,
            "tag": "Happy Tag",
            "email": "randomstring@go.happygrasshopper.com",
            "type": "default",
            "created": "2016-06-13 14:09:32",
            "modified": "2017-10-13 00:53:10"
        },
        ...
    ],
    "from": 1,
    "last_page": 1,
    "next_page_url": null,
    "path": "https://api.happygrasshopper.com/v2/tags",
    "per_page": 25,
    "prev_page_url": null,
    "to": 3,
    "total": 3
}

HTTP Request

GET v2/tags

HEAD v2/tags

Query Parameters

Parameter Status Description
tag optional Url encoded name of tag.
type optional Type of tag. For managers and team users, tags are created as team tags by default. Options: default, team.
per_page optional The number of reports returned per page.
created_before optional Limit results to only reports created before a specified url encoded date.
Format: yyyy-mm-dd or yyyy-mm-dd hh:mm:ss.
created_after optional Limit results to only reports created after a specified url encoded date.
Format: yyyy-mm-dd or yyyy-mm-dd hh:mm:ss.
updated_before optional Limit results to only reports updated before a specified url encoded date.
Format: yyyy-mm-dd or yyyy-mm-dd hh:mm:ss.
updated_after optional Limit results to only reports updated after a specified url encoded date.
Format: yyyy-mm-dd or yyyy-mm-dd hh:mm:ss.
context optional The identifier of the user whose reports should be displayed. See Request Context.

Create

Request:

var settings = {
    "url": "https://api.happygrasshopper.com/v2/tags",
    "method": "POST",
    "data": {
        "tags": "Happy,grasshopper, \"Remember, stay happy!\""
    },
    "headers": {
        "Accept": "application/json",
        "Content-Type":"application/json",
        "Authorization":"Bearer <api_key>"
    }
}

$.ajax(settings).done(function (response) {
    console.log(response);
});

Create a tag.

Response: The newly created tags.

{
    "tags": [ 
        {
            "id": 1,
            "tag": "Happy",
            "email": "randomstring1@go.happygrasshopper.com",
            "type": "default",
            "created": "2017-11-07 18:49:19",
            "modified": "2017-11-07 18:49:19"
        },
        {
            "id": 2,
            "tag": "grasshopper",
            "email": "randomstring2@go.happygrasshopper.com",
            "type": "default",
            "created": "2017-11-07 18:49:19",
            "modified": "2017-11-07 18:49:19"
        },
        {
            "id": 3,
            "tag": "Remember, stay happy!",
            "email": "randomstring3@go.happygrasshopper.com",
            "type": "default",
            "created": "2017-11-07 18:49:19",
            "modified": "2017-11-07 18:49:19"
        }
    ]
}

HTTP Request

POST v2/tags

Form Data

Parameter Type Status Description
tags string required A comma delimited string of tags. A tag with one or more commas in it's name should be enclosed in quotes.
type string optional For manager and team users, tags are created with a type of "team" by default. To create individual tags for managers or team users, "default" should be used as the type parameter.
context string optional The identifier of the user for whom the tags will be created. See Request Context.

Users

Index

Request:

var settings = {
    "url": "https://api.happygrasshopper.com/v2/users",
    "method": "GET",
    "headers": {
        "Accept": "application/json",
        "Authorization":"Bearer <api_key>"
    }
}

$.ajax(settings).done(function (response) {
    console.log(response);
});

Response: A paginated collection of users.

{
    "current_page": 1,
    "data": [
        {
            "id": 1,
            "email": "gus@happygrasshopper.com",
            "first_name": "Gus",
            "last_name": "Grasshopper",
            "phone": "1234567890",
            "created": "2016-06-13 13:32:43",
            "modified": "2017-11-05 01:05:51"
        },
        ...
    ],
    "from": 1,
    "last_page": 1,
    "next_page_url": null,
    "path": "https://api.happygrasshopper.com/v2/users",
    "per_page": 25,
    "prev_page_url": null,
    "to": 7,
    "total": 7
}

Display a paginated collection of users.

HTTP Request

GET v2/users

HEAD v2/users

Query Parameters

Parameter Status Description
email optional A user's email. This value is unique across all users.
first_name optional A user's first name.
last_name optional A user's last name.
phone optional A user's phone number.
per_page optional The number of reports returned per page.
created_before optional Limit results to only reports created before a specified url encoded date.
Format: yyyy-mm-dd or yyyy-mm-dd hh:mm:ss.
created_after optional Limit results to only reports created after a specified url encoded date.
Format: yyyy-mm-dd or yyyy-mm-dd hh:mm:ss.
updated_before optional Limit results to only reports updated before a specified url encoded date.
Format: yyyy-mm-dd or yyyy-mm-dd hh:mm:ss.
updated_after optional Limit results to only reports updated after a specified url encoded date.
Format: yyyy-mm-dd or yyyy-mm-dd hh:mm:ss.
context optional The identifier of the user whose users should be displayed. See Request Context.

Read

Request:

var settings = {
    "url": "https://api.happygrasshopper.com/v2/users/{user}",
    "method": "GET",
    "headers": {
        "Accept": "application/json",
        "Authorization":"Bearer <api_key>"
    }
}

$.ajax(settings).done(function (response) {
    console.log(response);
});

Response: The requested user.

{
    "id": 1,
    "email": "gus@happygrasshopper.com",
    "first_name": "Gus",
    "last_name": "Grasshopper",
    "phone": "1234567890",
    "created": "2016-06-13 13:32:43",
    "modified": "2017-11-05 01:05:51"
}

Display a specified user.

HTTP Request

GET v2/users/{user}

HEAD v2/users/{user}

Route Variable

Variable Description
user The user's id, email or identifier tied to the api key. Remember - Route variables and query parameters should be url encoded.

Query Parameters

Parameter Status Description
context optional The identifier of the user who manages the users. See Request Context.

Webhooks

JSON sample of webhook notification:

{
  "event_id": "f726a327-a1c7-4d72-bb2f-5fe1fa554843",
  "event": "contact_deleted",
  "payload": { // Payload contains basic info aboout the resource
    "contact": {
      "id": 1,
      "email": "gus@happygrasshopper.com"
    }
  },
  "user_id": 1,
  "occurred_at": "2017-12-14 21:13:47"
}

Webhooks notify users about events that happen in their account, removing the need to poll the API for changes. Webhooks post JSON to a specific URL when a registered event is triggered.

Supported webhook events

Event Description
blast_sent A blast message was successfully sent to your contacts.
campaign_ended A campaign has ended for a contact.
community_message_auto_scheduled A Send by Audience message has been auto scheduled for you.
community_message_ready A Send by Audience message ready to be scheduled by you.
community_message_sent A Send by Audience/Send by Message Type message has been sent to your contacts.
contact_created A new contact has been created in your account.
contact_deleted A contact has been deleted from your account.
contact_status_changed A contact has unsubscribed or set to invalid in your account.
contact_updated A contact has been updated in your account.

Index

Request:

var settings = {
    "url": "https://api.happygrasshopper.com/v2/webhooks",
    "method": "GET",
    "headers": {
        "Accept": "application/json",
        "Authorization":"Bearer <api_key>"
    }
}

$.ajax(settings).done(function (response) {
    console.log(response);
});

Response: The user object and all webhooks available to that user.

{
    "user": {
        "id": 1,
        "email": "gus@happygrasshopper.com",
        "first_name": "Gus",
        "last_name": "Grasshopper",
        "phone": "1234567890",
        "created": "2016-06-13 13:32:43",
        "modified": "2017-11-05 01:05:51"
    },
    "webhooks": [
        {
            "id": 1,
            "name": "Webhook Name",
            "events": [
                "contact_created",
                "contact_updated"
            ],
            "url": "https://requestb.in/1g8xh9b1",
            "enabled": true
        },
        ...
    ]
}

Display a listing of webhooks.

HTTP Request

GET v2/webhooks

HEAD v2/webhooks

Query Parameters

Parameter Status Description
context optional The identifier of the user whose webhooks should be displayed. See Request Context.

Create

Request:

var settings = {
    "url": "https://api.happygrasshopper.com/v2/webhooks",
    "method": "POST",
    "data": {
        "name": "Webhook Name",
        "events": ["contact_created","contact_updated"],
        "url": "https://requestb.in/1g8xh9b1",
        "enabled": true
    },
    "headers": {
        "Accept": "application/json",
        "Content-Type":"application/json",
        "Authorization":"Bearer <api_key>"
    }
}

$.ajax(settings).done(function (response) {
    console.log(response);
});

Store a newly created webhook in storage.

Response: The newly created webhook.

{
    "user": {
        "id": 1,
        "email": "gus@happygrasshopper.com",
        "first_name": "Gus",
        "last_name": "Grasshopper",
        "phone": "1234567890",
        "created": "2016-06-13 13:32:43",
        "modified": "2017-11-05 01:05:51"
    },
    "webhook": {
        "id": 1,
        "name": "Webhook Name",
        "events": [
            "contact_updated",
            "contact_created"
        ],
        "url": "https://requestb.in/1g8xh9b1",
        "enabled": true
    }
}

HTTP Request

POST v2/webhooks

Form Data

Parameter Type Status Description
name string required The name of the webhook being created.
Maximum: 255 characters
events array required Array of events that will trigger a webhook notification.
url url required The url of the webhook.
enabled boolean optional When false the webhook will be disabled and will no longer receive notification.
context string optional The identifier of the user for whom the webhook will be created. See Request Context.

Read

Request:

var settings = {
    "url": "https://api.happygrasshopper.com/v2/webhooks/1",
    "method": "GET",
    "headers": {
        "Accept": "application/json",
        "Authorization":"Bearer <api_key>"
    }
}

$.ajax(settings).done(function (response) {
    console.log(response);
});

Display the specified webhook.

Response:

{
    "user": {
        "id": 1,
        "email": "gus@happygrasshopper.com",
        "first_name": "Gus",
        "last_name": "Grasshopper",
        "phone": "1234567890",
        "created": "2016-06-13 13:32:43",
        "modified": "2017-11-05 01:05:51"
    },
    "webhook": {
        "id": 1,
        "name": "Webhook Name",
        "events": [
            "contact_updated",
            "contact_created"
        ],
        "url": "https://requestb.in/1g8xh9b1",
        "enabled": true
    }
}

HTTP Request

GET v2/webhooks/{webhook}

HEAD v2/webhooks/{webhook}

Route Variable

Variable Description
webhook The webhook's id. Remember - Route variables and query parameters should be url encoded.

Query Parameters

Parameter Status Description
context optional The identifier of the user whose webhook should be displayed. See Request Context.

Update

Example request:

var settings = {
    "url": "https://api.happygrasshopper.com/v2/webhooks/1",
    "method": "PUT",
    "data": {
        "name": "Webhook Name Updated",
        "events": ["contact_created"],
        "url": "https://requestb.in/1g8xh9b12",
        "enabled": false
    },
    "headers": {
        "Accept": "application/json",
        "Content-Type":"application/json",
        "Authorization":"Bearer <api_key>"
    }
}

$.ajax(settings).done(function (response) {
    console.log(response);
});

Update the specified webhook.

Response: The updated webhook.

{
    "user": {
        "id": 1,
        "email": "gus@happygrasshopper.com",
        "first_name": "Gus",
        "last_name": "Grasshopper",
        "phone": "1234567890",
        "created": "2016-06-13 13:32:43",
        "modified": "2017-11-05 01:05:51"
    },
    "webhook": {
        "id": 1,
        "name": "Webhook Name Updated",
        "events": [
            "contact_created"
        ],
        "url": "https://requestb.in/1g8xh9b12",
        "enabled": false
    }
}

HTTP Request

PUT v2/webhooks/{webhook}

Route Variable

Variable Description
webhook The webhook's id. Remember - Route variables and query parameters should be url encoded.

Form Data

Parameter Type Status Description
name string optional The name of the webhook being created.
Maximum: 255 characters
events array optional Array of events that will trigger a webhook notification.
url url optional The url of the webhook.
enabled boolean optional When false the webhook will be disabled and will no longer receive notification.
context string optional The identifier of the user for whom the webhook will be created. See Request Context.

Delete

Request:

var settings = {
    "url": "https://api.happygrasshopper.com/v2/webhooks/1",
    "method": "DELETE",
    "headers": {
        "Accept": "application/json",
        "Authorization":"Bearer <api_key>"
    }
}

$.ajax(settings).done(function (response) {
    console.log(response);
});

Delete the specified webhook.

Response:

{
    "success": true
}

HTTP Request

DELETE api/v2/webhooks/{webhook}

Route Variable

Variable Description
webhook The webhook's id. Remember - Route variables and query parameters should be url encoded.

Errors

Format: Error response format.

{
    "error": "Unfortunately, the request did not make our servers happy..."
}

Any http status returned from the Happy Grasshopper API that is not in the 2xx range of http statuses is most likely an error response. Error response all have the same format as shown in the provided example.

Happy Grasshopper's API uses the following http status codes:

Http Status Meaning
400 Bad Request -- One or more of the parameter passed with the request failed validation. The body of the error message will mention which parameter was invalid.
401 Unauthorized -- Your API key is invalid or revoked.
403 Forbidden -- You do not have access to the requested resource.
404 Not Found -- The specified resource could not be found.
405 Method Not Allowed -- You tried to access a resource with an invalid http request method.
410 Gone -- The requested resource has been removed from our servers.
418 I'm a teapot - The resulting response body may be short and stout.
429 Too Many Requests -- You're requesting too many resources within a short period of time! Slow down!... please :)
500 Internal Server Error -- There was a a problem (on our end) fulfilling the request. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

The body of all error responses will contain information describing why you received the error code listed above.