Developers

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.

Download OpenAPI specGet an API key

Download API Specifications

All API endpoints are documented using OpenAPI 3.0 (YAML). A single, specification covering the Partner, Client, User, Reports, Phishing, and Sent Emails APIs is available for download below.

Download OpenAPI 3.0 specification (YAML)

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.

Authorization header

# 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.

GET/v1/partner

curl "https://app.infimasecapis.com/v1/partner"
  -H "X-API-Key: YOUR_API_KEY"

The above command returns JSON structured like this:

Response

{
    "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.

GET/v1/clients

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:

Response

{
    "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
}

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.

GET/v1/clients/{client_id}/users

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:

Response

{
    "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
}

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

400

Bad request - No updatable fields provided, or an invalid value

401

Unauthorized - Missing or invalid API key

404

Not found - User not found

500

Internal server error

POST/v1/users/{user_id}

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:

Response

{
    "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.

GET/v1/users/{user_id}/training

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:

Response

{
    "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.

GET/v1/users/{user_id}/phishing

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:

Response

{
    "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
}

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).

GET/v1/clients/{client_id}/reports

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:

Response

{
    "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).

GET/v1/clients/{client_id}/reports/{report_id}

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:

Response

{
    "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.

POST/v1/sendphishing

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:

Response

{
    "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

400

Bad request - Invalid parameters or missing required fields (at least one of user_infima_id or email_address must be provided)

401

Unauthorized - Missing or invalid API key

403

Forbidden - User not found in partner’s managed clients

404

Not found - Specified user does not exist

429

Too many requests - Rate limit exceeded

500

Internal server error

POST/v1/sentemails

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:

Response

{
  "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.

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:

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.