Common API Objects and Fields

This section covers the fundamental API building blocks and fields that you’ll encounter throughout our API. Understanding these components is crucial for effective API integration.

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

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.

1{
2  "country": "AUS",
3  "createdFromScan": true,
4  "docScan": [
5    {
6      "ScanDelete": true,
7      "scanCreated": "2020-06-02",
8      "scanData": "VGhpcyBpcyBzb21lIGV4YW1wbGUgZGF0YS4=",
9      "scanDataRetrievalState": "NORMAL",
10      "scanDocId": "84a9a860-68ae-4d7d-9a53-54a1116d5051",
11      "scanFilename": "Important Document - ID1234567.pdf",
12      "scanMIME": "image/png",
13      "scanPageNum": 1,
14      "scanSide": "F",
15      "scanType": "PDF"
16    }
17  ],
18  "documentId": "84a9a860-68ae-4d7d-9a53-54a1116d5051",
19  "documentStatus": "DOC_SCANNED",
20  "idExpiry": "2020-02-01",
21  "idIssued": "1972-11-04",
22  "idNumber": "123456789",
23  "idType": "DRIVERS_LICENCE",
24  "region": "VIC"
25}

Scanned Documents in Business Check Results

Control document inclusion in results using the documentData parameter:

Parameter ValueBehavior
No parameterIncludes scanned document
fullIncludes full scanned document
metaExcludes scanned document, includes only metadata
1

Create Organization Entity

First, create an organization entity using the Create Entity API

2

Upload Document Scan

Upload the relevant document scan using the Create Document API

3

Complete Ownership Verification

Verify ownership using the Business Ownership Query API

4

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.

An entity contains multiple elements including:

  • Basic information (name, addresses, date of birth)
  • Organizational data (for businesses)
  • Document Objects (optional)
  • Additional metadata
1{
2  "entityId": "84a9a860-68ae-4d7d-9a53-54a1116d5051",
3  "entityType": "INDIVIDUAL",
4  "name": {
5    "displayName": "Jane Cecily Smith",
6    "familyName": "Smith",
7    "givenName": "Jane",
8    "honourific": "Duchess",
9    "middleName": "Cecily"
10  },
11  "dateOfBirth": {
12    "country": "AUS",
13    "dateOfBirth": "1978-11-12",
14    "locality": "Brisbane",
15    "yearOfBirth": "1978"
16  },
17  "addresses": [
18    {
19      "addressId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
20      "addressType": "RESIDENTIAL1",
21      "buildingName": "Tower of Babel",
22      "country": "TST",
23      "postalCode": "123-TST",
24      "state": "TS",
25      "streetName": "Test Eagle West",
26      "streetNumber": "42a",
27      "suburb": "Testburb"
28    }
29  ],
30  "gender": "F"
31}

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.

  • 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
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

CategoryType
Basic Typesdefunct
general.string
general.integer
general.float
general.bool
general.date
general.datetime
Transient Typestransient.string
transient.integer
Raw Data Typesraw.json.base64
raw.xml.base64
raw.base64
Error and Result Typeserror.code
error.message
result.code
result.id
Identity Typesid.external
id.number.primary
id.number.additional
id.msisdn
id.email
id.device
PII Typespii.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
Built with