1. Partner API v2
  2. Resources
  3. Collections

Collections

Admin-managed groups of users used as audiences for training, frameworks, and policies.
7 endpointsScope readCollectionUser
GET/v2/clients/{client_id}/collections

List collectionsLink to this endpoint

RequiresreadscopeCursor-paginatedReturns Page of Collection

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

Query parametersall optional unless marked

limitinteger

Default 100min 1 · max 500

cursorstring

Opaque cursor from the previous page's page.next_cursor.

curl "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/collections" \
  -H "X-API-Key: $INFIMA_API_KEY"
Response objectPage of Collection
dataarray of Collection
Show item properties(8)
idstring
client_idstring
namestring
descriptionstringNullable
member_countinteger
created_bystring
One ofdashboardapi
created_atstring (date-time)
updated_atstring (date-time)
pageobject
Show properties(2)
next_cursorstringNullable

Pass as cursor to fetch the next page. Null on the last page.

has_moreboolean
POST/v2/clients/{client_id}/collections

Create a collectionLink to this endpoint

RequireswritescopeReturns Collection

Creates an empty collection. Its created_by is api.

Names are unique within a client, and the name of a deleted collection stays taken: a name already used by a current or deleted collection of this client is 409 CONFLICT. Leading and trailing spaces are trimmed from name and description.

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

Request bodyapplication/json

namestringRequired

min length 1 · max length 150

descriptionstring
curl -X POST "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/collections" \
  -H "X-API-Key: $INFIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Finance team",
    "description": "Everyone who approves payments or vendor changes"
  }'
Response objectCollection
idstring
client_idstring
namestring
descriptionstringNullable
member_countinteger
created_bystring
One ofdashboardapi
created_atstring (date-time)
updated_atstring (date-time)
Errors400Invalid request409The object already existsError envelope →
GET/v2/clients/{client_id}/collections/{collection_id}

Get a collectionLink to this endpoint

RequiresreadscopeReturns Collection

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

collection_idstringRequired

Collection id (the collection's INFIMA id).

curl "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/collections/6f1c2a7e-3b9d-4c1a-9e8f-0a1b2c3d4e5f" \
  -H "X-API-Key: $INFIMA_API_KEY"
Response objectCollection
idstring
client_idstring
namestring
descriptionstringNullable
member_countinteger
created_bystring
One ofdashboardapi
created_atstring (date-time)
updated_atstring (date-time)
Errors404Not found within the key's accessError envelope →
DELETE/v2/clients/{client_id}/collections/{collection_id}

Delete a collectionLink to this endpoint

Requireswritescope

Deletes the collection, as deleting it in the dashboard does. Deletion is not blocked by what targets the collection; instead:

  • Its members leave it and fall back to the training of their directory group or the client. The users themselves are not changed, and training they already completed stays in their history.
  • Training scheduled for the collection is archived.
  • Framework assignments and policies whose audience is the collection stay on record but no longer reach anyone. They still report audience type collection, without an id.

The collection's name stays taken (see Create a collection).

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

collection_idstringRequired

Collection id (the collection's INFIMA id).

curl -X DELETE "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/collections/6f1c2a7e-3b9d-4c1a-9e8f-0a1b2c3d4e5f" \
  -H "X-API-Key: $INFIMA_API_KEY"
Errors404Not found within the key's accessError envelope →
GET/v2/clients/{client_id}/collections/{collection_id}/members

List collection membersLink to this endpoint

RequiresreadscopeCursor-paginatedReturns Page of User

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

collection_idstringRequired

Collection id (the collection's INFIMA id).

Query parametersall optional unless marked

limitinteger

Default 100min 1 · max 500

cursorstring

Opaque cursor from the previous page's page.next_cursor.

curl "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/collections/6f1c2a7e-3b9d-4c1a-9e8f-0a1b2c3d4e5f/members" \
  -H "X-API-Key: $INFIMA_API_KEY"
Response objectPage of User
dataarray of User
Show item properties(17)
idstring
client_idstring
emailstring (email)
first_namestring
last_namestring
departmentstringNullable
job_titlestringNullable
manager_emailstring (email)Nullable
statusstring
One ofactiveinactive
rolestring

The role used to weight a user's risk signals.

One ofadminexecutivehrfinancestandard
preferred_languagestring
One ofenesfr-ca
sourcestring

Where the user record came from: a directory sync (microsoft, google), added in the dashboard (manual), or created through this API (api). A manual or API user that a directory sync later picks up reports the directory.

One ofmicrosoftgooglemanualapi
groupobjectNullable

The directory group or manual group the user belongs to.

Show properties(2)
idstring
namestring
riskobject
Show properties(2)
scoreinteger
gradestring

Letter grade derived from the score. A is 800 and above, B 700, C 600, D 400, F below 400.

One ofABCDF
trainingobject
Show properties(3)
on_trackboolean
overdue_countinteger
next_courseobjectNullable
Show properties(3)
course_idstring
titlestring
due_onstring (date)
created_atstring (date-time)
updated_atstring (date-time)
pageobject
Show properties(2)
next_cursorstringNullable

Pass as cursor to fetch the next page. Null on the last page.

has_moreboolean
POST/v2/clients/{client_id}/collections/{collection_id}/members

Add membersLink to this endpoint

Requireswritescope

Adds one or more users of this client to the collection. Inactive users can be added.

  • Users already in the collection are skipped, not errors, so a retry is safe.
  • A user belongs to at most one collection. Adding a user who is in another collection of this client moves them here, as the dashboard does; they leave the other collection and its upcoming training.
  • Every id must be a user of this client. If any is not (unknown, deleted, or in another client), the request is 400 INVALID_REQUEST with one details entry per bad id (field is user_ids[<index>]) and no one is added.

added_count counts the users who joined (including those moved here); member_count is the collection's size afterwards.

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

collection_idstringRequired

Collection id (the collection's INFIMA id).

Request bodyapplication/json

user_idsarray of stringRequired

max 500 items

curl -X POST "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/collections/6f1c2a7e-3b9d-4c1a-9e8f-0a1b2c3d4e5f/members" \
  -H "X-API-Key: $INFIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": [
      "b7e1c0d2-44aa-5f9e-8c33-1a2b3c4d5e6f"
    ]
  }'
Response objectObject
added_countinteger
member_countinteger
Errors400Invalid request404Not found within the key's accessError envelope →
DELETE/v2/clients/{client_id}/collections/{collection_id}/members/{user_id}

Remove a memberLink to this endpoint

Requireswritescope

Takes the user out of the collection. They fall back to the training of their directory group or the client: upcoming training scheduled for the collection is removed for them, training that has already started stays in their history. The user is not otherwise changed. A user who is not a member of this collection is 404 (Collection member not found).

Path parameters

client_idstringRequired

Client id (the client's INFIMA id).

collection_idstringRequired

Collection id (the collection's INFIMA id).

user_idstringRequired

User id (the user's INFIMA id).

curl -X DELETE "https://app.infimasecapis.com/v2/clients/3f2a9c1e-7b44-5d2e-9a1f-0c6d8e4b2a10/collections/6f1c2a7e-3b9d-4c1a-9e8f-0a1b2c3d4e5f/members/b7e1c0d2-44aa-5f9e-8c33-1a2b3c4d5e6f" \
  -H "X-API-Key: $INFIMA_API_KEY"
Errors404Not found within the key's accessError envelope →