Entity extraData Key Value Pairs

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

{
  "kvpKey": "customer_reference",
  "kvpValue": "your-unique-identifier",
  "kvpType": "id.external"
}

{
  "kvpKey": "any-custom-key",
  "kvpValue": "your-custom-identifier",
  "kvpType": "id.external"
}

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

{
  "entity": {
    "entityProfile": "safe_harbour",
    "entityType": "INDIVIDUAL",
    "name": {
      "familyName": "TESTFamilyName",
      "givenName": "TESTGivenName"
    },
    "dateOfBirth": {
      "dateOfBirth": "1960-01-01"
    },
    "identityDocs": [
      {
        "country": "AUS",
        "idType": "DRIVERS_LICENCE",
        "idNumber": "85544842",
        "region": "VIC",
        "extraData": [
          {
            "kvpKey": "document_number",
            "kvpValue": "21631234"
          }
        ]
      }
    ],
    "addresses": [
      {
        "addressType": "RESIDENTIAL1",
        "country": "AUS",
        "postalCode": "2761",
        "state": "NSW",
        "streetName": "TEST Buckwell",
        "streetNumber": "176",
        "streetType": "Drive",
        "town": "HASSALL GROVE",
        "unitNumber": "2"
      }
    ],
    "extraData": [
      {
        "kvpKey": "consent.general",
        "kvpValue": "true",
        "kvpType": "general.bool"
      },
      {
        "kvpKey": "consent.docs",
        "kvpValue": "true",
        "kvpType": "general.bool"
      },
      {
        // Customer reference KVP
        "kvpKey": "customer_reference",
        "kvpValue": "frankie-customer-01",
        "kvpType": "id.external"
      }
    ]
  }
}

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

Guide to the API

KYC API Endpoints

Fraud & AML API Endpoints

IDV API Endpoints

KYB Trust Agent

KYB V2 API - Preview

Entity extraData Key Value Pairs

Customer Reference Number

Customer Reference Configuration

Example Implementation

​Customer Reference Number

​Customer Reference Configuration

​Example Implementation

Customer Reference Number

Customer Reference Configuration

Example Implementation