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.
Authentication
To authorize, use this code:
# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"-H"X-API-Key: YOUR_API_KEY"
Make sure to replace YOUR_API_KEY with your API key.
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:
This API retrieves data for all clients associated with an INFIMA account. A client is a company that is subscribed to INFIMA Services.
Request
Header
Type
Required
X-API-KEY
String
Required
Query Parameter
Description
Type
Required
limit
Maximum number of objects to return. Default 20. Minimum 1. Maximum 50.
Integer
Optional
offset
The index of the first object to return. Default: 0 (the first object).
Integer
Optional
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.
This API retrieves data for all users for a given client.
Request
Header
Type
Required
Authorization
String
Required
Path Parameter
Description
Type
Required
client_id
The id of the client to return users for
Integer
Required
Query Parameter
Description
Type
Required
limit
Maximum number of objects to return. Default 20. Minimum 1. Maximum 50.
Integer
Optional
offset
The index of the first object to return. Default: 0 (the first object).
Integer
Optional
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.
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}
This API retrieves training data for a specific user.
Request
Header
Type
Required
Authorization
String
Required
Path Parameter
Description
Type
Required
user_id
The id of the user
String
Required
Query Parameter
Description
Type
Required
limit
Maximum number of objects to return. Default 20. Minimum 1. Maximum 50.
Integer
Optional
offset
The index of the first object to return. Default: 0 (the first object).
Integer
Optional
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.
This API retrieves training data for a specific user.
Request
Header
Type
Required
Authorization
String
Required
Path Parameter
Description
Type
Required
user_id
The id of the user
String
Required
Query Parameter
Description
Type
Required
limit
Maximum number of objects to return. Default 20. Minimum 1. Maximum 50.
Integer
Optional
offset
The index of the first object to return. Default: 0 (the first object).
Integer
Optional
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.
Maximum number of objects to return. Default 20. Minimum 1. Maximum 50.
Integer
Optional
offset
The index of the first object to return. Default: 0 (the first object).
Integer
Optional
This API retrieves a download link to a specific report for a given client.
Objects
PartnerObject
Key
Description
Type
partner_name
The partner's name
String
created_date
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.
Timestamp
admins
The admins at the partner.
Array[AdminObject]
ClientObject
Key
Description
Type
id
The client's id
Integer
client_name
The client's name
String
created_date
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.
Timestamp
user_count
The number of users at the client.
Integer
phishing_click_rate
The phishing click rate for the entire client. Values range from 0 - 100.
Float
training_on_track_rate
The percentage of users at a client who are On-Track. Values range from 0 - 100.
Float
UserObject
Key
Description
Type
id
The user's id
String
email
The user's email address
String
first_name
The user's first name
String
last_name
The user's last_name
String
department
The user's department
String
created_date
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.
Timestamp
phishing_click_rate
The percentage of phishing attacks the user has clicked on. Values range from 0 - 100
Float
training_on_track
The user's training status. True if user is caught up on all courses.
Boolean
next_course
The name of the next course for the user to complete.
String
courses_behind
The number of courses the user needs to complete to be On-Track
Integer
AdminObject
Key
Description
Type
id
The user's id
String
email
The user's email address
String
role
The user's role. Either User or Administrator.
String
first_name
The user's first name
String
last_name
The user's last name
String
created_date
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.
Timestamp
TrainingResultsObject
Key
Description
Type
order
The order of the course. Begins with course 1.
Integer
course_name
The course name
String
completed
Has the user completed the course
Boolean
completed_date
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.
Timestamp
PhishingResultsObject
Key
Description
Type
status
The status of the simulated phish event. Values can be Sent, Opened, Clicked.
String
status_date
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.
Timestamp
PagingObject
Key
Description
Type
items
The requested data
Array[Object]
limit
The maximum number of objects returned
Integer
offset
The offset of the items returned
Integer
total
The total number of items available to return
Integer
ReportObject
Key
Description
Type
report_id
The id of the desired report.
string
report_type
The report type.
string
created_date
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.
Timestamp
updated_at
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.
Timestamp
download_link
URL to download the report.
string
Errors
The INFIMA API uses the following error codes:
Error Code
Meaning
400
Bad Request -- Your request is invalid.
401
Unauthorized -- Your API key is wrong.
429
Too Many Requests -- You've made too many requests for a given time period.
500
Internal Server Error -- We had a problem with our server. Try again later.
503
Service Unavailable -- We're temporarily offline for maintenance. Please try again later.
