Creating & Managing Individuals

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.

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.

1
POST /v2/individuals
2
```json JSON Request Body
3
{
4
  "individual": {
5
    "name": {
6
      "givenName": "Jane",
7
      "familyName": "Citizen"
8
    },
9
    "gender": {
10
      "gender": "FEMALE"
11
    },
12
    "dateOfBirth": {
13
      "year": "1992",
14
      "month": "08",
15
      "day": "15"
16
    },
17
    "nationality": "AUS",
18
    "addresses": [
19
      {
20
        "type": "RESIDENTIAL",
21
        "streetNumber": "123",
22
        "streetName": "Exhibition",
23
        "streetType": "Street",
24
        "locality": "Melbourne",
25
        "subdivision": "VIC",
26
        "postalCode": "3000",
27
        "country": "AUS"
28
      }
29
    ],
30
    "documents": {
31
      "IDENTITY": [
32
        {
33
          "type": "PASSPORT",
34
          "primaryIdentifier": "E1234567",
35
          "country": "AUS",
36
          "attachments": [
37
            {
38
              "filename": "passport.jpg",
39
              "mimeType": "image/jpeg",
40
              "side": "FRONT",
41
              "data": {
42
                "base64": "R0lGODlhAQABAIAAAP///wAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw=="
43
              }
44
            }
45
          ]
46
        }
47
      ]
48
    },
49
    "consents": [
50
      {
51
        "type": "GENERAL"
52
      },
53
      {
54
        "type": "DOCS"
55
      }
56
    ]
57
  }
58
}

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).

Date of Birth

The individual’s date of birth. The year, month, and day should be provided.

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.

Phone Numbers & Email Addresses

Arrays of phoneNumbers and emailAddresses objects to store contact information.

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.

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).

For a full list of consent types, refer to the Consent Types.

External References

The 1externalReferences1 array is used to store your own internal identifiers against the FrankieOne 1entityId1. 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.

1
"externalReferences": [
2
  {
3
    "type": "CUSTOMER", // Can be CUSTOMER, SYSTEM or OTHER
4
    "name": "customer-id",
5
    "value": "CUST-1138-90210",
6
    "description": "The customer's unique identifier in our core banking system."
7
  }
8
]

Custom Attributes

A flexible key-value object for storing any additional data relevant to your business that doesn’t fit into the other standard fields.

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.

1
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.

Example: Updating an Address This example updates an existing address by providing its addressId and the new field values.

1
PATCH /v2/individuals/{entityId}
2
```json JSON
3
{
4
  "individual": {
5
    "addresses": [
6
      {
7
        "addressId": "adr_01HBH9XJ4Z5Y6W7R8S9T0V1A2C",
8
        "postalCode": "3001"
9
      }
10
    ]
11
  }
12
}

4. Deleting an Individual & Its Elements

You can delete an entire entity or just specific pieces of information associated with it.

Deleting an Entire Individual

To permanently remove an individual and all their associated data, use the DELETE endpoint with their entityId.

1
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.