> ## Documentation Index
> Fetch the complete documentation index at: https://docs.frankieone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Callout icon="bell" color="#FFCA16" iconType="regular">
  The total size of the JSON entity structure (excluding identity documents)
  must not exceed 256KB.
</Callout>

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`](/docs/v1/api/kyc-api-endpoints/reference/entity/search-entity) API.

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

### Customer Reference Configuration

<CodeGroup>
  ```json Customer Reference KVP Structure theme={null}
  {
    "kvpKey": "customer_reference",
    "kvpValue": "your-unique-identifier",
    "kvpType": "id.external"
  }
  ```

  ```json Additional External IDs theme={null}
  {
    "kvpKey": "any-custom-key",
    "kvpValue": "your-custom-identifier",
    "kvpType": "id.external"
  }
  ```
</CodeGroup>

<Callout icon="thumbtack" color="#1A6CFF" iconType="regular">
  FrankieOne indexes any KVP with `kvpType` set to `id.external`. However, the
  portal displays only the `customer_reference` KVP as "Customer ID".
</Callout>

## Example Implementation

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

```json title="Create Entity with Customer Reference" {39-56} theme={null}
{
  "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"
      }
    ]
  }
}
```

<Callout icon="star" color="#3DD892" iconType="regular">
  Some customers have access to additional custom KVP features. Contact
  [help@frankieone.com <Icon icon="arrow-up-right-from-square" size={12} />](mailto:help@frankieone.com) to
  learn about options available for your integration.
</Callout>