Key Data Objects | FrankieOne

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.

👤 Address

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

📝 Consent

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.

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.

🪪 Document

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.

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

⚖️ Risk Assessment

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`).

🚦 Result & Status Codes

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.