Skip to main content
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 DataFor 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 NameDescriptionTypeRequired
addressIdUnique identifier for the address (used for updates).StringNo
countryThe ISO-3166-1 alpha-3 country code (e.g., AUS).StringYes
typeThe type of address, e.g., RESIDENTIAL, POSTAL. Determines how the address is used in verification.String (enum)Yes
typeDescriptionA description of the address for reference.StringNo
unitNumberUnit, apartment, flat, or suite number.StringNo
streetNumberThe number on the street (can be alphanumeric, e.g., 3A).StringNo
streetNameThe name of the street.StringYes
streetTypeThe street type, e.g., Road, St, Ave, Circuit.StringNo
buildingNameThe name of the building, apartment block, or condo. Include building level details here.StringNo
localityThe locality, town, village, suburb, or city.StringYes
districtThe district, region, county, or province.StringNo
neighborhoodThe neighborhood or suburb. Use only if locality is already captured and additional detail is needed.StringNo
subdivisionThe administrative area, state, or subdivision. Abbreviations (e.g., “VIC”) and full names (e.g., “Victoria”) are acceptable.StringNo
postalCodeThe postal or zip code.StringYes
careOfName of the individual or business at this address, if different from the entity’s name.StringNo
longFormThe 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.StringNo
statusThe status of the address (e.g., PREVIOUS, CURRENT, FUTURE). Should be used together with TYPE to provide more context.String (enum)No
validFromThe date when the entity started using this address.DateNo
validToThe date when the entity will stop using this address.DateNo
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
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 NameDescription
documentIdThe unique identifier for the document object within FrankieOne.
typeThe general type of document, such as DRIVERS_LICENSE, PASSPORT, UTILITY_BILL.
subtypeA more specific description of the document type.
primaryIdentifierThe main number on the document (e.g., license number or passport number).
secondaryIdentifierAny additional identifier on the document.
countryThe ISO-3166-1 alpha-3 country code where the document was issued.
expiryDateThe document’s expiration date.
issueDateThe 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 NameDescription
issueIdThe unique identifier for the issue.
categoryThe general category of the issue (e.g., AML, DUPLICATE, DOCUMENT).
issueThe specific type of issue (e.g., SANCTION, DATA_COMPARISON).
severityThe severity level, such as INFO, REVIEW, or BLOCK.
isClearedA 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 NameDescription
riskLevelThe overall risk level assigned to the entity, such as LOW, MEDIUM, or HIGH.
riskScoreThe numerical score that corresponds to the risk level.
riskFactorsAn 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.
StatusMeaning
PASSThe workflow completed and the entity passed all required checks.
FAILThe workflow completed and the entity did not pass the required checks.
REVIEWThe workflow produced results that require manual review. Check the issues array for details.
BLOCKEDThe 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.
ResultMeaning
MATCHThe check was successful and found a positive match.
NO_MATCHThe check was successful but did not find a matching record.
HITA match was found against a watchlist (e.g., AML or fraud). This is a positive outcome that requires attention.
CLEARNo match was found against a watchlist. This is a positive outcome.
ERRORThe step could not be completed due to a system or provider error.