> ## Documentation Index > Fetch the complete documentation index at: https://docs.frankieone.com/llms.txt > Use this file to discover all available pages before exploring further. # Create and Verify Entity > Create an entity object. An entity object can be used to simply store data around a given identity. You can attach ID documents, scans, PDFs, photos, videos, etc to the entity if you wish. If the entity is successfully created, take the details and documents provided, and set about verifying them all. So for example, you might extract: * The name from the entity.name object * The address from the entity.address object * The DoB.. All documents that are attached to the entity will also be verified (if possible). You can also specify the level of detail returned using the resultLevel parameter. You can choose "summary" or "full". For the "profile" check type you can also select "simple" to only get the entity profile result. SPECIAL NOTE: A "Full" response includes details of all checks and how they map against each element, along with all the details of pep/sanctions/etc checks too. Your account also needs to be configured to support a full response too (talk to your account manager for more information). If you're not configured for full responses, we'll only return summary level data regardless. ## OpenAPI ````yaml POST /entity/new/verify/{checkType}/{resultLevel} openapi: 3.0.0 info: description: > ------ This API allows developers to integrate the Frankie Financial Compliance Utility into their applications. The API allows: - Checking name, address, date of birth against national databases - Validating Australian driver's licences, passports, medicare, visas and other Australian national ID documents - Validating Australian electricity bills - Validating NZ driver's licences - Validating Chinese bank cards and national ID card - Validating International passports and national ID documents - PEP, Sanctions, Watchlist and adverse media checking - Australian visa checks - Fraud list and fraud background checks - ID validation and selfie check comparisons. ------ KYB specific services - Query organisation ownership - Perform KYC & AML checks on shareholders, beneficial owners and office bearers. - Query credit score and credit reports - International company searches - International company profiles ------ The full version of this documentation along with supplemental articles can be found here: - https://docs.frankieone.com/ ------ Sandbox base URL is: - https://api.uat.frankie.one/compliance/v1.2 - All calls are the same as production, only with test data. You can download the latest test data here: https://docs.frankieone.com/docs/test-data - Full Swagger definition, along with test data for playing in the sandbox can be obtained once initial commercial discussions have commenced. - Production and optional UAT access will be opened up only to those with a signed commercial contract. ------ Contact us at hello@frankiefinancial.com to speak with a sales rep about issuing a Customer ID and Sandbox api key. title: Frankie Financial API contact: email: help@frankieone.com version: 1.15.3 servers: - url: https://api.uat.frankie.one/compliance/v1.2 security: - api_key: [] tags: - description: >- Service status functions you can use to make sure things are up and running. name: Status - description: Operations on specific ID documents, specific to an entity (people). name: Document - description: Operations on specific entities (people / companies / etc) name: Entity - description: Operations on entities that are set to type ORGANISATION name: Business - description: >- These are callback/webhook functions. If you've requested a callback, this will be what is sent to you. You do not need to implement these as a client, but you do need to be able to accept them as a server. name: Push Notification - description: Functions used for retrieving past results name: Retrieve - description: Operations on entities to set specific flags and states. name: Flag paths: /entity/new/verify/{checkType}/{resultLevel}: post: tags: - Entity summary: Create and Verify Entity description: > Create an entity object. An entity object can be used to simply store data around a given identity. You can attach ID documents, scans, PDFs, photos, videos, etc to the entity if you wish. If the entity is successfully created, take the details and documents provided, and set about verifying them all. So for example, you might extract: * The name from the entity.name object * The address from the entity.address object * The DoB.. All documents that are attached to the entity will also be verified (if possible). You can also specify the level of detail returned using the resultLevel parameter. You can choose "summary" or "full". For the "profile" check type you can also select "simple" to only get the entity profile result. SPECIAL NOTE: A "Full" response includes details of all checks and how they map against each element, along with all the details of pep/sanctions/etc checks too. Your account also needs to be configured to support a full response too (talk to your account manager for more information). If you're not configured for full responses, we'll only return summary level data regardless. operationId: CreateCheckEntity parameters: - description: > Customer ID issued by Frankie Financial. This will never change. Your API key, which is mapped to this identity, will change over time. name: X-Frankie-CustomerID in: header required: true schema: type: string format: uuid - description: > 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. name: X-Frankie-CustomerChildID in: header schema: type: string format: uuid - description: > If this header parameter is supplied and set to 1, then the request will not wait for the process to finish, and will return a 202 if there are no obvious errors in the input. The request will then run in the background and send a notification back to the customer. See out callback API for details on this. See more details here: https://docs.frankieone.com/docs/asynchronous-calls-backgrounding-processes name: X-Frankie-Background in: header schema: type: integer minimum: 0 maximum: 1 - description: > 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. name: X-Frankie-Channel in: header schema: type: string - description: > When creating a new check, you need to define the checks you wish to run. The checkType is make up of a comma separated list of the types of check you wish to run. The order of the requested checks is not important, they will be re-ordered by the service and in some cases, depending on your account configuration, may be skipped. The validation that is performed on the requested checks is to: - ensure the check type is known - is suitable for the type of entity (no KYC for organisations) - disallow manual (mKYC) check with any other kind of KYC - disallow mixing the "profile" check with any other kind of check. The supported check types are: Profile: - "profile": By arrangement with Frankie we will create a "profile" check type that applies checks according to a recipe 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 provide a pre-defined combination of individual checkTypes (see the list below). But they offer a lot more besides, including rules for determining default settings, inbuilt 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 a recent feature (since v1.4.0) but are now the default checkType to use with Frankie Financial. **Individual Check Types** Whilst we strongly recommend the use of the "profile" checktype, it does map to any combination of the types below. If you wish to use these individually, please contact developer support for more details on how to use these effectively. 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. - "visa": ID Validate - One of: - "idvalidate": Checks to see if photo ID has had OCR scanning, ID document validation and photo comparison run against it. Can be used in conjunction with any of the KYC/ID/AML checks. Manual Check: - "manual": (mKYC) Checks user has a sufficient amount of operator verified ID and will then "pass" all Entity and ID related checks. 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. - "fraudcheck": 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. Device checks: - "device": This will allow you to pass in device details captured through services like ThreatMetrix or Sardine.ai 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). Speak with the Customer Success team when you're onboarding. name: checkType in: path required: true schema: type: string default: profile - description: | How much detail we return. Acceptable values are: * simple - Only available with "profile" check type. Returns just an EntityProfileResultObject (which is also included for "profile" checks at the other result levels), and a CheckEntityCheckResultObjectEntityResult with just the entity details but no separate results. * summary * full - You need to have your account configured for this. name: resultLevel in: path required: true schema: type: string enum: - simple - summary - full requestBody: $ref: '#/components/requestBodies/EntityCheckDetailsObject' responses: '200': description: >- The request was valid and able to be processed in some fashion. Results may or may not be successful, but it was completed as far as practical with no actual errors. Returns the entity object as it stands now. No docScan file data from any attached ID documents will be returned unless the /full variant is requested. content: application/json: schema: $ref: '#/components/schemas/CheckEntityCheckResultObject' '202': description: >- The request was valid and can potentially be fulfilled. The Frankie service has now accepted responsibility for processing and we will either push the results to you, or send you a notification, depending on the request and your configuration. content: application/json: schema: $ref: '#/components/schemas/AcceptedEntityResultObject' '400': description: >- Bad request. One or more request fields is either missing or incorrect. Details are in the error response. content: application/json: schema: $ref: '#/components/schemas/ErrorObject' '401': description: > The request has failed an authorisation check. This can happen for a variety of reasons, such as an invalid or expired API key, or invalid Customer/CustomerChildIDs. * NOTE: This does not include attempts to read/write data you don't have access to - that's a 404 error (as we don't want to leak information through guessing) content: application/json: schema: $ref: '#/components/schemas/ErrorObject' '404': description: >- Cannot return response. In the case of a query, or reference to a specific entity/check/etc, it means that the requested item was not found, or you don't have access to it. Please check your query before trying again. content: application/json: schema: $ref: '#/components/schemas/ErrorObject' '405': description: >- A request to POST an update to an object was not allowed due to it's state. This may indicate an already completed check, or a document that has been processed. You need to create a new document/check if you wish to update the object in question. content: application/json: schema: $ref: '#/components/schemas/ErrorObject' '415': description: >- For requests with payloads, an unsupported Content-Type was specified. The Frankie Financial API only supports a content type of application/json. content: application/json: schema: $ref: '#/components/schemas/ErrorObject' '422': description: > Unprocessable request. This can be triggered in a number of ways. * An attempt to force a check or scan to run, but there is insufficient data to be able to do so. * An attempt to run a document/entity specific scan or process on an unsupported document type (e.g. electricity comparison on a passport) Details of what is required will be in the issues list of the error response. content: application/json: schema: $ref: '#/components/schemas/ErrorObject' '429': description: >- The API client is making too many concurrent requests, and some are being throttled. Throttled requests can be retried after a short delay. content: application/json: schema: $ref: '#/components/schemas/ErrorObject' '500': description: Unexpected error. Something went wrong during the checking process. content: application/json: schema: $ref: '#/components/schemas/ErrorObject' '503': description: >- All of the ID sources configured by the customer are unavailable, or there is no available document processor. content: application/json: schema: $ref: '#/components/schemas/ErrorObject' components: requestBodies: EntityCheckDetailsObject: content: application/json: schema: $ref: '#/components/schemas/EntityCheckDetailsObject' description: The entity and any associated / additional information to be checked required: true schemas: CheckEntityCheckResultObject: description: > Describes all of the checks that were carried out against an entity as part of our cascading check process. Because there are a number of steps involved in checking an entity, (including the use of past checks done by you or others), there is an overall summary check result that will tell you the final disposition of the the check you requested. So if you requested a 2+2+governmentID+pep/sanctions/etc (i.e. everything) then there would have been several checks done in order to meet this requirement. Some may have even failed, but eventually we got there. The summary gives the final assessment, based on all available data. Detailed writeups on how this all works can be found here: https://docs.frankieone.com/docs/understanding-check-results type: object properties: blacklistCheckResults: description: > Collection of check results for the entity having been previously blacklisted. An array of matched blacklisted entities sorted by match confidence level (highest first). type: array items: $ref: '#/components/schemas/ProcessResultObject' x-omitempty: true checkResultsListSummaries: description: Contains a list of all checkSummary records (one for each check) type: array items: $ref: '#/components/schemas/ProcessResultObject' x-omitempty: true checkRisk: $ref: '#/components/schemas/ProcessResultObject' checkSummary: $ref: '#/components/schemas/ProcessResultObject' duplicateCheckResults: description: > Collection of check results for the entity having previously been checked. An array of matched checked entities sorted by match confidence level (highest first). type: array items: $ref: '#/components/schemas/ProcessResultObject' x-omitempty: true entity: $ref: '#/components/schemas/EntityObject' entityProfileResult: $ref: '#/components/schemas/EntityProfileResultObject' entityResult: $ref: '#/components/schemas/CheckEntityCheckResultObjectEntityResult' fraudCheckResults: $ref: '#/components/schemas/FraudCheckResultObject' manualCheckResults: description: | Collection of check results for the manual KYC. An array of one entry with the manual check result. type: array items: $ref: '#/components/schemas/ProcessResultObject' x-omitempty: true requestId: $ref: '#/components/schemas/RequestIDObject' sharedBlocklistCheckResults: description: > Collection of check results for the entity having been previously blacklisted in shared blocklist. An array of matched blacklisted entities sorted by match confidence level (highest first). type: array items: $ref: '#/components/schemas/ProcessResultObject' x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: CheckEntityCheckResultObject AcceptedEntityResultObject: description: > The following fields represent the data you need in order to retrieve the results of the requested function. See the details of the notification API for more. type: object properties: checkId: description: > If you're calling a processing function of some kind, a check number will be issued. This field will only be present if the function you're calling would normally return a checkId (such as scan, verify, and compare). type: string format: uuid entityId: description: > When an entity is created/uploaded, or generated from a document scan, it is assigned an entityId. This can then be referenced in subsequent calls if you're uploading more/updated data. type: string format: uuid example: 84a9a860-68ae-4d7d-9a53-54a1116d5051 function: description: | Short description of the function called. type: string linkURL: description: > Optional link that can be returned - used by the Push To Mobile service to allow API users to manage the use of the onboarding link themselves. type: string requestId: $ref: '#/components/schemas/RequestIDObject' ErrorObject: type: object required: - requestId - errorCode - errorMsg properties: commit: description: Server version indication type: string example: 2af478ed errorCode: description: Frankie error code type: string example: CORE-5990 errorMsg: description: Will describe the error type: string example: Everything went kaflooey. Stay clam. httpStatusCode: description: | Deprecated: HTTP status code. Same as that which is passed back in the header. type: integer example: 501 issues: type: array items: $ref: '#/components/schemas/ErrorObjectIssues' x-omitempty: true requestId: $ref: '#/components/schemas/RequestIDObject' x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: ErrorObject EntityCheckDetailsObject: description: > Contains all the details we'll check regarding an Entity. It is assumed that this will grow over time. Current supported check parameters: - entity: The Entity we're checking. This must be supplied. type: object required: - entity properties: deviceCheckDetails: $ref: '#/components/schemas/DeviceCheckDetailsObject' entity: $ref: '#/components/schemas/EntityObject' x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: EntityCheckDetailsObject ProcessResultObject: description: >- Stores the generic results of a process (check, scan, compare, verify, etc) type: object properties: checkDate: description: The date and time the item was checked to provide this result. type: string format: date-time checkId: $ref: '#/components/schemas/CheckIDObject' checkPerformedBy: description: > Service provider that performed the check. Basically the name of the connector, without the leading con_ type: string example: dvs checkSource: description: > Code that can be used to determine the underlying nature or data source of the checks performed. This may or may not be known by the connector, or may be a provider specific type (e.g. type "O") Note, this will actually be normalised by the core service into a standfardised result so that we're not accidentally counting sources twice. Original source will then be copied into the KVPs type: string example: DVS checkType: description: | Short indication of the type of check that was done. When used as a summary, it will the the checkType that was requested For granular results, it will be the individual check performed. type: string confidenceLevel: description: > Confidence in the result on a scale of 0 (no match) to 100 (strong/identical match). Whole integers only. Negative values are used to indicate untrusted results. type: integer format: int32 maximum: 100 minimum: 0 example: 70 providerCheckID: description: > The service provider will give us a receipt, transaction id, check number, or some such that gives us a unique id on their side that we can reconcile with type: string resultNotes: description: >- Any additional notes that may relate to the state. These are returned as typed KVPs type: array items: $ref: '#/components/schemas/KeyValuePairObject' x-omitempty: true resultState: $ref: '#/components/schemas/enumCheckResultState' riskLevel: description: > Only supplied in a summary result. Used to indicate the ovall risk score for the entity at this point in time, based on configurable rules. Some examples might include: * Current level of ID checks passed * Device ID scores * Current PEP/Sanctions/etc checks * Jurisdictional risk based on addresses, documents and other KVPs * Fraud check results In this case a higher score is a bad thing. General rule of thumb: * 0 - 30 = Low Risk * 31 - 50 = Medium Risk * 50 - 75 = High Risk * 75+ = Unacceptable type: integer maximum: 100 minimum: 0 example: 75 x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: ProcessResultObject EntityObject: description: | Describes all of the data being used to verify an entity. type: object properties: addresses: description: Collection of address objects. type: array items: $ref: '#/components/schemas/AddressObject' x-omitempty: true dateOfBirth: $ref: '#/components/schemas/DOBObject' entityId: description: > 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. type: string format: uuid example: 84a9a860-68ae-4d7d-9a53-54a1116d5051 entityProfile: description: > 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 type: string x-omitempty: true entityType: $ref: '#/components/schemas/enumEntityType' extraData: description: > 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 type: array items: $ref: '#/components/schemas/KeyValuePairObject' x-omitempty: true flags: description: > 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. type: array items: $ref: '#/components/schemas/EntityFlagObject' x-omitempty: true gender: $ref: '#/components/schemas/enumGender' identityDocs: description: Collection of identity documents (photos, scans, selfies, etc) type: array items: $ref: '#/components/schemas/IdentityDocumentObject' x-omitempty: true name: $ref: '#/components/schemas/PersonalNameObject' organisationData: $ref: '#/components/schemas/OrganisationDataObject' x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: EntityObject EntityProfileResultObject: description: > Contains the results of a check against an entity profile. The entityProfileResult will be returned instead of a checkSummary to provide the full details of the verification process. type: object properties: actionRecommended: description: > The recommended onboarding action for this entity after the profile check this result refers to. The action can also be an entity state set by you. - UNCHECKED: New entity with no checks applied - PASS - FAIL - PASS_MANUAL: Manual intervention was applied to achieve a pass - FAIL_MANUAL: Manual intervention was applied but the entity still fails - REFER: Manual intervention required - WAIT: Externally applied state, waiting for more entity details - ARCHIVED: Externally applied state, entity hidden from on onboarding list - INACTIVE: Externally applied state, entity hidden from on onboarding list, indexes and further changes will be blocked. type: string addressResults: description: > KYC match counts for each checked address, whether matched or not. The keys in this map are the address IDs. The match type in the value will be either "curr_addr" or "prev_addr". The resultant structure would look like: "addressResults": { "addressId": { "matchType": "curr_addr", "matchCount": 5, "verified": true }, "addressId": { "matchType": "prev_addr", "matchCount": 5, "verified": true } } type: object additionalProperties: $ref: '#/components/schemas/EntityProfileItemMatchResultObject' x-omitempty: true alternativeKycResults: description: > Collections of KYC match counts. If your recipe / entity profile contains KYC checks with multiple matching criteria, then the results of each criteria set will be here. The first item will be the best result (out of PASS, FAIL or UNCHECKED), if there is a tie then the first item will be the one with the highest priority (lowest order number, see EntityProfileAltKYCMatchResultObject). The first item will also be in the EntityProfileResultObject kycResults, but but without the extra attributes from EntityProfileAltKYCMatchResultObject (name, description, order, result). The items after the first will be the remaining alternatives in priority order (i.e. lowest order value to highest). Note: This will only be populated if you have multiple matching criteria in your recipe/profile. type: array items: $ref: '#/components/schemas/EntityProfileAltKYCMatchResultObject' x-omitempty: true checkId: $ref: '#/components/schemas/CheckIDObject' checkResults: description: > The basic result for each check type required for the profile. The results are listed in the order they are run so you can also see how far progressed through a check process you are. type: array items: $ref: '#/components/schemas/EntityProfileCheckResultMessage' x-omitempty: true checkType: description: Comma separated list of checks required for the entity profile. type: string example: two_plus,id,pep_media creditHeaderFailures: description: List of vendors from failed credit header sources. type: array items: type: string x-omitempty: true documentResults: description: > KYC match counts for each checked document, whether matched or not. The keys in this map are the document IDs. The match type in the value will be either "gov_id" or "other_id". The resultant structure would look like: documentResults: { "documentId" : { "matchType": "gov_id", "matchCount": 5, "verified": true }, "documentId": { "matchType": "other_id", "matchCount": 5, "verified": true } } type: object additionalProperties: $ref: '#/components/schemas/EntityProfileItemMatchResultObject' x-omitempty: true entityId: description: | Unique ID for the entity. type: string format: uuid example: 84a9a860-68ae-4d7d-9a53-54a1116d5051 issueList: type: array items: type: string x-omitempty: true kycResults: description: > Summary of primary KYC match counts. If you have a recipe that includes multiple potential matching criteria, then this will be the first set of criteria that matched. If the KYC matches failed overall, then this will be the first matching criteria set in the list. All potential matching criteria sets (including this one) will be included in the alternativeKycResults array type: array items: $ref: '#/components/schemas/EntityProfileKYCMatchResultObject' x-omitempty: true latestCheckDate: description: The date and time of the last check that contributed to this result. type: string format: date-time example: 2018-11-12T13:14:15Z+10:00 manualIntervention: description: >- Indicates if any manual actions have been involved in the check result. type: boolean policyName: description: >- The name of the policy within the profile used for this check. This may or may not incorporate the 'riskPolicy' that is also an attribute in this object. type: string example: SDD U18 profileName: description: The name of the profile used for this check. type: string example: Credit resolverRecommended: description: Workflow hint by arrangement with Frankie type: string riskLevel: description: | Risk level. One of: - LOW, - MEDIUM, - HIGH, - UACCEPTABLE - or UNKNOWN type: string example: LOW riskPolicy: description: > Risk policy. Contents depend on account configuration but would typically be one of: - SDD, - CDD, - EDD - or FAIL type: string example: SDD x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: EntityProfileResultObject CheckEntityCheckResultObjectEntityResult: description: | This will hold all of the check results that were performed against the type: object properties: addressesCheck: description: Collection of address objects. type: array items: $ref: '#/components/schemas/AddressCheckResultObject' x-omitempty: true adverseMediaCheck: description: > !!!!! DEPRECATED !!!!! Please use the multi-result AMLResultSets structure instead. Note: This single check result structure will be retired in v2.0 !!!!! DEPRECATED !!!!! Collection of check results for the entity being found in any adverse media An array sorted by type, then reverse chronological order of some/all background checks done on this entity. Older checks may have been previously done by you or another institution, and if so, these will be listed and appropriately anonymised/obfuscated. type: array items: $ref: '#/components/schemas/backgroundCheckResultObject' x-omitempty: true amlResultSets: description: > An array of Collections of PEP/Sanctions/WL/Media objects, as AML providers can return multiple results type: array items: $ref: '#/components/schemas/AMLResultSet' x-omitempty: true dateOfBirthCheck: $ref: '#/components/schemas/DOBCheckResultObject' entityId: description: | Unique ID for the entity. type: string format: uuid example: 84a9a860-68ae-4d7d-9a53-54a1116d5051 genderCheck: $ref: '#/components/schemas/GenderCheckResultObject' identityDocsCheck: description: >- Collection of identity documents (photos, scans, selfies, etc), and their check results type: array items: $ref: '#/components/schemas/IdentityDocumentCheckResultObject' x-omitempty: true nameCheck: $ref: '#/components/schemas/PersonalNameCheckResultObject' pepCheck: description: > !!!!! DEPRECATED !!!!! Please use the multi-result AMLResultSets structure instead. Note: This single check result structure will be retired in v2.0 !!!!! DEPRECATED !!!!! Collection of check results for the entity being a Politically Exposed Person An array sorted by type, then reverse chronological order of some/all background checks done on this entity. Older checks may have been previously done by you or another institution, and if so, these will be listed and appropriately anonymised/obfuscated. type: array items: $ref: '#/components/schemas/backgroundCheckResultObject' x-omitempty: true sanctionsCheck: description: > !!!!! DEPRECATED !!!!! Please use the multi-result AMLResultSets structure instead. Note: This single check result structure will be retired in v2.0 !!!!! DEPRECATED !!!!! Collection of check results for the entity being on a sanctions list An array sorted by type, then reverse chronological order of some/all background checks done on this entity. Older checks may have been previously done by you or another institution, and if so, these will be listed and appropriately anonymised/obfuscated. type: array items: $ref: '#/components/schemas/backgroundCheckResultObject' x-omitempty: true watchlistCheck: description: > !!!!! DEPRECATED !!!!! Please use the multi-result AMLResultSets structure instead. Note: This single check result structure will be retired in v2.0 !!!!! DEPRECATED !!!!! Collection of check results for the entity being on a watchlist An array sorted by type, then reverse chronological order of some/all background checks done on this entity. Older checks may have been previously done by you or another institution, and if so, these will be listed and appropriately anonymised/obfuscated. type: array items: $ref: '#/components/schemas/backgroundCheckResultObject' x-omitempty: true x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: CheckEntityCheckResultObjectEntityResult FraudCheckResultObject: description: > Collection of fraud check results for the entity. Contains fraud list and/or background result arrays. Other fraud check types will appear over time type: object properties: fraudBackgroundCheckResults: type: array items: $ref: '#/components/schemas/ProcessResultObject' x-omitempty: true fraudDeviceResults: type: array items: $ref: '#/components/schemas/ProcessResultObject' x-omitempty: true fraudListResults: type: array items: $ref: '#/components/schemas/ProcessResultObject' x-omitempty: true x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: FraudCheckResultObject RequestIDObject: description: > 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. type: string format: ulid x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: RequestIDObject example: 01BFJA617JMJXEW6G7TDDXNSHX ErrorObjectIssues: type: object required: - issueLocation properties: issue: description: Description of the problem type: string example: Invalid format. Must be YYYY-MM-DD issueLocation: description: Will describe the field or data location of the issue type: string example: dateOfBirth x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: ErrorObjectIssues DeviceCheckDetailsObject: description: > Contains any/all details we want to pass on to the device checking service as part of an activity / transaction. A transaction isn't just a payment, but can represent a number of different interaction types. See below for more. NOTE: If you're sending this data, then your recipe or requested checkTypes *MUST* include a "device" checkType. Otherwise this data will be ignored and dropped. type: object properties: activityType: description: > The type of activity we're checking. Choices are: - SIGNUP: Used when an entity is signing up to your service - LOGIN: Used when an already registered entity is logging in to your service - PAYMENT: Used when you wish to check that all is well for a payment - CONFIRMATION: User has confirmed an action and you wish to double check they're still legitimate You can also supply vendor specific activityTypes if you know them. To do this, make the first character an underscore _. So for example, to use BioCatch's LOGIN_3 type, you can send "_LOGIN_3" as a value. Note, if you do this, there is no error checking on the Frankie side, and thus if you supply an incorrect value, the call will fail. type: string additionalData: description: > Collection of additional data points you wish to add to the activity check. These are defined in conjunction with the Customer and the device checking service being used. Standard values are supplied upon request: | kvpKey | kvpType | kvpValue | | ------- | -------- | -------- | | detectedIp | general.string | The IP address you detect the transaction coming from | | accountId.src | id.external | Your account identifier. Can be a SHA hash or similar | | accountId.dst | id.external | Target/payee account identifier. Can be a SHA hash or similar | | entityId | id.external | Use this to override the Frankie entityID that would be used to identify | | amount | general.float | Amount involved in the transaction | | platform | general.string | One of APP, WEB, MOBILE_WEB. Assumes APP if not supplied | | | | Like the activityType, you can also specify vendor specific additional data parameters by adding a leading underscore "_" to the kvpKey. You can set the kvpType to one of the available types, or just use general.string (recommended) type: array items: $ref: '#/components/schemas/KeyValuePairObject' x-omitempty: true checkSessionKey: description: >- the unique session based ID that will be checked against the service. type: string x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: DeviceCheckDetailsObject CheckIDObject: description: >- Unique identifier for every check/comparison/verification. Make sure you reference this ID whenever updating check details. This ID will also be used when pushing check results back to you. type: string format: uuid x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: CheckIDObject example: 54a1116d-68ae-4d7d-9a53-505184a9a860 KeyValuePairObject: description: Individual key-value pair type: object properties: kvpKey: description: Name of the data type: string example: ACN kvpType: $ref: '#/components/schemas/enumKVPType' kvpValue: description: Value of the data type: string example: '406655338' x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: KeyValuePairObject enumCheckResultState: description: > Check state for an individual data point - "UNCHECKED": Check has not yet been performed - "NOT_SUPPORTED": the requested check type is not supported by this connector. - "CHECKING": Checks are underway. - "UNPROCESSABLE": The data supplied was unprocessable. - "NO_MATCH": All checks complete, no records found that matched the details supplied - "CHECKED_PARTIAL_SUCCESS": All checks complete, but only some succeeded. - "CHECKED_SUCCESS_WITH_NOTES": All checks complete, but there are some notes (e.g. PEP or sanctions). - "CHECKED_SUCCESS_CLEAR": All checks complete, no additional notes - "CHECKED_FAILED": All checks complete, but all failed. type: string enum: - UNCHECKED - CHECKING - UNPROCESSABLE - NOT_SUPPORTED - NO_MATCH - CHECKED_PARTIAL_SUCCESS - CHECKED_SUCCESS_WITH_NOTES - CHECKED_SUCCESS_CLEAR - CHECKED_FAILED x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: EnumCheckResultState example: CHECKED_PARTIAL_SUCCESS AddressObject: type: object required: - country properties: addressId: description: > As addresses are added to an entity, they're assigned an id to assist with tracking. If you're adjusting an address, you will need to include the addressId so as to be able to reference it correctly in the list. type: string format: uuid example: 86932629-bdb4-158f-e670-741e89ff78ba addressType: $ref: '#/components/schemas/enumAddressType' buildingName: description: The name of the building, apartment block, condo, etc type: string example: Highland Tower careOf: description: > Individual or business name at this address if not the same as the name of the entity to which this address belongs. type: string country: description: > The ISO-3166-1 country. You must use the alpha3 country code (e.g. AUS, USA, IDR, KOR, etc) We'll convert as needed. See: https://en.wikipedia.org/wiki/ISO_3166-1 type: string example: AUS endDate: description: > The date this address was no longer used (if available). Used mostly with business addresses. type: string format: date example: '0001-01-01' extraData: description: > Set of key-value pairs that provide arbitrary additional type-specific data. This data will typically not be visible in the Frankie Portal. If updating an existing address, 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 type: array items: $ref: '#/components/schemas/KeyValuePairObject' x-omitempty: true longForm: description: > In some cases, the address will need to be supplied in "long form", such as when it is determined from a document scan, or is un-parsable in some way. The service will attempt to convert it to it's constituent parts where possible. WARNING: Use of longForm is not guaranteed to produce perfect results, due to the variety of potential formats. You've been warned. Failure to break down or disambiguate the address will result in an error. type: string example: 42a Test Eagle Road, Testville, TST 123-TST, Testalia postalCode: description: The post code of the address. type: string example: '3000' region: description: The county, province, cantonment type: string example: MELBOURNE startDate: description: > The date this address first because active. Used mostly with business addresses. type: string format: date example: '2023-03-10' state: description: The state. Use local abbreviations, such as VIC(toria) or TX (Texas) type: string example: VIC streetName: description: > The name of the street This field can in fact be a bit flexible, potentially containing the streetNumber and streetType as well. Most services in use can work it out. If this field has been auto-populated by Google (see writeup here: https://docs.frankieone.com/docs/working-with-addresses then the bulk of the address will be in this field. If you can avoid it though, please try and keep things separate. type: string example: 9 ROYCE AVENUE streetNumber: description: > The number on the street. Generally a number, but can also be alphanumeric (e.g. 3A) type: string example: FLAT 27 streetType: description: The street "type" - e.g. Road, St, Ave, Circuit, etc type: string example: Road suburb: description: >- The suburb in the town/city. Only use this if you require a suburb AND a town/city, otherwise, just use the "town" parameter. type: string example: Testburb town: description: The town/village/suburb/city type: string example: MELBOURNE unitNumber: description: Unit/Apartment/Flat/Suite/etc number type: string example: FLAT 27 unstructuredLongForm: type: string x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: AddressObject DOBObject: type: object properties: country: description: > ISO-3166-1 code for the country of birth. You must use the alpha3 country code (e.g. AUS, USA, IDR, KOR, etc) We'll convert as needed. See https://en.wikipedia.org/wiki/ISO_3166-1 type: string example: AUS dateOfBirth: description: Date of Birth in YYYY-MM-DD format type: string format: date example: '1978-11-12' locality: description: > Place of birth other than country If locality is given, then country must also be provided. type: string example: Brisbane unstructuredDateOfBirth: type: string yearOfBirth: description: >- Year of birth or "unknown". This will be autoextracted if dateOfBirth is supplied. type: string example: '1978' x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: DOBObject enumEntityType: description: | Indicates the type of an entity. - "INDIVIDUAL": An individual. - "TRUST": A trust. - "ORGANISATION": An organisation. type: string enum: - INDIVIDUAL - TRUST - ORGANISATION x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: EnumEntityType example: ORGANISATION EntityFlagObject: description: > Similar to a KVP, the flag has a key (the flag you're indicating) and an integer value. Values are tied to the specific flag (see table below). Generally they're true (1)/false(0) indicators. | flag | values | Description | | ------- | -------- | -------- | | ongoing_pep | 0, 1, 2 | 0 = no, 1 = pep/sanctions, 2 = 1+media | | | | | type: object properties: flag: description: Name of the flag type: string value: description: flag value. type: integer x-omitempty: false x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: EntityFlagObject enumGender: description: | Used to indicate of the entity in question is: - "M"ale - "F"emale - "U"nspecified - "O"ther (for want of a better option) type: string enum: - U - F - M - O x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: EnumGender example: F IdentityDocumentObject: type: object required: - idType - country properties: country: description: > The ISO-3166-alpha3 country code of the issuing national. Once set, this cannot be changed. See https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes for more type: string example: AUS createdFromScan: description: > This document's data was initially created from scanned and processed images. The value cannot be set manually and any attempt to do so will just be ignored. type: boolean readOnly: true example: true docScan: description: > Collection of one or more objects that describe scan(s) that need to be put through OCR or facial recognition. These should all be from the one ID document, such as front/back, or page 1, 2, 3, etc. You can upload multiple scans in a single call, or in multiple calls. Note: if you do upload over multiple calls, make sure you include the documentId (see above), and indicate that this is happening with a "more_data" checkAction type: array items: $ref: '#/components/schemas/ScannedDocumentObject' x-omitempty: true documentId: description: > When an ID document is created/uploaded, it is assigned a documentId. You'll see this in a successful response or successfully accepted response. This can then be referenced in subsequent calls if you're uploading more/updated data. type: string format: uuid example: 84a9a860-68ae-4d7d-9a53-54a1116d5051 documentStatus: $ref: '#/components/schemas/enumDocumentStatus' extraData: description: > Set of key-value pairs that provide ID type-specific data. If updating an existing document, then existing values with the same name will be overwritten. New values will be added. If this document is scanned through OCR or similar processes, then extracted data will be found here (Some may be used to populate other fields like idNumber and idExpiry as well) type: array items: $ref: '#/components/schemas/KeyValuePairObject' x-omitempty: true idExpiry: description: The expiry date of the document (if known) in YYYY-MM-DD format. type: string format: date example: '2020-02-01' idIssued: description: The issued date of the document (if known) in YYYY-MM-DD format. type: string format: date example: '1972-11-04' idNumber: description: The ID number of the document (if known). type: string example: '123456789' idSubType: description: The sub-type of identity document. Very document specific. type: string idType: $ref: '#/components/schemas/enumIdType' manuallyModified: description: > If this document was originally populated from scanned data, then manually adjusted (e.g. if the scan's results weren't 100% correct or data was missing), then this will be set to true. The value cannot be set manually and any attempt to do so will just be ignored. type: boolean readOnly: true example: 'false' region: description: | Regional variant of the ID (e.g. VIC drivers licence) You should always use the local abbreviation for this. E.g. - VIC for The Australian state of Victoria - MA for the US state of Massachusetts - etc type: string example: VIC x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: IdentityDocumentObject PersonalNameObject: type: object required: - familyName properties: displayName: description: > In some cases, the name will need to be supplied in "long form", such as when it is determined from a document scan, or is un-parsable in some way. The service will attempt to convert it to it's constituent parts where possible. type: string example: Jane Cecily Smith familyName: description: Family name / Surname of the individual. type: string example: Smith givenName: description: First / Given name type: string example: Jane honourific: description: Mr/Ms/Dr/Dame/Dato/etc. type: string example: Duchess middleName: description: Middle name(s) / Initials type: string example: Cecily x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: PersonalNameObject OrganisationDataObject: description: | Organisation details for entities. Returned from an ASIC report. type: object properties: adverseCreditDataPresent: type: boolean aliases: type: array items: type: string x-omitempty: true class: $ref: '#/components/schemas/CodeDescription' contactDetails: $ref: '#/components/schemas/OrganisationDataObjectContactDetails' disclosingEntityIndicator: type: boolean extractedDate: type: string format: date nullable: true includesNonBeneficiallyHeld: type: boolean industryCodes: type: array items: $ref: '#/components/schemas/IndustryCodesObject' x-omitempty: true industryDeclarations: type: array items: $ref: '#/components/schemas/IndustryDeclarationsObject' x-omitempty: true kycCustomerType: type: string lastCheckDate: type: string format: date legalFormDetails: $ref: '#/components/schemas/OrganisationDataObjectLegalFormDetails' normalisedLegalStatus: type: string ownershipResolved: type: boolean registeredName: type: string registration: $ref: '#/components/schemas/OrganisationDataObjectRegistration' registries: $ref: '#/components/schemas/Registries' reviewDate: type: string format: date nullable: true shareStructure: type: array items: $ref: '#/components/schemas/ShareStructureObject' x-omitempty: true startDate: type: string format: date status: $ref: '#/components/schemas/CodeDescription' subType: $ref: '#/components/schemas/CodeDescription' subclass: $ref: '#/components/schemas/CodeDescription' type: $ref: '#/components/schemas/CodeDescription' x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: OrganisationDataObject EntityProfileItemMatchResultObject: description: Match summary for a single checked address or document type: object properties: checked: description: True if an attempt was made to verify type: boolean example: true matchCount: description: The number of distinct sources that matched this address or document type: integer example: 5 matchSources: description: > List of sources that matched. The matchCount will be the number of entries in this list. type: array items: type: string x-omitempty: true matchType: description: > The match type that this count and result refer to. For document matches this will be "gov_id" or "other_id". For addresses ir will be "curr_addr" or "prev_addr" depending on the status of the address at the time of the check. type: string example: gov_id nonmatchSources: description: > List of sources that did not match, only if available from service provider. type: array items: type: string x-omitempty: true verified: description: True if there is at least one match type: boolean example: true x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: EntityProfileItemMatchResultObject EntityProfileAltKYCMatchResultObject: description: | Summary of all KYC matches for a given set of criteria type: object properties: description: description: A full description for these results type: string kycResults: description: | Summary of this alternative KYC match counts. type: array items: $ref: '#/components/schemas/EntityProfileKYCMatchResultObject' x-omitempty: true name: description: A short human readable name for these results type: string order: description: > For multiple matching criteria sets, the priority order in which this result set was defined. 1 = highest priority criteria set 2 = second highest priority ... n = lowest priority type: integer result: description: | The current state of this alternative KYC check. One of: - PASS: Enough matches to pass. - FAIL: Not enough matches, zero or more, but less than required. - UNCHECKED: No results. type: string x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: EntityProfileAltKYCMatchResultObject EntityProfileCheckResultMessage: type: object properties: checkClass: description: | The class of checks to which this check type belongs. One of: - kyc - aml - fraud - none type: string example: kyc checkType: description: A single check type that this result message applies to. type: string example: one_plus code: description: > Alphanumeric code that is unique for each failure message to simplify result processing and display. Values to be decided. type: string message: description: Short description of why not passed type: string example: Partial match name: description: A short human readable name for the check type. type: string example: 1+1 result: description: > The current state of the check. One of: - PASS - FAIL - UNCHECKED: Not attempted or service not available. For example AML not attempted if KYC fails. - NA: Not required. For example Visa check when there is no visa document and your account configuration indicates the check can be skipped. type: string x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: EntityProfileCheckResultMessage EntityProfileKYCMatchResultObject: description: | Summary of all KYC matches for a given set of criteria type: object properties: matchCount: description: > Number of matches for this set of match types. In other words the sum of the matchCounts in the matchTypes map. Note that for match sets that include government ID (gov_id) this will not neccessaily be the count of matched sources. type: integer example: 2 matchCountRequired: description: > Number of distinct matches (sources and/or matched government ID documents) required for this set of match types. type: integer example: 1 matchTypes: description: > The match types that this overall count and result refer to. Currently one or more of: - name - address - dob - gender - gov_id - other_id These will be keys in a map whose values hold the values for the individual match types. The resultant structure would look like the following. Here dob has zero matches and is not verfied but it was check, so other than the checked flag the value object is simply empty. A completely empty object would imply that match type was not checked. "matchTypes": { "address": { "matchCount": 1, "matchSources": [ "au-elec-roll" ], "checked": true, "verified": true }, "dob": { "checked": true } } So for a one_plus KYC check there will be two EntityProfileKYCMatchResultObject records. One for 'name' and one for 'address, dob' (like the sample above). type: object additionalProperties: $ref: '#/components/schemas/EntityProfileKYCMatchResultObjectMatchTypes' x-omitempty: true verified: description: True if there are enough matches to meet the requirement type: boolean example: false x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: EntityProfileKYCMatchResultObject AddressCheckResultObject: description: > This object holds the address that was checked and the results associated with said checks. You can also leave the checkResult blank/nil if there are no results for that address if you wish. This is useful for returning results on a freshly crerated entity where the API user would want to confirm that the data has indeed been stored, and be able to capture relevant addressIDs - perhaps to address issues as to why it wasn't checked. type: object properties: address: $ref: '#/components/schemas/AddressObject' checkResult: $ref: '#/components/schemas/generalCheckResultArray' x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: AddressCheckResultObject backgroundCheckResultObject: description: >- Contains the details of a background check for a given entity. Background checks include Politically Exposed Person (PEP), sanctions lists, watchlists and adverse media. type: object properties: backgroundCheckType: $ref: '#/components/schemas/enumBackgroundCheckType' checkDetails: description: >- Any additional notes that may relate to the state. Free form notes that may contain JSON blobs needing further interpretation. type: array items: $ref: '#/components/schemas/KeyValuePairObject' x-omitempty: true checkFrequency: $ref: '#/components/schemas/enumBackgroundCheckFrequency' checkId: $ref: '#/components/schemas/CheckIDObject' checkPerformedBy: description: > Service provider that performed the check. Basically the name of the connector, without the leading con_ type: string example: dvs checkSource: description: > Code that can be used to determine the underlying nature or data source of the checks performed. This may or may not be known by the connector, or may be a provider specific type (e.g. type "O") type: string example: DVS confidenceLevel: description: >- Confidence in the current results on a scale of 0 (none) to 100 (as certain as possible). Whole integers only. type: integer format: int32 maximum: 100 minimum: 0 example: 70 currentState: $ref: '#/components/schemas/enumBackgroundCheckState' firstCheckDate: description: The date and time the item was first checked. type: string format: date-time example: 2017-11-12T13:14:15Z+10:00 latestCheckDate: description: The date and time the item was last checked to provide this result. type: string format: date-time example: 2018-11-12T13:14:15Z+10:00 x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: BackgroundCheckResultObject AMLResultSet: description: Wrapper object to contain a single set of AML check results. type: object properties: checkResultsListMedia: description: > Collection of check results for the entity being found in any adverse media An array sorted by type, then reverse chronological order of some/all background checks done on this entity. Older checks may have been previously done by you or another institution, and if so, these will be listed and appropriately anonymised/obfuscated. type: array items: $ref: '#/components/schemas/backgroundCheckResultObjectContainer' x-omitempty: true checkResultsListPEP: description: > Collection of check results for the entity being a Politically Exposed Person An array sorted by type, then reverse chronological order of some/all background checks done on this entity. Older checks may have been previously done by you or another institution, and if so, these will be listed and appropriately anonymised/obfuscated. type: array items: $ref: '#/components/schemas/backgroundCheckResultObjectContainer' x-omitempty: true checkResultsListSanctions: description: > Collection of check results for the entity being on a sanctions list An array sorted by type, then reverse chronological order of some/all background checks done on this entity. Older checks may have been previously done by you or another institution, and if so, these will be listed and appropriately anonymised/obfuscated. type: array items: $ref: '#/components/schemas/backgroundCheckResultObjectContainer' x-omitempty: true checkResultsListWatchlists: description: > Collection of check results for the entity being on a watchlist An array sorted by type, then reverse chronological order of some/all background checks done on this entity. Older checks may have been previously done by you or another institution, and if so, these will be listed and appropriately anonymised/obfuscated. type: array items: $ref: '#/components/schemas/backgroundCheckResultObjectContainer' x-omitempty: true groupDetails: $ref: '#/components/schemas/backgroundCheckResultObjectContainer' x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: AMLResultSet DOBCheckResultObject: type: object properties: checkResult: $ref: '#/components/schemas/generalCheckResultArray' dob: $ref: '#/components/schemas/DOBObject' x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: DOBCheckResultObject GenderCheckResultObject: type: object properties: checkResult: $ref: '#/components/schemas/generalCheckResultArray' gender: $ref: '#/components/schemas/enumGender' x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: GenderCheckResultObject IdentityDocumentCheckResultObject: description: > This object holds the identityDocument that was checked and the results associated with said checks. You can also leave the checkResult blank/nil if there are no results for that identityDocument if you wish. This is useful for returning results on a freshly crerated entity where the API user would want to confirm that the data has indeed been stored, and be able to capture relevant documentIds - perhaps to address issues as to why it wasn't checked. type: object properties: checkResult: $ref: '#/components/schemas/generalCheckResultArray' idDocument: $ref: '#/components/schemas/IdentityDocumentObject' x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: IdentityDocumentCheckResultObject PersonalNameCheckResultObject: type: object properties: checkResult: $ref: '#/components/schemas/generalCheckResultArray' name: $ref: '#/components/schemas/PersonalNameObject' x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: PersonalNameCheckResultObject enumKVPType: description: > Used to describe the contents of the KVP data. The general.* and raw.* types are pretty much what they say on the tin. All raw.* fields will be base64 encoded so as to not interfere with JSON structuring. These are useful for returning/storing large quantities of data that doesn't necessarily require processing now, or may be useful to a calling client. The id.* and pii.* are used to indicate that this is data that can be used to create new document objects, or entities. They should also be treated with the utmost care and attention when it comes to securing them too. id.external can be used to capture an object's ID on an external service, and can potentially be searchable in the index Note - This is different from a result.id. defunct is used to mark an existing KVP deleted when the value must be retained, for example for audit purposes. result.* are used to capture response codes and transaction IDs from external services error.* types can be used when processing a document that returns an error, but doesn't necessarily require a full blown error response. type: string enum: - defunct - general.string - general.integer - general.float - general.bool - general.date - general.datetime - raw.json.base64 - raw.xml.base64 - raw.base64 - error.code - error.message - result.code - result.id - id.external - id.number.primary - id.number.additional - id.msisdn - id.email - id.device - pii.name.full - pii.name.familyname - pii.name.givenname - pii.name.middlename - pii.gender - pii.address.longform - pii.address.shortform - pii.address.street1 - pii.address.street2 - pii.address.postalcode - pii.address.town - pii.address.suburb - pii.address.region - pii.address.state - pii.address.country - pii.dob - transient.string example: id.external x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: EnumKVPType enumAddressType: description: > Used to indicate what sort address this is, such as residential, business, postal, etc. RESIDENTIAL1-4 can be used to indicate the reverse chronological order of addresses. RESIDENTIAL or RESIDENTIAL1 is the current address RESIDENTIAL2 is the previous address, and so on. For Individual postal/mailing addresses, use POSTAL. For Businesses, use OFFICIAL_CORRESPONDANCE type: string enum: - OTHER - RESIDENTIAL - RESIDENTIAL1 - RESIDENTIAL2 - RESIDENTIAL3 - RESIDENTIAL4 - BUSINESS - POSTAL - REGISTERED_OFFICE - PLACE_OF_BUSINESS - OFFICIAL_CORRESPONDANCE - PLACE_OF_BIRTH x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: EnumAddressType example: REGISTERED_OFFICE ScannedDocumentObject: description: the document to be attached and optionally scanned (if supported) type: object properties: ScanDelete: description: > Used as a way of indicating to the service that the original scanned document is not to be kept after it has been processed. We will retain any metadata and the results of processing (where required by regulation or the customer), but the original file uploaded will eventually be remnoved once processing is complete. If ScanDelete is set to true, any call with /full at the end will still not return the file contents, regardless of whether the file has been deleted yet (the deletion process is a background task that can take a few minutes to occur) type: boolean scanCreated: description: > The date and time the scan was created. Not the date of the scanned document, which should be in the idIssued attribute of the document that owns this scan. type: string format: date-time example: '2020-06-02' scanData: description: > Base64 encoded string of a photo or scan of an ID document to be verified. If supplied and of a supported type, the Frankie service will attempt to use OCR tech to extract the data from the scanned doc/image. In a result message, this field will be left blank, unless the "full" action is requested. type: string format: byte example: >- VGhpcyBpcyBzb21lIGV4YW1wbGUgZGF0YS4gV29vLCBJIGJldCB5b3UgcmVncmV0IHRoZSB0aW1lIHlvdSB3YXN0ZWQgZGVjb2RpbmcgdGhpcywgaHVoPw== scanDataRetrievalState: $ref: '#/components/schemas/enumScanDataRetrievalState' scanDocId: description: > When an document scan is created/uploaded, it is assigned a scanDocId. You'll see this in a successful response or successfully accepted response. This can then be referenced in subsequent calls if you're uploading more/updated data. type: string format: uuid example: 84a9a860-68ae-4d7d-9a53-54a1116d5051 scanFilename: description: > If you're uploading a file where it's important to keep the original filename, then you can provide that here. Otherwise the Frankie service will assign an arbitrary name based on the scanDocIdand an extension based on the MIME type type: string example: Important Document - ID1234567.pdf scanMIME: $ref: '#/components/schemas/enumMIMEType' scanPageNum: description: > If uploading multiple pages - it's handy to keep a track of these. There is no enforcement of these numbers at all. You can have 10 page 1's and a page 29 if you wish. type: integer minimum: 0 example: 1 scanSide: $ref: '#/components/schemas/enumScanSide' scanType: $ref: '#/components/schemas/enumScanType' x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: ScannedDocumentObject enumDocumentStatus: description: > Current status of a document. - "INITIALISING": the state whilst you're uploading and updating - "SCAN_IN_PROGRESS": the state whilst it's being scanned. - "DOC_SCANNED": the document has been scanned and data extracted as best as possible. It's still possible to update the details and add more scans if you wish. - "DOC_CHECKED": the document has been used as part of a check that has been finalised in some way. You can no longer update this document and any attempt will generate an error. type: string enum: - INITIALISING - SCAN_IN_PROGRESS - DOC_SCANNED - DOC_CHECKED x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: EnumDocumentStatus example: DOC_SCANNED enumIdType: description: | Valid ID types - "OTHER": Generic document type. Unspecified. - "DRIVERS_LICENCE": Driver's licence. - "PASSPORT": Passport - "VISA": Visa document (not Visa payment card) - "IMMIGRATION": Immigration card - "NATIONAL_ID": Any national ID card - "TAX_ID": Any national tax identifier - "NATIONAL_HEALTH_ID": Any national health program ID card (e.g. Medicare, NHS) - "CONCESSION": State issued concession card - "HEALTH_CONCESSION": State issued health specific concession card - "SENIORS_HEALTH_CONCESSION": State issued health specific concession card for seniors - "PENSION": State issued pension ID - "MILITARY_ID": Military ID - "BIRTH_CERT": Birth certificate - "CITIZENSHIP": Citizenship certificate - "MARRIAGE_CERT": Marriage certificate - "DEATH_CERT": Death certificate - "NAME_CHANGE": Name chage confirmation - "UTILITY_BILL": Regulated utility bill, such as electricity, gas, etc - "BANK_STATEMENT": Bank/card statement - "BANK_ACCOUNT": Bank account - "INTENT_PROOF": A proof of intent. Generally a photo/video, or a scanned letter - "ATTESTATION": A document of attestation (e.g. Statutory Declaration). NOTE: these cannot be used as a supporting document - "SELF_IMAGE": A "selfie" used for comparisions - "EMAIL_ADDRESS": An email address - "MSISDN": A mobile phone number - "DEVICE": A device ID - "VEHICLE_REGISTRATION": Vehicle registration number - "PROOF_OF_ADDRESS": Can be any type of document that provides a proof of address - "HOUSE_REGISTRATION": House registration document - "YELLOW_HOUSE_REGISTRATION": Yellow House Registration Thor Ror 13 - "WORK_PERMIT": Work permit - "EMPLOYMENT_CERTIFICATE": Certificate of employment - "NOTARY_PUBLIC_ID": Notary Public Identification - "AVIATION_SECURITY_ID": Aviation Security Identification - "MARITIME_SECURITY_ID": Maritime Security Identification Business related documentation - "EXTERNAL_ADMIN": Details of appointed administrator. - "CHARGES": Details of any charges that have been laid against a company or director - "PRE_ASIC": Any documents that are Pre-ASIC - "ANNUAL_RETURN": Details of a company's annual return - "REPORT": Frankie generated report. - "TRUST_DEED": Corporate trust deed - "PARTNERSHIP_AGREEMENT": Partnership agreement documents - "ADMIN_CHANGE": Change of Administrator - "COMPANY_REPORT": ASIC filed company reports Special document types - "CHECK_RESULTS": A special document type for specifying results of checks completed other than through Frankie. type: string enum: - OTHER - DRIVERS_LICENCE - PASSPORT - VISA - IMMIGRATION - NATIONAL_ID - TAX_ID - NATIONAL_HEALTH_ID - CONCESSION - HEALTH_CONCESSION - SENIORS_HEALTH_CONCESSION - PENSION - MILITARY_ID - BIRTH_CERT - CITIZENSHIP - MARRIAGE_CERT - DEATH_CERT - NAME_CHANGE - MOBILE_PHONE - UTILITY_BILL - BANK_STATEMENT - BANK_ACCOUNT - INTENT_PROOF - ATTESTATION - SELF_IMAGE - EMAIL_ADDRESS - MSISDN - DEVICE - VEHICLE_REGISTRATION - PROOF_OF_ADDRESS - HOUSE_REGISTRATION - YELLOW_HOUSE_REGISTRATION - WORK_PERMIT - EMPLOYMENT_CERTIFICATE - NOTARY_PUBLIC_ID - AVIATION_SECURITY_ID - MARITIME_SECURITY_ID - EXTERNAL_ADMIN - CHARGES - PRE_ASIC - ANNUAL_RETURN - REPORT - TRUST_DEED - PARTNERSHIP_AGREEMENT - ADMIN_CHANGE - COMPANY_REPORT - CHECK_RESULTS x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: EnumIdType example: DRIVERS_LICENCE CodeDescription: description: A common pairing of a short code and a long description. type: object properties: code: type: string description: type: string x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: CodeDescription OrganisationDataObjectContactDetails: type: object properties: email: type: string faxNumber: type: string telephoneNumber: type: string websiteURL: type: string x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: OrganisationDataObjectContactDetails IndustryCodesObject: type: object properties: code: type: string description: type: string x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: IndustryCodesObject IndustryDeclarationsObject: type: object properties: description: type: string language: type: string x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: IndustryDeclarationsObject OrganisationDataObjectLegalFormDetails: type: object properties: basis: type: string capital: type: string comments: type: string control: type: string incorp: type: string partner: type: string responsibility: type: string stocks: type: string x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: OrganisationDataObjectLegalFormDetails OrganisationDataObjectRegistration: type: object properties: countryIso: type: string date: type: string format: date number: type: string previousNumber: type: string registryCode: type: string registryDescription: type: string state: type: string unstructuredDate: type: string unstructuredFoundationDate: type: string x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: OrganisationDataObjectRegistration Registries: type: object properties: abr: $ref: '#/components/schemas/Abr' x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: Registries ShareStructureObject: description: > Describes a collection of shares of a particular type and their attributes, One or more ShareStructures make up a company's shares that are then parcelled out as shareholdings. type: object properties: amountDue: type: number amountPaid: type: number classCode: type: string classTitle: type: string docNumber: type: string docNumberQualifier: type: string sharesIssued: type: integer status: type: string x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: ShareStructureObject EntityProfileKYCMatchResultObjectMatchTypes: type: object properties: checked: description: True if an attempt was made to verify type: boolean example: true matchCount: description: > Number of distinct matches for this match type. Note that for government ID (gov_id) this is the count of matched documents, not sources. type: integer example: 1 matchSources: description: > List of sources that matched. Note that the matchCount is not always a count of the matchSources. Particularly for gov_id, the count is the number of distinct documents matched, not the number of sources. type: array items: type: string x-omitempty: true nonmatchSources: description: > List of sources that did not match, only if available from service provider. type: array items: type: string x-omitempty: true verified: description: True if there is at least one match type: boolean example: true x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: EntityProfileKYCMatchResultObjectMatchTypes generalCheckResultArray: description: >- An array in reverse chronological order of all checks done on this data point for the given entity. Older checks may have been previously done by you or another institution, and if so, these will be listed. type: array items: $ref: '#/components/schemas/generalCheckResultObject' x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: GeneralCheckResultArray enumBackgroundCheckType: description: > Different types of checks available. Note: WATCHLIST can also cover PEP and/or SANCTION as well, depending on source provider used. GROUP is an internal 'meta-check' to store the group details for an AMLResultSet. type: string enum: - PEP - SANCTION - WATCHLIST - MEDIA - GROUP x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: EnumBackgroundCheckType example: PEP enumBackgroundCheckFrequency: description: How often these checks run. type: string enum: - ADHOC - YEARLY - QUARTERLY - MONTHY - WEEKLY - DAILY x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: EnumBackgroundCheckFrequency example: DAILY enumBackgroundCheckState: description: > Current state, based on the most recent check. - "CLEAR": The no checks have ever turned up results - "PAST_HITS": Past checks have returned hits, but now they're clear. - "POSSIBLE_HIT": The most recent checks turned up some results that may be relevant - "ACTIVE_HITS": The current checks are returning definitive hits. type: string enum: - CLEAR - PAST_HITS - POSSIBLE_HIT - ACTIVE_HITS x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: EnumBackgroundCheckState example: CLEAR backgroundCheckResultObjectContainer: description: Wraps up a BCRO with its internal ID. type: object properties: bcro: $ref: '#/components/schemas/backgroundCheckResultObject' id: description: Internal ID of this BCRO. Use this if you need to set the status. type: string format: uuid x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: BackgroundCheckResultObjectContainer enumScanDataRetrievalState: description: > The reason why the scanData in a response is missing. - "NORMAL": The scanData was retrieved and is included. If it is empty then it was never provided or was provided empty. - "EXCLUDED": The retrieval request was not for 'full' data, or the object has 'ScanDelete' set so the scanData is not included - "FAILED": The scanData could not be retrieved from the secure document store. The enumScanDataRetrievalState will not usually be set in a request. If a ScannedDocumentObject in a response has a 'FAILED' retrieval state then that object should not be sent back in a future possible update. It should either be omitted or the original data should be resent if it is available from another source. However it is safe to send the object in an update with the state received in a response. Any state other than 'NORMAL' (or '') will cause the blank scanData to be ignored, but other fields in the object will be updated if needed. type: string enum: - NORMAL - EXCLUDED - FAILED x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: EnumScanDataRetrievalState example: NORMAL enumMIMEType: description: >- The standard MIME type of the file being uploaded. We'll double-check to be certain, but this can help speed things up type: string enum: - image/jpeg - image/avif - image/png - image/gif - image/webp - image/tiff - image/bmp - image/heic - image/heif - application/zip - application/x-zip - application/x-zip-compressed - application/x-tar - application/x-rar-compressed - application/x-gzip - application/gzip - application/x-bzip2 - application/x-7z-compressed - application/pdf - application/rtf - application/postscript - application/json - audio/mpeg - audio/m4a - audio/x-wav - audio/amr - text/plain - text/rtf - application/msword - >- application/vnd.openxmlformats-officedocument.wordprocessingml.document - application/vnd.ms-excel - application/vnd.openxmlformats-officedocument.spreadsheetml.sheet - application/vnd.ms-outlook - application/vnd.ms-powerpoint - application/vnd.oasis.opendocument.text - >- application/vnd.openxmlformats-officedocument.presentationml.presentation - video/avi - video/x-m4a - video/mp4 - video/webm - video/quicktime - video/msvideo - video/x-msvideo - video/x-ms-wmv - video/mpeg x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: EnumMIMEType example: image/png enumScanSide: description: >- Describes if a scan is of the "F"ront or "B"ack of an ID. If not supplied, Front is always assumed. type: string enum: - F - B x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: EnumScanSide example: F enumScanType: description: | Valid ID document scan general types. - "PHOTO": Any photo - "VIDEO": Any video - "AUDIO": Any audio - "PDF": PDF or PS (may contain text, images or both) - "DOC": Word doc, RTF, etc - "ZIP": Any compressed file(s) type: string enum: - PHOTO - VIDEO - AUDIO - PDF - DOC - ZIP x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: EnumScanType example: PDF Abr: type: object properties: abn: type: string acn: type: string addresses: type: array items: $ref: '#/components/schemas/MainBusinessPhysicalAddress' businessNames: type: array items: $ref: '#/components/schemas/BusinessName' charityEndorsements: type: array items: $ref: '#/components/schemas/CharityEndorsement' charityTypes: type: array items: $ref: '#/components/schemas/CharityType' description: type: string dgrEndorsements: type: array items: $ref: '#/components/schemas/DgrEndorsement' gst: type: array items: $ref: '#/components/schemas/GoodsAndServicesTax' historicalChanges: type: array items: $ref: '#/components/schemas/HistoricalChange' lastUpdated: type: string format: date-time name: type: string registeredDate: type: string format: date-time status: type: string statusEffectiveFrom: type: string type: type: string typeCode: type: string updatedDate: type: string format: date-time x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: Abr generalCheckResultObject: description: Contains the details of a check on a given data point type: object properties: checkProcessResults: $ref: '#/components/schemas/ProcessResultObject' checkRequestedBy: description: > Who performed the check. If it was the calling customer, the value will be "You". If it was another institution that has previously validated this data, then a generic description of their industry will be provided, such as "Bank", "Insurance", "Other FI". type: string example: Bank x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: GeneralCheckResultObject MainBusinessPhysicalAddress: type: object properties: effectiveFrom: type: string format: date-time effectiveTo: type: string format: date-time postcode: type: string stateCode: type: string x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: MainBusinessPhysicalAddress BusinessName: type: object properties: effectiveFrom: type: string format: date-time effectiveTo: type: string format: date-time name: type: string type: type: string x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: BusinessName CharityEndorsement: type: object properties: effectiveFrom: type: string format: date-time effectiveTo: type: string format: date-time type: type: string x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: CharityEndorsement CharityType: type: object properties: description: type: string effectiveFrom: type: string format: date-time effectiveTo: type: string format: date-time x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: CharityType DgrEndorsement: type: object properties: endorsedFrom: type: string format: date-time endorsedTo: type: string format: date-time x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: DgrEndorsement GoodsAndServicesTax: type: object properties: effectiveFrom: type: string format: date-time effectiveTo: type: string format: date-time x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: GoodsAndServicesTax HistoricalChange: type: object properties: businessName: type: array items: type: string date: type: string format: date-time entityStatus: type: array items: type: string goodsAndServicesTax: type: array items: type: string mainBusinessPhysicalAddress: type: array items: type: string mainName: type: array items: type: string mainTradingName: type: array items: type: string x-go-type: import: alias: models_common package: bitbucket.org/ff_common/models/common type: HistoricalChange securitySchemes: api_key: description: API key issued by Frankie Financial. This will rotate regularly. type: apiKey name: api_key in: header ````