Fetch Audit Events

The Productiv events API is an administration API that can be used to fetch a stream of audit events for activities performed by users using the Productiv platform. The API provides information for different types of actions that a user has performed as described in this section.

Prerequisites

  • In order to query this API, you would also need to send an access_token as part of the Authorization header. To see the steps for generating an access token check out Authorization.

Get Audit Events Endpoint

GET https://public-api.productiv.com/services/pull/v1/customer/audit-events

Include the following headers and path parameters along with your requests:

Headers

Parameter Value
content-type application/json
Authorization Bearer access_token
Required Scope https://api.productiv.com/report.read

Query Params

Parameter Description
startTime Timestamp in ISO format for the start of the time range (inclusive) to query events for. Ex. 2020-01-01T00:00:00Z
endTime Timestamp in ISO format for the end of the time range (exclusive) to query events for. Ex. 2020-02-01T00:00:00Z
pageToken (Optional) To get the next page of events in the time range after the previous query response.
  • Each request returns a max of 500 events at a time. If there are potentially more events in the queried time range, the response contains a nextPageToken.
  • The API can only be queried with the oldest startTime of 180 days ago.
  • The API can only be queried for a maximum time range of 30 days at a time.

Response

If the request is successful, a JSON response will be returned. This JSON object will contain the following parameters:

Parameter Description
success Will be set to true in case of a successful response.
nextPageToken A successful query only contains upto 500 events in the response. If the queried time range has more than 500 events, then the nextPageToken is returned. This can be used to query the next page of events in the time range. If no nextPageToken is returned, then no more events are present in the time range.
events An array of Audit Events for the queried time range. 
{
    "success": Boolean,
    "nextPageToken": String,
    "events": [
        {
            "id": String,
            "ts": String,
            "eventType": String,
            "userId": String,
            "eventProperties": Map<String,Any>
        }
    ]
}

Audit Event Object

Every audit event should have the following properties in the object:

Property Datatype Description
id String Unique id for the event
ts String UTC Timestamp in ISO format of the event.
eventType String Type of event from the list of supported event types.
userId String Email of the user who performed the event.
eventProperties (optional) Map Event-specific properties (if any) as per the eventType. See event types for details.

Audit Event Object Schema Examples

{
    "id": "250cf8b51c773f3f8dc8b4be867a9a12",
    "ts": "2020-10-01T00:00:00Z",
    "eventType": "LoggedIn",
    "userId": "testuser@random.com"
}

{
  "id": "250cf8b51c773f3f8dc8b4be867a9a12",
  "ts": "2020-10-01T00:00:00Z",
  "eventType": "AppConnected",
  "userId": "testuser@random.com",
  "eventProperties": {
    "app": "test-app"
  }
}

Audit Event Types

We record the following kinds of event types based for the actions performed by users in the Productiv platform.

Event Type Category Event-specific Properties Returned Description
LoggedIn Access Management N/A A user logged in
AdminAddedUser Access management provisionedUserId(String), roles(Array), allowedApps(Array) A superadmin added a new user to the account
AdminRemovedUser Access management deprovisionedUserId(String) A superadmin removed an existing user from the account
AdminUpdatedUserRole Access management provisionedUserId(String), roles(Array) A superadmin changed the role for an existing user
AppConnected App connection app(String) An app integration was connected
AppDisconnected App connection app(String) An app integration was deauthorized
AppRemoved App connection app(String) An app integration and data was removed
UploadedOrgData Data upload N/A New org chart was uploaded
UploadedContractCsv Data upload N/A A contract csv file was ingested
UploadedContractFile Data upload N/A A contract pdf file was uploaded
UploadedSpendCsv Data upload N/A A spend export was uploaded
DownloadedUsersList Data download N/A A csv file report for usage data by user was downloaded
DownloadedContractCsv Data download N/A An ingested contract csv file was downloaded
DownloadedContractFile Data download N/A An uploaded contract pdf file was downloaded
DownloadedSpendCsv Data download N/A An uploaded spend export was downloaded
DownloadedOrgData Data download N/A The current org chart data was downloaded as a csv file

Response Errors

Error Code Error Message Description
400 Bad Request Returned if any invalid/unexpected query parameter/value is present in the request.
401 Unauthorized Returned if access_token used in request is invalid or expired.
403 Forbidden Returned if access_token does not have the required scope to use this API.
422 Unprocessable Entity Returned if the request payload is invalid
429 Too Many Requests Returned if rate limit has been exceeded
500 Internal Server Error Unknown error processing the request

Example Error Response Schema

{
    "code": "401",
    "message": "Invalid access_token",
    "success": false
}