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//checks and GET /document//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.
Authorizations
API key issued by Frankie Financial. This will rotate regularly.
Headers
Customer ID issued by Frankie Financial. This will never change. Your API key, which is mapped to this identity, will change over time.
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.
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
Optionally include child accounts in your 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.
Only include entity IDs in the search results, not whole entities
Limit the number of search results returned. Results may also be capped by a hard limit applied by the search service.
Body
An entity object with the parameters you wish to search on.
Describes all of the data being used to verify an entity.
Collection of address objects.
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.
"84a9a860-68ae-4d7d-9a53-54a1116d5051"
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
Indicates the type of an entity.
- "INDIVIDUAL": An individual.
- "TRUST": A trust.
- "ORGANISATION": An organisation.
INDIVIDUAL, TRUST, ORGANISATION "ORGANISATION"
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
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.
Used to indicate of the entity in question is:
- "M"ale
- "F"emale
- "U"nspecified
- "O"ther (for want of a better option)
U, F, M, O "F"
Collection of identity documents (photos, scans, selfies, etc)
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.
Contains the results of a given entity search.
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.
"01BFJA617JMJXEW6G7TDDXNSHX"
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.
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..
1234