Introduction

Welcome to the reference for the INFIMA API. Use this API to access results on your Security Awareness Training Program.

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 uses API keys to allow access to the API. You can register a new key in the INFIMA Partner Dashboard.

INFIMA expects for the API key to be included in all API requests to the server in a header that looks like the following:

X-API-Key: YOUR_API_KEY

You must replace YOUR_API_KEY with your personal API key.

Partner

Get Partner

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

This API retrieves data for a partner. A partner manages Security Awareness Training for multiple clients.

Request

Header	Type	Required
`X-API-KEY`	String	Required

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.

Client

Get Clients

curl "https://app.infimasecapis.com/v1/clients?limit={limit}&offset={offset}"
  -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,
            "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,
            "created_date": "2010-04-01T18:17:13Z"
        }
    ],
    "limit": 2,
    "offset": 0,
    "total": 20
}

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.

User

Get Users

curl "https://app.infimasecapis.com/v1/clients/{client_id}/users"
  -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",
            "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
        },
        {
            "id": "8cc9bfd4-0da6-59de-b5f5-f28e2779a828",
            "email": "john.doe@companya.com",
            "first_name": "John",
            "last_name": "Doe",
            "department": "Engineering",
            "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
        }
    ],
    "limit": 2,
    "offset": 0,
    "total": 5
}

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.

Get User Training Results

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
}

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.

Get User Phishing Results

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
}

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.

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

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.