> ## Documentation Index
> Fetch the complete documentation index at: https://docs.frankieone.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Creating & Managing Individuals
> A guide to the complete lifecycle of an 'individual' entity, from creation and retrieval to updates and deletion.
The `individual` is the core object in the FrankieOne platform, representing a single customer. This guide covers the complete lifecycle of creating and managing these entities via the API.
### Video Guide
***
## 1. Creating an Individual
To begin any verification, you must first create an `individual` entity. This is done by sending a `POST` request with the customer's details to the `/v2/individuals` endpoint. A successful request will return a `201 Created` status and the full `individual` object, including a unique `entityId`.
##### Warning: Capture the entityId
The `entityId` returned in the response is critical for all subsequent operations, such as updating the entity or executing a workflow.
### Example: Creating a Standard Individual
This example shows a standard request to create an individual with their name, date of birth, address, and a passport document.
```http HTTP Request theme={null}
POST /v2/individuals
```
```json JSON Request Body theme={null}
{
"individual": {
"name": {
"givenName": "Jane",
"familyName": "Citizen"
},
"gender": {
"gender": "FEMALE"
},
"dateOfBirth": {
"year": "1992",
"month": "08",
"day": "15"
},
"nationality": "AUS",
"addresses": [
{
"type": "RESIDENTIAL",
"streetNumber": "123",
"streetName": "Exhibition",
"streetType": "Street",
"locality": "Melbourne",
"subdivision": "VIC",
"postalCode": "3000",
"country": "AUS"
}
],
"documents": {
"IDENTITY": [
{
"type": "PASSPORT",
"primaryIdentifier": "E1234567",
"country": "AUS",
"attachments": [
{
"filename": "passport.jpg",
"mimeType": "image/jpeg",
"side": "FRONT",
"data": {
"base64": "R0lGODlhAQABAIAAAP///wAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw=="
}
}
]
}
]
},
"consents": [
{
"type": "GENERAL"
},
{
"type": "DOCS"
}
]
}
}
```
### Anatomy of the `individual` Object
The `individual` object is a rich structure that holds all the information about your customer. Below is a breakdown of its key components.
#### Name
The primary legal name of the individual. You can also provide an array of `alternateNames` for other names the individual may be known by (e.g., maiden name).
The primary `name` object is required, and must contain at least a `familyName`. For entries in `alternateNames`, the `familyName` is also the only mandatory field.
#### Date of Birth
The individual's date of birth. The `year`, `month`, and `day` should be provided.
The `normalized` field in the response is read-only. The `type` field is optional and defaults to `GREGORIAN`.
#### Addresses & Place of Birth
An array of address objects. The `country` field (ISO 3166-1 alpha-3) is mandatory for each address. Use `status: 'PREVIOUS'` for past addresses. The `placeOfBirth` object uses the same address structure.
While the `addresses` field is optional, if you include it, the `country` field within each address object is mandatory.
* Use the `status` field to indicate if the address is `CURRENT` or `PREVIOUS`.
* Use `type` to specify the address type, such as `RESIDENTIAL` or `BUSINESS`.
* Both `CURRENT` and `PREVIOUS` addresses can be provided to give a complete picture of the individual's residential history.
#### Phone Numbers & Email Addresses
Arrays of `phoneNumbers` and `emailAddresses` objects to store contact information.
Both `emailAddresses` and `phoneNumbers` are optional. If included, the `type` field is required for each entry. Use `isPreferred: true` to indicate the primary contact method.
#### Documents
An object containing arrays of documents, categorized by their class (e.g., `IDENTITY`, `SUPPORTING`). The `type` and `country` are required for each document.
Each document can have multiple `attachments`. The `data` field, containing the `base64` encoded file, is mandatory for each attachment.
For a full list of document types, refer to the [Country Specific Documents](/docs/v2/kyc/global-kyc-coverage/global-kyc-guide#country-and-document-coverage).
#### Consents
An array of consent objects. This is critical for compliance. You must provide the consent types relevant to the checks you will perform (e.g., `GENERAL`, `DOCS`).
Consult with your AML team and the FrankieOne team to determine the appropriate consent flags for your use case.
For a full list of consent types, refer to the [Consent Types](/docs/key-data-objects).
#### External References
The `externalReferences` array is used to store your own internal identifiers against the FrankieOne entityId. This is crucial for linking a user in your system to their corresponding profile in FrankieOne.
Each object in the array requires a name and a value.
```json Example: Storing an Internal Customer ID theme={null}
"externalReferences": [
{
"type": "CUSTOMER", // Can be CUSTOMER, SYSTEM or OTHER
"name": "customer-id",
"value": "CUST-1138-90210",
"description": "The customer's unique identifier in our core banking system."
}
]
```
##### `externalReferences`with`type = "ACCOUNT"`
When using FrankieOne Fraud and Transaction Monitoring, external references with type `ACCOUNT` are used to link an individual to their financial accounts. See [TM Implementation Guide — The detail object](/v2/docs/tm/implementation) for how this data is used during activity evaluation.
* The reference represents an account (for example, a bank account, wallet, loan, or trading account).
* The `value` field should contain your account ID.
* The `metadata`object holds account details (such as status and product type), which are copied into the [**activity evaluation**](/v2/docs/tm/implementation) when account enrichment is enabled for your configuration and `partyAccount` matches this reference.
#### Custom Attributes
Custom attributes on an individual entity are a flexible key-value object for storing any additional data relevant to your business that doesn't fit into the other standard fields. These attributes are stored on the entity profile, are visible in the FrankieOne Portal, and can be used as criteria in an individual's risk profile configuration.
**Note:** The activity evaluation API also accepts a separate `customAttributes` object under the `detail` object. That field passes context-specific data at the time of evaluation for use in custom rules. See [TM Implementation Guide — The detail object](/v2/docs/tm/implementation) for details.
```json theme={null}
{
"customAttributes": {
"accountTier": {
"type": "STRING",
"value": "premium"
},
"annualIncome": {
"type": "NUMBER",
"value": "95000"
}
}
}
```
#### Other Fields
* `gender`: The individual’s gender (e.g., `MALE`, `FEMALE`, `NON_BINARY`).
* `nationality`: The individual’s nationality as an ISO 3166-1 alpha-3 code.
***
## 2. Retrieving an Individual
To fetch the current state of an individual entity, use a `GET` request with their unique `entityId`.
```HTTP HTTP theme={null}
GET /v2/individuals/{entityId}
```
The response will contain the full `individual` object, identical in structure to the response from the creation request.
***
## 3. Updating an Individual
To modify an existing individual, use a `PATCH` request. This method allows for partial updates, meaning you only need to send the fields you wish to change.
To update a specific element within an array (like an address or document), you must include its unique ID (e.g., `addressId`, `documentId`) in the object you send.
**Example:**
* **Updating an Address** This example updates an existing address by providing its `addressId` and the new field values.
````HTTP HTTP theme={null}
PATCH /v2/individuals/{entityId}
```json JSON
{
"individual": {
"addresses": [
{
"addressId": "adr_01HBH9XJ4Z5Y6W7R8S9T0V1A2C",
"postalCode": "3001"
}
]
}
}
````
***
## 4. Deleting an Individual & Its Elements
You can delete an entire entity or just specific pieces of information associated with it.
##### Deletion is Permanent
Deleting an entity or its elements is an irreversible action. This data cannot be recovered. Only perform deletions when you are certain the data is no longer required for any operational, audit, or compliance purpose.
### Deleting an Entire Individual
To permanently remove an individual and all their associated data, use the `DELETE` endpoint with their `entityId`.
```HTTP HTTP theme={null}
DELETE /v2/individuals/{entityId}
```
### Deleting Specific Elements
To remove a specific piece of information without deleting the whole entity, use the corresponding endpoint from the table below. You will need the unique ID for the element you wish to delete.
| Element to Delete | Endpoint |
| :------------------ | :------------------------------------------------------------------------------------ |
| Name | `DELETE /v2/individuals/{entityId}/names/{nameId}` |
| Date of Birth | `DELETE /v2/individuals/{entityId}/datesOfBirth/{dateOfBirthId}` |
| Address | `DELETE /v2/individuals/{entityId}/addresses/{addressId}` |
| Email Address | `DELETE /v2/individuals/{entityId}/emailaddresses/{emailAddressId}` |
| Phone Number | `DELETE /v2/individuals/{entityId}/phonenumbers/{phoneNumberId}` |
| Document | `DELETE /v2/individuals/{entityId}/documents/{documentId}` |
| Document Attachment | `DELETE /v2/individuals/{entityId}/documents/{documentId}/attachments/{attachmentId}` |
| External Reference | `DELETE /v2/individuals/{entityId}/externalreferences/{referenceId}` |
| Consent | `DELETE /v2/individuals/{entityId}/consents/{consentType}` |