Create & Manage an Entity
This guide provides an overview of how to create and manage entities using the FrankieOne KYC v2 API.
Create an Individual Entity
To create an individual entity eligible for verification, use the POST /v2/individuals API endpoint. This endpoint allows you to provide detailed information about the individual, such as their name, date of birth, address, and consents, to ensure accurate verification.
When creating an individual entity, you can include various information in the request body. Here are some examples:
Name & Alternate Names
When creating an individual entity, you can specify their primary name and alternate names to ensure accurate identification and verification. The name object is used for the primary name, while the alternateNames array allows you to include additional names the individual may be known by.
The primary name is required, with the family name being the only mandatory field. Alternate names are optional and also require only the family name if provided.
Primary Name Example
Alternate Names Example
Email Addresses & Phone Numbers
When creating an individual entity, you can include one or more email addresses and phone numbers using the emailAddresses and phoneNumbers arrays in the request body. These fields allow you to provide detailed contact information for the individual.
Both emailAddresses and phoneNumbers fields are optional. If included, the type field is required for each entry. The isPreferred field can be used to indicate the primary email address or phone number.
Email Address Example
Phone Number Example
Date of Birth
When creating an individual entity, you can include their date of birth using the dateOfBirth object in the request body. This ensures accurate identification and verification. Optionally, you can specify alternate dates of birth using the alternateDatesOfBirth object for cases where multiple formats or calendars are applicable.
Date of Birth Example
Alternate Dates of Birth Example
Addresses & Place of Birth
When creating an individual entity, you can include one or more addresses using the addresses array in the request body. Each address object allows you to provide detailed information such as street name, street number, postal code, and more. Additionally, you can specify the individual’s place of birth using the placeOfBirth object, which provides similar fields to describe the location of birth.
While the addresses field is optional, if included, the country field is the only required field. The status field is also optional and can be set to CURRENT, PREVIOUS, or UNKNOWN to indicate the address’s relevance. Similarly, the placeOfBirth object is optional but can be used to provide detailed information about the individual’s birth location.
Address Example
Place of Birth Example
Gender & Nationality
When creating an individual entity, you can specify their gender and nationality using the gender and/or nationality fields in the request body. These fields are optional but can help provide additional context for the individual.
The gender field accepts the following values: MALE, FEMALE, NON_BINARY, OTHER, and UNSPECIFIED. The nationality field should be a valid ISO 3166-1 alpha-3 country code (e.g., AUS for Australia).
Gender & Nationality Example
External References
When creating an individual entity, you can include external references using the externalReferences array in the request body. This allows you to associate external identifiers with the individual for tracking, integration, or verification purposes.
The type field can have values such as SYSTEM, CUSTOMER, or OTHER. Both name and value fields are required for each external reference. Optionally, you can include a description to provide additional context.
External Reference Example
Custom Attributes
When creating an individual entity, you can include custom attributes using the customAttributes object in the request body. This allows you to store additional information specific to your use case. Each custom attribute is represented as a key-value pair, where the key is the attribute name and the value contains the attribute details.
Custom Attributes Example
Consents
Consents are essential for ensuring compliance with legal and regulatory requirements when verifying an individual’s identity. Different types of consents are required depending on the verification type, such as general identity checks, document verification, or credit checks. Below is a detailed description of the available consent types:
Consent Types
These consents must be obtained before proceeding with any verification checks.
Consult with your AML team and the FrankieOne team to determine the appropriate consent flags for your use case.
Consent Example
Documents & Attachments
When creating an individual entity, you can include documents and attachments using the documents array in the request body. This allows you to associate various types of documents with the individual for verification purposes. Each document object can contain multiple attachments, such as images or files.
Attachments within a document can include metadata such as file type, page number, and location. Ensure that all attachments are properly scanned and free of malware before submission.
Documents are classified into categories such as REPORT, SUPPORTING, IDENTITY, or OTHER. The type and country fields are mandatory for each document, while the subtype field is optional and can provide additional context about the document (e.g., FACIAL_COMPARISON).
Document Types
Documents Example
Sample Request
Sample Response
Success
Status: 201 Created
The response from the API will include the details of the created individual entity, including unique identifiers for various elements such as names, dates of birth, addresses, and documents. This information is crucial for tracking and managing the entity within the FrankieOne system.
The sample response below demonstrates the structure of the data returned when creating an individual entity. Key objects, such as entityId, nameId, and documentId, are generated by the FrankieOne system and serve as unique identifiers for the respective elements. These IDs are essential for managing and interacting with the created entity in subsequent API calls.
Ensure you collect the entityId from the response. This identifier is critical for performing further operations, such as updates, retrievals, or deletions, on the individual entity.
Manage an Entity
Once you’ve created an Individual Entity, you can manage the entity and its elements using various API endpoints. Below is a summary of the available endpoints for managing individual entities, including creating, updating, retrieving, and deleting records.
Get an Entity
To retrieve an individual entity, use the GET /v2/individuals/{entityId} endpoint. This endpoint allows you to fetch detailed information about the entity, including its names, dates of birth, addresses, and documents.
Replace {entityId} with the unique identifier of the individual entity you want to retrieve.
Update an Entity
To update an individual entity, use the PATCH /v2/individuals/{entityId} endpoint. This endpoint allows you to modify existing information about the entity, such as names, addresses, and documents.
Replace {entityId} with the unique identifier of the individual entity you want to update.
Key Considerations for Updating an Entity
- Partial Updates: The
PATCHmethod allows you to update only specific fields without affecting the entire entity. Include only the fields you want to update in the request body. Unspecified fields will remain unchanged. - Element-Specific Updates: To update specific elements of the entity (e.g., names, addresses, or documents), use the unique identifier of the element (e.g.,
nameId,addressId, ordocumentId) from the response of theGET /v2/individuals/{entityId}endpoint. - Validation: Always validate the data before sending the update request to avoid errors or inconsistencies in the entity’s information.
- Permissions: Ensure you have the necessary permissions to update the entity and its elements. Unauthorized updates may result in data loss or corruption.
- Sensitive Information: Be cautious when updating sensitive information, as incorrect updates may lead to compliance issues or data integrity problems.
- Adding New Consents: When adding new consents, they won’t be duplicated. New consent types will simply be added if they are not already applied to the individual entity.
Example: Updating a Name
To update a name, include the nameId and the fields you want to modify in the request body.
Request Body Example
Example: Updating an Address
To update an address, include the addressId and the fields you want to modify in the request body.
Request Body Example
Ensure that you include only the fields you want to update. Fields not included in the request body will remain unchanged.
The PATCH method is ideal for partial updates, allowing you to modify specific fields without overwriting the entire entity. This ensures data integrity and minimizes the risk of accidental data loss.
Managing Entity Documents
Documents associated with an individual entity can be managed using the following endpoints. These endpoints allow you to create, retrieve, update, and delete documents and their attachments.
Create a Document
To create a new document for an individual entity, use the POST /v2/individuals/{entityId}/documents endpoint. This allows you to associate a document with the entity for verification purposes.
Request Body Example
Retrieve All Documents
To retrieve all documents associated with an individual entity, use the GET /v2/individuals/{entityId}/documents endpoint.
Response Example
Retrieve a Single Document
To retrieve a specific document by its ID, use the GET /v2/individuals/{entityId}/documents/{documentId} endpoint.
Response Example
Update a Document
To update an existing document, use the PATCH /v2/individuals/{entityId}/documents/{documentId} endpoint. This allows you to modify specific fields of the document.
Request Body Example
Delete a Document
To delete a document associated with an individual entity, use the DELETE /v2/individuals/{entityId}/documents/{documentId} endpoint.
Deleting a document is a permanent action and cannot be undone. Ensure that you have the necessary permissions and that you are certain about the deletion before proceeding.
Delete an Attachment
To delete a specific attachment from a document, use the DELETE /v2/individuals/{entityId}/documents/{documentId}/attachments/{attachmentId} endpoint.
Deleting an attachment does not delete the entire document. Only the specified attachment will be removed.
Delete an Entity
To delete an individual entity, use the DELETE /v2/individuals/{entityId} endpoint. This endpoint allows you to remove the entity and all associated records from the system.
Warning
Deleting an entity is a permanent action and cannot be undone. Ensure that you have the necessary permissions and that you are certain about the deletion before proceeding. Please ensure you only delete entities that are no longer needed for any purpose, including audit or compliance.
Deleting Individual Entity Elements
To manage and delete specific elements of an individual entity, use the following endpoints. These endpoints allow you to remove names, dates of birth, addresses, email addresses, phone numbers, consents, external references, and document attachments.
Delete a Name
To delete a name associated with an individual entity, use the DELETE /v2/individuals/{entityId}/names/{nameId} endpoint.
Replace {entityId} with the unique identifier of the individual entity and {nameId} with the unique identifier of the name you want to delete.
Delete a Date of Birth
To delete a date of birth associated with an individual entity, use the DELETE /v2/individuals/{entityId}/datesOfBirth/{dateOfBirthId} endpoint.
Replace {entityId} with the unique identifier of the individual entity and {dateOfBirthId} with the unique identifier of the date of birth you want to delete.
Delete an Address
To delete an address associated with an individual entity, use the DELETE /v2/individuals/{entityId}/addresses/{addressId} endpoint.
Replace {entityId} with the unique identifier of the individual entity and {addressId} with the unique identifier of the address you want to delete.
Delete an Email Address
To delete an email address associated with an individual entity, use the DELETE /v2/individuals/{entityId}/emailaddresses/{emailAddressId} endpoint.
Replace {entityId} with the unique identifier of the individual entity and {emailAddressId} with the unique identifier of the email address you want to delete.
Delete a Phone Number
To delete a phone number associated with an individual entity, use the DELETE /v2/individuals/{entityId}/phonenumbers/{phoneNumberId} endpoint.
Replace {entityId} with the unique identifier of the individual entity and {phoneNumberId} with the unique identifier of the phone number you want to delete.
Withdraw a Consent
To withdraw a previously provided consent, use the DELETE /v2/individuals/{entityId}/consents/{consentType} endpoint.
Replace {entityId} with the unique identifier of the individual entity and {consentType} with the type of consent you want to withdraw (e.g., GENERAL, DOCS, etc.).
Delete an External Reference
To delete an external reference associated with an individual entity, use the DELETE /v2/individuals/{entityId}/externalreferences/{referenceId} endpoint.
Replace {entityId} with the unique identifier of the individual entity and {referenceId} with the unique identifier of the external reference you want to delete.
Delete a Document
To delete a document associated with an individual entity, use the DELETE /v2/individuals/{entityId}/documents/{documentId} endpoint.
Deleting a document is a permanent action and cannot be undone. Ensure that you have the necessary permissions and that you are certain about the deletion before proceeding.
Delete an Attachment
To delete a specific attachment from a document, use the DELETE /v2/individuals/{entityId}/documents/{documentId}/attachments/{attachmentId} endpoint.
Deleting an attachment does not delete the entire document. Only the specified attachment will be removed.