API Overview

Our API may be used to programmatically integrate with our referral system. All API requests require a username and key to be defined, therefore you must have a company account with us before being able to successfully make requests.

For each method documented, we also provide example success responses in JSON and XML.

If you have any questions regarding our API, please refer to our Help & Support.


To use the Ambassador API, you must be a registered user and have an api key. You must use an api key to make API requests. The API key can also be generated via the curl command-line tool.

For example: curl -F username=your_username -F password=your_password https://api.getambassador.com/api-key/

Once you have an API key, you must pass Authorization: Token <your-api-key> as a header.

For example: curl -X GET https://api.getambassador.com/event/ -H 'Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b'

Replace the url with the api url, and the token with your token.


For api endpoints representing lists, you can paginate using the page and page_size parameters.

page indicates the page number.

page_size indicates the number of results per page.

The endpoint will return count, next, and previous.

count indicates the total objects in the list.

next and previous are the api endpoint urls to the next and previous pages, respectively.

Searching and Ordering

Most api endpoints representing lists support searching and ordering using the search and ordering parameters. The endpoint will indicate which terms are searchable.

search will perform a search on supported fields using the specified term e.g. <url>/?search=john will return results that contain the search term 'john'.

ordering will sort results by the specified field e.g. <url>/?ordering=company_name will return results sorted by company_name. Use the - to sort descending.

Searching is not case sensitive, concatenated search terms will return results containing ALL of the terms.

Entry Point

This is the entry point for the Ambassador API.

Follow the hyperinks each resource offers to explore the API.

Note that you can also explore the API from the command line, for instance using the curl command-line tool.

For example: curl -X GET https://api.getambassador.com/ -H "Accept: application/json; indent=4"

Content-Type: application/json
Vary: Accept

    "companies": "https://api.getambassador.com/companies/"