Individuals API

Individual Verification

The following examples show how to use the FrankieOne API to perform functions related to an individual.

Create an individual entity

To create an individual entity eligible for verification, make a request to the POST /v2/individuals API endpoint.

• To add a name to an individual, use the name object in the request body.

"name": {
	"givenName": "Johnny",
	"middleName": "Tan",
	"familyName": "Doe",
	"displayName": "Johnny Tan Doe"
}

• To add a date of birth to an individual, use the dateOfBirth object in the request body.

...
"dateOfBirth": {
	"year": "1990",
	"month": "05",
	"day": "15"
},
...

• To add an address to an individual, use the addresses array in the request body.
• To add multiple addresses, add a separate address to the addresses array.

...
"addresses": 
[
	{
		"type": "RESIDENTIAL",
		"streetName": "King",
		"streetNumber": "123",
		"streetType": "Street",
		"neighborhood": "Melbourne CBD",
		"locality": "Melbourne",
		"subdivision": "VIC",
		"country": "AUS",
		"postalCode": "3000",
		"status": "CURRENT"
	}
]
...

• To acknowledge consent for an individual, use the consents array in the request body.

...
"consents": 
[
	{
		"type": "GENERAL"
	},
	{
		"type": "CREDITHEADER"
	},
	{
		"type": "DOCS"
	},	
]
}
...

Sample request

curl --location 'http://api.{{env}}.frankie.one/v2/individuals' \
--header 'api_key: {{your_apiKey}}' \
--header 'X-Frankie-CustomerID: {{your_CustomerID}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
  "individual": {
"name": 
{
		"givenName": "Johnny",
		"middleName": "Tan",
		"familyName": "Doe",
		"displayName": "Johnny Tan Doe"
	},
"dateOfBirth": 
{
		"year": "1990",
		"month": "05",
		"day": "15"
},
"addresses": 
[
{
"type": "RESIDENTIAL",
	"streetName": "King",
	"streetNumber": "123",
	"streetType": "Street",
	"neighborhood": "Melbourne CBD",
	"locality": "Melbourne",
	"subdivision": "VIC",
	"country": "AUS",
	"postalCode": "3000",
	"status": "CURRENT"
}
],
"consents": 
[
	{
		"type": "GENERAL"
	},
	{
		"type": "CREDITHEADER"
	},
	{
		"type": "DOCS"
	}
]
}
}'

Sample response

🚧

Collect the entityId in the response as it will be used in subsequent API calls for this individual.

Status: 201 Created

{
  "individual": {
    "entityId": "{entityId}",
    "entityType": "INDIVIDUAL",
    "createdAt": "2024-01-31T23:21:57.296Z",
    "schemaVersion": 2,
    "addresses": [
      {
        "addressId": "{addressId}",
        "type": "RESIDENTIAL",
        "streetName": "King",
        "streetNumber": "123",
        "streetType": "Street",
        "neighborhood": "Melbourne CBD",
        "locality": "Melbourne",
        "subdivision": "VIC",
        "country": "AUS",
        "postalCode": "3000",
        "status": "CURRENT"
      }
    ],
    "name": {
      "nameId": "{nameId}",
      "givenName": "Johnny",
      "middleName": "Tan",
      "familyName": "Doe",
      "displayName": "Johnny Tan Doe"
    },
    "dateOfBirth": {
      "dateOfBirthId": "{dateOfBirthId}"
      "normalized": "1990-03-31",
      "year": "1990",
      "month": "03",
      "day": "27",
      "type": "GREGORIAN"
      },
"consents": 
[
	{
		"type": "GENERAL"
	},
	{
		"type": "CREDITHEADER"
	},
	{
		"type": "DOCS"
	},	
]
}
  },
  "requestId": "{requestId}"
}

Note: Service Profiles have been intentionally omitted for brevity

Addresses

🚧

Don't forget the Address ID.

When updating an address, don’t forget to include the addressId field. This would have been in the response message when you first added the address.

You can always get the addressId (and all other IDs) if you call the GET /v2/{entityType}/{entityId} API call.

🚧

Don't forget the Country

This field is mandatory and must be one of the ISO-3166-alpha-3 codes.

See here: List of ISO 3166 country codes

Address Types

Addresses have a number of available type options. Whilst this is an optional field, it is good practice to include the type to assist with processing and checking. It is recommended that these following types be used:

• **RESIDENTIAL **- This will be the primary address used when trying to determine the country of residence and primary current address. If RESIDENTIAL has been used for this, note that this will be deprecated and removed in the next major version of the API.
• **POSTAL **- This is a mailing address. It is also used as the current residential address if no RESIDENTIAL type is found.

Street Address and the use of the streetName field

It can be hard to break down an address and so we’ve made the streetName field quite flexible.

Whilst it is best to break the address into its constituent parts, you can combine streetNumber, streetName and streetType into the streetName field if required.

🚧

It's better to break down the address fields.

Whilst combining the fields is readily supported, best matching results are found when you break the address down into as many fields as you can.

Structured Addresses

It is always best to use the structured address and map in 1-1 the following fields.

Example 1: Full Address Entered as Separate Fields (preferable)

...
"addresses": 
[
	{
		"type": "RESIDENTIAL",
		"streetName": "King",
		"streetNumber": "123",
		"streetType": "Street",
                "locality": "Melbourne",
		"subdivision": "VIC",
		"country": "AUS",
		"postalCode": "3000",
		"status": "CURRENT"
	}
]
...

Example 2: Full Address Entered as Long Form

...
"addresses": 
[
	{
		"type": "RESIDENTIAL",
		"longForm": "123 King Street, Melbourne 3000, Victoria, Australia",
		"status": "CURRENT"
	}
]
...

Consent

Before proceeding with data verification checks, obtaining consent is essential and varies based on the verification type. While general consent encompasses standard verifications against government databases, it may not include credit checks and document validations. Consult with your AML team and the FrankieOne team to determine what consent flags you need to supply.

Retrieve an individual entity

The individual entity can be retrieved at any time by making a request to the GET /v2/individuals/{entityId} API endpoint.

Update an individual entity

The individual entity can be updated at any time by making a request to the PATCH /v2/individuals/{entityId} API endpoint.

To update a specific element of an individual entity, be sure to provide the relevant information you wish to update along with the ID of the object. This does not the case with primary entity elements (name, dateOfBirth, placeOfBirth)

Example 1: update a name

"name": 
{
	"givenName": "James",
	"familyName": "Done"
}

Example 2: update an address

"addresses": 
[
	{
		"addressId": "{addressId}",
		"status": "CURRENT"
	}
]

Example 3: update alternateDatesOfBirth

"alternateDatesOfBirth": 
{
	"dateOfBirthId": "{dateOfBirthId}",
        "year": "1992",
	"month": "12",
	"day": "05"
}

Adding entity elements

To add a new object to an existing entity, simply add the new object without an ID.

Example 1: adding an address

"addresses": 
[
	{
		"type": "RESIDENTIAL",
		"streetNumber": "123",
		"streetName": "King",
		"streetType": "Street",
		"locality": "Melbourne",
		"postalCode": "3000",
		"subdivision": "NSW",
		"country": "AUS",
		"status": "CURRENT"
	}
]

Adding consents

Consents will not be duplicated so new consent types will simply be added if not already applied.

Example 2: adding consents

"consents":  
[  
	{  
		"type": "CREDITHEADER"  
	}  
]

Deleting entity elements

Individual entity objects can be deleted at any time by making a request to the DELETE /v2/individuals/{entityId}/{objectType}/{objectId} API endpoint.

Example 1: deleting a phoneNumber

DELETE /v2/individuals/{entityId}/phonenumbers/{objectId}

Example 2: deleting a emailAddress

DELETE /v2/individuals/{entityId}/emailaddresses/{objectId}

Deleting documents

Individual document objects can be deleted at any time by making a request to the DELETE /v2/individuals/{entityId}/documents/{documentId} API endpoint.

DELETE /v2/individuals/{entityId}/documents/{documentId}

Deleting document attachments

Individual document attachment objects can be deleted at any time by making a request to the DELETE /v2/individuals/{entityId}/documents/{documentId}/attachments/{attachmentId} API endpoint.

DELETE /v2/individuals/{entityId}/documents/{documentId}/attachments/{attachmentId}

Withdrawing consent

Individual consent of a certain type can be withdrawn at any time by making a request to the DELETE /v2/individuals/{entityId}/consents/{consentType} API endpoint.

DELETE /v2/individuals/{entityId}/consents/CREDITHEADER

Delete an individual entity

The individual entity can be deleted at any time by making a request to the DELETE /v2/individuals/{entityId} API endpoint.

❗️

Individual entities that are deleted can not be recovered by FrankieOne.

Please ensure you only delete entities that are no longer needed for any purpose, including audit or compliance.