> ## 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. # Key Data Objects > These are the critical data structures you will work with when using the FrankieOne API. This guide details the primary data objects used in FrankieOne API requests and responses. Understanding these structures is essential for sending data correctly and interpreting the verification results. An **Address** object contains the location details for an entity. Providing a complete, structured address is critical for successful verification against data sources. Best Practices for Address Data For optimal verification results, always provide addresses using **structured fields** rather than the `longForm` string. Supplying each component—such as `streetNumber`, `streetName`, `locality`, and `country`—enables more accurate matching and validation. * **Break down addresses:** Always separate address components into their individual fields wherever possible. While `streetName` can combine `streetNumber`, `streetName`, and `streetType` if needed, providing each field separately yields the most accurate results. * **Address types:** * `RESIDENTIAL`: The primary address used to determine the entity’s country of residence and current living address. * `POSTAL`: A mailing address. If a `RESIDENTIAL` address is not provided, this will be used as the default residential address. * **Address status:** Use the `status` field to indicate if the address is current or future. This helps in understanding the context of the address. * **Updating addresses:** Always include the `addressId` (returned when the address was first added) to ensure the correct record is modified. * **Country codes:** Ensure the `country` field is a valid ISO-3166-1 alpha-3 code ([reference](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes)). * **Building details:** Include any building details, such as building level, in the `buildingName` field. #### Common Address Fields | Field Name | Description | Type | Required | | :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | -------- | | `addressId` | Unique identifier for the address (used for updates). | String | No | | `country` | The **ISO-3166-1 alpha-3** country code (e.g., `AUS`). | String | Yes | | `type` | The type of address, e.g., `RESIDENTIAL`, `POSTAL`. Determines how the address is used in verification. | String (enum) | Yes | | `typeDescription` | A description of the address for reference. | String | No | | `unitNumber` | Unit, apartment, flat, or suite number. | String | No | | `streetNumber` | The number on the street (can be alphanumeric, e.g., `3A`). | String | No | | `streetName` | The name of the street. | String | Yes | | `streetType` | The street type, e.g., Road, St, Ave, Circuit. | String | No | | `buildingName` | The name of the building, apartment block, or condo. Include building level details here. | String | No | | `locality` | The locality, town, village, suburb, or city. | String | Yes | | `district` | The district, region, county, or province. | String | No | | `neighborhood` | The neighborhood or suburb. Use only if `locality` is already captured and additional detail is needed. | String | No | | `subdivision` | The administrative area, state, or subdivision. Abbreviations (e.g., "VIC") and full names (e.g., "Victoria") are acceptable. | String | No | | `postalCode` | The postal or zip code. | String | Yes | | `careOf` | Name of the individual or business at this address, if different from the entity's name. | String | No | | `longForm` | The full address as a single string. Use only if breaking down the address is not possible. If the separate fields are supplied, `longForm` will not be used when sending to providers. | String | No | | `status` | The status of the address (e.g., `PREVIOUS`, `CURRENT`, `FUTURE`). Should be used together with `TYPE` to provide more context. | String (enum) | No | | `validFrom` | The date when the entity started using this address. | Date | No | | `validTo` | The date when the entity will stop using this address. | Date | No | ##### Maximum Lengths for NZ Addresses For New Zealand addresses, the following maximum lengths are recommended: * **Address line 1** (building name + unit number + street name + street type): 256 characters * **Address line 2** (distinct to Frankie): 256 characters * **Suburb**: 50 characters * **City**: 50 characters * **Postcode**: 15 characters The **Consent** object is a mandatory part of any verification request. It confirms that you have permission from the user to perform the specified checks. The type of consent required depends on the data sources you intend to use. #### Common Consent Types | Consent Flag | Description | | :--------------- | :----------------------------------------------------------------------------------------------------------- | | `GENERAL` | The user has consented to standard name, address, and date of birth checks. | | `DOCS` | The user has consented to having their identity documents (e.g., passport) checked against official sources. | | `CREDITHEADER` | The user has consented to having their details checked against a credit bureau. This is a premium feature. | | `UNDER18` | A parent or guardian has provided consent for a user who is under 18 years of age. | | `PAYROLL` | This consent is used to allow access to verifying an identity using payroll data. | | `INSURANCE` | This consent is used to allow access to verifying an identity using workcover data. | | `SUPERANNUATION` | This consent is used to allow access to verifying an identity using superannuation data. | A **Document** object represents a piece of identification provided by the user, such as a passport, driver's license, or utility bill. ##### Document Class Guidance When creating a document object, set the `class` field to `IDENTITY` for documents used to verify a person's identity (such as passports or driver's licenses). This ensures the document is processed correctly for identity verification checks. #### Common Document Fields | Field Name | Description | | :-------------------- | :----------------------------------------------------------------------------------- | | `documentId` | The unique identifier for the document object within FrankieOne. | | `type` | The general type of document, such as `DRIVERS_LICENSE`, `PASSPORT`, `UTILITY_BILL`. | | `subtype` | A more specific description of the document type. | | `primaryIdentifier` | The main number on the document (e.g., license number or passport number). | | `secondaryIdentifier` | Any additional identifier on the document. | | `country` | The **ISO-3166-1 alpha-3** country code where the document was issued. | | `expiryDate` | The document's expiration date. | | `issueDate` | The document's date of issue. | An **Issue** is created by a workflow whenever a potential problem is detected that may require manual review. Your system should be designed to handle these issues, often by flagging the case for a compliance officer. #### Key Issue Fields | Field Name | Description | | :---------- | :-------------------------------------------------------------------------- | | `issueId` | The unique identifier for the issue. | | `category` | The general category of the issue (e.g., `AML`, `DUPLICATE`, `DOCUMENT`). | | `issue` | The specific type of issue (e.g., `SANCTION`, `DATA_COMPARISON`). | | `severity` | The severity level, such as `INFO`, `REVIEW`, or `BLOCK`. | | `isCleared` | A boolean indicating if the issue has been manually resolved in the Portal. | The **Risk Assessment** object is returned as part of a `workflowResult` and contains the calculated risk profile for the entity based on your configured policies. #### Key Risk Fields | Field Name | Description | | :------------ | :--------------------------------------------------------------------------------------- | | `riskLevel` | The overall risk level assigned to the entity, such as `LOW`, `MEDIUM`, or `HIGH`. | | `riskScore` | The numerical score that corresponds to the risk level. | | `riskFactors` | An array of the specific factors that contributed to the score (e.g., `age`, `country`). | Interpreting the status of a verification is critical. The API provides results at both the overall **workflow** level and for each individual **step**. #### Common Workflow Statuses (`workflowResult.status`) This tells you the final outcome of the entire verification process. | Status | Meaning | | :-------- | :---------------------------------------------------------------------------------------------- | | `PASS` | The workflow completed and the entity passed all required checks. | | `FAIL` | The workflow completed and the entity did not pass the required checks. | | `REVIEW` | The workflow produced results that require manual review. Check the `issues` array for details. | | `BLOCKED` | The workflow was blocked from completing, often due to a blocklist match. | #### Common Step Results (`workflowStepResults[].result`) This tells you the outcome of a specific check within the workflow. | Result | Meaning | | :--------- | :-------------------------------------------------------------------------------------------------------------- | | `MATCH` | The check was successful and found a positive match. | | `NO_MATCH` | The check was successful but did not find a matching record. | | `HIT` | A match was found against a watchlist (e.g., AML or fraud). This is a positive outcome that requires attention. | | `CLEAR` | No match was found against a watchlist. This is a positive outcome. | | `ERROR` | The step could not be completed due to a system or provider error. | ***