openapi: 3.0.3
info:
title: Core V2 Audit API
version: 2.0.0
description: This is the APIs for V2 Core. It allows you to do common operations, such as read audit entries or get workflow lists.
contact:
name: FrankieOne
url: https://www.frankieone.com/
email: help@frankieone.com
servers:
- url: https://api.uat.frankie.one
security:
- Api-Key: []
tags:
- name: Audit
description: Manage audit entries
paths:
/v2/audit:
parameters:
- $ref: '#/components/parameters/Api-Key'
- $ref: '#/components/parameters/X-Frankie-CustomerID'
- $ref: '#/components/parameters/X-Frankie-CustomerChildID'
- $ref: '#/components/parameters/X-Frankie-Channel'
get:
summary: List audit events
description: List all audit events with filtering.
parameters:
- $ref: '#/components/parameters/query_filter_entity_id'
- $ref: '#/components/parameters/query_filter_workflow_names'
- $ref: '#/components/parameters/query_filter_workflow_risk_levels'
- $ref: '#/components/parameters/query_filter_sources'
- $ref: '#/components/parameters/query_filter_request_id'
- $ref: '#/components/parameters/query_filter_timestamp_after'
- $ref: '#/components/parameters/query_filter_timestamp_before'
- $ref: '#/components/parameters/query_filter_channels'
- $ref: '#/components/parameters/sort'
- $ref: '#/components/parameters/query_sort_fields'
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/limit'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
requestId:
$ref: '#/components/schemas/Request-ID'
meta:
$ref: '#/components/schemas/List-Operation-Meta'
events:
description: List of audit events matching the query.
type: array
items:
$ref: '#/components/schemas/Audit'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
Invalid EntityId:
value:
errorCode: API-0400,
errorMsg: 'Multiple Errors: See Issues list'
details:
- issue: 'entityId in path must be of type uuid: "test"'
issueLocation: VALIDATE-entityId
requestId: 01HM5XJ7VASZ3EJMB1VQGTBFJ4
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
Invalid authentication:
value:
errorCode: AUTH-0002,
errorMsg: Unauthorized
details:
- issue: Invalid Authentication provided. Access denied.
issueLocation: request
requestId: 00000000S6MNG7624K2TDXT1E3
No Api-Key:
value:
errorCode: AUTH-0401
errorMsg: Unauthorized
details:
- issue: No api key provided. Access denied.
issueLocation: request
requestId: 00000001S6MNG7624K2TDXT1E3
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
operationId: listAuditEvents
tags:
- Audit
security:
- Api-Key: []
components:
schemas:
Supplementary-Data-AuditEvent-KYC:
type: object
description: 'Contains requirements and results for KYC supplementary data.
'
allOf:
- $ref: '#/components/schemas/Supplementary-Data-AuditEvent-Base'
- type: object
description: 'Contains requirements and results for KYC supplementary data.
'
properties:
requirements:
type: string
description: The requirements for this KYC check.
result:
type: string
description: The result of this KYC check.
Workflow-Step-Summary-Entity-Lookup-Address:
type: object
description: 'Object containing address details, categorized by address type.
Each address type may include specific properties relevant to its context.
'
properties:
RESIDENTIAL:
description: 'Represents a residential address, typically used for services or communications directed to personal living spaces.
'
$ref: '#/components/schemas/Workflow-Step-Summary-Entity-Lookup-Residential'
Code-Description:
type: object
properties:
code:
description: Short standard code or normalized representation of the information
type: string
description:
description: The information relevant to the code, could be a more descriptive information
type: string
Audit-Event-Result-Summary:
type: object
properties:
sourceNormalized:
type: string
description: The normalized source of the event or result.
objectId:
type: string
description: The identifier of the object used by the connector, if known.
objectType:
type: string
description: The type of object used by the connector, if known.
result:
type: string
description: The outcome of the action or check, e.g., "MATCH" or "TokenRetrieved".
notes:
$ref: '#/components/schemas/Custom-Attributes'
Workflow-Step-Risk-Result:
type: object
description: 'Calculated risk result for a workflow step.
'
properties:
level:
type: string
description: Current risk level.
contributedScore:
type: integer
description: Risk score contributed by this step.
overallScore:
type: integer
description: Current overall risk score.
factors:
type: array
description: List of contributing score factors.
items:
$ref: '#/components/schemas/Workflow-Step-Risk-Result-Detail'
Supplementary-Data-AuditEvent-AML-Connector:
type: object
description: 'Includes requirements and results for AML Connector supplementary data.
'
allOf:
- $ref: '#/components/schemas/Supplementary-Data-AuditEvent-Base-Connector'
- type: object
description: Includes requirements and results for AML Connector supplementary data.
properties:
numHits:
type: integer
format: int32
minimum: 0
description: Total number of AML hits from this provider.
numFalsePositives:
type: integer
format: int32
minimum: 0
description: Total number of AML hits marked as false positives from this provider.
numTruePositives:
type: integer
format: int32
minimum: 0
description: Total number of AML hits marked as true positives from this provider.
numUnknown:
type: integer
format: int32
minimum: 0
description: Total number of AML hits marked as unknown from this provider.
numUnresolved:
type: integer
format: int32
minimum: 0
description: Total number of AML hits that remain unresolved from this provider.
numUnresolvedPEP:
type: integer
format: int32
minimum: 0
description: Total number of AML hits with unresolved PEP entries from this provider.
numUnresolvedSanction:
type: integer
format: int32
minimum: 0
description: Total number of AML hits with unresolved sanction entries from this provider.
numUnresolvedWatchlist:
type: integer
format: int32
minimum: 0
description: Total number of AML hits with unresolved watchlist entries from this provider.
numUnresolvedAdverseMedia:
type: integer
format: int32
minimum: 0
description: Total number of AML hits with unresolved adverse media entries from this provider.
Issue:
type: object
properties:
issue:
type: string
description: Description of the issue.
issueLocation:
type: string
description: The location or context where the issue was identified.
issueType:
type: string
description: The type or category of the issue.
Workflow-Step-Risk-Result-Detail:
type: object
description: 'Details of a calculated risk result for a workflow step.
'
required:
- factor
- score
- value
properties:
factor:
type: string
description: Name of the risk factor contributing to this score.
score:
type: integer
description: Score contributed by this factor.
value:
type: string
description: Value used for the score factor.
Request-ID:
type: string
example: 01HN9XHZN6MGXM9JXG50K59Q85
description: The unique request identifier for the API call made.
Supplementary-Data-AuditEvent-Base-Connector:
type: object
required:
- type
allOf:
- $ref: '#/components/schemas/Supplementary-Data-AuditEvent-Base'
- type: object
properties:
connectorName:
type: string
description: The connector service used to generate the result.
connectorDriverName:
type: string
description: The specific connector driver used to generate the result.
connectorConfiguration:
type: array
items:
$ref: '#/components/schemas/Audit-Event-Connector-Config'
description: The configuration used by the connector for processing the request.
validationIssues:
type: array
items:
$ref: '#/components/schemas/Audit-Event-Error'
description: Any issues found during validation that prevented the connector from processing the request.
resultSummary:
type: array
items:
$ref: '#/components/schemas/Audit-Event-Result-Summary'
description: A summary of the results of the check performed by this connector.
Audit-Result-Change:
type: object
properties:
objectId:
type: string
description: Unique identifier of the object that was changed.
objectType:
type: string
description: Type of the object that was changed, e.g., "result".
changeDescription:
type: string
description: Description of the change that was made.
previousStatus:
type: string
description: The status of the object before the change.
newStatus:
type: string
description: The status of the object after the change.
Entity-ID:
type: string
description: 'Entities are assigned an auto-generated UUID to ensure global uniqueness, represented as entityId. The entityId allows for precise modification when required.
To modify an entity, set the entityId of the entity you wish to update in an update request.'
example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
readOnly: true
Matchlist-Entry-Reason-Code:
type: string
description: The reason code for the matchlist entry. This code will be translated to a configured description string. Supported codes are 1 to 24 characters long, consisting only of uppercase letters (A-Z), digits (0-9), underscores (_), or hyphens (-), with no spaces or special characters.
pattern: ^[A-Z0-9_-]{1,24}$
Supplementary-Data-AuditEvent-Individual-Change:
type: object
description: 'Contains information about changes to individual KYC supplementary data, including added, updated, invalidated fields, and validation issues.
'
allOf:
- $ref: '#/components/schemas/Supplementary-Data-AuditEvent-Base'
- type: object
properties:
fieldsAdded:
type: array
items:
$ref: '#/components/schemas/Audit-Event-Change'
description: New fields that were added.
fieldsUpdated:
type: array
items:
$ref: '#/components/schemas/Audit-Event-Change'
description: Fields that were updated.
fieldsInvalidated:
type: array
items:
$ref: '#/components/schemas/Audit-Event-Change'
description: Fields that were changed and invalidated a result.
resultsInvalidated:
type: array
items:
$ref: '#/components/schemas/Audit-Event-Change'
description: Results that were invalidated.
validationIssues:
type: array
items:
$ref: '#/components/schemas/Audit-Event-Error'
description: Issues found during validation that prevented the change from being made.
Supplementary-Data-AuditEvent-Matchlist-Entries:
type: object
description: 'Contains audit event details for managing multiple matchlist entries. Only a summary of the changes is provided, not the full list of entries.
For a single operation, use `Supplementary-Data-AuditEvent-Matchlist-Entry`.
'
allOf:
- $ref: '#/components/schemas/Supplementary-Data-AuditEvent-Base'
- $ref: '#/components/schemas/Audit-Matchlist'
- type: object
properties:
entries:
$ref: '#/components/schemas/Audit-Matchlist-Entries'
Supplementary-Data-AuditEvent-Organization-Data-Fetch-Connector:
type: object
description: Contains details relevant to KYB Connector audit events.
allOf:
- $ref: '#/components/schemas/Supplementary-Data-AuditEvent-Base-Connector'
Supplementary-Data-AuditEvent-Activity-Result:
type: object
properties:
result:
type: string
description: The overall result of the activity.
class:
type: string
description: The classification of the result.
riskLevel:
type: string
description: The risk level associated with the activity.
activities:
type: array
items:
$ref: '#/components/schemas/Supplementary-Data-AuditEvent-Activity-Detail'
Activity-ID:
type: string
readOnly: true
description: Activity ID that identifies an activity within the Frankie platform
format: ulid
AuditEvent-Channel:
type: string
example: API
description: The channel through which the audit event was generated.
enum:
- API
- PORTAL
- ONESDK
- SYSTEM
Error-Base:
type: object
properties:
errorCode:
type: string
errorMsg:
type: string
details:
type: array
items:
$ref: '#/components/schemas/Issue'
Process-Result-ID:
type: string
description: When a process result object is first created, it is assigned an ID. When updating the process result object, set the processResultID to the ID of the process result object you are referring to.
readOnly: true
Supplementary-Data-AuditEvent-Activity-Detail:
type: object
properties:
activityId:
$ref: '#/components/schemas/Activity-ID'
processResultId:
$ref: '#/components/schemas/Process-Result-ID'
Supplementary-Data-AuditEvent-Duplicate:
type: object
description: 'Contains details relevant to duplicate hits for an audit event.
'
allOf:
- $ref: '#/components/schemas/Supplementary-Data-AuditEvent-Base'
- type: object
properties:
result:
type: string
description: The result of the duplicate check.
duplicates:
type: array
description: The list of entities found to be duplicates, along with their respective process result IDs.
items:
type: object
properties:
entityId:
$ref: '#/components/schemas/Entity-ID'
processResultId:
$ref: '#/components/schemas/Process-Result-ID'
Supplementary-Data-AuditEvent-IDV-Connector:
type: object
description: 'Contains requirements and results for IDV Connector supplementary data.
'
allOf:
- $ref: '#/components/schemas/Supplementary-Data-AuditEvent-Base-Connector'
- type: object
description: Contains requirements and results for IDV Connector supplementary data.
properties:
notes:
$ref: '#/components/schemas/Custom-Attributes'
Audit-Matchlist:
type: object
description: 'Contains details about a matchlist used in an audit event.
'
properties:
matchlist:
type: object
properties:
name:
type: string
description: 'The unique name identifying the matchlist.
'
action:
$ref: '#/components/schemas/Matchlist-Action'
description: 'The action to be taken if a match is found in the matchlist.
'
riskScore:
type: number
description: 'The risk score to assign if there is a match, unless overridden by risk configuration.
'
Supplementary-Data-AuditEvent-Decision:
type: object
description: 'Includes requirements and results for Decision Step supplementary data.
'
allOf:
- $ref: '#/components/schemas/Supplementary-Data-AuditEvent-Base'
- type: object
properties:
previous:
type: object
description: Shows the previous status.
properties:
workflowStatus:
type: string
Audit-Event-Risk-Override-Result:
type: object
description: 'Represents the risk profile of an entity before and after a risk override, including details about the type of override applied.
'
required:
- overrideType
properties:
riskBeforeOverride:
type: object
description: The risk profile of the entity before the override was applied.
properties:
riskScore:
type: number
description: The risk score of the entity before the override.
riskLevel:
$ref: '#/components/schemas/Risk-Level'
description: The risk level of the entity before the override.
overrideType:
type: string
description: 'The type of risk override that was applied.
- `SPECIFIC`: Only a specific risk factor of the entity was overridden. This does not immediately change the overall risk level or score, but will impact the next run of the workflow.
- `OVERALL`: All risk factors of the entity were overridden, which changes both the current risk score and the risk level.
'
enum:
- SPECIFIC
- OVERALL
riskAfterOverride:
type: object
description: The risk profile of the entity after the override was applied.
properties:
level:
$ref: '#/components/schemas/Risk-Level'
description: The risk level of the entity after the override.
score:
type: integer
description: The risk score after the override.
factors:
type: array
description: A list of risk factors considered during the override process.
items:
$ref: '#/components/schemas/Audit-Event-Risk-Factor-Override-Data'
Audit-Event-Change:
type: object
properties:
objectId:
type: string
description: Unique identifier of the object that was changed.
objectType:
type: string
description: Type of the object that was changed, e.g., "User" or "Name".
changeDescription:
type: string
description: Description of the change that was made, including which fields were added, modified, or deleted.
Supplementary-Data-AuditEvent-Fraud-Details:
type: object
description: Details of a single fraud check result.
properties:
checkType:
$ref: '#/components/schemas/Fraud-Check-Types'
processResultId:
$ref: '#/components/schemas/Process-Result-ID'
result:
type: string
description: The outcome of the fraud check.
Supplementary-Data-AuditEvent-Base:
type: object
required:
- type
properties:
type:
type: string
enum:
- RISK_ASSESSMENT
- KYC
- DECISION
- KYC_CONNECTOR
- INDIVIDUAL_CHANGE
- KYB
- ORG_DATA_FETCH_CONNECTOR
- RESULT_UPDATE
- AML_CONNECTOR
- AML
- IDV
- IDV_CONNECTOR
- RISK_OVERRIDE
- ENTITY_LOOKUP
- MATCHLIST
- MATCHLIST_ENTRY
- MATCHLIST_ENTRIES
- MATCHLIST_RESULT
- VISA
- ACTIVITY
- FRAUD
origin:
$ref: '#/components/schemas/Audit-Event-Origin'
errors:
type: array
items:
$ref: '#/components/schemas/Audit-Event-Error'
description: Any errors that occurred during the process and prevented the results from being retrieved or generated.
Supplementary-Data-AuditEvent-Matchlist:
type: object
description: 'Contains details relevant to managing a matchlist for an audit event.
'
allOf:
- $ref: '#/components/schemas/Supplementary-Data-AuditEvent-Base'
- $ref: '#/components/schemas/Matchlist-Base'
Supplementary-Data-AuditEvent-KYB:
type: object
description: 'Captures details relevant to KYB processes and is associated with specific KYB-related audit events.
Associated audit events include: creation of an entity, creation of a service profile for an entity, invoking a workflow, and saving organizations and linked entities to Org-DOS.
'
allOf:
- $ref: '#/components/schemas/Supplementary-Data-AuditEvent-Base'
- type: object
properties:
matchDetails:
$ref: '#/components/schemas/Audit-Event-Organization-Entity-Match'
linkedOrganizationIds:
type: array
description: List of organization IDs related to the focus organization.
items:
type: string
format: uuid
linkedIndividualIds:
type: array
description: List of individual IDs related to the focus organization.
items:
type: string
format: uuid
linkedUnknownIds:
type: array
description: List of unknown entity IDs related to the focus organization.
items:
type: string
format: uuid
Supplementary-Data-AuditEvent-AML:
type: object
description: 'Includes requirements and results for AML supplementary data.
'
allOf:
- $ref: '#/components/schemas/Supplementary-Data-AuditEvent-Base'
- type: object
description: 'Includes requirements and results for AML supplementary data.
'
properties:
result:
type: string
description: The result of the AML check.
numHits:
type: integer
format: int32
minimum: 0
description: Total number of AML hits from this provider.
numFalsePositives:
type: integer
format: int32
minimum: 0
description: Total number of AML hits marked as false positives from this provider.
numTruePositives:
type: integer
format: int32
minimum: 0
description: Total number of AML hits marked as true positives from this provider.
numUnknown:
type: integer
format: int32
minimum: 0
description: Total number of AML hits marked as unknown from this provider.
numUnresolved:
type: integer
format: int32
minimum: 0
description: Total number of AML hits that remain unresolved from this provider.
numUnresolvedPEP:
type: integer
format: int32
minimum: 0
description: Total number of AML hits with unresolved PEP entries from this provider.
numUnresolvedSanction:
type: integer
format: int32
minimum: 0
description: Total number of AML hits with unresolved sanction entries from this provider.
numUnresolvedWatchlist:
type: integer
format: int32
minimum: 0
description: Total number of AML hits with unresolved watchlist entries from this provider.
numUnresolvedAdverseMedia:
type: integer
format: int32
minimum: 0
description: Total number of AML hits with unresolved adverse media entries from this provider.
Supplementary-Data-AuditEvent-KYC-Connector:
type: object
description: 'Contains requirements and results for KYC Connector supplementary data.
'
allOf:
- $ref: '#/components/schemas/Supplementary-Data-AuditEvent-Base-Connector'
Audit-Event-Risk-Factor-Override-Data:
type: object
description: Information about a risk factor that has been manually overridden, including details of the factor, original and override scores, and the override process.
required:
- factor
- score
- value
properties:
factor:
type: string
description: The name of the risk factor that was overridden.
score:
type: integer
description: The original score of the risk factor before the override was applied.
value:
type: string
description: The value associated with the risk factor.
manualOverrideScore:
type: number
description: The manually assigned score for the risk factor, replacing the original score when the override is applied.
status:
$ref: '#/components/schemas/Risk-Factor-Status'
Audit-Matchlist-Entry:
type: object
description: 'A single entry in a matchlist.
For bulk operations, use `Audit-Matchlist-Entries`.
'
allOf:
- $ref: '#/components/schemas/Matchlist-Entry-Base'
- type: object
description: 'Audit event details for managing a single matchlist entry operation.
'
title: Matchlist Entry
properties:
attributes:
type: array
description: 'A list of attributes associated with the matchlist entry, including details such as attribute type, value, and any additional metadata relevant to the entry.
'
minItems: 1
items:
$ref: '#/components/schemas/Matchlist-Entry-Attribute-Type'
state:
$ref: '#/components/schemas/Matchlist-Entry-State'
batchName:
type: string
description: 'Optional batch name to identify the source of this entry.
'
example: blocklist.csv
Supplementary-Data-AuditEvent-IDV:
type: object
description: 'Contains requirements and results for KYC supplementary data.
'
allOf:
- $ref: '#/components/schemas/Supplementary-Data-AuditEvent-Base'
- type: object
description: 'Contains requirements and results for KYC supplementary data.
'
properties:
idvRequirements:
type: array
items:
type: string
description: The requirements for this IDV check.
result:
type: string
description: The result of this IDV check.
notes:
$ref: '#/components/schemas/Custom-Attributes'
resultSummary:
type: array
items:
$ref: '#/components/schemas/Audit-Event-Result-Summary'
description: A summary of the results.
Supplementary-Data-AuditEvent-Matchlist-Result:
type: object
description: 'Contains audit event details for matchlist screening results.
'
allOf:
- $ref: '#/components/schemas/Supplementary-Data-AuditEvent-Base'
- type: object
properties:
totalMatches:
type: integer
format: int32
minimum: 0
description: Total number of matches across all matchlists.
matchSummaries:
type: array
description: Summary of results for each provider.
items:
type: object
allOf:
- $ref: '#/components/schemas/Audit-Matchlist'
properties:
numMatches:
type: integer
format: int32
minimum: 0
description: Number of matched entries in the matchlist.
entries:
type: array
description: List of matched entries.
items:
$ref: '#/components/schemas/Audit-Matchlist-Entry'
Risk-Factor-Status:
type: string
enum:
- VALID
- STALE
- OVERRIDDEN
- DISCARDED
description: "The current status of the risk factor:\n - VALID: The risk factor is applicable to the entity.\n - STALE: The risk factor is no longer applicable to the entity. If this status is returned, it means that at the time of risk assessment, the risk factor was valid.\n - OVERRIDDEN: The risk factor was manually overridden. If present, manualOverrideScore was used for risk score calculation in the risk assessment.\n - DISCARDED: The risk factor was added during workflow execution but was discarded at a later stage in the same workflow. This factor was not used in the final risk assessment.\n"
default: VALID
Error:
type: object
x-examples:
'400':
requestId: 0123456789ABCDEFGHIJKLMNOP
errorCode: API-0400
errorMsg: Parsing credentials from "<invalid>" failed, because invalid.
httpStatusCode: 400
'401':
requestId: 0123456789ABCDEFGHIJKLMNOP
errorCode: API-0401
errorMsg: Unauthenticated due to invalid credentials.
httpStatusCode: 401
'409':
requestId: 0123456789ABCDEFGHIJKLMNOP
errorCode: API-0409
errorMsg: Conflict.
httpStatusCode: 409
allOf:
- $ref: '#/components/schemas/Error-Base'
- type: object
properties:
requestId:
$ref: '#/components/schemas/Request-ID'
Matchlist-Action:
type: string
description: "Default action recommended for a match. The action can be one of the following:\n - `BLOCK`
# --- truncated at 32 KB (65 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/frankieone/refs/heads/main/openapi/frankieone-audit-api-openapi.yml