Common API Objects and Fields

Understanding Object IDs

Our API uses unversioned GUIDs to uniquely identify objects within our service. These IDs are:

Automatically assigned upon object creation
Included in all message responses
Used for subsequent API operations (update/modify/delete)

The following objects are uniquely identified using these IDs:

Customers
Entities
Documents
Addresses
Document scans
Checks
Batches
Transaction groups

The Document Object

What's a Document Object?

A document object represents various types of information or documentation, such as:

Identity documents (e.g., driver’s licenses)
Contact information (phone numbers, email addresses)
Reports or utility bills
Collections of related data

Documents can exist as metadata only (e.g., ID number, country, and state) or include actual document scans.

Document Object Example

{
  "country": "AUS",
  "createdFromScan": true,
  "docScan": [
    {
      "ScanDelete": true,
      "scanCreated": "2020-06-02",
      "scanData": "VGhpcyBpcyBzb21lIGV4YW1wbGUgZGF0YS4=",
      "scanDataRetrievalState": "NORMAL",
      "scanDocId": "84a9a860-68ae-4d7d-9a53-54a1116d5051",
      "scanFilename": "Important Document - ID1234567.pdf",
      "scanMIME": "image/png",
      "scanPageNum": 1,
      "scanSide": "F",
      "scanType": "PDF"
    }
  ],
  "documentId": "84a9a860-68ae-4d7d-9a53-54a1116d5051",
  "documentStatus": "DOC_SCANNED",
  "idExpiry": "2020-02-01",
  "idIssued": "1972-11-04",
  "idNumber": "123456789",
  "idType": "DRIVERS_LICENCE",
  "region": "VIC"
}

Scanned Documents in Business Check Results

Document Data Options
Performance Note

Control document inclusion in results using the documentData parameter:

Parameter Value	Behavior
No parameter	Includes scanned document
`full`	Includes full scanned document
`meta`	Excludes scanned document, includes only metadata

Including full scanned documents increases result retrieval time. Choose the appropriate documentData parameter based on your needs.

Create Organization Entity

First, create an organization entity using the Create Entity API

Upload Document Scan

Upload the relevant document scan using the Create Document API

Complete Ownership Verification

Verify ownership using the Business Ownership Query API

Perform Business Check

Execute the check with your chosen documentData parameter

The Entity Object

An entity represents either a person or business in our system. It contains structured data including personal/organizational information and can hold multiple Document Objects.

Entity Structure Overview

An entity contains multiple elements including:

Basic information (name, addresses, date of birth)
Organizational data (for businesses)
Document Objects (optional)
Additional metadata

Entity Object Example

{
  "entityId": "84a9a860-68ae-4d7d-9a53-54a1116d5051",
  "entityType": "INDIVIDUAL",
  "name": {
    "displayName": "Jane Cecily Smith",
    "familyName": "Smith",
    "givenName": "Jane",
    "honourific": "Duchess",
    "middleName": "Cecily"
  },
  "dateOfBirth": {
    "country": "AUS",
    "dateOfBirth": "1978-11-12",
    "locality": "Brisbane",
    "yearOfBirth": "1978"
  },
  "addresses": [
    {
      "addressId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "addressType": "RESIDENTIAL1",
      "buildingName": "Tower of Babel",
      "country": "TST",
      "postalCode": "123-TST",
      "state": "TS",
      "streetName": "Test Eagle West",
      "streetNumber": "42a",
      "suburb": "Testburb"
    }
  ],
  "gender": "F"
}

Key Value Pairs (KVPs)

Key Value Pairs provide flexibility for storing additional data that doesn’t fit into our standard object structure. While stored as strings, KVPs include type hints for better data handling.

KVP Types Overview

Basic Types
Identity & PII Types
Result Types

general.*: Generic data types (string, integer, float, bool, date, datetime)
raw.*: Binary/encoded data (json.base64, xml.base64, base64)
transient.*: Temporary data that’s only valid for one API call

id.*: Identity-related data (external, number.primary, msisdn, email)
pii.*: Personal identifiable information (name.full, address.longform, dob)

result.*: Response codes and transaction IDs
error.*: Error-related information
defunct: Marks deleted KVPs (retained for audit)

Important KVP Notes

External IDs

KVPs with id.external type in an entity’s extraData are indexed and searchable via the /search API.

Transient Data

Transient types are perfect for one-time sensitive data transmission - they’re processed but never stored.

RequestID (Transaction ID)

Every API response includes a unique RequestID based on the ULID (Universally Unique Lexicographically Sortable Identifier) specification.

Structure

Time-based UUID (ULID format)
Contains millisecond-precision timestamp
Includes random element
Sortable alphabetically and chronologically

Usage

Trace results within FrankieOne
Retrieve past API call results
Track transactions in your system
Essential for troubleshooting

Always save the RequestID in your logs. It’s the most valuable piece of information when troubleshooting with FrankieOne support.

While RequestIDs are chronologically sortable, don’t rely on them for strict time-based operations. Use dedicated timestamp fields for such purposes.

Full List of Valid KVP Types

Complete KVP Type Reference

Category	Type
Basic Types	defunct
	general.string
	general.integer
	general.float
	general.bool
	general.date
	general.datetime
Transient Types	transient.string
	transient.integer
Raw Data Types	raw.json.base64
	raw.xml.base64
	raw.base64
Error and Result Types	error.code
	error.message
	result.code
	result.id
Identity Types	id.external
	id.number.primary
	id.number.additional
	id.msisdn
	id.email
	id.device
PII Types	pii.name.full
	pii.name.familyname
	pii.name.givenname
	pii.name.middlename
	pii.gender
	pii.address.longform
	pii.address.street1
	pii.address.street2
	pii.address.postalcode
	pii.address.town
	pii.address.suburb
	pii.address.region
	pii.address.state
	pii.address.country
	pii.dob

Guide to the API

KYC API Endpoints

Fraud & AML API Endpoints

IDV API Endpoints

KYB Trust Agent

KYB V2 API - Preview

Common API Objects and Fields

Understanding Object IDs

The Document Object

Scanned Documents in Business Check Results

The Entity Object

Key Value Pairs (KVPs)

External IDs

Transient Data

RequestID (Transaction ID)

Structure

Usage

Full List of Valid KVP Types

Understanding Object IDs

​The Document Object

​Scanned Documents in Business Check Results

​The Entity Object

​Key Value Pairs (KVPs)

External IDs

Transient Data

​RequestID (Transaction ID)

Structure

Usage

​Full List of Valid KVP Types

The Document Object

Scanned Documents in Business Check Results

The Entity Object

Key Value Pairs (KVPs)

RequestID (Transaction ID)

Full List of Valid KVP Types