Financial API EndpointsEntity

Search for Entity

Search for an existing entity that matches the criteria supplied

Criteria are supplied in the form of a populated entity object, with the name/address/DoB details supplied. You can also include documents that can be used to further refine your search (see the /document/search function for minimum requirements for a document search)

At an absolute minimum, you must supply one of the following combinations:

  • name.familyName +
  • name.givenNames

or

  • name.familyName +
  • one identityDocument object (that meets minimum criteria)

Obviously, the more data you provide, the better search results we can provide.

The service will return a list of matching entities with confidence levels.

If you are the “owner” of the entity - i.e. the same CustomerID and CustomerChildID (if relevant) - then the full details of the entity and any owned documents will be returned, except for the contents of any attached scans.

If you are not the owner of the entity (or linked documents), then just the ID and confidence level is returned. You can still use this ID to retrieve any check results (see GET /entity/{entityId}/checks and GET /document/{documentId}/checks)

If you’re operating a parent account, you can also optionally include your child accounts in the search by specifying child=true in the query parameters.

Note: This functionality must be enabled by Frankie administrators. Please contact your sales representative if you wish to discuss this.

Headers

api_keystringRequired
X-Frankie-CustomerIDstringRequired
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-CustomerChildIDstringOptional

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-ChannelstringOptional

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

childbooleanOptional
Optionally include child accounts in your search
searchTypestringOptionalDefaults to entity_search
The type of search to score matches for. This parameter should not be specified unless by specific arrangement with Frankie. If the search type "none" is used, then no scoring will be applied and there will be no confidence level for the results.
onlyEntityIdsbooleanOptional
Only include entity IDs in the search results, not whole entities
resultLimitintegerOptional
Limit the number of search results returned. Results may also be capped by a hard limit applied by the search service.

Request

This endpoint expects an object.
addresseslist of objectsOptional
Collection of address objects.
dateOfBirthobjectOptional
entityIdstringOptionalformat: "uuid"

When an entity is first created, it is assigned an ID. When updating an entity, make sure you set the entityId One exception to this is when an entity is created from a document object. It is expected that this object would be passed into a /check or /entity call to set it.

entityProfilestringOptional

If the entity is using the new profiles feature, then their profile name will be found here.

Note: If setting a profile, you must ensure that the profile matches a known configuration.

See here for valid values: https://docs.frankieone.com/docs/test-entity-verification

entityTypeenumOptional

Indicates the type of an entity.

  • “INDIVIDUAL”: An individual.
  • “TRUST”: A trust.
  • “ORGANISATION”: An organisation.
Allowed values:
extraDatalist of objectsOptional

Set of key-value pairs that provide arbitrary additional type-specific data. You can use these fields to store external IDs, or other non-identity related items if you need to. If updating an existing entity, then existing values with the same name will be overwritten. New values will be added.

See here for more information about possible values you can use: https://docs.frankieone.com/docs/key-value-pairs

flagslist of objectsOptional

Used to set additional information flags with regards to this entity and for ongoing processing.

Flags might include having the entity (not) participate in regular pep/sanctions screening Others will follow over time.

genderenumOptional

Used to indicate of the entity in question is:

  • “M”ale
  • “F”emale
  • “U”nspecified
  • “O”ther (for want of a better option)
Allowed values:
identityDocslist of objectsOptional

Collection of identity documents (photos, scans, selfies, etc)

nameobjectOptional
organisationDataobjectOptional
Organisation details for entities. Returned from an ASIC report.

Response

The request was valid and able to be processed in some fashion. Returns a list of potentially matching entity or entity references, along with a confidence level in the match.
requestIdstring

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.

entitySearchResultslist of objectsOptional

The list of (potentially) matching entities with confidence levels.

If you are the “owner” of the entity - i.e. the same CustomerID and CustomerChildID (if relevant) - then by default the full details of the entity and any owned documents will be returned, except for the contents of any attached scans.

If you are not the owner of the entity (or linked documents), then just the ID and confidence level is returned. You can still use this ID to retrieve any check results (see GET /entity/{entityId}/checks and GET /document/{documentId}/checks)

If the onlyEntityIds query parameter was set in the search request, then only the IDs and confidence levels will be return in either case.

totalEntitiesMatchedintegerOptional
The number of entity matches, which may be more than are included in these results if the resultLimit query parameter was used or a hard limit on results was reached..

Errors