Running your first Invotra API request

What you’ll need:

• Your Invotra instance
• Your chosen authentication method

Invotra instance

The URL format for the APIs is:

https://your-instance.invotra.com/api/0.3/{endpoint}

Authentication

You can authenticate against the Invotra APIs using a user session or an API key.

Session-based authentication provides access to the Invotra APIs for a specific user.

An API key provides full Webmaster-level access to all API endpoints.

Session authentication

Firstly, login via the /sessions/login endpoint.

curl -v -X POST "https://your-instance.invotra.com/api/0.3/sessions/login" -H "Content-Type: application/json" -d "{\"username\":\"your-username\",\"password\":\"your-password\"}"

Your session-cookie will be returned in the “Set-Cookie” response header.

Set-Cookie: {session-name}={session-id}

Include your session cookie in the headers for subsequent requests, for example, for your own profile data:

curl -X GET "https://your-instance.invotra.com/api/0.3/users/me" -H "Cookie: {session-name}={session-id}"

Example response:

{
  "uuid":"xxx",
  "username":"your-username",
  "user_avatar":"https://your-instance.invotra.com/system/files/profile.jpg",
  "email":"your@email.com",
  "external_id":"12345",
  "roles":["Organisational user"],
  "status":"Active",
  "phone":"07123 456789",
  ...
}

API key

The API key should be passed in using the “X-API-Key” request header.

For example, a list of the users in Invotra:

curl -X GET "https://your-instance.invotra.com/api/0.3/users/search" -H "X-API-Key: your-api-key"

Example response:

{
  "Count": 50,
  "Results": [
    {
      "uuid":"xxx",
      "username":"user 1",
      "user_avatar":"https://your-instance.invotra.com/system/files/profile.jpg",
      "email":"your@email.com",
      "external_id":"12345",
      "roles":["Organisational user"],
      "status":"Active",
      "phone":"07123 456789",
      ...
    },
    {
      "uuid":"yyy",
      "username":"user 2",
      ...
    }
}

Parameters

Parameters can be used to filter and sort the API responses.

Available parameters can be found on the full specification under each endpoint. See the link at the bottom of the page.

List endpoints are paged at 25 items with a count of the total item along with the results set.

The “Offset” parameter can be used to navigate through results, providing a method of paging.

The “Limit” parameter can be used to limit the results below 25 items.

For example, the first 10 users on the second page of results:

curl -X GET "https://your-instance.invotra.com/api/0.3/users/search?offset=25&limit=10" -H "X-API-Key: your-api-key"

The “Sort” parameter defines the value to sort the results by.

The “Order” parameter defines the order for the results.

For example, to filter the users in the request above alphabetically by first name:

curl -X GET "https://your-instance.invotra.com/api/0.3/users/search?sort=firstname&order=asc&offset=25&limit=10" -H "X-API-Key: your-api-key"

API documentation

For a full list of available endpoints and operations click here.