openapi: 3.0.3
info:
title: Core V2 Audit Individual Entities 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: Individual Entities
description: Manage individual entity records
paths:
/v2/individuals:
parameters:
- $ref: '#/components/parameters/levelQuery'
post:
summary: Create an individual entity
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/individuals_entity_response'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'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
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
Internal Server Error:
value:
errorCode: SYS-1063,
errorMsg: Failed to generate KYC report
requestId: 01HM5EM2QNNSC9K0PX9VC06HX3
'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: createIndividuals
description: 'Creates an Individual entity object which can be used to store data about an individual. You can optionally include documents, attachments, references etc. to the entity.
Information stored in an entity object can be used to verify the individual against external data sources for the purposes of eKYC, or in other verifications supported by FrankieOne.'
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/individuals_create'
description: Create an individual
tags:
- Individual Entities
security:
- Api-Key: []
- jwt:
- kyc:api
/v2/individuals/{entityId}:
parameters:
- $ref: '#/components/parameters/entityId'
- $ref: '#/components/parameters/levelNoIdQuery'
patch:
summary: Update an individual entity
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/individuals_update'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/individuals_entity_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: updateIndividual
description: Update any of the information of the Individual Entity with the matching entity ID.
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:
- Individual Entities
security:
- Api-Key: []
- jwt:
- kyc:api
get:
summary: Get an individual entity
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/individuals_entity_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'
examples:
Unable to retrieve entity:
value:
errorCode: ENT-1010,
errorMsg: Unable to retrieve requested entity
details:
- issue: entityId
issueLocation: Cannot retrieve entityId (027d1e3d-95af-f19a-313a-3b869da9ce10)
requestId: 01HM5EM2QNNSC9K0PX9VC06HX3
'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: getIndividual
description: Retrieve all the information of the Individual Entity with the matching entity ID.
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:
- Individual Entities
security:
- Api-Key: []
- jwt:
- kyc:api
delete:
summary: Delete an individual entity
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
requestId:
$ref: '#/components/schemas/Request-ID'
entityId:
$ref: '#/components/schemas/Entity-ID'
'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: deleteIndividual
description: Delete Individual Entity with the matching entity ID.
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:
- Individual Entities
security:
- Api-Key: []
- jwt:
- kyc:api
components:
schemas:
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
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
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.
Relationship:
type: object
properties:
entityId:
$ref: '#/components/schemas/Entity-ID'
entityType:
$ref: '#/components/schemas/Entity-Type'
origin:
$ref: '#/components/schemas/Relationship-Origin'
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
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'
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:<service_name>; or User:<user_name>).
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.
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'
Request-ID:
type: string
example: 01HN9XHZN6MGXM9JXG50K59Q85
description: The unique request identifier for the API call made.
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'
Issue-ID:
type: string
description: Unique identifier for the risk issue.
readOnly: true
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
Date-Base:
type: object
properties:
year:
type: string
description: Year in "YYYY" format.
example: '1990'
month:
type: string
description: Month in "MM" format.
example: '03'
day:
type: string
description: Day in "DD" format.
example: '27'
unstructured:
type: string
description: 'Raw date format without normalization or standardization to the Gregorian calendar.
This can be used to provide non-Gregorian dates (e.g., Islamic dates).'
example: 12 Rajab 1445 AH
type:
$ref: '#/components/schemas/Date-Type'
Risk-Factor-ID:
type: string
description: Unique identifier of the risk factor.
readOnly: true
Document-Information:
type: object
required:
- type
- country
properties:
documentId:
$ref: '#/components/schemas/Document-ID'
entityId:
$ref: '#/components/schemas/Entity-ID'
expiryDate:
$ref: '#/components/schemas/Date'
description: The expiry date of the document in YYYY-MM-DD format.
issueDate:
$ref: '#/components/schemas/Date'
description: The issue date of the document in YYYY-MM-DD format.
primaryIdentifier:
type: string
description: The primary ID number of the document, e.g., the ID number on a driver licence.
example: '000734130'
secondaryIdentifier:
type: string
description: The secondary ID number of the document, e.g., the card number on a driver licence.
example: P0001975
type:
$ref: '#/components/schemas/Document-Type'
subtype:
type: string
description: The sub-type of the document, if relevant. This can include specific report or attestation types, e.g., FACIAL_COMPARISON (attestation) or KYC (report).
example: Photo Comparison
subdivision:
type: string
description: The abbreviated ISO 3166 subdivision/region where the ID was issued, e.g., "VIC" for the Australian state of Victoria or "MA" for the US state of Massachusetts.
example: VIC
country:
type: string
maxLength: 3
description: 'The ISO 3166 alpha-3 country code where the document was issued, if relevant.
For more information, please refer to: https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes'
example: AUS
createdAt:
type: string
format: date-time
description: The date and time when the document record was created, in ISO 8601 format.
example: '2024-01-15T02:18:11.365Z'
readOnly: true
updatedAt:
type: string
format: date-time
description: The date and time when the document record was last updated, in ISO 8601 format.
example: '2025-01-16T02:18:11.365Z'
readOnly: true
validFrom:
$ref: '#/components/schemas/Date'
description: The date when the validity period for this document began, if applicable.
validTo:
$ref: '#/components/schemas/Date'
description: The date when the validity period for this document ended, if applicable.
sourceId:
type: string
description: The source from which specific information was sourced. This is a link to an informationSource object in the informationSources map.
example: 324f15f64-5717-4562-b3fc-2c963f66ffa1
readOnly: true
supplementaryData:
$ref: '#/components/schemas/Document-Supplementary-Data'
customAttributes:
$ref: '#/components/schemas/Custom-Attributes'
attachments:
type: array
description: 'List of scans, pages, or files for a single document, e.g., front and back images of a driver licence, or page 1, 2, and 3 of a supporting document.
Attachments can be uploaded in a single call or in multiple calls. To upload attachments over multiple calls, include the documentId in the request.'
items:
$ref: '#/components/schemas/Document-Attachment'
Document-Supplementary-Data-Citizenship:
type: object
description: Supplementary information relevant to a citizenship certificate.
allOf:
- $ref: '#/components/schemas/Document-Supplementary-Data-Base'
- type: object
description: Supplementary information relevant to a citizenship certificate.
properties:
acquisitionDate:
type: string
description: The date citizenship was acquired.
example: 2000/01/01
primaryCountry:
type: string
description: The primary country of citizenship, represented by its three-letter ISO 3166-1 alpha-3 code.
example: USA
secondaryCountry:
type: string
description: The secondary country of citizenship, if applicable, represented by its three-letter ISO 3166-1 alpha-3 code.
example: CAN
Risk-Assessment-ID:
type: string
description: Unique identifier of the risk assessment.
readOnly: true
Date-Of-Birth-Alternate:
type: object
allOf:
- type: object
properties:
dateOfBirthId:
type: string
description: 'As dates of birth are added to an entity, they are assigned a unique identifier to assist with modification and reference.
To modify a date of birth, include the dateOfBirthId in an update request for the individual.'
sourceId:
type: string
description: The source from which specific information was sourced. This is a link to an informationSource object in the informationSources map.
readOnly: true
- $ref: '#
# --- truncated at 32 KB (98 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/frankieone/refs/heads/main/openapi/frankieone-individual-entities-api-openapi.yml