Skip to main content
POST
(AUS Only) Create Business Entity and Query UBO

Authorizations

​
api_key
string
header
required

API key issued by Frankie Financial. This will rotate regularly.

Headers

​
X-Frankie-CustomerID
string<uuid>
required

Customer ID issued by Frankie Financial. This will never change. Your API key, which is mapped to this identity, will change over time.

​
X-Frankie-CustomerChildID
string<uuid>

If, as a Frankie Customer, you are acting on behalf of your own customers, then you can populate this field with a Frankie-assigned ID.

Note: If using a CustomerChildID, you will also need a separate api_key for each child.

Any documents, checks, entities that are created when this field has been populated will now be tied to this CustomerID + CustomerChildID combination. Just as Customers cannot see data created by other Customers, so too a Customer's Children will not be able to see each other's data.

A Customer can see the documents/entities and checks of all their Children.

​
X-Frankie-Channel
string

Open string that can be used to define the "channel" the request comes in from. It can potentially be used in routing and risk calculations upon request. Default values that can be used are:

  • api
  • portal
  • smartui

Any alphanumeric string is supported though. Anything over 64 characters will be truncated.

Query Parameters

​
checkType
enum<string>[]

When creating a new check, we need to define the checks we wish to run. If this parameter is not supplied then the check will be based on a configured check type for each entity category.

The checkType is make up of a comma separated list of the types of check we wish to run.

The order is important, and must be of the form:

  • Entity Check (if you're running this). Choose one from the available options
  • ID Check (If you want this)
  • PEP Checks (again if you want this, choose one of the options)

Entity Checks - One of:

  • "one_plus": Checks name, address and DoB against a minimum of 1 data source. (also known as a 1+1)
  • "two_plus": Checks name, address and DoB against a minimum of 2 independent data sources (also known as a 2+2)

ID Checks - One of:

  • "id": Checks all of the identity documents, but not necessarily the entity itself independently. Use this in conjunction with a one_plus or two_plus for more.

Fraud Checks - One or more of:

  • "fraudlist": Checks to see if the identity appears on any known fraud lists. Should be run after KYC/ID checks have passed.
  • "fraudid": Checks external ID services to see if details appear in fraud detection services (e.g. EmailAge or FraudNet)

PEP Checks - One of:

  • "pep": Will only run PEP/Sanctions checks (no identity verification)
  • "pep_media": Will run PEP/Sanctions checks, as well as watchlist and adverse media checks. (no identity verification)
  • NOTE: These checks will ONLY run if either the KYC/ID checks have been run prior, or it is the only check requested.

Pre-defined combinations (deprecated):

  • "full": equivalent to "two_plus,id,pep_media" or "pep_media" if the target is an organisation.
  • "default": Currently defined as "two_plus,id" or "pep" if the target is an organisation.
  • NOTE: These options are now deprecated and support for these options will be eventually halted. Please specify check_types explicitly.

Custom:

  • By arrangement with Frankie you can define your own KYC check type.

This will allow you to set the minimum number of matches for: - name - date of birth - address - government id

This allows for alternatives to the "standard" two_plus or one_plus (note, these can be overridden too).

Profile:

  • "profile": By arrangement with Frankie you can have a "profile" check type that applies checks according to a profile that you assign to the entity from a predefined set of profiles.

The profile to use will be taken from the entity.entityProfile field if set, or be run through a set of configurable rules to determine which one to use.

Profiles act a little like the Pre-defined combinations above in that they can map to a defined list. But they offer a lot more besides, including rules for determining default settings, inbuild data aging and other configurable features. They also allow for a new result set top be returned that provides a more detailed and useful breakdown of the check/verification process.

Entity Profiles are the future of checks with Frankie Financial.

Available options:
one_plus,
two_plus,
id,
fraudlist,
fraudcheck,
pep,
pep_media,
profile,
full,
default
​
entityCategories
enum<string>[]

A comma separated list that specifies the categories of entities associated with the target organisation that will be checked.

  • organisation - Just the organisation itself.
  • ubos - All ultimate beneficial owners.
  • pseudo_ubos - Use an alternative category when an organisation has no actual UBOs. The actual category to use is defined via configuration, default is no alternative category.
  • nibos - Non-Individual Beneficial Owners
  • bos_associated - Beneficial owners that have been manually associated, rather than retrieved from registry sources
  • direct_owners - All direct owners of the company, both organisations and individuals, may include UBOs for for simple ownership.
  • officers - All officers of the company
  • officers_directors - All directors of the company
  • officers_secretaries - All secretaries of the company
  • officers_other - All non-director officers of the company
  • officers_associated - All officers of the company that were associated manually, rather than retrieved from registry sources
  • all - All direct and indirect owners, both organisations and individuals (including UBOs), and officers of all organisations.
Available options:
organisation,
ubos,
pseudo_ubos,
nibos,
bos_associated,
direct_owners,
officers,
officers_directors,
officers_secretaries,
officers_other,
officers_associated,
all
​
resultLevel
enum<string>
default:summary

The result level allows you to specify the level of detail returned for the entity check. You can choose summary or full.

Available options:
summary,
full
​
validation
enum<string>

Should a validation check be run before the ownership query. The default is specified via configuration. The validation checks to see if the provided organisation is suitable for an ownership query by looking for the ACN in public data sources. Options are:

  • "on": Validate only when ACN is not provided. This is the typical default.
  • "acn": Validate even if ACN is provided.
  • "only": Like "acn" but only do validation query, don't proceed with ownership query. This option cannot be set as the default via configuration.
  • "off": Never validate. The Ownership query will then fail if an ACN is not provided.
Available options:
on,
off,
only,
acn
​
generateReport
enum<string>

The type of human readable report, if any, to generate based on the ownership query results. Options are:

  • SINGLE-LEVEL-AML: ASIC report
  • UBO: UBO report
Available options:
SINGLE-LEVEL-AML,
UBO
​
preset
string

Name of configured preset query parameters to use. Any individual parameters provided in the request will override the same parameter in the configured preset.

​
includeHistorical
boolean

If set to true, historical ownership data will be requested.

​
onlyProfile
boolean

If set to true, a full UBO report will not be requested. Note: This param is deprecated, use ownershipMode instead.

​
noLoad
string[]

Do not load the named result objects from cache, but force them to be retrieved from an approproate service, if and when they are required. Options are:

  • abr
  • ownership
​
ownershipMode
enum<string>
default:full

Define the ownership mode you wish to run.

Valid ownership modes are:

  • full
  • onlyProfile
  • onlyUBO
Available options:
full,
onlyProfile,
onlyUBO

Body

application/json

The organisation to be queried. An entity object that must have an organisation object with at least one organisation number.

Details of the organisation for which ownership should be queried. This should at least contain the ACN in the externalIds.

​
organisation
object
required

Describes all of the data being used to verify an entity.

​
associations
object[]

A list of manual associations you wish to make with the business to be queried.

If your configuration supports this (ask your customer success representative), you can potentially compare any UBOs or office holders you supply against those found through local registries.

Response

This is what you will find in the payload of a retrieved response should the ownership query succeed, or you're querying the past checks for a given business.

NOTE: When requesting the initial report, you will only ever receive a 202 response.

The result of an /business/ownership/query call retrieved via GET /retrieve/response/{requestId} after you receive a notification that the result is ready.

​
flags
object[]

Used to set additional information flags for this response.

Example:

"kyb_target"

​
organisationCheckId
string<uuid>

Batch identifier for the KYC/AML check results if any.

​
organisationCheckResult
object

The results of KYC/AML check on a organisation with a prior ownership query. This will be retrived via GET /retrieve/response/{requestId} after you receive a notification that the results are ready.

​
ownershipCheckDate
string<date-time>

If an ownership result is provided in this response then this is the date and time the service provided that result.

​
ownershipCheckId
string<uuid>

Unique identifier for the ownership check.

​
ownershipQueryError
object
​
ownershipQueryResult
object
​
reportError
object
​
reportResult
object

The positive result of a report generation request if any.

​
requestId
string<ulid>

Unique identifier for every request. Can be used for tracking down answers with technical support.

Uses the ULID format (a time-based, sortable UUID)

Note: this will be different for every request.

Example:

"01BFJA617JMJXEW6G7TDDXNSHX"

​
uboResponse
object