This article explains how a multitenant organization can use the API to retrieve information about the instances it manages: license validity, contracted components, contracted and active users, date of the last launched campaign, organization type and sector.
What it is for
The Instance management section lets you view the inventory of organizations from the platform. The Managed instances endpoint provides the same information in an automated way, intended for cases where an external system needs to consume it. For example:
- A dashboard that shows the status of all instances in one place.
- A process that alerts about licenses that are about to expire.
- A periodic check that compares active users against contracted users.
- Tracking of instances that have not launched campaigns recently.
If you are looking for instance management from the platform, see Multitenant.
Before you start
- Verify that your organization manages instances. The endpoint is only available to multitenant organizations that manage instances.
- Register an application in Settings > Integrations > Registered applications with the read_managed_instances scope selected. The full procedure is described in API integration in SMARTFENSE.
- Obtain an access token using the Authorization code or Client Credentials flow. Both are supported by this endpoint.
Note: the read_managed_instances scope is only offered to organizations that manage instances. If you do not see it when registering the application, your organization has no managed instances associated with it.
Query the instances
GET /api/v1/organization/managed-instances
The path is relative to your instance URL. Include the token in the Authorization header of the request:
curl -X GET "https://tenantname.takesecurity.com/api/v1/organization/managed-instances" \ -H "Authorization: Bearer <access_token>"
Where tenantname is the name of your instance.
The response includes the managed instances at any level of the hierarchy, both active and deactivated.
Query parameters
All parameters are optional and can be combined.
| Parameter | Type | Description |
|---|---|---|
| name | string | Returns only the instances whose name contains this text. Not case-sensitive. |
| page | integer | Page number to query. Default value: 1. |
| page_size | integer | Number of records per page. Default value: 50. Maximum value: 50. |
| validity_end_date_before | string (date) | Returns only the instances whose validity ends on this date or earlier. Format: YYYY-MM-DD. |
Example: instances whose license expires on or before December 31, 2026.
GET /api/v1/organization/managed-instances?validity_end_date_before=2026-12-31
Response
The response is paginated and delivered in application/json format:
{
"count": 123,
"next": "https://tenantname.takesecurity.com/api/.../?page=4",
"previous": "https://tenantname.takesecurity.com/api/.../?page=2",
"results": [
{
"name": "string",
"url": "http://example.com",
"active": true,
"validity_start_date": "2019-08-24",
"validity_end_date": "2019-08-24",
"contracted_users": 0,
"active_users": 0,
"last_campaign_launched_at": "2019-08-24T14:15:22Z",
"company_type": { ... },
"sector": { ... },
"components": [ ... ]
}
]
}- count: total number of instances that match the filters.
- next and previous: URL of the next and previous page. Use them to go through all the results.
- results: list of instances on the queried page.
Fields of each instance
| Field | Type | Description |
|---|---|---|
| name | string | Instance name. |
| url | string (URI) | Address used to access the instance. |
| active | boolean | Indicates whether the instance is active. |
| validity_start_date | date or null | License validity start date. It is null if it was not loaded. |
| validity_end_date | date | License validity end date. |
| contracted_users | integer | Number of contracted users. |
| active_users | integer | Number of users active at this moment. They are counted the same way as in the license information, so they can be compared with the contracted users. |
| last_campaign_launched_at | date-time or null | Start date and time of the last launched campaign, of any component. It is null if the instance never launched a campaign. |
| company_type | object | Organization type. |
| sector | object or null | Organization sector. It is null if it was not loaded. |
| components | array of objects | Contracted components. |
Important: company_type, sector and each element of components are reported with a stable code and their name in the organization's language. Use the code to automate processes and the name only to display the information.
How the last launched campaign is calculated
The last_campaign_launched_at field follows these rules:
- It does not count test campaigns.
- It does not count campaigns scheduled for a later date.
- An itinerary counts as a single campaign.
- It reports the date the campaign started, not the date of the last email sent.
Response codes
| Code | Meaning |
|---|---|
| 200 | Successful request. |
| 400 | One of the filters does not have a valid value. |
| 401 | No access token was provided, or the token is invalid or expired. |
| 403 | The token does not have the required scope, or the organization has no managed instances available to query. |
| 429 | The allowed request limit was exceeded. Retry after the time indicated in the Retry-After header. |
Note: if you receive a 400 when filtering by date, verify that validity_end_date_before follows the YYYY-MM-DD format.
💡 Best practices
- Register an application dedicated to this integration, with read_managed_instances as its only scope if you do not need others.
- Go through all pages by following the next field until it is null. The maximum per page is 50 instances.
- Use validity_end_date_before to detect licenses that are about to expire in advance.
- Compare active_users with contracted_users to identify instances close to their license limit.
- Review last_campaign_launched_at to detect instances without recent activity.
- Use the code of the organization type, sector and components in your automated processes. The name may change depending on each organization's language.
- If you receive a 429, wait for the time indicated in Retry-After before retrying.