API Reference
Welcome to the INFIMA API reference documentation. This API provides access to comprehensive results and insights from your Security Awareness Training Program, allowing you to effectively monitor and manage your organization’s cybersecurity education initiatives. It also lets you provision clients, add users, and organize users into collections directly from your own tooling.
Download API Specifications
All API endpoints are documented using OpenAPI 3.0 (YAML). A single, specification covering the Partner, Client, User, Collections, Policies, Dark Web Monitoring, Reports, Phishing, and Sent Emails APIs is available for download below.
These specifications are compatible with tools such as Swagger UI and Postman. The downloaded YAML contains the complete API surface described above.
Authentication
INFIMA utilizes API keys for authentication and access control to the API. To obtain a new API key, you can register one through the INFIMA Partner Dashboard. For detailed instructions on how to do this, please refer to our knowledge base article at https://kb.infimasec.com/docs/reporting-api/.
For all API requests to the server, INFIMA requires the API key to be included in the request header. The header should be formatted as follows:
X-API-Key: YOUR_API_KEY
You must replace YOUR_API_KEY with your personal API key.
To authorize, use this code. Make sure to replace YOUR_API_KEY with your API key.
# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
-H "X-API-Key: YOUR_API_KEY"
Partner
Get Partner
GET/v1/partner
This API retrieves data for a partner. A partner manages Security Awareness Training for multiple clients.
Request
Headers
X-API-KEYStringRequired
Response
On success, the HTTP status code in the response header is 200 OK and the response body contains a partner object in JSON format.
curl "https://app.infimasecapis.com/v1/partner"
-H "X-API-Key: YOUR_API_KEY"
The above command returns JSON structured like this:
{
"partner_name": "Partner Co",
"created_date": "2010-02-04T18:37:01Z",
"admins": [
{
"id": "521f055b-e0cf-5bcd-9ce0-a412d194d544",
"email": "john.doe@partner.co",
"role": "Administrator",
"created_date": "2010-10-17T17:37:54Z"
},
{
"id": "28c114e8-28a9-5b70-bca6-5d0edeb7dbc8",
"email": "jane.doe@partner.co",
"role": "User",
"created_date": "2010-07-27T15:43:17Z"
}
]
}Client
Get Clients
GET/v1/clients
This API retrieves data for all clients associated with an INFIMA account. A client is a company that is subscribed to INFIMA Services.
Request
Headers
X-API-KEYStringRequired
Query parameters
limitIntegerOptional
Maximum number of objects to return. Default 20. Minimum 1. Maximum 50.
offsetIntegerOptional
The index of the first object to return. Default: 0 (the first object).
idsList of integersOptional
The ids of specified clients to return.
Response
On success, the HTTP status code in the response header is 200 OK and the response body contains an array of Client objects (wrapped in a paging object) in JSON format.
curl "https://app.infimasecapis.com/v1/clients?limit={limit}&offset={offset}
&ids={id1,id2}"
-H "X-API-Key: YOUR_API_KEY"
The above command returns JSON structured like this:
{
"items": [
{
"id": 1,
"client_name": "Client 1",
"phishing_click_rate_total": 25.0,
"phishing_click_rate_last_year": 25.0,
"training_on_track_rate": 33.3333,
"user_count": 500,
"inactive_user_count": 12,
"created_date": "2010-02-04T18:37:01Z"
},
{
"id": 2,
"client_name": "Client 2",
"phishing_click_rate_total": 40.0,
"phishing_click_rate_last_year": 40.0,
"training_on_track_rate": 33.3333,
"user_count": 2000,
"inactive_user_count": 45,
"created_date": "2010-04-01T18:17:13Z"
}
],
"limit": 2,
"offset": 0,
"total": 20
}Create Client
POST/v1/clients
This API creates a new client under your partner organization. The new client is automatically enrolled in the Security Awareness Foundations training curriculum, the same as a client created in the Partner Dashboard.
Request
Headers
X-API-KEYStringRequired
Request body (JSON)
company_nameStringRequired
The name of the client company.
Creating a client requires a partner-level API key with global access — a client-scoped key cannot create clients. The client is always created under the organization the API key belongs to; it cannot be specified in the payload.
Response
On success, the HTTP status code in the response header is 201 Created and the response body contains the new client’s identity in JSON format. Use id to address the client in other endpoints (for example when creating users).
Error responses
400Bad request - company_name missing or invalid JSON payload
401Unauthorized - Missing or invalid API key
403Forbidden - API key does not have global access
500Internal server error
curl -X POST "https://app.infimasecapis.com/v1/clients"
-H "X-API-Key: YOUR_API_KEY"
-H "Content-Type: application/json"
-d '{
"company_name": "Client 3"
}'
The above command returns JSON structured like this:
{
"id": 3,
"client_name": "Client 3"
}User
Get Users
GET/v1/clients/{client_id}/users
This API retrieves data for all users for a given client.
Request
Headers
X-API-KEYStringRequired
Path parameters
client_idIntegerRequired
The id of the client to return users for
Query parameters
limitIntegerOptional
Maximum number of objects to return. Default 20. Minimum 1. Maximum 50.
offsetIntegerOptional
The index of the first object to return. Default: 0 (the first object).
statusStringOptional
Filter users by status: active, inactive, or all. Default active.
Response
On success, the HTTP status code in the response header is 200 OK and the response body contains an array of User objects (wrapped in a paging object) in JSON format.
curl "https://app.infimasecapis.com/v1/clients/{client_id}/users?status=all"
-H "X-API-Key: YOUR_API_KEY"
The above command returns JSON structured like this:
{
"items": [
{
"id": "521226a6-1f4f-520d-aedb-205cf50990d5",
"email": "joe@companya.com",
"first_name": "Joe",
"last_name": "Doe",
"department": "HR",
"status": "active",
"preferred_language": "en",
"role": "standard",
"created_date": "2010-01-01T00:00:00Z",
"phishing_click_rate_total": 20.0,
"phishing_click_rate_last_year": 20.0,
"training_on_track": false,
"next_course": "Phishing",
"courses_behind": 2,
"risk_score": 720
},
{
"id": "8cc9bfd4-0da6-59de-b5f5-f28e2779a828",
"email": "john.doe@companya.com",
"first_name": "John",
"last_name": "Doe",
"department": "Engineering",
"status": "active",
"preferred_language": "es",
"role": "executive",
"created_date": "2010-01-27T15:37:06Z",
"phishing_click_rate_total": 50.0,
"phishing_click_rate_last_year": 50.0,
"training_on_track": true,
"next_course": "",
"courses_behind": 0,
"risk_score": 540
}
],
"limit": 2,
"offset": 0,
"total": 5
}Create User
POST/v1/clients/{client_id}/users
This API creates a single user for a given client. Only email is required. The user is created active and is placed in the client’s manually-managed user group, so directory sync will not remove them.
Request
Headers
X-API-KEYStringRequired
Path parameters
client_idIntegerRequired
The id of the client to create the user for
Request body (JSON)
emailStringRequired
The user’s email address. Normalized to lowercase.
first_nameStringOptional
The user’s first name.
last_nameStringOptional
The user’s last name.
departmentStringOptional
The user’s department.
job_titleStringOptional
The user’s job title.
manager_emailStringOptional
The email address of the user’s manager.
roleStringOptional
The user’s risk role. One of admin, executive, hr, finance, or standard. When provided, the role is marked as manually set so a later directory sync will not overwrite it. When omitted, INFIMA classifies the user from job title, department, and email.
preferred_languageStringOptional
The user’s preferred training-content language. One of en, es, or fr-ca.
collection_idIntegerOptional
Places the new user in a collection in the same call. The collection must belong to the same client.
No welcome email is sent — onboarding communication stays with you, the partner. The user’s training is evaluated immediately, so any framework-required courses are assigned right away.
Response
On success, the HTTP status code in the response header is 201 Created and the response body contains the new user’s identity in JSON format. id is the user id used by the other user endpoints.
Error responses
400Bad request - email missing, invalid role or preferred_language, or collection_id not found for this client
401Unauthorized - Missing or invalid API key
403Forbidden - API key has no access to this client
500Internal server error
curl -X POST "https://app.infimasecapis.com/v1/clients/{client_id}/users"
-H "X-API-Key: YOUR_API_KEY"
-H "Content-Type: application/json"
-d '{
"email": "jane@companya.com",
"first_name": "Jane",
"last_name": "Doe",
"department": "Finance",
"job_title": "Controller",
"role": "finance",
"preferred_language": "en",
"collection_id": 12
}'
The above command returns JSON structured like this:
{
"id": "9a1226a6-1f4f-520d-aedb-205cf5099abc",
"email": "jane@companya.com",
"first_name": "Jane",
"last_name": "Doe",
"status": "active",
"role": "finance"
}Update User
POST/v1/users/{user_id}
This API updates a user’s status, preferred language, and/or role. Only the fields provided in the request body are changed. At least one field must be provided.
Request
Headers
X-API-KEYStringRequired
Path parameters
user_idStringRequired
The id of the user to update
Request body (JSON)
statusStringOptional
The user’s status. Either active or inactive.
preferred_languageStringOptional
The user’s preferred training-content language. One of en, es, or fr-ca.
roleStringOptional
The user’s risk role. One of admin, executive, hr, finance, or standard.
Response
On success, the HTTP status code in the response header is 200 OK and the response body contains a status of "updated".
Error responses
400Bad request - No updatable fields provided, or an invalid value
401Unauthorized - Missing or invalid API key
404Not found - User not found
500Internal server error
curl -X POST "https://app.infimasecapis.com/v1/users/{user_id}"
-H "X-API-Key: YOUR_API_KEY"
-H "Content-Type: application/json"
-d '{
"status": "inactive",
"preferred_language": "es",
"role": "executive"
}'
The above command returns JSON structured like this:
{
"status": "updated"
}Get User Training Results
GET/v1/users/{user_id}/training
This API retrieves training data for a specific user.
Request
Headers
X-API-KEYStringRequired
Path parameters
user_idStringRequired
The id of the user
Query parameters
limitIntegerOptional
Maximum number of objects to return. Default 20. Minimum 1. Maximum 50.
offsetIntegerOptional
The index of the first object to return. Default: 0 (the first object).
Response
On success, the HTTP status code in the response header is 200 OK and the response body contains an array of TrainingResults objects (wrapped in a paging object) in JSON format.
curl "https://app.infimasecapis.com/v1/users/{user_id}/training"
-H "X-API-Key: YOUR_API_KEY"
The above command returns JSON structured like this:
{
"items": [
{
"order": 1,
"course_name": "Safe Web Usage",
"passed": true,
"passed_date": "2010-06-07T18:36:17Z"
},
{
"order": 2,
"course_name": "Phishing and Safe Email Use",
"passed": false,
"passed_date": "0001-01-01T00:00:00Z"
},
{
"order": 3,
"course_name": "Securing Your Electronic Data and Devices",
"passed": true,
"passed_date": "2010-04-15T21:11:04Z"
},
{
"order": 4,
"course_name": "Introduction to Social Engineering",
"passed": true,
"passed_date": "2010-04-15T21:11:04Z"
}
],
"limit": 20,
"offset": 0,
"total": 4
}Get User Phishing Results
GET/v1/users/{user_id}/phishing
This API retrieves training data for a specific user.
Request
Headers
X-API-KEYStringRequired
Path parameters
user_idStringRequired
The id of the user
Query parameters
limitIntegerOptional
Maximum number of objects to return. Default 20. Minimum 1. Maximum 50.
offsetIntegerOptional
The index of the first object to return. Default: 0 (the first object).
Response
On success, the HTTP status code in the response header is 200 OK and the response body contains an array of PhishingResults objects (wrapped in a paging object) in JSON format.
curl "https://app.infimasecapis.com/v1/users/{user_id}/phishing"
-H "X-API-Key: YOUR_API_KEY"
The above command returns JSON structured like this:
{
"items": [
{
"status": "Clicked",
"status_date": "2010-12-11T17:45:04Z"
},
{
"status": "Opened",
"status_date": "2010-12-11T17:45:04Z"
},
{
"status": "Clicked",
"status_date": "2010-12-11T17:45:04Z"
},
{
"status": "Opened",
"status_date": "2010-12-11T17:45:04Z"
},
{
"status": "Sent",
"status_date": "2010-12-11T17:45:04Z"
},
{
"status": "Sent",
"status_date": "2010-12-11T17:45:04Z"
},
{
"status": "Clicked",
"status_date": "2010-12-09T20:51:50Z"
},
{
"status": "Clicked",
"status_date": "2010-09-12T00:00:00Z"
},
{
"status": "Opened",
"status_date": "2010-09-12T00:00:00Z"
}
],
"limit": 20,
"offset": 0,
"total": 9
}Collections
Get Collections
GET/v1/clients/{client_id}/collections
This API retrieves the collections for a given client. A collection is an admin-managed group of users. Collections are addressed by their numeric id — use this endpoint to discover ids.
Request
Headers
X-API-KEYStringRequired
Path parameters
client_idIntegerRequired
The id of the client to return collections for
Query parameters
limitIntegerOptional
Maximum number of objects to return. Default 200. Maximum 1000.
offsetIntegerOptional
The index of the first object to return. Default: 0 (the first object).
Response
On success, the HTTP status code in the response header is 200 OK and the response body contains an array of Collection objects (wrapped in a paging object) in JSON format.
curl "https://app.infimasecapis.com/v1/clients/{client_id}/collections"
-H "X-API-Key: YOUR_API_KEY"
The above command returns JSON structured like this:
{
"items": [
{
"id": 12,
"name": "Finance Team",
"description": "Users handling payments",
"member_count": 14,
"created_date": "2010-03-01T12:00:00Z"
},
{
"id": 15,
"name": "New Hires",
"member_count": 3,
"created_date": "2010-05-10T09:30:00Z"
}
],
"limit": 200,
"offset": 0,
"total": 2
}Create Collection
POST/v1/clients/{client_id}/collections
This API creates a collection for a given client. Collection names are unique per client.
Request
Headers
X-API-KEYStringRequired
Path parameters
client_idIntegerRequired
The id of the client to create the collection for
Request body (JSON)
nameStringRequired
The collection name. Unique per client.
descriptionStringOptional
A description of the collection.
Response
On success, the HTTP status code in the response header is 201 Created and the response body contains the new collection object in JSON format.
Error responses
400Bad request - name missing or invalid JSON payload
401Unauthorized - Missing or invalid API key
403Forbidden - API key has no access to this client
409Conflict - a collection with this name already exists for this client
500Internal server error
curl -X POST "https://app.infimasecapis.com/v1/clients/{client_id}/collections"
-H "X-API-Key: YOUR_API_KEY"
-H "Content-Type: application/json"
-d '{
"name": "Finance Team",
"description": "Users handling payments"
}'
The above command returns JSON structured like this:
{
"id": 12,
"name": "Finance Team",
"description": "Users handling payments",
"member_count": 0,
"created_date": "2010-03-01T12:00:00Z"
}Get Collection Members
GET/v1/clients/{client_id}/collections/{collection_id}/members
This API retrieves the users in a collection.
Request
Headers
X-API-KEYStringRequired
Path parameters
client_idIntegerRequired
The id of the client the collection belongs to
collection_idIntegerRequired
The id of the collection
Query parameters
limitIntegerOptional
Maximum number of objects to return. Default 200. Maximum 1000.
offsetIntegerOptional
The index of the first object to return. Default: 0 (the first object).
Response
On success, the HTTP status code in the response header is 200 OK and the response body contains an array of CollectionMember objects (wrapped in a paging object) in JSON format.
Error responses
401Unauthorized - Missing or invalid API key
403Forbidden - API key has no access to this client
404Not found - Collection not found for this client
500Internal server error
curl "https://app.infimasecapis.com/v1/clients/{client_id}/collections/{collection_id}/members"
-H "X-API-Key: YOUR_API_KEY"
The above command returns JSON structured like this:
{
"items": [
{
"user_infima_id": "521226a6-1f4f-520d-aedb-205cf50990d5",
"name": "Joe Doe",
"email": "joe@companya.com"
}
],
"limit": 200,
"offset": 0,
"total": 1
}Add Collection Member
POST/v1/clients/{client_id}/collections/{collection_id}/members
This API adds an existing user to a collection. The user must belong to the same client as the collection.
Request
Headers
X-API-KEYStringRequired
Path parameters
client_idIntegerRequired
The id of the client the collection belongs to
collection_idIntegerRequired
The id of the collection
Request body (JSON)
user_infima_idStringRequired
The id of the user to add to the collection.
A user belongs to at most one collection. Adding a user who is already in another collection moves them — they are removed from the prior collection in the same operation.
Response
On success, the HTTP status code in the response header is 200 OK and the response body contains a status of "added".
Error responses
400Bad request - user_infima_id missing or invalid JSON payload
401Unauthorized - Missing or invalid API key
403Forbidden - API key has no access to this client
404Not found - Collection not found for this client, or user not found for this client
500Internal server error
curl -X POST "https://app.infimasecapis.com/v1/clients/{client_id}/collections/{collection_id}/members"
-H "X-API-Key: YOUR_API_KEY"
-H "Content-Type: application/json"
-d '{
"user_infima_id": "521226a6-1f4f-520d-aedb-205cf50990d5"
}'
The above command returns JSON structured like this:
{
"status": "added"
}Remove Collection Member
DELETE/v1/clients/{client_id}/collections/{collection_id}/members/{user_id}
This API removes a user from a collection.
Request
Headers
X-API-KEYStringRequired
Path parameters
client_idIntegerRequired
The id of the client the collection belongs to
collection_idIntegerRequired
The id of the collection
user_idStringRequired
The id of the user to remove from the collection
Response
On success, the HTTP status code in the response header is 200 OK and the response body contains a status of "removed".
Error responses
401Unauthorized - Missing or invalid API key
403Forbidden - API key has no access to this client
404Not found - Collection not found for this client
500Internal server error
curl -X DELETE "https://app.infimasecapis.com/v1/clients/{client_id}/collections/{collection_id}/members/{user_id}"
-H "X-API-Key: YOUR_API_KEY"
The above command returns JSON structured like this:
{
"status": "removed"
}Policies
Get Policies
GET/v1/clients/{client_id}/policies
This API retrieves all active policies for a given client, with sign-off progress. Policies can be scoped to the whole client or to a specific user group (scope_type of tenant, user_container, or collection); sign-off percentages are computed against the policy’s audience, not the whole client. Sign-off fields are omitted for policies that don’t require acknowledgment.
Request
Headers
X-API-KEYStringRequired
Path parameters
client_idIntegerRequired
The id of the client to return policies for
Query parameters
limitIntegerOptional
Maximum number of objects to return. Default 200. Maximum 1000.
offsetIntegerOptional
The index of the first object to return. Default: 0 (the first object).
A user counts as signed off only if they acknowledged the current version of the policy within its renewal window. Publishing a new version, or the renewal period lapsing, moves users back to unsigned.
Response
On success, the HTTP status code in the response header is 200 OK and the response body contains an array of Policy objects (wrapped in a paging object) in JSON format.
Error responses
401Unauthorized - Missing or invalid API key
403Forbidden - API key has no access to this client
500Internal server error
curl "https://app.infimasecapis.com/v1/clients/{client_id}/policies"
-H "X-API-Key: YOUR_API_KEY"
The above command returns JSON structured like this:
{
"items": [
{
"id": 7,
"title": "Acceptable Use Policy",
"description": "Company-wide acceptable use of IT systems",
"version": 3,
"scope_type": "tenant",
"scope_id": 1,
"requires_acknowledgment": true,
"renewal_period_days": 365,
"created_date": "2010-01-12T09:00:00Z",
"audience_user_count": 500,
"acknowledged_count": 425,
"acknowledged_percentage": 85.0
},
{
"id": 9,
"title": "Wire Transfer Procedures",
"version": 1,
"scope_type": "collection",
"scope_id": 12,
"requires_acknowledgment": true,
"renewal_period_days": 180,
"created_date": "2010-04-02T15:30:00Z",
"audience_user_count": 14,
"acknowledged_count": 9,
"acknowledged_percentage": 64.2857
},
{
"id": 11,
"title": "Office Visitor Guidelines",
"version": 1,
"scope_type": "tenant",
"scope_id": 1,
"requires_acknowledgment": false,
"renewal_period_days": 365,
"created_date": "2010-05-20T11:15:00Z"
}
],
"limit": 200,
"offset": 0,
"total": 3
}Get Policy Users
GET/v1/clients/{client_id}/policies/{policy_id}/users
This API retrieves the per-user sign-off status for a specific policy. Only users in the policy’s audience are returned. Use the status filter to get just the users who have — or have not — signed off.
Request
Headers
X-API-KEYStringRequired
Path parameters
client_idIntegerRequired
The id of the client the policy belongs to
policy_idIntegerRequired
The id of the policy
Query parameters
statusStringOptional
Filter users by sign-off status: signed, unsigned, or all. Default all.
limitIntegerOptional
Maximum number of objects to return. Default 200. Maximum 1000.
offsetIntegerOptional
The index of the first object to return. Default: 0 (the first object).
Response
On success, the HTTP status code in the response header is 200 OK and the response body contains an array of PolicyUser objects (wrapped in a paging object) in JSON format.
Error responses
400Bad request - Invalid status value
401Unauthorized - Missing or invalid API key
403Forbidden - API key has no access to this client
404Not found - Policy not found for this client
500Internal server error
curl "https://app.infimasecapis.com/v1/clients/{client_id}/policies/{policy_id}/users?status=unsigned"
-H "X-API-Key: YOUR_API_KEY"
The above command returns JSON structured like this:
{
"items": [
{
"id": "521226a6-1f4f-520d-aedb-205cf50990d5",
"email": "joe@companya.com",
"name": "Joe Doe",
"acknowledged": false
},
{
"id": "8cc9bfd4-0da6-59de-b5f5-f28e2779a828",
"email": "john.doe@companya.com",
"name": "John Doe",
"acknowledged": false
}
],
"limit": 200,
"offset": 0,
"total": 2
}Dark Web Monitoring
Get Dark Web Exposures
GET/v1/clients/{client_id}/darkweb/exposures
This API retrieves per-user Dark Web exposure counts for a given client, split into resolved and unresolved. Every active user is returned, including users with zero exposures. The optional time period bounds the exposure’s discovery date; the resolved/unresolved split always reflects the exposure’s status today.
Request
Headers
X-API-KEYStringRequired
Path parameters
client_idIntegerRequired
The id of the client to return exposure counts for
Query parameters
startTimestamp or dateOptional
Only count exposures discovered at or after this time. ISO 8601 timestamp (UTC) or YYYY-MM-DD date.
endTimestamp or dateOptional
Only count exposures discovered at or before this time. ISO 8601 timestamp (UTC) or YYYY-MM-DD date; a date covers through the end of that day.
limitIntegerOptional
Maximum number of objects to return. Default 200. Maximum 1000.
offsetIntegerOptional
The index of the first object to return. Default: 0 (the first object).
Dark Web Monitoring is a per-client feature. If it is not enabled for the client, this endpoint returns 403 rather than misleading zero counts.
Response
On success, the HTTP status code in the response header is 200 OK and the response body contains an array of ExposureCount objects (wrapped in a paging object) in JSON format.
Error responses
400Bad request - Invalid start or end value, or start after end
401Unauthorized - Missing or invalid API key
403Forbidden - API key has no access to this client, or Dark Web Monitoring is not enabled for this client
500Internal server error
curl "https://app.infimasecapis.com/v1/clients/{client_id}/darkweb/exposures?start=2010-01-01&end=2010-06-30"
-H "X-API-Key: YOUR_API_KEY"
The above command returns JSON structured like this:
{
"items": [
{
"id": "521226a6-1f4f-520d-aedb-205cf50990d5",
"email": "joe@companya.com",
"first_name": "Joe",
"last_name": "Doe",
"resolved_exposures": 3,
"unresolved_exposures": 2
},
{
"id": "8cc9bfd4-0da6-59de-b5f5-f28e2779a828",
"email": "john.doe@companya.com",
"first_name": "John",
"last_name": "Doe",
"resolved_exposures": 1,
"unresolved_exposures": 0
}
],
"limit": 200,
"offset": 0,
"total": 2
}Reports
Get Reports
GET/v1/clients/{client_id}/reports
This API retrieves all reports for a given client.
Request
Headers
X-API-KEYStringRequired
Path parameters
client_idIntegerRequired
The id of the client to return reports for
Query parameters
limitIntegerOptional
Maximum number of objects to return. Default 20. Minimum 1. Maximum 50.
offsetIntegerOptional
The index of the first object to return. Default: 0 (the first object).
curl "https://app.infimasecapis.com/v1/clients/{client_id}/reports"
-H "X-API-Key: YOUR_API_KEY"
The above command returns JSON structured like this:
{
"items": [
{
"report_id": "521226a6-1f4f-520d-aedb-205cf50990d5",
"report_type": "phishing_overview",
"created_date": "2010-01-01T00:00:00Z",
"updated_at" : "2010-01-01T00:00:00Z",
},
{
"report_id": "8cc9bfd4-0da6-59de-b5f5-f28e2779a828",
"report_type": "training_status_report",
"created_date": "2010-01-27T15:37:06Z",
"updated_at" : "2010-01-27T15:37:06Z",
}
],
"limit": 0,
"offset": 0,
"total": 2
}Download Report
GET/v1/clients/{client_id}/reports/{report_id}
This API retrieves a download link to a specific report for a given client.
Request
Headers
X-API-KEYStringRequired
Path parameters
client_idIntegerRequired
The id of the client to return the report for
Report_idIntegerRequired
The id of the desired report
Query parameters
limitIntegerOptional
Maximum number of objects to return. Default 20. Minimum 1. Maximum 50.
offsetIntegerOptional
The index of the first object to return. Default: 0 (the first object).
curl "https://app.infimasecapis.com/v1/clients/{client_id}/reports/{report_id}"
-H "X-API-Key: YOUR_API_KEY"
The above command returns JSON structured like this:
{
"items": [
{
"report_id": "521226a6-1f4f-520d-aedb-205cf50990d5",
"report_type": "training_overview",
"created_date": "2010-01-01T00:00:00Z",
"updated_at" : "2010-01-01T00:00:00Z",
"download_link": "infimasec.com/{report_id}"
},
],
"limit": 2,
"offset": 0,
"total": 5
}Phishing
Send Phishing
POST/v1/sendphishing
Request
Headers
X-API-KEYStringRequired
Request body (JSON)
user_idStringRequired
The id of the user who will receive the phishing attempt
phishing_templateIntegerRequired
The id of the desired template
send_timeTimestampOptional
The time at which the attempt will be sent. Timestamps are returned in ISO 8601 format as Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ.
Response
On success, the phishing email will be scheduled to be sent at the specified time. If no time was specified, it will send immediately.
curl -X POST "https://app.infimasecapis.com/v1/sendphishing"
-H "X-API-Key: YOUR_API_KEY"
-H "Content-Type: application/json"
-d '{
"user_id": "uf3fd541-03ec-4242-b4e8-b29425e95bdf",
"phishing_template": 1,
"send_time": "2010-01-01T00:00:00Z"
}'
The above command returns JSON structured like this:
{
"message": "Phishing email scheduled successfully"
}Sent Emails
Retrieve Sent Emails
POST/v1/sentemails
This API retrieves sent email records for users within the partner’s managed clients. Returns up to 30 days of email events from the specified start time. If no start time is provided, returns the last 30 days of events.
Request
Headers
X-API-KEYStringRequired
Request body (JSON)
user_infima_idStringRequired unless email_address is provided
INFIMA user identifier (UUID format). Preferred and prioritized — will be used if present.
email_addressStringRequired unless user_infima_id is provided
Email address of the user. Used only when user_infima_id is not supplied.
message_typesArray[String]Optional
Filter results to only include specified message types. If not provided, all message types are returned. Valid values: training-invite, phishing, phish-reminder, certificate, monthly-report
start_timeTimestampOptional
Start time for the query range in ISO 8601 format (UTC). Returns up to 30 days of events from this time. If not provided, returns the last 30 days.
When both identifiers are provided, user_infima_id takes precedence over email_address. If you supply a user_infima_id, the system will use it to resolve the user and ignore the email_address value. Prefer using user_infima_id when available.
Response
On success, the HTTP status code in the response header is 200 OK and the response body contains an array of SentEmail objects (wrapped in a paging object) in JSON format.
Error responses
400Bad request - Invalid parameters or missing required fields (at least one of user_infima_id or email_address must be provided)
401Unauthorized - Missing or invalid API key
403Forbidden - User not found in partner’s managed clients
404Not found - Specified user does not exist
429Too many requests - Rate limit exceeded
500Internal server error
curl -X POST "https://app.infimasecapis.com/v1/sentemails"
-H "X-API-Key: YOUR_API_KEY"
-H "Content-Type: application/json"
-d '{
"user_infima_id": "c66ce2a3-829d-46ee-820e-28698671c3d5",
"start_time": "2024-01-15T00:00:00Z"
}'
The above command returns JSON structured like this:
{
"items": [
{
"message_infima_id": "a4f8d2e1-7b3c-4e6f-9d8a-1c5e3f7a9b2d",
"user_infima_id": "c66ce2a3-829d-46ee-820e-28698671c3d5",
"event_time": "2024-01-20T14:30:00Z",
"from_email": "training@infimasec.com",
"subject": "Complete your security awareness training",
"send_method": "microsoft-api",
"message_type": "training-invite"
},
{
"message_infima_id": "b7e4f9c2-5a8d-4f1e-8c3b-2d6a9f8e7c5b",
"user_infima_id": "c66ce2a3-829d-46ee-820e-28698671c3d5",
"event_time": "2024-01-18T09:15:00Z",
"from_email": "phishing-test@infimasec.com",
"subject": "Important: Update your password",
"send_method": "smtp",
"message_type": "phishing"
}
],
"limit": 100,
"offset": 0,
"total": 2
}Objects
PartnerObject
partner_nameString
The partner’s name
created_dateTimestamp
The date the partner was created. Timestamps are returned in ISO 8601 format as Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ.
adminsArray[AdminObject]
The admins at the partner.
ClientObject
idInteger
The client’s id
client_nameString
The client’s name
created_dateTimestamp
The date the client was created. Timestamps are returned in ISO 8601 format as Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ.
user_countInteger
The number of active users at the client.
inactive_user_countInteger
The number of inactive (deactivated) users at the client.
phishing_click_rate_totalFloat
The phishing click rate for the entire client. Values range from 0 - 100.
phishing_click_rate_last_yearFloat
The phishing click rate for the client over the last year. Values range from 0 - 100.
training_on_track_rateFloat
The percentage of users at a client who are On-Track. Values range from 0 - 100.
UserObject
idString
The user’s id
emailString
The user’s email address
first_nameString
The user’s first name
last_nameString
The user’s last_name
departmentString
The user’s department
statusString
The user’s status. Either active or inactive.
preferred_languageString
The user’s preferred training-content language. One of en, es, or fr-ca.
roleString
The user’s risk role. One of admin, executive, hr, finance, or standard. Unclassified users are reported as standard.
created_dateTimestamp
The date the user was created. Timestamps are returned in ISO 8601 format as Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ.
phishing_click_rate_totalFloat
The percentage of phishing attacks the user has clicked on. Values range from 0 - 100.
phishing_click_rate_last_yearFloat
The percentage of phishing attacks the user has clicked on in the last year. Values range from 0 - 100.
training_on_trackBoolean
The user’s training status. True if user is caught up on all courses.
next_courseString
The name of the next course for the user to complete.
courses_behindInteger
The number of courses the user needs to complete to be On-Track
risk_scoreInteger
The user’s risk score.
AdminObject
idString
The user’s id
emailString
The user’s email address
roleString
The user’s role. Either User or Administrator.
first_nameString
The user’s first name
last_nameString
The user’s last name
created_dateTimestamp
The date the admin was created. Timestamps are returned in ISO 8601 format as Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ.
CollectionObject
idInteger
The collection’s id
nameString
The collection’s name. Unique per client.
descriptionString
A description of the collection. Omitted when empty.
member_countInteger
The number of users in the collection.
created_dateTimestamp
The date the collection was created. Timestamps are returned in ISO 8601 format as Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ.
CollectionMemberObject
user_infima_idString
The user’s id
nameString
The user’s full name
emailString
The user’s email address
PolicyObject
idInteger
The policy’s id
titleString
The policy’s title
descriptionString
A description of the policy. Omitted when empty.
versionInteger
The current policy version. Sign-off status is tracked against the current version.
scope_typeString
The policy’s audience scope. One of tenant (whole client), user_container, or collection.
scope_idInteger
The id of the audience the policy applies to. For collection scope this is a collection id; for tenant scope it equals the client id.
requires_acknowledgmentBoolean
Whether users must sign off on this policy.
renewal_period_daysInteger
How long an acknowledgment stays valid. After this many days a user must sign off again.
created_dateTimestamp
The date the policy was created. Timestamps are returned in ISO 8601 format as Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ.
audience_user_countInteger
The number of active users in the policy’s audience. Only present when requires_acknowledgment is true.
acknowledged_countInteger
The number of audience users who have signed off on the current version within the renewal window. Only present when requires_acknowledgment is true.
acknowledged_percentageFloat
The percentage of audience users who have signed off. Values range from 0 - 100; 0 when the audience is empty. Only present when requires_acknowledgment is true.
PolicyUserObject
idString
The user’s id
emailString
The user’s email address
nameString
The user’s full name
acknowledgedBoolean
Whether the user has signed off on the current policy version within its renewal window.
acknowledged_atTimestamp
The date the user signed off. Omitted when acknowledged is false. Timestamps are returned in ISO 8601 format as Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ.
ExposureCountObject
idString
The user’s id
emailString
The user’s email address
first_nameString
The user’s first name
last_nameString
The user’s last name
resolved_exposuresInteger
The number of the user’s Dark Web exposures that have been marked resolved.
unresolved_exposuresInteger
The number of the user’s Dark Web exposures still unresolved.
TrainingResultsObject
orderInteger
The order of the course. Begins with course 1.
course_nameString
The course name
completedBoolean
Has the user completed the course
completed_dateTimestamp
The date the user completed the course. Timestamps are returned in ISO 8601 format as Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ.
PhishingResultsObject
statusString
The status of the simulated phish event. Values can be Sent, Opened, Clicked.
status_dateTimestamp
The date the status event occurred. For example, when was the phish sent. Timestamps are returned in ISO 8601 format as Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ.
PagingObject
itemsArray[Object]
The requested data
limitInteger
The maximum number of objects returned
offsetInteger
The offset of the items returned
totalInteger
The total number of items available to return
ReportObject
report_idstring
The id of the desired report.
report_typestring
The report type.
created_dateTimestamp
The date the report was created. Timestamps are returned in ISO 8601 format as Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ.
updated_atTimestamp
The date the report was updated. Timestamps are returned in ISO 8601 format as Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ.
download_linkstring
URL to download the report.
SentEmailObject
message_infima_idString
Unique identifier for the sent message (UUID format)
user_infima_idString
INFIMA user identifier (UUID format)
event_timeTimestamp
Time when the email was sent. Timestamps are returned in ISO 8601 format as Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ.
from_emailString
Sender email address
subjectString
Email subject line
send_methodString
Method used to send the email. Valid values: microsoft-api, smtp, gmail-api
message_typeString
Type of message sent. Valid values: training-invite, phishing, phish-reminder, certificate, monthly-report
Errors
The INFIMA API uses the following error codes:
400Bad Request — Your request is invalid.
401Unauthorized — Your API key is wrong.
403Forbidden — Your API key does not have access to the requested client or action.
404Not Found — The requested resource does not exist.
409Conflict — The request conflicts with existing data, such as a duplicate collection name.
429Too Many Requests — You’ve made too many requests for a given time period.
500Internal Server Error — We had a problem with our server. Try again later.
503Service Unavailable — We’re temporarily offline for maintenance. Please try again later.