openapi: 3.0.3 info: title: Core V2 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 - name: Request description: Retrieve background request results - name: Status description: All valid customers will get a successful response. 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: [] /v2/workflows: get: summary: Get a list of executable workflows responses: '200': description: OK content: application/json: schema: type: object properties: requestId: $ref: '#/components/schemas/Request-ID' workflows: type: array description: Provide a set of workflow lookup objects. items: $ref: '#/components/schemas/Workflow-Lookup' '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: getWorkflows description: Get a list of workflows that can be executed parameters: - $ref: '#/components/parameters/Api-Key' - $ref: '#/components/parameters/X-Frankie-CustomerID' - $ref: '#/components/parameters/X-Frankie-CustomerChildID' - $ref: '#/components/parameters/X-Frankie-Channel' - $ref: '#/components/parameters/X-Frankie-Username' - $ref: '#/components/parameters/serviceNameQuery' - $ref: '#/components/parameters/includeQuery' tags: - Individual Workflows security: - Api-Key: [] - jwt: - kyc:api /v2/search/serviceprofiles: parameters: - $ref: '#/components/parameters/sortFields' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/limit' post: summary: Search for profiles responses: '200': description: OK content: application/json: schema: properties: meta: $ref: '#/components/schemas/List-Operation-Meta' requestId: $ref: '#/components/schemas/Request-ID' matches: type: array items: $ref: '#/components/schemas/Search-Matches' '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: searchProfiles description: >- Search for Individuals and Organizations that match the provided search parameters. Search parameters are supplied in the form of an entity object. parameters: - $ref: '#/components/parameters/Api-Key' - $ref: '#/components/parameters/X-Frankie-CustomerID' - $ref: '#/components/parameters/X-Frankie-CustomerChildID' - $ref: '#/components/parameters/X-Frankie-Channel' - $ref: '#/components/parameters/X-Frankie-Username' requestBody: content: application/json: schema: $ref: '#/components/schemas/Search-Profile' description: Search for a profile tags: - Search security: - Api-Key: [] - jwt: - kyc:api /v2/search/matchlists: parameters: - $ref: '#/components/parameters/X-Frankie-CustomerID' - $ref: '#/components/parameters/X-Frankie-CustomerChildID' - $ref: '#/components/parameters/X-Frankie-RequestID' - $ref: '#/components/parameters/X-Frankie-Channel' post: summary: Search for matchlist entries description: Retrieve all matching entries for the search criteria. operationId: searchMatchlists tags: - Matchlists parameters: - $ref: '#/components/parameters/limit' requestBody: content: application/json: schema: $ref: '#/components/schemas/Search-Matchlists-Request' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Search-Matchlists-Matches-Response' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: Unprocessable content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Service Unavailable content: application/json: schema: $ref: '#/components/schemas/Error' /v2/matchlists: get: summary: Retrieve a list of matchlist details responses: '200': description: OK content: application/json: schema: type: object properties: requestId: $ref: '#/components/schemas/Request-ID' matchlists: type: array items: $ref: '#/components/schemas/Matchlist' '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: getMatchlist description: Retrieve a list of matchlists that new entries can be added or removed. parameters: - $ref: '#/components/parameters/Api-Key' - $ref: '#/components/parameters/X-Frankie-CustomerID' - $ref: '#/components/parameters/X-Frankie-CustomerChildID' - $ref: '#/components/parameters/X-Frankie-Channel' - $ref: '#/components/parameters/X-Frankie-Background' - $ref: '#/components/parameters/X-Frankie-Username' - $ref: '#/components/parameters/query_matchlist_states' tags: - Matchlists security: - Api-Key: [] - jwt: - kyc:api /v2/matchlists/{matchlistName}/entries: parameters: - $ref: '#/components/parameters/matchlistName' post: summary: Create one or more entries in a matchlist requestBody: content: application/json: schema: $ref: '#/components/schemas/Create-Matchlist-Entries-Request' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Matchlist-Entries-Response' '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: createMatchlistEntry description: >- Create a new entry in an existing matchlist. Entries must have at least one attribute and those attributes must be of valid types. Attribute values must have at least one non-whitespace character in their values. Optionally a batch name can be provided in the request, which will be applied to all given entries. The batch name should reflect the source of the entry list, for example blocklist.csv. The entries can later be retrieved by batch name. Optionally a reference can be provided for each entry in the request. The reference should be a unique name (but uniqueness is not required) from for example an externally sourced blocklist. The entries can later be retrieved by reference. Optionally each entry can refer to an entity ID and type (both ID and type, or neither), to indicate that the entry is based on en existing entity. parameters: - $ref: '#/components/parameters/Api-Key' - $ref: '#/components/parameters/X-Frankie-CustomerID' - $ref: '#/components/parameters/X-Frankie-CustomerChildID' - $ref: '#/components/parameters/X-Frankie-Channel' - $ref: '#/components/parameters/X-Frankie-Username' tags: - Matchlists security: - Api-Key: [] - jwt: - kyc:api get: summary: Get a list of matchlist entries responses: '200': description: OK content: application/json: schema: type: object properties: requestId: $ref: '#/components/schemas/Request-ID' entries: type: array items: $ref: '#/components/schemas/Matchlist-Entry' '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: getMatchlistEntries description: >- The query parameter `entityId` can be used to filter the entries by entity ID. The entity UUID must be in lower case. The query parameter `reference` can be used to filter the entries by reference. The query parameter `batchName` can be used to filter the entries by batch name. The query parameter `states` can be used to filter the entries by state. If set, the response will include only entries with the specified states. By default only `ACTIVE` entries are returned if the matchlist is `ACTIVE`. If the matchlist is `ARCHIVED` only `EXPIRED` entries will be returned. Possible values are: `ACTIVE`, `EXPIRED`, and `DELETED`. Multiple values can be provided as a comma-separated list. For example, `DELETED,EXPIRED`. The query parameter `sortFields` (`createdAt`, `updatedAt` or `state`) can be set to one or more fields for sorting. The default is to use just `createdAt`. The query parameter `sort` can set the sort order to ascending (`asc`) or descending (`desc`). The default is ascending. The query parameters `limit` (default 10) and `page` (default 1) can be used to control paging of the returned entries. The values given must be positive. If no matching entries are found, or the page is too large, then the entries array will be empty, but the result code is still 200. In addition to the entries, the response will also include the basic details of the matchlist, including its state. This is important, since if a matchlist is `ARCHIVED`, all previously `ACTIVE` entries will be `EXPIRED`, and will only be seen in the response if the `states` includes `EXPIRED`. So the entries array will be blank for `ARCHIVED` matchlists if `states` is not given. parameters: - $ref: '#/components/parameters/Api-Key' - $ref: '#/components/parameters/X-Frankie-CustomerID' - $ref: '#/components/parameters/X-Frankie-CustomerChildID' - $ref: '#/components/parameters/X-Frankie-Channel' - $ref: '#/components/parameters/X-Frankie-Username' - $ref: '#/components/parameters/query_entry_states' - $ref: '#/components/parameters/query_batch_name' - $ref: '#/components/parameters/query_reference' - $ref: '#/components/parameters/query_entity_id' - $ref: '#/components/parameters/query_entry_id' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/matchlist_sort_fields' - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/limit' tags: - Matchlists security: - Api-Key: [] - jwt: - kyc:api /v2/matchlists/{matchlistName}/entries/{entryId}: parameters: - $ref: '#/components/parameters/matchlistName' - $ref: '#/components/parameters/entryId' patch: operationId: updateMatchlistEntry summary: Modify a matchlist entry description: >- This can be used in updating a matchlist entry's non-attribute fields such as `reference`, `state`, `reason`. This endpoint can also be used to "delete" an entry by changing its state to `DELETED` and capturing comments. NOTE: Updating `attributes` field of a matchlist entry is not allowed. An entry could be used in existing matches, and modifying attributes directly could lead to inconsistencies. As a workaround, retrieve the entry details, then create a new entry with the original and updated values. The old entry should have its state changed to `DELETED`. requestBody: content: application/json: schema: type: object properties: entry: $ref: '#/components/schemas/Update-Matchlist-Entry-Request' comment: $ref: '#/components/schemas/Comment' responses: '200': description: OK content: application/json: schema: type: object properties: requestId: $ref: '#/components/schemas/Request-ID' entry: $ref: '#/components/schemas/Matchlist-Entry' '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' parameters: - $ref: '#/components/parameters/Api-Key' - $ref: '#/components/parameters/X-Frankie-CustomerID' - $ref: '#/components/parameters/X-Frankie-CustomerChildID' - $ref: '#/components/parameters/X-Frankie-Channel' - $ref: '#/components/parameters/X-Frankie-Background' - $ref: '#/components/parameters/X-Frankie-Username' tags: - Matchlists security: - Api-Key: [] - jwt: - kyc:api get: operationId: getMatchlistEntry summary: Retrieve a matchlist entry description: Retrieve a single matchlist entry using an entryId. responses: '200': description: OK content: application/json: schema: type: object properties: requestId: $ref: '#/components/schemas/Request-ID' entry: $ref: '#/components/schemas/Matchlist-Entry' '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' parameters: - $ref: '#/components/parameters/Api-Key' - $ref: '#/components/parameters/X-Frankie-CustomerID' - $ref: '#/components/parameters/X-Frankie-CustomerChildID' - $ref: '#/components/parameters/X-Frankie-Channel' - $ref: '#/components/parameters/X-Frankie-Background' - $ref: '#/components/parameters/X-Frankie-Username' tags: - Matchlists security: - Api-Key: [] - jwt: - kyc:api /v2/matchlists/{matchlistName}/entries/addEntity: parameters: - $ref: '#/components/parameters/matchlistName' post: summary: Add an individual entity to a matchlist requestBody: content: application/json: schema: $ref: '#/components/schemas/Add-Matchlist-Entity-Request' responses: '200': description: OK content: application/json: schema: type: object properties: requestId: $ref: '#/components/schemas/Request-ID' entry: $ref: '#/components/schemas/Matchlist-Entry' '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' '409': description: Conflict 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: addMatchlistEntity description: >- Creates an individual entity and its attributes as a new entry in an existing matchlist. parameters: - $ref: '#/components/parameters/Api-Key' - $ref: '#/components/parameters/X-Frankie-CustomerID' - $ref: '#/components/parameters/X-Frankie-CustomerChildID' - $ref: '#/components/parameters/X-Frankie-Channel' - $ref: '#/components/parameters/X-Frankie-Background' - $ref: '#/components/parameters/X-Frankie-Username' tags: - Matchlists security: - Api-Key: [] - jwt: - kyc:api /v2/matchlists/{matchlistName}/entries/removeEntity: parameters: - $ref: '#/components/parameters/matchlistName' patch: summary: Remove an individual entity matchlist requestBody: content: application/json: schema: $ref: '#/components/schemas/Remove-Matchlist-Entity-Request' responses: '200': description: OK content: application/json: schema: type: object properties: requestId: $ref: '#/components/schemas/Request-ID' entityId: $ref: '#/components/schemas/Entity-ID' matchlistId: $ref: '#/components/schemas/Matchlist-ID' state: $ref: '#/components/schemas/Matchlist-Entry-State' '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: removeMatchlistEntity description: >- Remove a matchlist entry's state using an entity ID. This automatically sets the state of the entry to `DELETED` . - **Important**: Deletion cannot be undone. - Delete a matchlist entry using the `entityId` associated with the entry. - Deleted entries will not be used for screening. - However, deleted entries can still be retrieved: - By `entityId`, using the multi-entry `GET` (list) API, by specifying an `includeStates` filter that includes `DELETED`. parameters: - $ref: '#/components/parameters/Api-Key' - $ref: '#/components/parameters/X-Frankie-CustomerID' - $ref: '#/components/parameters/X-Frankie-CustomerChildID' - $ref: '#/components/parameters/X-Frankie-Channel' - $ref: '#/components/parameters/X-Frankie-Background' - $ref: '#/components/parameters/X-Frankie-Username' tags: - Matchlists security: - Api-Key: [] - jwt: - kyc:api components: securitySchemes: Api-Key: type: apiKey in: header name: api_key description: '' jwt: type: http scheme: bearer bearerFormat: JWT parameters: Api-Key: name: api_key in: header schema: type: string example: 245c765b124a098d09ef8765.... description: Your API key provided by FrankieOne required: true X-Frankie-CustomerID: name: X-Frankie-CustomerID in: header required: true schema: type: string example: 12345678-1234-1234-1234-123456789012 description: Your Customer ID provided by FrankieOne X-Frankie-CustomerChildID: name: X-Frankie-CustomerChildID in: header required: false schema: type: string example: 87654321-4321-4321-4321-210987654321 description: Your Customer Child ID provided by FrankieOne X-Frankie-Channel: name: X-Frankie-Channel in: header required: false schema: type: string description: >- Open string that can be used to define the "channel" the request comes in from. It can potentially be used in routing and risk calculations upon request. Default values that can be used are: api portal smartui Any alphanumeric string is supported though. Anything over 64 characters will be truncated. query_filter_entity_id: name: entityId in: query schema: type: string description: Entity ID required: false query_filter_workflow_names: name: workflowNames in: query schema: type: array items: type: string description: List of Workflow Names to filter the audit events upon example: - KYC Onboarding - Transaction Monitoring required: false query_filter_workflow_risk_levels: name: workflowRiskLevels in: query schema: type: array items: type: string description: List of workflow risk levels to filter the audit events upon example: - LOW - HIGH required: false query_filter_sources: name: sources in: query schema: type: array items: type: string description: List of Sources that the audit events will be filtered upon example: - user@username.com - FrankieOne System - Experian Connector required: false query_filter_request_id: name: requestId in: query schema: type: string description: Request Identifier to filter the audit events upon required: false query_filter_timestamp_after: name: afterTimestamp in: query schema: type: string format: date description: >- Filter the Audit Events after the given filter based on the Event 'timestamp' value required: false query_filter_timestamp_before: name: beforeTimestamp in: query schema: type: string format: date description: >- Filter the Audit Events before the given filter based on the Event 'timestamp' value required: false query_filter_channels: name: channels in: query schema: type: array items: $ref: '#/components/schemas/AuditEvent-Channel' description: List of Channels to filter the audit events upon required: false sort: in: query name: sort schema: type: string enum: - asc - desc description: Order of the sort fields will be sorted upon query_sort_fields: name: sortFields in: query example: timestamp schema: type: array items: type: string enum: - timestamp description: >- The list of sort fields that will be used in the query, the order of the sort fields will determine the order in which the items are sorted page: in: query name: page example: 2 schema: type: integer description: The page number that you want to retrieve for the list query limit: in: query name: limit schema: type: integer minimum: 1 default: 20 example: 20 description: Limit the number of items that will be returned as part of the request X-Frankie-Username: name: X-Frankie-Username in: header description: Username provided by API caller required: false schema: type: string example: fred.flintstone@frankieone.com serviceNameQuery: name: serviceName in: query schema: type: string description: The unique name of the service profile includeQuery: name: include in: query style: form explode: false schema: type: array items: type: string enum: - workflowDefinition default: [] description: Query parameter to include additional fields of fetch workflow sortFields: name: sortFields in: query style: form explode: false schema: type: array items: type: string description: |- List of fields that the Process Results will be filtered with Available values : createdAt, updatedAt X-Frankie-RequestID: name: X-Frankie-RequestID in: header description: GUID identifier for request required: true schema: type: string example: 82988375-1F9C-40C7-8543-ECCA0D94CC7C X-Frankie-Background: name: X-Frankie-Background schema: type: integer enum: - 0 - 1 description: > If this header parameter is supplied and set to 1, then the request will not wait for the process to finish, and will return a 202 if there are no obvious errors in the input. The request will then run in the background and send a notification back to the customer. See our callback API for details on this. in: header required: false query_matchlist_states: name: states in: query style: form explode: false schema: description: List of states to include in the response. type: array items: $ref: '#/components/schemas/Matchlist-State' description: >- If set, the response will include only entries with the specified states. By default, only `ACTIVE` entries are returned. Possible values are: `ACTIVE`, and `ARCHIVED`. Multiple values can be provided as a comma-separated list. For example, `ACTIVE,ARCHIVED`. If the value is not one of the possible values, it will be ignored. If the value is not provided, only `ACTIVE` entries are returned. matchlistName: name: matchlistName in: path schema: type: string description: The name of the matchlist. required: true query_entry_states: name: states in: query style: form explode: false schema: description: List of states to include in the response. type: array items: $ref: '#/components/schemas/Matchlist-Entry-State' description: >- If set, the response will include only entries with the specified states. By default, only `ACTIVE` entries are returned. Possible values are: `ACTIVE`, `EXPIRED`, and `DELETED`. Multiple values can be provided as a comma-separated list. For example, `DELETED,EXPIRED`. query_batch_name: name: batchName in: query schema: description: Batch name of entries to include in the response. type: string example: blocklist.csv description: >- If set, the response will include only entries from the specified batch. By default, all entries will be returned. query_reference: name: reference in: query schema: description: Reference of entries to include in the response. type: string example: CERT-BAD-ACTOR-1234-5678 description: >- If set, the response will include only entries with the specified reference. By default, all entries will be returned. query_entity_id: name: entityId in: query schema: description: Entity ID of entries to include in the response. type: string format: uuid example: 12345678-1234-1234-1234-123456789012 description: >- If set, the response will include only entries created with the specified entityId. By default, all entries will be returned. query_entry_id: name: entryId in: query schema: description: Entry ID of entries to include in the response. type: string format: uuid example: 12345678-1234-1234-1234-123456789987 description: >- If set, the response will include only the entry with the specified id. By default, all entries will be returned. matchlist_sort_fields: name: sortFields in: query style: form explode: false example: state schema: type: array description: List of sort fields items: type: string description: One sort field enum: - updatedAt - createdAt - state description: >- The list of sort fields that will be used in the query. The order of the sort fields will determine the order in which the items are sorted. If state is added the sort order will always be `ACTIVE`, `EXPIRED`, `DELETED`. entryId: name: entryId in: path schema: type: string description: The unique identifier of the matchlist entry. required: true schemas: AuditEvent-Channel: type: string example: API description: The channel through which the audit event was generated. enum: - API - PORTAL - ONESDK - SYSTEM Request-ID: type: string example: 01HN9XHZN6MGXM9JXG50K59Q85 description: The unique request identifier for the API call made. List-Operation-Meta: type: object description: >- Meta information about the request and response returned during a list operation. properties: page: type: integer description: The current page number of the request. total: type: integer description: The total number of items found for the search criteria. limit: type: integer description: The limit applied to this response. count: type: integer description: The number of items returned in this response. sort: type: string enum: - asc - desc description: The sort order applied to the items in the response. sortFields: type: array items: type: string enum: - createdAt - updatedAt AuditEvent-Type: type: string enum: - CUSTOMER_SETUP - CUSTOMER_UPDATE - ENTITY_CREATE - ENTITY_LOOKUP - ENTITY_PURGE - ENTITY_RESULT_UPDATE - ENTITY_RESULT_INVALIDATE - ENTITY_UPDATE - GENERATE_REPORT - LEGACY_AUDIT - MATCHLIST_ENTRY - PORTAL_ACTION - RISK_OVERRIDE - SERVICE_PROFILE_CREATE - SERVICE_PROFILE_UPDATE - SERVICE_PROFILE_STATE_CHANGE - WORKFLOW_EVENT - WORKFLOW_COMPLETE - WORKFLOW_RISK_CHANGE - WORKFLOW_STATUS_CHANGE - OTHER description: >- Type of the audit event. - CUSTOMER_SETUP: Audit event for customer setup. - CUSTOMER_UPDATE: Audit event for updating a customer. - ENTITY_CREATE: Create entity. - ENTITY_LOOKUP: Lookup entity. - ENTITY_PURGE: Delete entity and all associated information. - ENTITY_RESULT_UPDATE: Manual result update. - ENTITY_RESULT_INVALIDATE: Invalidate result. - ENTITY_UPDATE: Update entity. - GENERATE_REPORT: Generate a report. - LEGACY_AUDIT: Audit event from V1. - MATCHLIST_ENTRY: Matchlist entry operations. - PORTAL_ACTION: Portal events. - RISK_OVERRIDE: Risk override. - SERVICE_PROFILE_CREATE: Create service profile. - SERVICE_PROFILE_UPDATE: Update service profile. - SERVICE_PROFILE_STATE_CHANGE: Service profile state change. - WORKFLOW_EVENT: Generic event in a workflow other than status, risk, or complete. - WORKFLOW_COMPLETE: Workflow is complete. - WORKFLOW_RISK_CHANGE: Workflow risk change. - WORKFLOW_STATUS_CHANGE: Workflow status change. - OTHER: Other event type. Object-Type: description: The type of object being annotated. type: string enum: - ADDRESS - NAME - PHONE_NUMBER - EMAIL - DATE_OF_BIRTH - WEBSITE - SHAREHOLDER - OFFICIAL - UBO - REGISTRATION - SHAREHOLDING - SHARECAPITAL - DOCUMENT - DOCUMENT_ATTACHMENT - RESULT_PROCESS - RESULT_STEP - RESULT_WORKFLOW - SERVICE_PROFILE - AUDIT_EVENT - EXTERNAL_REFERENCE - RISK_ASSESSMENT - MATCHLIST 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 Workflow-Execution-ResultEnum: type: string description: | Outcome of this workflow execution. Possible results: - UNCHECKED: The workflow has not yet been run and has no result. - IN_PROGRESS: The workflow is currently running and awaiting completion. - REVIEW: The workflow produced results that require review. Check the risks and step results for more details. - PASS: The workflow successfully completed with a PASS recommendation. - FAIL: The workflow finished with a FAIL recommendation. - COMPLETE: The workflow has finished and the results are considered complete. PASS/FAIL is not required. - INCOMPLETE: The workflow has finished and the results are considered incomplete. PASS/FAIL is not required. - NEEDS_APPROVAL: The workflow requires an approval process. Once approved, re-run the workflow. - APPROVED: The workflow was approved, typically by an external source such as a human. - REJECTED: The workflow was rejected, typically by an external source such as a human. - BLOCKED: The workflow was blocked from completing. Manual review is required. - CLEAR: The workflow completed with no issues raised. Often used for ongoing monitoring workflows. - URGENT: The workflow completed with matters requiring urgent review. Often used for ongoing monitoring workflows that return sanctions or similarly critical items. - MONITOR: The workflow completed and further monitoring is required. Should be manually reviewed. default: UNCHECKED enum: - UNCHECKED - IN_PROGRESS - REVIEW - PASS - FAIL - COMPLETE - INCOMPLETE - NEEDS_APPROVAL - APPROVED - REJECTED - BLOCKED - CLEAR - URGENT - MONITOR AuditEvent-Status: type: string example: SUCCESS enum: - SUCCESS - ERROR - INFO Risk-Level: type: string enum: - UNKNOWN - LOW - MEDIUM - HIGH - UNACCEPTABLE description: | The risk level classification: - UNKNOWN: Risk level is not determined. - LOW: Low risk. - MEDIUM: Medium risk. - HIGH: High risk. - UNACCEPTABLE: Risk level is unacceptable. Entity-Type: type: string enum: - INDIVIDUAL - ORGANIZATION - UNKNOWN description: >- The type of entity within Frankie. This can be "INDIVIDUAL", "ORGANIZATION", or "UNKNOWN". readOnly: true Comment: type: object properties: commentId: type: string description: Unique identifier for the comment. example: 55fc5d54-46f7-49c8-bf78-e07ec79cd6e7 readOnly: true text: type: string description: The text content of the comment. example: Update after speaking to customer over the phone directly. Workflow-LifecyclePhaseEnum: type: string description: > Specifies the lifecycle phase of the customer in which this workflow is executed: - ONBOARDING: Workflow is in the onboarding stage. - MONITORING: Workflow is in the monitoring stage. - OTHER: Workflow is in another stage. enum: - ONBOARDING - MONITORING - OTHER default: OTHER 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-Origin: type: object description: >- Specifies the origin of the entity being audited, which may include its source or creation context. Provides details on how and why the entity was created, tracking its provenance across different contexts. properties: entityId: $ref: '#/components/schemas/Entity-ID' entityType: $ref: '#/components/schemas/Entity-Type' details: type: array items: $ref: '#/components/schemas/Code-Description' description: |- Provides additional context about the origin. For example, in the case of KYB: code: "FOCUS_ORG" description: "Organization that triggered the creation of this entity." Audit-Event-Error: type: object properties: code: type: string description: >- The error code, usually similar to an HTTP error code but not always, e.g., API-400. description: type: string description: >- A description of the error, which may originate from the connector itself or the provider. location: type: string description: If known, the location of the error, e.g., a field name. 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. 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. 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-Risk-Assessment: type: object description: > Contains risk profile, results, and both current and previous risk scores and risk levels at the time of risk assessment step execution. allOf: - $ref: '#/components/schemas/Supplementary-Data-AuditEvent-Base' - type: object properties: previousRisk: type: object properties: riskScore: type: number description: The risk score of the entity at the previous step. riskLevel: $ref: '#/components/schemas/Risk-Level' description: The risk level of the entity at the previous step. risk: $ref: '#/components/schemas/Workflow-Step-Risk-Result' 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. 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-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-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. Audit-Event-Connector-Config: type: object properties: configurationKey: type: string description: The key or name of the configuration that was used. description: type: string description: A brief description of the purpose or function of the configuration. value: type: string description: The value assigned to the configuration. Attribute: type: object required: - type - value properties: type: description: The attribute type. type: string maxLength: 64 value: description: The value assigned to the attribute. type: string Custom-Attributes: type: object additionalProperties: $ref: '#/components/schemas/Attribute' 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' 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. 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-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. Supplementary-Data-AuditEvent-Result-Update: type: object description: | Contains details about changes to results. allOf: - $ref: '#/components/schemas/Supplementary-Data-AuditEvent-Base' - type: object properties: resultsUpdated: type: array items: $ref: '#/components/schemas/Audit-Result-Change' description: Results that were updated. 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. 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-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-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' Risk-Factor-Status: type: string enum: - VALID - STALE - OVERRIDDEN - DISCARDED description: | The current status of the risk factor: - VALID: The risk factor is applicable to the entity. - 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. - OVERRIDDEN: The risk factor was manually overridden. If present, manualOverrideScore was used for risk score calculation in the risk assessment. - 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. default: VALID 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-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' Supplementary-Data-AuditEvent-Risk-Override: type: object description: | Contains all details related to a risk override event, including: - The previous risk profile (score and level before the override). - The current risk profile (score and level after the override). - The type of override applied. - The risk factors affected by the override. allOf: - $ref: '#/components/schemas/Supplementary-Data-AuditEvent-Base' - $ref: '#/components/schemas/Audit-Event-Risk-Override-Result' Workflow-Step-Summary-Entity-Lookup-Residential: type: object required: - country - status properties: country: type: string description: > Country The ISO-3166-1 country. You must use the alpha3 country code (e.g. AUS, USA, IDR, KOR, etc). For more details refer to: https://en.wikipedia.org/wiki/ISO_3166-1 status: type: string description: | The status of the address, indicating its relevance over time. * `CURRENT` - The address is currently in use. * `PREVIOUS` - The address was used in the past. * `FUTURE` - The address is planned for future use. * `UNKNOWN` - There is no valid address status available. enum: - CURRENT - PREVIOUS - FUTURE - UNKNOWN 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' Supplementary-Data-AuditEvent-Entity-Lookup: type: object description: | Contains details relevant to entity lookup for an audit event. allOf: - $ref: '#/components/schemas/Supplementary-Data-AuditEvent-Base' - $ref: '#/components/schemas/Workflow-Step-Summary-Entity-Lookup-Address' Organization-Registry: type: object properties: registry: description: Registry the organization is registered at type: string registryDescription: description: The description of the registry type: string Audit-Event-Organization-Entity-Match: type: object description: >- Details of the entity matching process during creation, specifically for KYB (Know Your Business). properties: country: type: string description: >- The ISO-3166-1 country code. You must use the alpha-3 country code (e.g., AUS, USA, IDR, KOR, etc). Conversion will be handled as needed. For more details, refer to: https://en.wikipedia.org/wiki/ISO_3166-1 registrationNumber: type: string description: The registration number of the organization in the registry. registry: $ref: '#/components/schemas/Organization-Registry' subdivision: type: string description: >- The administrative area, state, or sub-division. Use local abbreviations, such as VIC (Victoria) or TX (Texas). name: type: string description: The name as registered in the primary registry of the organization. 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-Organization-Data-Fetch-Connector: type: object description: Contains details relevant to KYB Connector audit events. allOf: - $ref: '#/components/schemas/Supplementary-Data-AuditEvent-Base-Connector' Matchlist-ID: type: string format: uuid description: >- Matchlists are assigned an auto-generated UUID to ensure global uniqueness, represented as matchlistId. The matchlistId allows for precise modification when required. To create or modify a matchlist entry, set the matchlistId of the matchlist you wish to update in a matchlist entry request. example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 readOnly: true Matchlist-Action: type: string description: >- Default action recommended for a match. The action can be one of the following: - `BLOCK`: Recommended action is to block the entity. - `ALERT`: Recommended action is to create an alert for the entity. - `ALLOW`: Recommended action is to allow the entity. - `REVIEW`: Recommended action is to review the entity. - `NONE`: No action; only use the `riskFactor` if any. enum: - BLOCK - ALERT - ALLOW - REVIEW - NONE Matchlist-Base: type: object description: Basic details about a matchlist, excluding metadata. properties: matchlistId: $ref: '#/components/schemas/Matchlist-ID' name: type: string description: Unique name identifying the matchlist. description: type: string description: Description of the matchlist. isDefault: description: Flag indicating whether this matchlist is the default list. type: boolean action: $ref: '#/components/schemas/Matchlist-Action' riskScore: type: number description: >- Risk score to assign if there is a match, unless overridden by risk configuration. 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' 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. 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}$ Matchlist-Entry-Base: type: object description: Basic details about a matchlist entry, excluding metadata. properties: entryId: type: string format: uuid readOnly: true description: Unique identifier for the matchlist entry. entityId: type: string example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 description: >- The entity ID from which the attributes of this entry are derived. This is optional and can be used to link the matchlist entry to an entity. entityType: $ref: '#/components/schemas/Entity-Type' description: >- The type of entity from which the attributes of this entry are derived. This is optional and can be used to link the matchlist entry to an entity. reference: type: string description: Optional reference describing the context of this entry. example: CERT-BAD-ACTOR-1234-5678 reasons: description: >- The reasons for the matchlist entry. These codes will be translated to configured description strings. type: array items: $ref: '#/components/schemas/Matchlist-Entry-Reason-Code' Matchlist-Entry-Attribute-Type: type: string description: >- Entity attributes eligible for screening. A matchlist entry may not contain both `ORG_*` and `IND_*` attributes, and they must match the `ENTITY_TYPE` if it is provided. enum: - ENTITY_TYPE - EMAIL_ADDRESS - EMAIL_DOMAIN - PHONE_NUMBER - ADDR_STREET_NUMBER - ADDR_STREET_NAME - ADDR_STREET_TYPE - ADDR_NEIGHBORHOOD - ADDR_LOCALITY - ADDR_DISTRICT - ADDR_SUBDIVISION - ADDR_COUNTRY - ADDR_POSTAL_CODE - ADDR_UNSTRUCTURED_LONG_FORM - DOC_CLASS - DOC_TYPE - DOC_SUBTYPE - DOC_PRIMARY_IDENTIFIER - DOC_SECONDARY_IDENTIFIER - IND_DISPLAY_NAME - IND_GIVEN_NAME - IND_FAMILY_NAME - IND_MIDDLE_NAME - IND_DATE_OF_BIRTH - IND_NATIONALITY - ORG_REGISTERED_SUBDIVISION - ORG_REGISTERED_COUNTRY - ORG_REGISTRATION_NUMBER - ORG_REGISTRATION_NUMBER_TYPE - ORG_NAME Matchlist-Entry-State: type: string description: |- The state of the matchlist entry. - `ACTIVE`: The matchlist entry is active and can be used for matching. - `EXPIRED`: The matchlist entry has expired. It is visible and retrievable, but cannot be used for matching. - `DELETED`: The matchlist entry has been marked as deleted, rendering it unusable. To modify an entry's state, use `Matchlist-Entry-State-Writeable`. default: ACTIVE readOnly: true enum: - ACTIVE - EXPIRED - DELETED 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-Matchlist-Entry: type: object description: > Contains audit event details for managing a single matchlist entry. For bulk operations, use `Supplementary-Data-AuditEvent-Matchlist-Entries`. required: - matchlist - entry allOf: - $ref: '#/components/schemas/Supplementary-Data-AuditEvent-Base' - $ref: '#/components/schemas/Audit-Matchlist' - type: object properties: entry: $ref: '#/components/schemas/Audit-Matchlist-Entry' Audit-Matchlist-Entries: type: object description: > Audit event details for managing multiple matchlist entries. This provides a summary of the changes, not the full list of entries. For a single operation, use `Audit-Matchlist-Entry`. properties: numOfEntries: type: integer description: | The number of matchlist entries to be added or updated. minimum: 2 example: 2 attributes: type: array description: > A list of attributes that were added or modified for the matchlist entries. minItems: 1 items: $ref: '#/components/schemas/Matchlist-Entry-Attribute-Type' state: description: | The state of the matchlist entries that were added or updated. $ref: '#/components/schemas/Matchlist-Entry-State' default: ACTIVE batchName: type: string description: | Optional batch name to identify the source of these entries. example: blocklist.csv 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-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' 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-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' Service-Profile-State: type: string description: >- Current state of the Service Profile - INIT: Initial state when the profile is created. - AUTO: Automatically assigned state, typically after initial processing. - ACTIVE: The profile is active and in use. - ARCHIVED: The profile has been archived and is no longer active. - BLOCKLISTED: The profile is blocked from further actions. - INACTIVE: The profile is inactive, not currently in use. - DELETED: The profile has been deleted. - DUPLICATE: The profile is a duplicate of another existing profile. enum: - INIT - AUTO - ACTIVE - ARCHIVED - BLOCKLISTED - INACTIVE - DELETED - DUPLICATE Supplementary-Data-AuditEvent-Entity-Profile-State-Change: type: object description: >- Contains details relevant to changes in the state of an entity or its service profiles. If the serviceProfileId is omitted, the state change applies to all service profiles associated with the entity. allOf: - $ref: '#/components/schemas/Supplementary-Data-AuditEvent-Base' - type: object properties: previousState: $ref: '#/components/schemas/Service-Profile-State' currentState: $ref: '#/components/schemas/Service-Profile-State' processResultId: $ref: '#/components/schemas/Process-Result-ID' Activity-ID: type: string readOnly: true description: Activity ID that identifies an activity within the Frankie platform format: ulid Supplementary-Data-AuditEvent-Activity-Detail: type: object properties: activityId: $ref: '#/components/schemas/Activity-ID' processResultId: $ref: '#/components/schemas/Process-Result-ID' 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' Supplementary-Data-AuditEvent-Activity: type: object description: > Contains details relevant to activity monitoring hits for an audit event. allOf: - $ref: '#/components/schemas/Supplementary-Data-AuditEvent-Base' - type: object properties: results: type: array items: $ref: >- #/components/schemas/Supplementary-Data-AuditEvent-Activity-Result Fraud-Check-Types: type: string description: | The supported types of fraud checks. enum: - DEVICE - IP - EMAIL_ADDRESS - PHONE_NUMBER 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-Fraud: type: object description: Contains details relevant to fraud hits for an audit event. allOf: - $ref: '#/components/schemas/Supplementary-Data-AuditEvent-Base' - type: object properties: result: type: string description: The overall result of the fraud check. details: type: array description: A list of fraud checks that were performed and their results. items: $ref: >- #/components/schemas/Supplementary-Data-AuditEvent-Fraud-Details Audit: type: object required: - eventId - schemaVersion - requestId - level - type - description - source - channel - eventStatus - timestamp properties: eventId: type: string format: uuid example: 123e4567-e89b-12d3-a456-426614174000 description: Unique identifier for the audit event. schemaVersion: type: integer example: 2 description: Version of the audit event schema. elapsedTimeInMilliSeconds: type: integer example: 2 description: The total time, in milliseconds, that the operation took. level: type: integer example: 2 description: | Level of the audit event. 1 -- Conclusion of the entire process. What happened. 2 -- Conclusion of a sub-task. Why the overall event happened. 3 -- Finer detail within a task. How the overall event came to be. requestId: $ref: '#/components/schemas/Request-ID' type: $ref: '#/components/schemas/AuditEvent-Type' timestamp: type: string format: date-time example: '2020-01-01T00:00:00.000Z' description: The timestamp of the audit event. source: type: string example: FrankieOne System description: >- Source of the audit event, which could be an internal system or a user. functionName: type: string example: executeVendorCheck description: Name of the function that generated the audit event. description: type: string example: Executing Vendor Check for Entity description: Brief description of the audit event. descriptionDetails: type: string example: | A new entity has been created with the following attributes: - Name - Address description: More in-depth description of the audit log event. objectId: type: string objectType: $ref: '#/components/schemas/Object-Type' entityId: $ref: '#/components/schemas/Entity-ID' batchId: type: string description: ID of the batch associated with the audit event. channel: $ref: '#/components/schemas/AuditEvent-Channel' serviceProfileId: type: string description: ID of the profile associated with the audit event. serviceName: type: string example: kyc description: Name of the profile associated with the audit event. status: $ref: '#/components/schemas/Workflow-Execution-ResultEnum' description: Current status of the workflow. workflowExecutionId: type: string description: ID of the workflow execution associated with the audit event. workflowName: type: string example: safe_harbour_1+1 description: Name of the workflow associated with the audit event. workflowVersion: type: string example: v23 description: Version of the workflow associated with the audit event. stepResultId: type: string description: ID of the step result associated with the audit event. stepName: type: string example: kyc-equifax description: Name of the step associated with the audit event. stepVersion: type: string example: v2.0.0 description: Version of the step associated with the audit event. eventStatus: $ref: '#/components/schemas/AuditEvent-Status' riskScore: type: number example: 10 description: Risk score associated with the audit event. riskLevel: $ref: '#/components/schemas/Risk-Level' description: Risk level associated with the audit event. entityType: $ref: '#/components/schemas/Entity-Type' userComment: $ref: '#/components/schemas/Comment' lifecyclePhase: $ref: '#/components/schemas/Workflow-LifecyclePhaseEnum' supplementaryData: type: object oneOf: - $ref: >- #/components/schemas/Supplementary-Data-AuditEvent-Risk-Assessment - $ref: '#/components/schemas/Supplementary-Data-AuditEvent-KYC' - $ref: '#/components/schemas/Supplementary-Data-AuditEvent-Decision' - $ref: >- #/components/schemas/Supplementary-Data-AuditEvent-Individual-Change - $ref: '#/components/schemas/Supplementary-Data-AuditEvent-KYC-Connector' - $ref: '#/components/schemas/Supplementary-Data-AuditEvent-Result-Update' - $ref: '#/components/schemas/Supplementary-Data-AuditEvent-AML-Connector' - $ref: '#/components/schemas/Supplementary-Data-AuditEvent-AML' - $ref: '#/components/schemas/Supplementary-Data-AuditEvent-IDV' - $ref: '#/components/schemas/Supplementary-Data-AuditEvent-IDV-Connector' - $ref: '#/components/schemas/Supplementary-Data-AuditEvent-Risk-Override' - $ref: '#/components/schemas/Supplementary-Data-AuditEvent-Entity-Lookup' - $ref: '#/components/schemas/Supplementary-Data-AuditEvent-KYB' - $ref: >- #/components/schemas/Supplementary-Data-AuditEvent-Organization-Data-Fetch-Connector - $ref: '#/components/schemas/Supplementary-Data-AuditEvent-Matchlist' - $ref: >- #/components/schemas/Supplementary-Data-AuditEvent-Matchlist-Entry - $ref: >- #/components/schemas/Supplementary-Data-AuditEvent-Matchlist-Entries - $ref: >- #/components/schemas/Supplementary-Data-AuditEvent-Matchlist-Result - $ref: '#/components/schemas/Supplementary-Data-AuditEvent-Duplicate' - $ref: >- #/components/schemas/Supplementary-Data-AuditEvent-Entity-Profile-State-Change - $ref: '#/components/schemas/Supplementary-Data-AuditEvent-Activity' - $ref: '#/components/schemas/Supplementary-Data-AuditEvent-Fraud' discriminator: propertyName: type mapping: RISK_ASSESSMENT: >- #/components/schemas/Supplementary-Data-AuditEvent-Risk-Assessment KYC: '#/components/schemas/Supplementary-Data-AuditEvent-KYC' DECISION: '#/components/schemas/Supplementary-Data-AuditEvent-Decision' INDIVIDUAL_CHANGE: >- #/components/schemas/Supplementary-Data-AuditEvent-Individual-Change KYC_CONNECTOR: '#/components/schemas/Supplementary-Data-AuditEvent-KYC-Connector' RESULT_UPDATE: '#/components/schemas/Supplementary-Data-AuditEvent-Result-Update' AML_CONNECTOR: '#/components/schemas/Supplementary-Data-AuditEvent-AML-Connector' AML: '#/components/schemas/Supplementary-Data-AuditEvent-AML' IDV: '#/components/schemas/Supplementary-Data-AuditEvent-IDV' IDV_CONNECTOR: '#/components/schemas/Supplementary-Data-AuditEvent-IDV-Connector' RISK_OVERRIDE: '#/components/schemas/Supplementary-Data-AuditEvent-Risk-Override' ENTITY_LOOKUP: '#/components/schemas/Supplementary-Data-AuditEvent-Entity-Lookup' KYB: '#/components/schemas/Supplementary-Data-AuditEvent-KYB' ORG_DATA_FETCH_CONNECTOR: >- #/components/schemas/Supplementary-Data-AuditEvent-Organization-Data-Fetch-Connector MATCHLIST: '#/components/schemas/Supplementary-Data-AuditEvent-Matchlist' MATCHLIST_ENTRY: >- #/components/schemas/Supplementary-Data-AuditEvent-Matchlist-Entry MATCHLIST_ENTRIES: >- #/components/schemas/Supplementary-Data-AuditEvent-Matchlist-Entries MATCHLIST_RESULT: >- #/components/schemas/Supplementary-Data-AuditEvent-Matchlist-Result DUPLICATE: '#/components/schemas/Supplementary-Data-AuditEvent-Duplicate' ENTITY_PROFILE_STATE_UPDATE: >- #/components/schemas/Supplementary-Data-AuditEvent-Entity-Profile-State-Change ACTIVITY: '#/components/schemas/Supplementary-Data-AuditEvent-Activity' FRAUD: '#/components/schemas/Supplementary-Data-AuditEvent-Fraud' 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. Error-Base: type: object properties: errorCode: type: string errorMsg: type: string details: type: array items: $ref: '#/components/schemas/Issue' Error: type: object x-examples: '400': requestId: 0123456789ABCDEFGHIJKLMNOP errorCode: API-0400 errorMsg: Parsing credentials from "" 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' Subscription-Type: type: string description: >- Specifies the type of service profile subscription. This value determines the category of the service profile subscription. enum: - AML - ACTIVITY Monitoring-Type: type: string description: >- The type of workflow subscription. This determines which types are subscribing to a workflow. allOf: - $ref: '#/components/schemas/Subscription-Type' Workflow-Step-Type: type: string enum: - BLOCKLIST - DUPLICATE - DECISION - BRANCH - MONITOR_TOGGLE - OTHER - KYC - AML - IDV - START - FINISH Workflow-Step: type: object properties: name: type: string description: Name of the step (must be unique) example: Run KYC description: type: string description: Description of the step example: Run the KYC step version: type: string description: Version of the step example: 1.0.0 type: $ref: '#/components/schemas/Workflow-Step-Type' configuration: type: object description: Configuration for the step dependsOn: type: object description: Map of branch condition and step name that this step depends on additionalProperties: type: array items: type: string Workflow-Definition: type: object description: Workflow definition properties: definitionUpdatedAt: description: The date and time the workflow was last updated type: string format: date-time example: '2023-01-15T02:18:11.365Z' version: description: The version of the workflow type: string example: v1 steps: description: The steps of the workflow type: array items: $ref: '#/components/schemas/Workflow-Step' Workflow-Lookup: type: object properties: serviceName: type: string description: Name of the service. workflowId: type: string description: Unique identifier of the workflow. workflowName: type: string description: Name of the workflow. type: type: string description: Type of the workflow. lifecyclePhase: $ref: '#/components/schemas/Workflow-LifecyclePhaseEnum' monitoringTypes: type: array items: $ref: '#/components/schemas/Monitoring-Type' description: | The types of monitoring to which this workflow is subscribed. If not provided, the workflow is subscribed to all monitoring types. definition: $ref: '#/components/schemas/Workflow-Definition' Search-Type: type: string description: |- Specifies the type of search to perform. - "EXACT": Returns only results that exactly match the search term. - "FUZZY": Returns results that are similar to the search term. enum: - EXACT - FUZZY Search-Field: type: string description: |- List of fields that can be searched. - "NAME": Searches all name parts of the profile. - "GIVEN_NAME": Searches the given name of the individual linked to the profile. - "FAMILY_NAME": Searches the family name of the individual linked to the profile. - "MIDDLE_NAME": Searches the middle name of the individual linked to the profile. - "DISPLAY_NAME": Searches the preferred display name. By default, this is the combined given, middle, and family names. - "OTHER_NAME": Searches other names of the individual linked to the profile. - "EXTERNAL_REFERENCE": Searches the external reference of the entity linked to the profile. Planned for future implementation: - "ALL": Searches all fields. - "ADDRESS": Searches the address of the entity linked to the profile. - "EMAIL_ADDRESS": Searches the email address of the entity linked to the profile. - "PHONE_NUMBER": Searches the phone number of the entity linked to the profile. - "DOCUMENT_IDENTIFIER": Searches primary and secondary identifiers in documents linked to the profile. enum: - ALL - NAME - GIVEN_NAME - FAMILY_NAME - MIDDLE_NAME - DISPLAY_NAME - OTHER_NAME - ADDRESS - EMAIL_ADDRESS - PHONE_NUMBER - DOCUMENT_IDENTIFIER - EXTERNAL_REFERENCE Search-Term: type: object required: - term - field properties: term: description: >- The value to search for in profiles. This term will be matched against the specified field. type: string field: $ref: '#/components/schemas/Search-Field' Search-Criteria: type: object required: - type - terms properties: type: $ref: '#/components/schemas/Search-Type' terms: type: array items: $ref: '#/components/schemas/Search-Term' description: List of search terms to be used as criteria. Status-Override-Type-Filter: type: string description: >- Filter on the status override type. Accepted values are: - ONLY_OVERRIDDEN: Returns only profiles with manually overridden statuses. - EXCLUDE_OVERRIDDEN: Excludes profiles with manually overridden statuses. - ALL: Returns both profiles with and without manually overridden statuses. enum: - ONLY_OVERRIDDEN - EXCLUDE_OVERRIDDEN - ALL default: ALL Workflow-Execution-Statuses: type: object required: - status - overrideType properties: overrideType: $ref: '#/components/schemas/Status-Override-Type-Filter' status: description: >- List of workflowStatus value that the Service Profiles will be filter with type: array items: $ref: '#/components/schemas/Workflow-Execution-ResultEnum' Workflow-Issue-Category: type: string enum: - AML - BAD_DATA - BIOMETRICS - BLOCKLISTED - DECEASED - DEVICE - DOCUMENT - DUPLICATE - EXPIRY - FRAUD - IDV - INFORMATIONAL - KYC - SYSTEM - VERIFY - VISA - WATCHLIST - ACTIVITY description: |- General category of issue found: - AML: Anti-Money Laundering issues. - BAD_DATA: Indicates that the data provided is invalid or incorrect. - BIOMETRICS: Issues found during a biometrics check. - BLOCKLISTED: The entity has a hit on a blocklist. - DECEASED: Indicates that the entity is deceased. - DEVICE: Issues found during device checks. - DOCUMENT: Issues found during a document check. - DUPLICATE: Indicates that the entity has duplicates. - EXPIRY: Indicates that a process or document for the entity has expired. - FRAUD: Possible fraud detected. - IDV: Issues found during an Identity Verification (IDV) process. - INFORMATIONAL: Informational messages that are not issues but are required to be returned. - KYC: Issues found during a Know Your Customer (KYC) process. - SYSTEM: System-level issues. - VERIFY: Issues found during a verification process. - VISA: Issues found during a visa check. - WATCHLIST: Issues found during a watchlist check. - ACTIVITY: Issues found during an activity process. Workflow-Issue-Severity: type: string enum: - INFO - REVIEW - BLOCK - WARNING - CRITICAL - ERROR description: | The severity level of the issue. Possible values: - INFO: Informational only. - REVIEW: Requires review. - BLOCK: Blocks further processing. - WARNING: Warning, but not blocking. - CRITICAL: Critical issue. - ERROR: Error encountered. Workflow-Issue-Type: type: string enum: - AML_ISSUE - BAD_DATA_ADDRESS - BAD_DATA_DOB - BAD_DATA_EMAIL - BAD_DATA_ID - BAD_DATA_MOBILE - BAD_DATA_NAME - BLOCKED - COMPROMISED_DOCUMENT - CREDIT_HEADER - DATA_COMPARISON - DATA_CONSISTENCY - DATA_VALIDATION - DENY_LIST - DECEASED - DEVICE_FRAUD_MATCH - DEVICE_INVALID - DOCUMENT_COMPARISON - DUPLICATE - FRAUD_CHECK - FRAUD_DEVICE - FRAUD_IP_ADDRESS - FRAUD_EMAIL_ADDRESS - FRAUD_PHONE_NUMBER - FRAUD_ISSUE - FRAUD_LIST - IMAGE_INTEGRITY - INTERNAL_MATCH - LIVENESS_DETECTION - MATCHED_EXTERNAL - MATCHED_INTERNAL - MATCHED_SHARED - MEDIA - NOT_FOUND - OCR - PARTIAL - PEP - REQUIRES_AML - REQUIRES_IDV - REQUIRES_KYC - REQUIRES_VISA - SANCTION - SERVICE_ERROR - SERVICE_TIMEOUT - VISA_FAILED - VISUAL_AUTHENTICITY - WATCHLIST - ACTIVITY_AML - ACTIVITY_FRAUD - ACTIVITY_DEVICE description: |- For each category, this provides the specific issue type. AML: - PEP: The entity has Politically Exposed Person (PEP) hits. - SANCTION: The entity has sanction hits. - MEDIA: The entity has adverse media hits. - WATCHLIST: The entity has watchlist hits. BAD_DATA: - BAD_DATA_NAME: Name is required for verification but is missing or unusable due to data quality issues. - BAD_DATA_DOB: Date of Birth is required for verification but is missing or unusable due to data quality issues. - BAD_DATA_ADDRESS: Address is required for verification but is missing or unusable due to data quality issues. - BAD_DATA_ID: ID is required for verification but is missing or unusable due to data quality issues. - BAD_DATA_EMAIL: Email is required for verification but is missing or unusable due to data quality issues. - BAD_DATA_MOBILE: Mobile is required for verification but is missing or unusable due to data quality issues. BLOCKLISTED: - MATCHED_INTERNAL: The entity matched an internal blocklist. - MATCHED_SHARED: The entity matched a shared blocklist. - MATCHED_EXTERNAL: The entity matched an external blocklist. DECEASED: - DECEASED: The person whose data is being verified is deceased. DEVICE: - DEVICE_FRAUD_MATCH: Fraud detected on the device. - DEVICE_INVALID: The device is invalid. DUPLICATE: - DUPLICATE: The entity is a duplicate of another entity. EXPIRY: - REQUIRES_KYC: KYC process needs to be re-initiated. - REQUIRES_IDV: IDV process needs to be re-initiated. - REQUIRES_AML: AML process needs to be re-initiated. - REQUIRES_VISA: Visa process needs to be re-initiated. FRAUD: - FRAUD_LIST: The entity is on a fraud list. - FRAUD_CHECK: Fraud detected during checks. - FRAUD_DEVICE: Device fraud detected. - FRAUD_IP_ADDRESS: IP address fraud detected. - FRAUD_EMAIL_ADDRESS: Email address fraud detected. - FRAUD_PHONE_NUMBER: Phone number fraud detected. IDV: - DATA_COMPARISON: Data comparison issue. - DATA_VALIDATION: Data validation issue. - DATA_CONSISTENCY: Data consistency issue. - VISUAL_AUTHENTICITY: Visual authenticity issue. - IMAGE_INTEGRITY: Image integrity issue. - COMPROMISED_DOCUMENT: Document is compromised. - LIVENESS_DETECTION: Liveness detection failed. - DOCUMENT_COMPARISON: Document comparison issue. INFORMATIONAL: - CREDIT_HEADER: Credit header information was returned as part of a credit agency check. KYC: - PARTIAL: The KYC check was only partially successful. - NOT_FOUND: No match was found for the given data. OCR: - OCR: The OCR data does not match what was entered by the user. SYSTEM: - SERVICE_TIMEOUT: All providers have timed out. - SERVICE_ERROR: All providers have returned an error or an internal error has occurred. VISA: - DENY_LIST: The entity matched a visa deny list. - VISA_FAILED: Visa check failed from the provider. WATCHLIST: - INTERNAL_MATCH: The entity matched an internal watchlist. ACTIVITY: - ACTIVITY_AML: AML-related activity issue. - ACTIVITY_FRAUD: Fraud-related activity issue. - ACTIVITY_DEVICE: Device-related activity issue. Workflow-Execution-ScopeEnum: type: string enum: - LAST - ANY description: | Determines how workflow status and name filters are applied: - LAST: Applies filters only to the most recent workflow execution. - ANY: Searches across all workflow executions. default: ANY example: LAST Search-Filters: type: object properties: entityIds: type: array items: type: string description: Entity IDs to filter the Service Profiles by. createdAtBefore: type: string format: date-time description: >- Filter Service Profiles created on or before this date and time (inclusive). createdAtAfter: type: string format: date-time description: >- Filter Service Profiles created on or after this date and time (inclusive). updatedAtAfter: type: string format: date-time description: >- Filter Service Profiles updated on or after this date and time (inclusive). updatedAtBefore: type: string format: date-time description: >- Filter Service Profiles updated on or before this date and time (inclusive). assignees: type: array items: type: string description: Filter Service Profiles by assignee(s). reviewers: type: array items: type: string description: Filter Service Profiles by reviewer(s). states: description: List of Service Profile state values to filter Service Profiles. type: array items: $ref: '#/components/schemas/Service-Profile-State' workflowNames: type: array items: type: string description: Filter by workflow execution summary workflow names. workflowExecutionStatuses: description: >- Filter by combinations of workflowStatus and statusOverrideType. If this filter is used, the deprecated statusOverrideType and workflowStatuses filters are ignored. type: array items: $ref: '#/components/schemas/Workflow-Execution-Statuses' statusOverrideType: type: string description: |- Filter by status override type. Accepted values are: - ONLY_OVERRIDDEN: Returns only profiles with manually overridden statuses. - EXCLUDE_OVERRIDDEN: Excludes profiles with manually overridden statuses. - ALL: Returns both profiles with and without manually overridden statuses. If not provided, the default behavior is ALL. enum: - ONLY_OVERRIDDEN - EXCLUDE_OVERRIDDEN - ALL default: ALL deprecated: true workflowStatuses: deprecated: true description: List of workflowStatus values to filter Service Profiles. type: array items: $ref: '#/components/schemas/Workflow-Execution-ResultEnum' issueCategories: type: array items: $ref: '#/components/schemas/Workflow-Issue-Category' description: List of issue categories to filter Service Profiles. issueSeverities: type: array items: $ref: '#/components/schemas/Workflow-Issue-Severity' description: List of issue severities to filter Service Profiles. riskLevels: type: array items: $ref: '#/components/schemas/Risk-Level' description: >- Filter by workflow execution summary risk levels. If workflow name is not provided, all execution summaries are searched. issues: type: array items: $ref: '#/components/schemas/Workflow-Issue-Type' description: >- Filter for issues. Should match categories being filtered for. For each category, this provides the actual issue. VERIFY: NOT_FOUND (was 404) BAD_DATA_NAME BAD_DATA_DOB BAD_DATA_ADDRESS BAD_DATA_ID BAD_DATA_EMAIL BAD_DATA_MOBILE DECEASED: DECEASED EXPIRY: REQUIRES_KYC REQUIRES_IDV REQUIRES_AML INFORMATIONAL: CREDIT_HEADER AML: PEP SANCTION MEDIA WATCHLIST FRAUD: FRAUD_LIST FRAUD_CHECK DEVICE: DEVICE_FRAUD_MATCH DEVICE_INVALID TRANSACTION: AML_ISSUE FRAUD_ISSUE BLOCKED WATCHLIST: INTERNAL_MATCH DUPLICATE: DUPLICATE BLOCKLISTED: MATCHED_INTERNAL MATCHED_SHARED MATCHED_EXTERNAL SYSTEM: SERVICE_TIMEOUT SERVICE_ERROR workflowExecutionScope: $ref: '#/components/schemas/Workflow-Execution-ScopeEnum' Search-Profile: type: object properties: search: $ref: '#/components/schemas/Search-Criteria' filters: $ref: '#/components/schemas/Search-Filters' Risk-Assessment-ID: type: string description: Unique identifier of the risk assessment. readOnly: true Workflow-Execution-StateEnum: type: string description: | Current state of the workflow execution. Possible values: - COMPLETED: The workflow execution has completed successfully. - CANCELED: The workflow execution was canceled. - TERMINATED: The workflow execution was terminated before completion. - ERROR: The workflow execution encountered an error. - TIMEOUT: The workflow execution timed out. - IN_PROGRESS: The workflow execution is currently in progress. enum: - COMPLETED - CANCELED - TERMINATED - ERROR - TIMEOUT - IN_PROGRESS Profile-ID: type: string description: Unique identifier of the Service Profile. Risk-Factor-ID: type: string description: Unique identifier of the risk factor. readOnly: true Risk-Factor: type: object properties: riskFactorId: $ref: '#/components/schemas/Risk-Factor-ID' factor: type: string description: Name of the Frankie risk factor. readOnly: true value: type: string description: Value assigned to the risk factor. readOnly: true score: type: number description: Risk score assigned to the factor (based on customer configuration). readOnly: true description: type: string description: Description of the risk factor. readOnly: true workflowExecutionId: type: string description: >- Unique identifier of the workflow execution in which the risk factor was generated. readOnly: true stepResultId: type: string description: >- Unique identifier of the step result if the factor originated from a step. readOnly: true manualOverrideScore: type: number description: >- If present, this score overrides all others and is used as the final score in risk assessment. status: $ref: '#/components/schemas/Risk-Factor-Status' createdAt: type: string format: date-time description: Timestamp when the risk factor was created. readOnly: true updatedAt: type: string format: date-time description: Timestamp when the risk factor was last updated. readOnly: true updatedBy: type: string description: >- Identifier of the user or system that updated this risk factor (e.g., System:; or User:). readOnly: true updatedRequestId: type: string description: Identifier of the request that updated this risk factor. readOnly: true createdServiceProfileId: type: string format: uuid description: >- Identifier of the service profile associated with this risk factor when it was created. createdWorkflowExecutionId: type: string description: >- Identifier of the workflow execution that originally created the risk factor. createdStepResultId: type: string description: >- Identifier of the step result that originally created the risk factor. Risk-Assessment: type: object required: - entityId - serviceProfileId - workflowId - workflowExecutionId properties: serviceProfileId: $ref: '#/components/schemas/Profile-ID' riskAssessmentId: $ref: '#/components/schemas/Risk-Assessment-ID' workflowId: type: string description: Unique identifier of the workflow. workflowExecutionId: type: string description: Unique identifier of the workflow execution. entityId: type: string description: Unique identifier of the entity being assessed. schemaVersion: type: integer description: Version of the risk assessment schema. createdAt: type: string format: date-time description: Timestamp when the risk assessment was created. updatedAt: type: string format: date-time description: Timestamp when the risk assessment was last updated. updatedBy: type: string description: Identifier of the user or system that updated this assessment. updatedRequestId: type: string description: Identifier of the request that updated this assessment. workflowRiskScore: type: number description: Risk score calculated for the workflow. workflowRiskLevel: $ref: '#/components/schemas/Risk-Level' description: >- Risk level of the workflow execution associated with this risk assessment. riskScore: type: number description: Risk score calculated for the entity. riskLevel: $ref: '#/components/schemas/Risk-Level' description: Risk level of the entity. isOutdated: type: boolean description: >- Indicates whether the assessment is out of date, either due to manual updates or changes to risk factors that were assessed. default: false riskFactors: type: array items: $ref: '#/components/schemas/Risk-Factor' readOnly: true description: List of risk factors considered in this assessment. Workflow-Execution-Steps: type: object properties: order: type: array items: type: string passed: type: array items: type: string failed: type: array items: type: string incomplete: type: array items: type: string notApplicable: type: array items: type: string Issue-ID: type: string description: Unique identifier for the risk issue. readOnly: true Workflow-Issue: type: object required: - category - issue - severity properties: issueId: allOf: - $ref: '#/components/schemas/Issue-ID' readOnly: true category: $ref: '#/components/schemas/Workflow-Issue-Category' issue: $ref: '#/components/schemas/Workflow-Issue-Type' workflowExecutionId: type: string description: >- Identifier of the workflow execution in which this issue was generated. stepResultId: type: string description: >- Identifier of the step from which this issue originated, if applicable. isCleared: type: boolean description: >- Indicates if this specific issue has been manually flagged as addressed. createdBy: type: string description: User or system that created this issue. readOnly: true createdAt: type: string format: date-time description: The timestamp when the issue was created. readOnly: true updatedAt: type: string format: date-time description: The timestamp when the issue was last updated. readOnly: true updatedBy: type: string description: >- User or system that last updated this issue (e.g., System: or User:). readOnly: true updatedRequestId: type: string description: Identifier of the request that updated this issue. readOnly: true severity: $ref: '#/components/schemas/Workflow-Issue-Severity' Workflow-Execution-Summary: type: object description: > Summary of the workflow execution. ### Using and interpreting the status field The result of the workflow is represented in the **status** field. Users can manually override this status with a different value to change the outcome of the workflow. When the **status** field is overridden, the **statusOverrideRequestId** field is populated with the request ID of the override request. If the **statusOverrideRequestId** field is present and non-empty, it indicates that the status has been manually changed. 1. Initial State: - When a workflow completes, its result is set in the **status** field. 2. Status Override: - Users may override the **status** field with a different value (e.g., change FAIL to PASS). 3. Identifying Overrides: - To determine if a status has been overridden, check for the presence of the **statusOverrideRequestId** field. - If present, it indicates that the status has been manually changed. 4. Additional Override Information: - **statusOverrideBy**: Identifies the user who performed the override (may not always be present). - **statusOverrideAt**: Timestamp of when the override occurred. 5. Interpretation: - If **statusOverrideRequestId** is empty or absent, no override has occurred. - If **statusOverrideRequestId** is present, then a manual override has occurred. properties: schemaVersion: type: integer description: Version of the schema used for this workflow execution. workflowName: type: string description: Name of the workflow. workflowExecutionId: type: string description: Unique identifier for the workflow execution. workflowExecutionState: $ref: '#/components/schemas/Workflow-Execution-StateEnum' description: Current state of the workflow execution. status: $ref: '#/components/schemas/Workflow-Execution-ResultEnum' description: Current status/result of the workflow execution. statusOverrideAt: type: string format: date-time description: Timestamp when the status override occurred. statusOverrideRequestId: type: string description: Request ID associated with the status override. statusOverrideBy: type: string description: Identifier of the user who performed the status override. riskAssessment: $ref: '#/components/schemas/Risk-Assessment' description: Risk assessment for the workflow execution. isManual: type: boolean description: Indicates if the workflow was executed manually. steps: $ref: '#/components/schemas/Workflow-Execution-Steps' description: Steps executed as part of the workflow. startedAt: type: string format: date-time description: The timestamp when the workflow execution started. endedAt: type: string format: date-time description: The timestamp when the workflow execution ended. issues: type: array description: List of issues encountered during the workflow execution. items: $ref: '#/components/schemas/Workflow-Issue' lifecyclePhase: $ref: '#/components/schemas/Workflow-LifecyclePhaseEnum' description: Current lifecycle phase of the workflow. monitoringTypes: description: | The types of monitoring that subscribe to the workflow. type: array items: $ref: '#/components/schemas/Monitoring-Type' Service-Profile-Subscription: type: object properties: serviceProfileId: type: string description: The unique identifier of the service profile. status: type: string enum: - ENABLED - DISABLED description: >- Indicates whether the subscription is currently active and operational. type: $ref: '#/components/schemas/Subscription-Type' workflowName: type: string description: >- The name of the monitoring workflow executed when a monitoring alert occurs. workflowId: type: string description: The unique identifier of the monitoring workflow. enabledAt: type: string format: date-time description: The date and time when the subscription was most recently enabled. enabledRequestId: type: string description: The request identifier for the most recent enable action. enabledBy: type: string description: The user who most recently enabled the subscription. disabledAt: type: string format: date-time description: The date and time when the subscription was most recently disabled. disabledRequestId: type: string description: The request identifier for the most recent disable action. disabledBy: type: string description: The user who most recently disabled the subscription. Service-Profile-Base: type: object properties: serviceProfileId: type: string description: The unique identifier for the service profile. example: 55fc5d54-46f7-49c8-bf78-e07ec79c42fd readOnly: true latestRiskAssessmentId: $ref: '#/components/schemas/Risk-Assessment-ID' description: >- The ID of the latest risk assessment in the most recent workflow with a valid assessment. Omitted if no valid risk assessment exists. latestWorkflowExecutionId: type: string description: |- The ID of the most recent workflow execution. Omitted if no workflows exist. entityId: type: string readOnly: true entityName: type: string readOnly: true entityType: type: string readOnly: true organizationType: type: string example: SOLE TRADER readOnly: true country: type: string description: >- The ISO 3166 alpha-3 code representing the individual's country of residence or the business's country of registration. example: AUS readOnly: true schemaVersion: type: integer description: The version number of the schema. example: 2 readOnly: true createdAt: type: string format: date-time description: The UTC date and time when this service profile was created. example: '2024-01-15T02:18:11.365Z' readOnly: true createdRequestId: type: string description: >- The unique ULID identifier of the request that created this service profile. example: 01HMR2ERSKCYAVXKS1FKSRT2T4 readOnly: true createdBy: type: string description: The user or client that created this profile. example: Ryan Reynolds readOnly: true updatedAt: type: string format: date-time description: >- The UTC date and time when this service profile was last updated, if applicable. example: '2024-01-15T02:18:11.365Z' readOnly: true updatedBy: type: string description: The user or client that last updated this profile. example: Ryan Reynolds readOnly: true updatedRequestId: type: string description: >- The unique ULID identifier of the request that last updated this service profile. example: 01HMR2ERSKCYAVXKS1FKSRT2T4 readOnly: true assignee: type: string description: The name of the officer assigned to approve this profile. example: Ryan Gosling reviewer: type: string description: The name of the officer assigned to review this profile. example: Ryan Trahan currentWorkflowId: type: string readOnly: true currentWorkflowName: type: string description: The name of the current workflow, if applicable. workflowSummaries: type: array items: $ref: '#/components/schemas/Workflow-Execution-Summary' readOnly: true serviceName: type: string description: The name of the service associated with this profile. readOnly: true customerReference: type: string readOnly: true description: Customer-specific identifier(s). subscriptions: type: array description: >- The list of subscriptions associated with the service profile. A subscription determines if the service profile is subscribed to a particular ongoing process. items: $ref: '#/components/schemas/Service-Profile-Subscription' readOnly: true Service-Profile: allOf: - $ref: '#/components/schemas/Service-Profile-Base' - type: object properties: state: $ref: '#/components/schemas/Service-Profile-State' Search-Confidence: type: number format: float minimum: 0 maximum: 1 description: > Confidence level of the search result, represented as a number between 0 and 1. A higher value indicates greater confidence in the accuracy of the search result. Search-Field-Match: type: object properties: field: $ref: '#/components/schemas/Search-Field' confidence: $ref: '#/components/schemas/Search-Confidence' Search-Match: type: object properties: serviceProfile: $ref: '#/components/schemas/Service-Profile' confidence: $ref: '#/components/schemas/Search-Confidence' fieldsMatched: type: array items: $ref: '#/components/schemas/Search-Field-Match' Search-Matches: type: array items: $ref: '#/components/schemas/Search-Match' Matchlist-Entry-Attribute: type: object description: Represents a single attribute of a matchlist entry. required: - type - value properties: type: $ref: '#/components/schemas/Matchlist-Entry-Attribute-Type' value: description: >- The value of the attribute, e.g., last name "Smith" if the type is IND_FAMILY_NAME. type: string Matchlist-Entry-Attributes: type: array description: All attributes associated with a matchlist entry. minItems: 1 items: $ref: '#/components/schemas/Matchlist-Entry-Attribute' Matchlists-Search-Criteria: type: object description: Specification of the matchlist entry attributes to search for. required: - attributes properties: type: $ref: '#/components/schemas/Search-Type' attributes: $ref: '#/components/schemas/Matchlist-Entry-Attributes' Matchlists-Search-Filter: type: object description: >- Specification of the matchlists to be searched. By default, only the default matchlist is searched. properties: listScope: type: string description: >- The lists to search in. If not provided, the search will be performed only in the default list. - DEFAULT: Search in the default list. - ALL: Search in all lists. - CUSTOM: Search in the lists provided in the searchLists parameter. default: DEFAULT enum: - DEFAULT - ALL - CUSTOM searchLists: type: array description: The IDs of matchlists to search in. Required if listScope is CUSTOM. items: type: string format: uuid description: The ID of the matchlist to search in. Search-Matchlists-Request: type: object description: Request to search for entries one or more matchlists required: - search properties: search: $ref: '#/components/schemas/Matchlists-Search-Criteria' filter: $ref: '#/components/schemas/Matchlists-Search-Filter' Matchlist-Entry-Base-With-Audit: type: object description: Basic details about a matchlist entry, including audit metadata. allOf: - $ref: '#/components/schemas/Matchlist-Entry-Base' - type: object properties: createdBy: type: string readOnly: true description: >- The user who created the matchlist entry. This is set to the value in the `X-Frankie-Username` header. createdAt: type: string format: date-time readOnly: true description: The date and time when the matchlist entry was created. updatedBy: type: string readOnly: true description: >- The user who last updated the matchlist entry. This is set to the value in the `X-Frankie-Username` header. On creation, this is the same as `createdBy`. updatedAt: type: string format: date-time readOnly: true description: >- The date and time when the matchlist entry was last updated. On creation, this is the same as `createdAt`. Matchlists-Search-Matched-Attribute: type: object description: An entry attribute that matched the matchlist search criteria. required: - attribute properties: attribute: $ref: '#/components/schemas/Matchlist-Entry-Attribute' confidence: $ref: '#/components/schemas/Search-Confidence' Matchlists-Search-Matched-Entry: type: object description: An entry that matched the matchlist search criteria. required: - matchlistId - entry - attributes properties: matchlistId: type: string format: uuid description: Unique identifier of the matchlist to which this entry belongs. entry: $ref: '#/components/schemas/Matchlist-Entry-Base-With-Audit' attributes: type: array description: >- All attributes of the matchlist entry. At least one attribute will match to some extent. minItems: 1 items: $ref: '#/components/schemas/Matchlists-Search-Matched-Attribute' confidence: $ref: '#/components/schemas/Search-Confidence' Search-Matchlists-Matches-Response: type: object description: >- All matches for a matchlist search. The entries contain the matchlist ID reference for looking up the matchlist details in matchlists. If there are no matches, empty lists are returned. Results will be ordered by descending entry match confidence for fuzzy searches, and otehrwise by matchlist and entry ID. required: - requestId - matchlists - entries - meta properties: requestId: $ref: '#/components/schemas/Request-ID' matchlists: type: object description: > List of matchlists with at least one matches entry in the entries list. Keyed on the matchlist ID which is also present in entries. additionalProperties: $ref: '#/components/schemas/Matchlist-Base' entries: type: array description: >- The list of matches that match the search criteria. Includes associated match strengths if the search was fuzzy. If no matches were found, the list will be empty. items: $ref: '#/components/schemas/Matchlists-Search-Matched-Entry' meta: type: object description: >- Meta information about the request and response that will be returned during a search operation required: - total - limit - count properties: total: type: integer description: >- The Total number of items that have been found for the search criteria limit: type: integer description: The current limit applied for this response count: type: integer description: The number of items that were returned in this response Matchlist-State: type: string description: |- The state of the matchlist. Possible values: - "ACTIVE": The matchlist is active and can be used for matching. Note: the default matchlist is always active. - "ARCHIVED": The matchlist is archived and cannot be used for matching. default: ACTIVE enum: - ACTIVE - ARCHIVED Matchlist: type: object description: >- A matchlist is a collection of entries used to match against incoming data. allOf: - $ref: '#/components/schemas/Matchlist-Base' - type: object description: Additional details about the matchlist. title: Matchlist properties: state: $ref: '#/components/schemas/Matchlist-State' createdBy: type: string readOnly: true description: The user who created the matchlist. createdAt: type: string format: date-time readOnly: true description: The date and time when the matchlist was created. updatedBy: type: string readOnly: true description: >- The user who last updated the matchlist. On creation, this is the same as `createdBy`. updatedAt: type: string format: date-time readOnly: true description: >- The date and time when the matchlist was last updated. On creation, this is the same as `createdAt`. Matchlist-Entry: type: object description: Represents a single entry in a matchlist. allOf: - $ref: '#/components/schemas/Matchlist-Entry-Base' - type: object description: >- Additional entry details that are only visible to the matchlist owner. title: Matchlist Entry required: - attributes properties: attributes: $ref: '#/components/schemas/Matchlist-Entry-Attributes' state: $ref: '#/components/schemas/Matchlist-Entry-State' batchName: type: string description: Optional batch name to identify the source of this entry. example: blocklist.csv createdBy: type: string readOnly: true description: >- The user who created the matchlist entry. This is set to the value in the `X-Frankie-Username` header. createdAt: type: string format: date-time readOnly: true description: The date and time when the matchlist entry was created. updatedBy: type: string readOnly: true description: >- The user who last updated the matchlist entry. This is set to the value in the `X-Frankie-Username` header. On creation, this is the same as `createdBy`. updatedAt: type: string format: date-time readOnly: true description: >- The date and time when the matchlist entry was last updated. On creation, this is the same as `createdAt`. Entity-ID-Writeable: 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 Create-Matchlist-Entry-Request: type: object description: >- Request to create an entry in a matchlist. The entity ID and type must either both be omitted, or both be provided. Note that the entity type is separate from the entity type in the attributes to be searched for. For example an entry may be created from an address of an individual, but the search may be set to only apply to organisations. required: - attributes properties: entityId: $ref: '#/components/schemas/Entity-ID-Writeable' description: >- The entity ID of the entity from which the attributes of this entry are derived. This is optional and can be used to link the matchlist entry to an entity entityType: $ref: '#/components/schemas/Entity-Type' description: >- The type of the entity from which the attributes of this entry are derived. This is optional and can be used to link the matchlist entry to an entity. reference: type: string description: Optional reference to describe the context of this entry. example: CERT-BAD-ACTOR-1234-5678 reasons: description: >- Optional reasons for the matchlist entry. These codes will translate to configured description strings. type: array items: $ref: '#/components/schemas/Matchlist-Entry-Reason-Code' attributes: $ref: '#/components/schemas/Matchlist-Entry-Attributes' Create-Matchlist-Entries-Request: type: object description: Request to create one or more entries in a matchlist required: - entries properties: batchName: type: string description: >- Optional name to identify a batch of matchlist entries. This name should reflect the source of the batch. When entries are later retrieved, they can be filtered by this batch name. example: blocklist.csv entries: description: Entries to create in the matchlist type: array minItems: 1 items: $ref: '#/components/schemas/Create-Matchlist-Entry-Request' comment: $ref: '#/components/schemas/Comment' Matchlist-Entry-Matchlist: type: object description: >- The basic details for the matchlist to which the entry or entries belong. required: - matchlistId - name - action - state properties: matchlistId: type: string format: uuid description: Unique identifier of the matchlist. name: type: string description: Unique name of the matchlist. action: $ref: '#/components/schemas/Matchlist-Action' state: $ref: '#/components/schemas/Matchlist-State' Matchlist-Entries-Response: type: object description: Response object for a list of matchlist entries. required: - requestId - matchlist - entries properties: requestId: $ref: '#/components/schemas/Request-ID' matchlist: $ref: '#/components/schemas/Matchlist-Entry-Matchlist' entries: description: Entries in the matchlist. type: array items: $ref: '#/components/schemas/Matchlist-Entry' Matchlist-Entry-State-Writeable: type: string description: |- The state of the matchlist entry. - `ACTIVE`: The matchlist entry is active and can be used for matching. - `EXPIRED`: The matchlist entry has expired. It is visible and retrievable, but cannot be used for matching. - `DELETED`: The matchlist entry has been marked as deleted, rendering it unusable. To modify an entry's state, use `Matchlist-Entry-State-Writeable`. default: ACTIVE enum: - ACTIVE - EXPIRED - DELETED Update-Matchlist-Entry-Request: type: object description: > Request to change the state and the optional parts of an entry in a matchlist. properties: reference: type: string description: | Optional reference to describe the context of this entry. example: CERT-BAD-ACTOR-1234-5678 reasons: type: array description: > Optional reasons for the matchlist entry. These codes will translate to configured description strings. Note: Reasons are not additive to existing reasons. Updating the reasons will replace the existing value. items: $ref: '#/components/schemas/Matchlist-Entry-Reason-Code' state: $ref: '#/components/schemas/Matchlist-Entry-State-Writeable' Entity-Type-Writeable: type: string enum: - INDIVIDUAL - ORGANIZATION - UNKNOWN description: >- The type of entity within Frankie. This can be "INDIVIDUAL", "ORGANIZATION", or "UNKNOWN". Add-Matchlist-Entity-Request: type: object description: Used for adding an entity to a matchlist required: - entityId properties: entityId: $ref: '#/components/schemas/Entity-ID-Writeable' description: >- The entity ID of the entity from which the attributes of this entry will be derived. entityType: $ref: '#/components/schemas/Entity-Type-Writeable' description: >- The entity type of the entity from which the attributes of this entry will be derived. reasons: description: >- The reasons for the matchlist entry. These codes will translate to configured description strings. type: array items: $ref: '#/components/schemas/Matchlist-Entry-Reason-Code' comment: $ref: '#/components/schemas/Comment' Remove-Matchlist-Entity-Request: type: object description: Used for removing an entity from a matchlist. required: - entityId properties: entityId: $ref: '#/components/schemas/Entity-ID-Writeable' description: >- The entity ID of the entity from which the entry to be marked as deleted was derived. entityType: $ref: '#/components/schemas/Entity-Type-Writeable' description: >- The entity type of the entity from which the attributes of this entry will be derived. comment: $ref: '#/components/schemas/Comment'