Creating & Managing Individuals

Video Guide

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.

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

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

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.

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 type (e.g., IDENTITY, SUPPORTING). The type and country are required for each document.

Each document can have multiple attachments, which are stored in an array. Each attachment must have a unique attachmentId and a fileName. The fileType is also required to specify the format of the attachment (e.g., PDF, JPEG).

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.

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.
• externalReferences: An array for storing your own internal identifiers against the FrankieOne entity. The type can be SYSTEM, CUSTOMER, or OTHER. The name and value fields are required.
• customAttributes: A flexible key-value object for storing any additional data relevant to your business.

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}

1
{
2
  "individual": {
3
    "addresses": [
4
      {
5
        "addressId": "adr_01HBH9XJ4Z5Y6W7R8S9T0V1A2C",
6
        "postalCode": "3001"
7
      }
8
    ]
9
  }
10
}

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.