API Reference

This section provides a technical overview on how to interact with the API and interactive testing can be performed via our swagger documentation. 

Overview

Endpoint & Versioning

All APIs are reached on the https://client-api.culture.ai endpoint with the version prefixing the API name, for example version 1 of the test API would be /v1/test.

Changes to APIs will be made iteratively unless breaking, in which case you will be notified ahead of time and in our release notes of the upcoming changes. We will always make an effort to keep our APIs backwards compatible with changes being made to new major versions only.

Authentication

Generate an API key in your administration dashboard valid for the scopes that the APIs you want to call require, then pass it in the Authorization header of your request as Basic <API KEY>. You may also restrict the IP ranges each API key can be called from, for additional security.

You can find permissions listed along with the API endpoints below.

Requests & Responses

GET request parameters can be passed via JSON or query string, but we recommend passing them as JSON with the Content-Type of application/json to work around query string length limitations. All other requests should pass their parameters in a JSON string via the request/post body.

Responses will always be made with the Content-Type set to application/json and a JSON object being returned.

Errors

Whenever an error is encountered you will receive a < 400 status code JSON response with the key error in it, describing what exactly was wrong about the request. Here are all the status codes you can expect and some example error messages:

Pagination & Ordering

CultureAI supports a cursor-offset hybrid pagination system, which allows you to determine the total amount of records and paginate through real time data feeds without receiving duplicates or skipping records. Ordering is not currently supported on any APIs at this early stage, but we plan to in the future.

APIs which support pagination will note the request supporting a pagination cursor, return their items inside the data key as opposed to the root of the JSON response, include a total key representing the total amount of items there is to retrieve, and (assuming there is more items to retrieve) include a nextPageCursor key which you pass as the paginationCursor on your request for the next page. You can control how many items are returned in each page with the pageSize parameter, the default is 50 and the maximum is 500.

Here is an example of a paginated request using the employee list API, we start by fetching a page of 5 employees:

GET https://client-api.culture.ai/v1/employees?pageSize=5 
Accept: application/json 
Authorization: Basic <API_KEY>

Which gives us a response indicating there are 11 employees total and another page from our current position:

{
    "data": [
        {
            "id": 11123,
            "name": "Test Account 1",
            "email": "test1@culture.ai"
        },
        {
            "id": 11124,
            "name": "Test Account 2",
            "email": "test2@culture.ai"
        },
        ....
    ],
    "total": 11,
    "nextPageCursor": "eyJzdGFydCI6MSwibWF4SWQiOjE4MTQ3MX0="
}

To fetch the next page we make another request, identical to the first but with the parameter paginationCursor set to the value of nextPageCursor from our previous response:

GET https://client-api.culture.ai/v1/employees?pageSize=5&paginationCursor=eyJzdGFydCI6MSwibWF4SWQiOjE4MTQ3MX0 
Accept: application/json 
Authorization: Basic <API_KEY>

API Endpoints

Connection Testing 

Tests your connection and authentication with the CultureAI API, requires no scopes. Returns minimal data about who you are authenticated as and what the read API key was for your verification.

Request 

This API does not support any parameters.

GET https://client-api.culture.ai/v1/me 
Accept: application/json 
Authorization: Basic <API_KEY>

Response 

{
    "apiKey": "API_KEY",
    "client": "Culture AI"
}

Get Employees 

Fetches the employees you have synced, imported or manually created in access management settings.

Requires the employee.read scope.

Request 

This API only supports the standard pagination parameters.

GET https://client-api.culture.ai/v1/employees 
Accept: application/json 
Authorization: Basic <API KEY>

Response 

This API follows the standard pagination response structure, with each employee in the data array containing the following values:

Here is an example response:

{
    "data": [
        {
            "id": 523163,
            "name": "Test Account",
            "email": "test@culture.ai"
        }
        ....
    ],
    "total": 52,
    "nextPageCursor": "eyJzdGFydCI6NSwibWF4SWQiOjE4MTQ3MX0="
}

Employee's Risks 

List employee's associated security decision, livelihood, impact and organisation risk scores from the People & Teams Dashboard.

Requires the risk.read scope.

Request 

This API supports the standard pagination parameters, in addition to:

Get all users/risks:

GET https://client-api.culture.ai/v1/risks
Accept: application/json 
Authorization: Basic <API_KEY>

Get risks for a subset of employees:

GET https://client-api.culture.ai/v1/risks?ids[]=12345&ids[]=678910
Accept: application/json 
Authorization: Basic <API_KEY>

Response 

This API follows the standard pagination response structure, with each object in the data array representing a single employee's score & risk data following the below structure:

Here is an example response:

{
    "data": [
        {
            "employeeId": 523163,
            "securityDecisionScore": 100,
            "securityDecisionScoreThreshold": "LOW",
            "overallRiskScore": 50,
            "overallRiskScoreThreshold": "MED",
            "liklihoodRiskScore": 77,
            "liklihoodRiskScoreThreshold": "HIGH",
            "impactRiskScore": 0,
            "impactRiskScoreThreshold": "LOW"
        }
        ...
    ],
    "total": 52,
    "nextPageCursor": "eyJzdGFydCI6NSwibWF4SWQiOjE4MTQ3MX0="
}

Behavioural Event Creation 

Creates an event for a new or existing behaviour (Security decision) against a given employee, if you're creating an event for a new behaviour it must be set-up by an admin within Custom Behaviour settings before the CultureAI Platform will process the event.

Requires the behaviour.event.create scope.

Please note that behavioural event creation is a paid upgrade to your CultureAI account. If you'd be interested in trailing this, please get in touch with your account manager.

Request 

A dot implies the following key is in a sub object of the previous. So foo.bar would have bar in the object foo

POST https://client-api.culture.ai/v1/risks
Accept: application/json
Authorization: Basic <API_KEY>

{
    "behaviour": {
        "reference": "LEAVING_DESKTOP_UNLOCKED"
    },
    "event": {
        "employee": {
            "email": "robby.rogers@culture.ai"
        },
        "reference": 5000,
        "date": "2024-02-22",
        "time": "09:58:32",
        "description": "Laptop was left unlocked on longue table",
        "metadata": [
            {
                "key": "area",
                "value": "Social Lounge 1",
                "important": true
            },
            {
                "key": "spottedBy",
                "value": "IT Support",
                "important": false
            },
            {
                "key": "operatingSystem",
                "value": "Windows",
                "important": false
            }
        ]
    }
}

Response 

Here is an example response when ingesting an event for a new behaviour, note how the id is null because the event has not been processed and the status is PENDING_BEHAVIOUR_SETUP to indicate the event was ingested to a behaviour which has not been set-up within Custom Behaviour settings:

{
    "id": null,
    "ingestionId": 16,
    "status": "PENDING_BEHAVIOUR_SETUP"
}

Here is an example response when ingesting an event for a behaviour which has already been set-up, the event will appear immediately in the UI with triggered processes such as Interventions & Just-in-time-education processing within a few minutes of ingestion, usually within a minute.

{
    "id": 5313640,
    "ingestionId": 17,
    "status": "INGESTED"
}

List Email Reports 

Fetches email reports from users submitted by the CultureAI reporting plugin or synchronized via integration.

Requires the triage.reports.emails.read scope.

This API supports the standard pagination parameters, in addition to:

GET https://client-api.culture.ai/v1/triage/reports/emails
Accept: application/json
Authorization: Basic <API_KEY>

Note, some fields may be returned as 'null' where the source does not provide sufficient metadata (e.g. 3rd party integration).

Here is an example response:

[
  {
    "caseId": 10,
    "reportType": "CULTUREAI",
    "reportTypeId": 406,
    "externalReference": null,
    "reportedAt": "2021-11-30 22:11:19",
    "isSimulated": 0,
    "isSharedMailbox": 0,
    "recipients": [
      {
        "name": "Bob Smith",
        "email": "bob.smith@culture.ai"
      },
      {
        "name": "Another User",
        "email": "another.user@culture.ai"
      }
    ],
    "sender": {
      "name": "payroll",
      "email": "urgent@thirdparty.culture.ai"
    },
    "subject": "Urgent: Payroll details need updating",
    "riskScore": 97,
    "attachments": 1,
    "reportedBy": {
      "id": 46,
      "name": "Targeted User",
      "email": "targeted.user@culture.ai"
    },
    "reportReason": "PHISHING",
    "interactions": ['CLICKED']
  }
]

Fetch Reported Email Contents 

Fetches a reported email and associated metadata, only supported for the 'CULTUREAI' report source.

Requires the triage.reports.emails.detail scope.

Request

GET https://client-api.culture.ai/v1/triage/reports/emails/detail
Accept: application/json
Authorization: Basic <API_KEY>
Content-Type: application/json

{
  "reportType": "CULTUREAI",
  "reportTypeId": 406
}

Here is an example response:

{
  "headers": "Received: from ...",
  "links": [
    "https:\/\/app.domain.eu\/account\/profile\/u-tQ0u6I-g11j9",
    "https:\/\/app.domain.eu\/monitors\/686069?to_ts=1638299909000",
    "https:\/\/app.domain.eu\/monitors#686069\/edit",
    "https:\/\/app.domain.eu\/event\/event?id=6275296781375450081",
    "https:\/\/app.domain.eu\/account\/login\/mobile?dd_referrer=subscription_email&dd_m=1&",
    "https:\/\/app.domain.eu\/account\/preferences"
],
  "body": "<html><head>\r\n<meta http-equiv=\"Co...",
  "attachments": [],
  "raw": "UmVjZWl2ZWQ6IGZyb20gQ1dMUDEyM01CMzc3OS5HQlJ..."
}

Bug Reports & Feature Requests

If you spot anything wrong with our APIs (We're only human!) or have new features you'd like to see, or data you'd like to pull out, don't hesitate to contact us on success@culture.ai.