openapi: 3.0.3
info:
title: Core V2 Audit IDV 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: IDV
description: Get a token and/or upload documents to initiate an IDV process
paths:
/v2/individuals/{entityId}/actions/idv/token:
parameters:
- $ref: '#/components/parameters/entityId'
post:
summary: Queries the IDV provider for a token to be used with their sdk. This allows a provider SDK to be instantiated, this is to be called before starting the IDV or OCR process.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/IDV-Token-Request'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/IDV-Token-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: getIDVToken
description: Get an IDV Token for the given individual.
parameters:
- $ref: '#/components/parameters/Api-Key'
- $ref: '#/components/parameters/X-Frankie-CustomerID'
- $ref: '#/components/parameters/X-Frankie-CustomerChildID'
- $ref: '#/components/parameters/X-Frankie-Channel'
tags:
- IDV
security:
- Api-Key: []
- jwt:
- kyc:api
/v2/individuals/{entityId}/actions/idv/ocr:
parameters:
- $ref: '#/components/parameters/entityId'
post:
summary: Submit an identity document photo for ocr processing. Results will be in the form of an identity document with populated with ocr results.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/IDV-OCR-Request'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/IDV-OCR-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: processIDVOCR
description: Submit an identity document photo for ocr processing. Results will be in the form of an identity document with populated with ocr results if successful. Status will be COMPLETE_OCR if OCR was successful and no further images are required. The image can be uploaded or captured via a vendor SDK after calling get IDV token, or can be submitted directly as a fileData.
parameters:
- $ref: '#/components/parameters/Api-Key'
- $ref: '#/components/parameters/X-Frankie-CustomerID'
- $ref: '#/components/parameters/X-Frankie-CustomerChildID'
- $ref: '#/components/parameters/X-Frankie-Channel'
tags:
- IDV
security:
- Api-Key: []
- jwt:
- kyc:api
/v2/individuals/{entityId}/actions/idv/process:
parameters:
- $ref: '#/components/parameters/entityId'
post:
summary: At the end of the IDV data capture process with all photos and videos captured, signal to IDV provider that check is ready to analyse and check.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/IDV-InitProcess-Request'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/IDV-InitProcess-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: initBiometrics
description: "At the end of the IDV data capture process with all photos and videos captured, signal to IDV provider\n that check is ready to analyse and check. If this call is successful, an entity\nis populated with with any details supplied if it doesn't not already have a name."
parameters:
- $ref: '#/components/parameters/Api-Key'
- $ref: '#/components/parameters/X-Frankie-CustomerID'
- $ref: '#/components/parameters/X-Frankie-CustomerChildID'
- $ref: '#/components/parameters/X-Frankie-Channel'
tags:
- IDV
security:
- Api-Key: []
- jwt:
- kyc:api
components:
schemas:
Session:
type: object
description: Session details for an activity, this is always scoped to a singular entity.
properties:
token:
type: string
description: A token to identify the specific session for the activity
Phone-Number-ID:
type: string
description: 'As phone numbers are added to an entity, they are assigned an ID to assist with tracking.
If you are adjusting phone numbers, you will need to include the ID to reference it correctly in the list.'
example: ad165f64-5717-4562-b3fc-2c963f66bfa9
Supplementary-Data-Activity-Device:
type: object
description: 'Defines the details of an activity device result.
'
allOf:
- $ref: '#/components/schemas/Supplementary-Data-Base'
- type: object
properties:
riskLevel:
type: string
activityResults:
type: array
items:
$ref: '#/components/schemas/Supplementary-Data-Activity-Result-Detail'
IDV-Token-Response:
type: object
description: IDV Token Response, contains the token and it's expiry, and any vendor specific parameters.
properties:
applicantId:
description: The ID of the applicant attached to this check.
type: string
country:
description: Country code to check for. Must be a ISO-3166 alpha-3 code entry.
example: AUS
type: string
documentType:
description: Document type that will be used for the check.
example: DRIVER_LICENCE
type: string
provider:
description: Underlying provider, used for selecting the correct SDK if not using SmartUI.
example: OCRLabs
type: string
smsSent:
description: Has a sms to the user already been sent as part of the token request
example: true
type: boolean
token:
description: Tokens are only valid for a limited time.
example: 41cf9401f0f889616bef
type: string
tokenExpiry:
description: The time at which the provided token will expire.
type: string
format: date-time
example: '2020-01-01T00:00:00.000Z'
vendorParameters:
description: Vendor specific parameters, used for passing through additional parameters from the vendor to instantiate the SDK.
additionalProperties:
type: string
example:
tokenURL: example1.com
type: object
requestId:
$ref: '#/components/schemas/Request-ID'
Process-ResultEnum:
type: string
enum:
- MATCH
- PARTIAL_MATCH
- INVALID_MATCH
- NO_MATCH
- CLEAR
- HIT
- BAD_DATA
- CREATED
- UPDATED
- DELETED
- FAIL
- NOT_APPLICABLE
- SUSPECTED
- REJECTED
- MANUAL
- CLEAR_AUTO
- OVERRIDE
readOnly: true
description: 'The actual pass/fail result of the element check
- MATCH: The element check matched the expected criteria.
- PARTIAL_MATCH: The element check partially matched the expected criteria.
- INVALID_MATCH: The element check matched but was invalid.
- NO_MATCH: The element check did not match the expected criteria.
- CLEAR: The element check was cleared.
- HIT: The element check hit a specific condition or threshold.
- BAD_DATA: The element check encountered bad data.
- CREATED: The element check resulted in the creation of a new record.
- UPDATED: The element check resulted in the update of an existing record.
- DELETED: The element check resulted in the deletion of a record.
- FAIL: The element check failed.
- NOT_APPLICABLE: The element check was not applicable in the given context.
- SUSPECTED: The element check raised a suspicion but did not confirm it.
- REJECTED: The element check was rejected.
- MANUAL: The element check was manually reviewed or processed.
- CLEAR_AUTO: The element check was cleared automatically.
- OVERRIDE: The element check was overridden by a manual action or system rule.
'
Document-Supplementary-Data-National-ID:
type: object
description: Supplementary information relevant to a national ID.
allOf:
- $ref: '#/components/schemas/Document-Supplementary-Data-Base'
- type: object
properties:
homeCountryFullName:
type: string
description: The original full name from the individual's home country national ID.
example: 张伟明
paternalFamilyName:
type: string
description: The individual's family name inherited from the father's side.
example: MENDOZA
maternalFamilyName:
type: string
description: The individual's family name inherited from the mother's side.
example: GARCIA
Supplementary-Data-Matchlist:
type: object
description: 'Each match against a matchlist entry generates a PRO (Process Result Object), and this object describes the details of the matched entry.
'
allOf:
- $ref: '#/components/schemas/Supplementary-Data-Base'
- $ref: '#/components/schemas/Matchlist-Entry-Base'
- type: object
properties:
matchlistId:
type: string
format: uuid
description: Unique identifier for the matchlist.
matchlistName:
type: string
description: Unique name of the matchlist.
matchlistAction:
$ref: '#/components/schemas/Matchlist-Action'
confidence:
$ref: '#/components/schemas/Search-Confidence'
matchedFields:
type: array
items:
$ref: '#/components/schemas/Supplementary-Data-Matchlist-Field'
Supplementary-Data-AML-SanctionsData:
type: object
description: 'Contains sanction information about a specific matched entity.
'
properties:
countryCode:
type: string
description: 'The ISO 3166-1 alpha-3 country code where the sanction entry was recorded.
'
countryName:
type: string
description: 'The ISO 3166 country name where the sanction entry was recorded.
'
sourceName:
type: string
description: 'The source of the sanction entry data.
'
sourceUrl:
type: string
format: uri
description: 'The URL where the original sanction information can be found.
'
sourceReason:
type: string
description: 'The reason provided for sanctioning the individual or organization.
'
listingStart:
type: string
description: 'The date when the listing started. Will attempt to use ISO 8601 date format; otherwise, the format supplied by the source.
'
listingEnd:
type: string
description: 'The date when the listing ended (if available or known). Will attempt to use ISO 8601 date format; otherwise, the format supplied by the source.
'
imageUrl:
type: string
format: uri
description: 'Optional URL of an image of the person or company logo of the sanctioned entity.
'
referenceDocs:
type: array
items:
$ref: '#/components/schemas/Supplementary-Data-AML-ReferenceDocs'
additionalData:
type: array
items:
$ref: '#/components/schemas/Supplementary-Data-AML-AdditionalData'
Supplementary-Data-Activity-AML:
type: object
description: 'Provides details of an activity Anti-Money Laundering (AML) result.
'
allOf:
- $ref: '#/components/schemas/Supplementary-Data-Base'
- type: object
properties:
riskLevel:
type: string
description: Indicates the assessed risk level for the activity.
activityResults:
type: array
description: A list of detailed results for the activity AML check.
items:
$ref: '#/components/schemas/Supplementary-Data-Activity-Result-Detail'
Individual-Name:
type: object
required:
- familyName
x-examples:
Example 1:
givenName: John
middleName: Jacob
familyName: Smith
properties:
nameId:
type: string
example: 87654321-4321-4321-4321-210987654321
description: Include the nameId of an existing name for this individual to modify it
readOnly: true
language:
type: string
example: eng
description: The ISO-639-3 standard code that best represents the language and character set of the individual's name
default: eng
givenName:
type: string
example: John
description: First name or given name
middleName:
type: string
example: R
description: Middle name(s) or middle initial(s)
familyName:
type: string
example: Doe
description: Last name, family name, or surname.
otherName:
type: string
example: null
description: Another name that this person may be known as, e.g., "Bob" as an alternative to "Robert".
prefix:
type: string
example: Dr.
description: Letters or words that come before an individual's full name (e.g., title or honorific).
suffix:
type: string
example: Jr.
description: Letters or words that come after an individual's full name (e.g., generational suffix).
sourceId:
type: string
example: 87654321-4321-4321-4321-210987654322
description: The source from where a specific information was sourced from. This is a link to an informationSource object in the informationSources map
readOnly: true
displayName:
type: string
example: John Doe
description: Long format of the individual's full name, including any prefix, suffix, middle, or other names. Best used when the proper structure of the individual's name is unknown.
Supplementary-Data-Fraud-IP-Address:
type: object
description: 'Defines the details of a single IP address fraud check.
'
allOf:
- $ref: '#/components/schemas/Supplementary-Data-Base'
- $ref: '#/components/schemas/Supplementary-Data-Fraud-IP-Address-Data'
Process-Result-Manual-StatusEnum-AML:
type: string
enum:
- TRUE_POSITIVE
- FALSE_POSITIVE
- TRUE_POSITIVE_ACCEPT
- TRUE_POSITIVE_REJECT
- UNKNOWN
- UNKNOWN_ACCEPT
- UNKNOWN_REJECT
description: 'The manual status that the AML process result should be set to after the results have been reviewed.
- FALSE_POSITIVE: The result is determined to be a false positive, but you do not necessarily want to resolve it.
- FALSE_POSITIVE_ACCEPT: The result is determined to be a false positive and you want to resolve it. "Accept" infers you want to accept the activity.
- TRUE_POSITIVE: The result is determined to be a true positive, but you do not necessarily want to resolve it.
- TRUE_POSITIVE_REJECT: The result is determined to be a true positive and you want to resolve it. "Reject" infers you want to reject the activity.
- UNKNOWN: The result is determined to be unknown, but you do not necessarily want to resolve it.
- UNKNOWN_ACCEPT: The result is determined to be unknown and you want to resolve it. "Accept" infers you want to accept the activity.
- UNKNOWN_REJECT: The result is determined to be unknown and you want to resolve it. "Reject" infers you want to reject the activity.
'
Relationship:
type: object
properties:
entityId:
$ref: '#/components/schemas/Entity-ID'
entityType:
$ref: '#/components/schemas/Entity-Type'
origin:
$ref: '#/components/schemas/Relationship-Origin'
Likelihood:
type: string
description: 'Likelihood of a particular scenario
'
enum:
- LOW
- MEDIUM
- HIGH
- VERY_HIGH
- UNKNOWN
Supplementary-Data-AML-WatchlistData:
type: object
description: 'Contains non-PEP/non-sanction watchlist and other source information about a specific matched entity.
'
properties:
countryCode:
type: string
description: 'The ISO 3166-1 alpha-3 country code where the watchlist entry was recorded.
'
countryName:
type: string
description: 'The ISO 3166 country name where the watchlist entry was recorded.
'
sourceName:
type: string
description: 'The source of the watchlist entry data.
'
sourceUrl:
type: string
format: uri
description: 'The URL where the original watchlist information can be found.
'
sourceReason:
type: string
description: 'The reason provided for adding the individual or organization to the watchlist.
'
listingStart:
type: string
description: 'The date when the listing started. Will attempt to use ISO 8601 date format; otherwise, the format supplied by the source.
'
listingEnd:
type: string
description: 'The date when the listing ended (if available or known). Will attempt to use ISO 8601 date format; otherwise, the format supplied by the source.
'
imageUrl:
type: string
format: uri
description: 'Optional URL of an image of the person or company logo of the entity on this list.
'
referenceDocs:
type: array
items:
$ref: '#/components/schemas/Supplementary-Data-AML-ReferenceDocs'
additionalData:
type: array
items:
$ref: '#/components/schemas/Supplementary-Data-AML-AdditionalData'
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.
Document-Supplementary-Data-Marriage-Certificate:
type: object
description: Supplementary information relevant to a marriage certificate.
allOf:
- $ref: '#/components/schemas/Document-Supplementary-Data-Base'
- type: object
description: Supplementary information relevant to a marriage certificate.
properties:
partner1GivenName:
type: string
description: The given name of partner 1.
example: Harry
partner1FamilyName:
type: string
description: The family name of partner 1.
example: Versailles
partner1OtherName:
type: string
description: The other name of partner 1.
example: S.
partner2GivenName:
type: string
description: The given name of partner 2.
example: Harry
partner2FamilyName:
type: string
description: The family name of partner 2.
example: Versailles
partner2OtherName:
type: string
description: The other name of partner 2.
example: S.
registrationDate:
type: string
description: The date the marriage was registered.
example: '2023'
marriageDate:
type: string
description: The date the marriage was held.
example: '2023-10-01'
dateOfPrint:
type: string
description: The date the birth certificate was printed.
example: '2023-10-01'
Supplementary-Data-Activity-Result-Detail-Indicator:
type: object
properties:
indicatorId:
$ref: '#/components/schemas/Indicator-ID'
name:
type: string
value:
type: string
score:
type: string
rules:
type: array
items:
$ref: '#/components/schemas/Supplementary-Data-Activity-Result-Detail-Rule'
Supplementary-Data-Matchlist-Attribute:
type: object
description: 'Information about a matched attribute within a matched field.
'
required:
- type
- confidence
properties:
type:
$ref: '#/components/schemas/Matchlist-Entry-Attribute-Type'
confidence:
$ref: '#/components/schemas/Search-Confidence'
description: 'Confidence score for the attribute match.
'
Request-ID:
type: string
example: 01HN9XHZN6MGXM9JXG50K59Q85
description: The unique request identifier for the API call made.
Supplementary-Data-Fraud-Device-Data:
type: object
description: 'Provides details of a single fraud check for device and related device data.
'
properties:
device:
$ref: '#/components/schemas/Device'
session:
$ref: '#/components/schemas/Session-Data'
indicators:
type: array
items:
$ref: '#/components/schemas/Supplementary-Data-Activity-Result-Detail-Indicator'
riskLevel:
$ref: '#/components/schemas/Risk-Level'
reference:
$ref: '#/components/schemas/Result-Reference'
Entity-Documents:
type: object
properties:
REPORT:
type: array
items:
$ref: '#/components/schemas/Document-Information'
SUPPORTING:
type: array
items:
$ref: '#/components/schemas/Document-Information'
IDENTITY:
type: array
items:
$ref: '#/components/schemas/Document-Information'
OTHER:
type: array
items:
$ref: '#/components/schemas/Document-Information'
Supplementary-Data-KYC-Address-MatchStrengths:
type: object
properties:
fullAddress:
type: integer
format: int32
minimum: 0
maximum: 100
streetNumber:
type: integer
format: int32
minimum: 0
maximum: 100
streetName:
type: integer
format: int32
minimum: 0
maximum: 100
streetType:
type: integer
format: int32
minimum: 0
maximum: 100
streetAll:
type: integer
format: int32
minimum: 0
maximum: 100
locality:
type: integer
format: int32
minimum: 0
maximum: 100
district:
type: integer
format: int32
minimum: 0
maximum: 100
subdivision:
type: integer
format: int32
minimum: 0
maximum: 100
postalCode:
type: integer
format: int32
minimum: 0
maximum: 100
country:
type: integer
format: int32
minimum: 0
maximum: 100
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
Supplementary-Data-AML-ReferenceDocs:
type: object
description: 'Captures references to source documents or websites, including the URL and, where available, a description of the original source.
'
properties:
url:
type: string
format: uri
description: URL of any external reference document related to this matched entity.
description:
type: string
description: If a description of the document is provided, it will be included here.
Matchlist-Entry-Reason-Code:
type: string
description: The reason code for the matchlist entry. This code will be translated to a configured description string. Supported codes are 1 to 24 characters long, consisting only of uppercase letters (A-Z), digits (0-9), underscores (_), or hyphens (-), with no spaces or special characters.
pattern: ^[A-Z0-9_-]{1,24}$
Supplementary-Data-Fraud-Email-Address:
type: object
description: 'Defines the details of a single email fraud check.
'
allOf:
- $ref: '#/components/schemas/Supplementary-Data-Base'
- type: object
properties:
emailAddressId:
$ref: '#/components/schemas/Email-Address-ID'
riskLevel:
$ref: '#/components/schemas/Risk-Level'
reference:
$ref: '#/components/schemas/Result-Reference'
indicators:
type: array
items:
$ref: '#/components/schemas/Supplementary-Data-Activity-Result-Detail-Indicator'
Process-Result-Object:
type: object
properties:
processResultId:
$ref: '#/components/schemas/Process-Result-ID'
sch
# --- truncated at 32 KB (150 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/frankieone/refs/heads/main/openapi/frankieone-idv-api-openapi.yml