Time	Status	User Agent
Retrieving recent requests…

Overview

The audit trail events method allows you to track and investigate actions that your employees perform in the Sumsub Dashboard. It can be used to monitor team activity, ensure compliance, and detect suspicious operations. This method is particularly useful when you need a detailed activity log for a specific employee, for example, during internal reviews or regulatory audits.

You can access audit trail data in the following ways:

API request — supports the complete set of event types, covering activities such as logins, applicant management actions, data downloads, exports, and more. You can filter results by employee, action type, and time range using Query Params when making a request. To understand how to interpret the API response, refer to the Response explained section.
Dashboard — provides access to a limited activity log on the Team → Activity log page, showing team and permission management actions, such as creating or updating accounts, changing roles, and so on. You can filter results by date range and action type directly on the page. All other event types can only be retrieved through the API.

🚧
Attention
This feature is available at an additional cost. Contact us to learn more.

📘
Notes

Events are sorted by event ID in ascending order.

The maximum number of events per request is 1000. Use the forwardMarker cursor to iterate over larger result sets.

Pagination

This endpoint uses forward-only cursor pagination. Keep the following in mind when making requests:

In the initial request, omit forwardMarker. Set from and to to define the time window.
If forwardMarker is returned in the response, pass it in the subsequent request to retrieve the next page.
If forwardMarker is not returned, you have reached the last page.

Request examples

// Example of initial request without 'forwardMarker'.

curl -X GET \
  'https://api.sumsub.com/resources/auditTrailEvents/list?from=2024-06-01+00:00:00&to=2024-06-30+23:59:59&limit=100' \
  -H 'X-App-Token: <your-app-token>' \
  -H 'X-App-Access-Sig: <your-signature>' \
  -H 'X-App-Access-Ts: <unix-timestamp>'

// Example of the following request where 'forwardMarker' has a priority, so 'from' is ignored when 'forwardMarker' and 'from' are provided together.

curl -X GET \
  'https://api.sumsub.com/resources/auditTrailEvents/list?from=2024-06-01+00:00:00&to=2024-06-30+23:59:59&[email protected]&activity=subject:loggedIn:dashboard:success&forwardMarker=eyJpZCI6IjY2NTlhMWIyYzNkNGU1ZjZhN2I4YzlkMSJ9&limit=100' \
  -H 'X-App-Token: <your-app-token>' \
  -H 'X-App-Access-Sig: <your-signature>' \
  -H 'X-App-Access-Ts: <unix-timestamp>'

Response explained

The response is a JSON object containing a page of audit trail events and a pagination cursor.

Field	Type	Description
`items`	Array of objects	List of audit trail events for the current page, ordered by event ID ascending.
`forwardMarker`	String	Cursor for the next page. Absent or `null` when this is the last page.
`pageSize`	Integer	The `limit` value applied to this page.

`items` element fields

Field	Type	Description
`id`	String	Unique event identifier.
`ts`	String	Event timestamp in milliseconds since Unix epoch.
`clientId`	String	Unique identifier of you as our client in the Sumsub system.
`activity`	String	Event type.
`subjectName`	String	Employee that executed the action.
`ip`	String	IP address from which the event was detected.
`userAgent`	String	User agent from which the event was detected.
`xClientId`	String	Source of the action: API, Dashboard, or SDK.
`correlationId`	String	Internal ID for investigating requests.
`applicantId`	String	Unique applicant identifier in the Sumsub system.
`externalUserId`	String	Unique applicant identifier on your side.
`imageId`	String	Unique identifier of the document image.
`description`	String	Additional information.
`auditLogId`	String	Reference to the raw audit log entry.

Event types

Event type	Description
`subject:loggedIn:dashboard:success`	User successfully logged in to the Dashboard.
`subject:loggedIn:dashboard:failure`	User failed to log in to the Dashboard.
`subject:loggedOut:dashboard`	User logged out of the Dashboard.
`subject:changed:applicant`	User changed the applicant profile.
`subject:loaded:applicant`	User loaded an applicant page in the Dashboard.
`subject:loaded:applicantList`	User loaded a page with a list of applicants in the Dashboard. Also can be an applicant page if `cnt=1`.
`subject:searched:applicant`	User searched for applicants in the Dashboard.
`subject:exported:applicantCsvList`	User exported the applicant list under filters as CSV.
`subject:exported:applicantActionCsvList`	User exported a list of applicant actions under filters as CSV.
`subject:loaded:applicantAction`	User loaded an applicant action page in the Dashboard.
`subject:loaded:applicantActionList`	User loaded a page with a list of applicant actions in the Dashboard.
`subject:downloaded:docImage`	User downloaded the image on the applicant page (by manually clicking the Download button only). There are other ways to download the image without triggering this event.
`subject:changed:applicantLevel`	User changed the applicant level settings. For example, created a new level, or deleted the existing one, changed the steps, and so on.
`subject:changed:questionnaire`	User changed the questionnaire settings. For example, added a new question or deleted the existing one.
`subject:changed:globalSettings`	User changed the global settings. For example, recognition settings or allowed duplicates.
`subject:changed:flow`	User changed the flow settings. For example, added, updated, or deleted any flow in the UI in: Integrations → Customizations.
`subject:changed:licenseKey`	User changed license key. For example, created, updated, or deleted the license key in the UI in: Integrations → Global Settings → Source Keys.
`subject:changed:poaStepSettings`	User changed the PoA step settings. For example, created, updated, or deleted settings in the UI in: Integrations → Global Settings → User verification → Proof of Address.
`subject:changed:dictionary`	User changed one of the dictionaries (MobileSDK, WebSDK, Common, and so on). For example, created or updated dictionary in the UI in: Integrations → SDK Translations.
`subject:changed:paymentMethodDefinitions`	User changed payment methods settings. For example, created, updated, or deleted one of the payment method definitions in the UI in: Integrations → Payment methods.
`subject:modified:workflowRevision`	User changed the workflow revision in the UI in: Integrations → Applicant workflows.
`subject:published:workflowRevision`	User published the workflow revision in the UI in: Integrations → Applicant workflows.
`subject:archived:workflowRevision`	User archived the workflow revision in the UI in: Integrations → Applicant workflows.
`subject:changed:autoCheck`	User changed auto check settings. For example, created, updated, or deleted auto check in the UI in: Admin Area → Auto-checks.
`subject:created:appToken`	User created an app token in the UI in: Dev space → App tokens.
`subject:upgraded:appToken`	App token was upgraded via the internal API.
`subject:deleted:appToken`	User deleted app token in the UI in: Dev space → App tokens.
`subject:modified:user`	User parameters were modified.
`subject:deleted:user`	User was deleted.
`subject:reset:password`	Password has been reset via the Dashboard or link.
`subject:modified:2fa`	Two-factor authentication settings were modified.
`subject:downloaded:report`	User downloaded the report.
`subject:opened:transactionTable`	User opened a list of transactions — for example, the Transactions page or the Transactions tab on the applicant page in the Dashboard.
`subject:opened:singleTransaction`	User opened a specific transaction — for example, from the Transactions page in the Dashboard or via a direct link.

Response examples

If the request is successfully sent and processed, you will get a response like the following:

{
  "items": [
    {
      "id": "6659a1b2c3d4e5f6a7b8c9d0",
      "ts": "171720000000",
      "clientId": "yourClientId",
      "activity": "subject:changed:applicantLevel",
      "subjectName": "[email protected]",
      "ip": "203.0.113.42",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "xClientId": "dashboard",
      "correlationId": "6e4a6f3b2c1d0e9f8a7b6c6c",
      "applicantId": "5e4a6f3b2c1d0e9f8a7b6c5d",
      "externalUserId": "client-user-42",
      "imageId": "63f1a2b3c4d5e6f7a8b9c0d1",
      "description": "Applicant level updated from Basic to Advanced",
      "auditLogId": "6659a1b2c3d4e5f6a7b8c900"
    },  
    {
      "id": "6659a1b2c3d4e5f6a7b8c9d1",
      "ts": "1717200060000",
      "clientId": "yourClientId",
      "activity": "subject:loggedIn:dashboard:success",
      "subjectName": "[email protected]",
      "ip": "203.0.113.42",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "xClientId": "dashboard",
      "correlationId": "req-abc-456"
    }
  ],
  "forwardMarker": "eyJpZCI6IjY2NTlhMWIyYzNkNGU1ZjZhN2I4YzlkMSJ9",
  "pageSize": 100
}

When there are no more pages, forwardMarker is not returned in the response like in the following example:

{
  "items": [
    {
      "id": "6659a1b2c3d4e5f6a7b8c9ff",
      "ts": "1717200060000",
      "clientId": "yourClientId",
      "activity": "subject:loggedOut:dashboard",
      "subjectName": "[email protected]",
      "ip": "203.0.113.42"
    }
  ],
  "pageSize": 100
}

If the request fails, you will receive an HTTP response containing an error code along with a message explaining the error. For example:

{
  "code": 400,
  "description": "Description",
  "correlationId": "0d3457fdac54803edf23c90000000000"
}

Overview

Attention

Notes

Pagination

Request examples

Response explained

items element fields

Event types

Response examples

`items` element fields