Entity extraData Key Value Pairs

Every entity in the FrankieOne system can include optional key-value pairs (KVPs) for storing additional data. These KVPs provide flexibility for custom data storage and enable special functionality within the FrankieOne service.

Customer Reference Number

The total size of the JSON entity structure (excluding identity documents) must not exceed 256KB.

The customer_reference Key Value Pair (KVP) allows you to store and index your organization’s unique identifier for an entity. This reference can later be used for searching through the /search API.

While the KvpType is typically optional for most KVPs, you must set it to id.external for customer references to be properly indexed.

Customer Reference Configuration

1{
2  "kvpKey": "customer_reference",
3  "kvpValue": "your-unique-identifier",
4  "kvpType": "id.external"
5}

FrankieOne indexes any KVP with kvpType set to id.external. However, the portal displays only the customer_reference KVP as “Customer ID”.

Example Implementation

Here’s a complete example showing how to create an entity with a customer reference:

Create Entity with Customer Reference
1{
2  "entity": {
3    "entityProfile": "safe_harbour",
4    "entityType": "INDIVIDUAL",
5    "name": {
6      "familyName": "TESTFamilyName",
7      "givenName": "TESTGivenName"
8    },
9    "dateOfBirth": {
10      "dateOfBirth": "1960-01-01"
11    },
12    "identityDocs": [
13      {
14        "country": "AUS",
15        "idType": "DRIVERS_LICENCE",
16        "idNumber": "85544842",
17        "region": "VIC",
18        "extraData": [
19          {
20            "kvpKey": "document_number",
21            "kvpValue": "21631234"
22          }
23        ]
24      }
25    ],
26    "addresses": [
27      {
28        "addressType": "RESIDENTIAL1",
29        "country": "AUS",
30        "postalCode": "2761",
31        "state": "NSW",
32        "streetName": "TEST Buckwell",
33        "streetNumber": "176",
34        "streetType": "Drive",
35        "town": "HASSALL GROVE",
36        "unitNumber": "2"
37      }
38    ],
39    "extraData": [
40      {
41        "kvpKey": "consent.general",
42        "kvpValue": "true",
43        "kvpType": "general.bool"
44      },
45      {
46        "kvpKey": "consent.docs",
47        "kvpValue": "true",
48        "kvpType": "general.bool"
49      },
50      {
51        // Customer reference KVP
52        "kvpKey": "customer_reference",
53        "kvpValue": "frankie-customer-01",
54        "kvpType": "id.external"
55      }
56    ]
57  }
58}

Some customers have access to additional custom KVP features. Contact help@frankieone.com to learn about options available for your integration.

Built with