Getting started
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.
0 Comments