Overview

Getting Started

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

API Endpoint URLs have the following structure:

https:// : Protocol to be used. HTTPS is required for security.
api.happygrasshopper.com : API hostname. This will always the same.
v3 : API version. v3 is the only actively supported version.
resources : The resource name, such as users, contacts etc.
{{identifier}} : resource identifier, most likely it's id or key.

Full URL: https://api.happygrasshopper.com/v3/resource/{{identifier}}

Authentication

Every Happy Grasshopper user has the ability to generate and revoke API keys in 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.

Authorization: Bearer ApiKeyHere

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. Happy Grasshopper API is available via HTTPS only. This ensures that API Key is always encrypted during transmission.

API keys have the same role as the user whom the key belongs to. For example, a user with only the User role API keys allows access only to contact/tags/etc. owned by that user while a user with the Team Administrator role API keys allows access to all contacts/tags/etc in each of their team user's account.

{info} Note that when an account is cancelled, it enters a grace period where the API key remains valid for a short period of time. Some endpoints will continue to work correctly so that there is no data loss however after some time API requests will receive a 403 Forbidden response for all requests.

Permission Levels

User: A regular user who only has access to owned resources.
Team Administrator: A team admin that has access to all team and team user resources.
Administrator: Only available to Happy Grasshopper employees.

Requests and Responses

Happy Grasshopper's API uses JSON encoding. When sending POST and PUT requests, request body should contain JSON-encoded data to create or update a resource. We also recommend including a header indicating content type of the request body: Content-Type: application/json.

For example, to update first name on a contact with id = 456 you can use the following request:

PUT /v3/contacts/456 HTTP/1.1
Authorization: Bearer apikeyhere
Content-Type: application/json
Accept: application/json

{"first_name": "Mary"}

Likewise, response body is also encoded using JSON format.

{
    "id": 1,
    "first_name": "Mary",
    "last_name": "Grasshopper", 
    ...
}

Date Format

Please note the date format in this example: 2012-04-23T02:23:11Z. It's ISO 8601 standard. And it is the date format we use for all date and time values returned from the API.

Time will is always be expressed in UTC.

Response Codes

On successful creation of a resource, you will get a "201 Created". For all other successful requests a "200 OK" response is returned or "204 No Content" if there is no data returned.

Response Bodies

In general, response bodies for creating or updating resources will be in the same format as returned by a GET request for that resource.

Error Responses

For successful requests, the API returns a HTTP status code appropriate for that request but if the server cannot process your request, the API typically returns a 4xx HTTP status code. For example:

400 Bad Request: We could not process this request.
403 Forbidden: You do not have access to the requested resource.
404 Not Found: This resource does not exist, it may have been deleted by the user.

If the server is unable to process a request, you may see a 5xx HTTP status code (e.g. 500 Internal Server Error, 503 Service Unavailable, 504 Gateway Timeout, etc..).

Searching

When searching resources in a collection you can filter results by specifying search conditions as query parameters in the URL. For example:

GET /v3/[email protected] HTTP/1.1

You can specify multiple search criteria and they will be combined using "OR" logic:

GET /v3/[email protected]&first_name=Gus HTTP/1.1

Get Started