> ## 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.

# 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.

<Callout icon="fingerprint" color="#1A6CFF" iconType="regular">
  ##### 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
</Callout>

## The Document Object

<AccordionGroup>
  <Accordion title="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

    <Callout icon="star" color="#3DD892" iconType="regular">
      Documents can exist as metadata only (e.g., ID number, country, and state) or include actual document scans.
    </Callout>
  </Accordion>

  <Accordion title="Document Object Example">
    ```json theme={null}
    {
      "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"
    }
    ```
  </Accordion>
</AccordionGroup>

## Scanned Documents in Business Check Results

<Tabs>
  <Tab title="Document Data Options">
    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 |
  </Tab>

  <Tab title="Performance Note">
    <Callout icon="bell" color="#FFCA16" iconType="regular">
      Including full scanned documents increases result retrieval time. Choose
      the appropriate `documentData` parameter based on your needs.
    </Callout>
  </Tab>
</Tabs>

<Steps>
  <Step title="Create Organization Entity">
    First, create an organization entity using the [Create Entity API](/docs/v1/api/kyc-api-endpoints/reference/entity/create-entity)
  </Step>

  <Step title="Upload Document Scan">
    Upload the relevant document scan using the [Create Document API](/docs/v1/api/kyc-api-endpoints/reference/document/create-document)
  </Step>

  <Step title="Complete Ownership Verification">
    Verify ownership using the [Business Ownership Query API](/docs/v1/api/kyc-api-endpoints/reference/business/business-ownership-query)
  </Step>

  <Step title="Perform Business Check">
    Execute the check with your chosen `documentData` parameter
  </Step>
</Steps>

## The Entity Object

<Info>
  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.
</Info>

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="Entity Object Example">
    ```json theme={null}
    {
      "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"
    }
    ```
  </Accordion>
</AccordionGroup>

## Key Value Pairs (KVPs)

<Info>
  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.
</Info>

<AccordionGroup>
  <Accordion title="KVP Types Overview">
    <Tabs>
      <Tab title="Basic 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
      </Tab>

      <Tab title="Identity & PII Types">
        * `id.*`: Identity-related data (external, number.primary, msisdn, email)
        * `pii.*`: Personal identifiable information (name.full, address.longform, dob)
      </Tab>

      <Tab title="Result Types">
        * `result.*`: Response codes and transaction IDs
        * `error.*`: Error-related information
        * `defunct`: Marks deleted KVPs (retained for audit)
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Important KVP Notes">
    <CardGroup cols={2}>
      <Card title="External IDs" icon="id-badge">
        KVPs with `id.external` type in an entity's extraData are indexed and searchable via the /search API.
      </Card>

      <Card title="Transient Data" icon="clock">
        Transient types are perfect for one-time sensitive data transmission - they're processed but never stored.
      </Card>
    </CardGroup>
  </Accordion>
</AccordionGroup>

## RequestID (Transaction ID)

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

<CardGroup cols={2}>
  <Card title="Structure" icon="code">
    * Time-based UUID (ULID format)
    * Contains millisecond-precision timestamp
    * Includes random element
    * Sortable alphabetically and chronologically
  </Card>

  <Card title="Usage" icon="gear">
    * Trace results within FrankieOne
    * Retrieve past API call results
    * Track transactions in your system
    * Essential for troubleshooting
  </Card>
</CardGroup>

<Check>
  Always save the RequestID in your logs. It's the most valuable piece of
  information when troubleshooting with FrankieOne support.
</Check>

<Callout icon="bell" color="#FFCA16" iconType="regular">
  While RequestIDs are chronologically sortable, don't rely on them for strict
  time-based operations. Use dedicated timestamp fields for such purposes.
</Callout>

## Full List of Valid KVP Types

<Accordion title="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                |
</Accordion>