swagger: "2.0" schemes: - https host: api.demo.frankiefinancial.io basePath: /compliance/v1.2 info: contact: email: dev-support@frankiefinancial.com 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. ------ Industry specific services - Comparing Australian electricity retailers for a better deal. ------ 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://apidocs.frankiefinancial.com/ The traditional Swagger view of this documentation can be found here: - https://app.swaggerhub.com/apis-docs/FrankieFinancial/kycutility ------ Sandbox base URL is: - https://api.demo.frankiefinancial.io/compliance/v1.2 - We do have an old sandbox at https://sandbox.frankiefinancial.com/compliance/v1.2 but this has been retired. - All calls are the same as production, only with canned 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 version: 1.5.3 x-apisguru-categories: - financial x-origin: - format: swagger url: https://app.swaggerhub.com/apiproxy/registry/FrankieFinancial/kycutility/1.5.3 version: "2.0" x-providerName: frankiefinancial.io consumes: - application/json produces: - application/json securityDefinitions: api_key: description: API key issued by Frankie Financial. This will rotate regularly. in: header name: api_key type: apiKey security: - api_key: [] parameters: AlertIDPathParameter: description: The alertId that was passed to you in a previous notification format: uuid in: path name: alertId required: true type: string AllDataQueryParameter: description: | Requests that literally all data should be included in the response to a "get checks" request. This is as opposed to a filtered view where expired results are by default not included for entities that have an assigned profile. in: query name: alldata required: false type: boolean AskingNicelyQueryParameter: description: | If set to true, the request is being made politely. in: query name: askingNicely required: false type: boolean AttributeQueryParameter: description: |+ Specify the blacklisted attribute. Valid values are: - "ENTIRE_PROFILE" - "FULL_NAME" - "EMAIL_ADDRESS" - "PHONE_NUMBER" - "ID_DOCUMENT" - "MAILING_ADDRESS" - "RESIDENTIAL_ADDRESS" in: query name: attribute required: false type: string BackgroundHeader: 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://apidocs.frankiefinancial.com/docs/asynchronous-calls-backgrounding-processes in: header maximum: 1 minimum: 0 name: X-Frankie-Background required: false type: integer BlockedByQueryParameter: description: | Specify who is setting the entity as blacklisted. in: query name: blockedBy required: false type: string BlocklistsQueryParameter: description: | Specify the blacklisted attribute. in: query items: type: string name: blockLists required: false type: array BusinessCheckResultLevelQueryParameter: default: summary description: | The result level allows you to specify the level of detail returned for the entity check. You can choose summary or full. enum: - summary - full in: query name: resultLevel required: false type: string BusinessCheckTypeQueryParameter: collectionFormat: csv description: | When creating a new check, we need to define the checks we wish to run. If this parameter is not supplied then the check will be based on a configured check type for each entity category. The checkType is make up of a comma separated list of the types of check we wish to run. The order is important, and must be of the form: - Entity Check (if you're running this). Choose one from the available options - ID Check (If you want this) - PEP Checks (again if you want this, choose one of the options) Entity Checks - One of: - "one_plus": Checks name, address and DoB against a minimum of 1 data source. (also known as a 1+1) - "two_plus": Checks name, address and DoB against a minimum of 2 independent data sources (also known as a 2+2) ID Checks - One of: - "id": Checks all of the identity documents, but not necessarily the entity itself independently. Use this in conjunction with a one_plus or two_plus for more. Fraud Checks - One or more of: - "fraudlist": Checks to see if the identity appears on any known fraud lists. Should be run after KYC/ID checks have passed. - "fraudid": Checks external ID services to see if details appear in fraud detection services (e.g. EmailAge or FraudNet) PEP Checks - One of: - "pep": Will only run PEP/Sanctions checks (no identity verification) - "pep_media": Will run PEP/Sanctions checks, as well as watchlist and adverse media checks. (no identity verification) * NOTE: These checks will ONLY run if either the KYC/ID checks have been run prior, or it is the only check requested. Pre-defined combinations: - "full": equivalent to "two_plus,id,pep_media" or "pep_media" if the target is an organisation. - "default": Currently defined as "two_plus,id" or "pep" if the target is an organisation. Custom: - By arrangement with Frankie you can define your own KYC check type. This will allow you to set the minimum number of matches for: - name - date of birth - address - government id This allows for alternatives to the "standard" two_plus or one_plus (note, these can be overridden too). Profile: - "profile": By arrangement with Frankie you can have a "profile" check type that applies checks according to a profile that you assign to the entity from a predefined set of profiles. The profile to use will be taken from the entity.entityProfile field if set, or be run through a set of configurable rules to determine which one to use. Profiles act a little like the Pre-defined combinations above in that they can map to a defined list. But they offer a lot more besides, including rules for determining default settings, inbuild data aging and other configurable features. They also allow for a new result set top be returned that provides a more detailed and useful breakdown of the check/verification process. Entity Profiles are the future of checks with Frankie Financial. in: query items: enum: - full - default - one_plus - two_plus - id - fraudlist - fraudcheck - pep - pep_media - profile type: string name: checkType required: false type: array uniqueItems: true BusinessEntityCategoriesQueryParameter: collectionFormat: csv description: | A comma separated list that specifies the categories of entities associated with the target organisation that will be checked. - organisation - Just the organisation itself. - ubos - All ultimate beneficial owners. - pseudo_ubos - Use an alterntive category when an organisation has no actual UBOs. The actual category to use is defined via configuration, default is no alterntive category. - direct_owners - All direct owners of the company, both organisations and individuals, may include UBOs for for simple ownership. - officers - All officers of the company - officers_directors - All directors of the company - officers_other - All non-director officers of the company - all - All direct and indirect owners, both organisations and individuals (including UBOs), and officers of all organisations. in: query items: enum: - organisation - ubos - pseudo_ubos - direct_owners - officers - officers_directors - officers_other - all type: string name: entityCategories required: false type: array uniqueItems: true BusinessGenerateReportQueryParameter: description: | The type of human readable report, if any, to generate based on the ownership query results. in: query name: generateReport required: false type: string BusinessIncludeHistoricalQueryParameter: description: | If set to true, historical ownership data will be requested. in: query name: includeHistorical required: false type: boolean BusinessOnlyProfileQueryParameter: description: | If set to true, a full UBO report will not be requested. in: query name: onlyProfile required: false type: boolean BusinessReportTypesQueryParameter: description: | Define the report(s) you wish to run. You can request more than one as a comma separated list. Duplicates will be ignored. Note: These reports are different to the business details and UBO queries and are meant to provide deeper detail and background on a business or organisation. Current valid report types are: - creditScore - creditReport in: query name: reportTypes required: true type: string BusinessValidationParameter: description: | Should a validation check be run before the ownership query. The default is specified via configuration. The validation checks to see if the provided organisation is suitable for an ownership query by looking for the ACN in public data sources. Options are: - "on": Validate only when ACN is not provided. This is the typical default. - "acn": Validate even if ACN is provided. - "only": Like "acn" but only do validation query, don't proceed with ownership query. This option cannot be set as the default via configuration. - "off": Never validate. The Ownership query will then fail if an ACN is not provided. enum: - on - off - only - acn in: query name: validation required: false type: string CheckClassActionQueryParameter: description: | Set the new status of the Check Class (PRO/BCRO). Valid values are: - "unknown" - "true_positive" - "true_positive_accept" - "true_positive_reject" - "false_positive" - "stale" in: query name: status required: true type: string CheckClassIDPathParameter: description: | A PRO/BCRO ID in: path name: checkClassId required: true type: string CheckClassPathParameter: description: | Specify which check Class this action will apply to (PRO, BCRO etc.). Valid values are: - "pro": Update a Process Result Object - "bcro": Update a Background Check Result Object. The class IDs in the request must be the IDs from Background Check Result Object Containers. - "fraudlist": Update a fraud list Process Result Object. The class IDs in the request must be check sources from fraudlist Process Result Objects. enum: - pro - bcro - fraudlist in: path name: checkClass required: true type: string CheckIDPathParameter: description: The checkId returned previously from an earlier call to */verify format: uuid in: path name: checkId required: true type: string CheckTypeParameter: default: default 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 of 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. 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). in: path name: checkType required: true type: string CommentQueryParameter: description: | A comment describing the reason for a request. in: query name: comment required: false type: string CustomerChildIDHeader: 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. format: uuid in: header name: X-Frankie-CustomerChildID required: false type: string CustomerIDHeader: description: | Customer ID issued by Frankie Financial. This will never change. Your API key, which is mapped to this identity, will change over time. format: uuid in: header name: X-Frankie-CustomerID required: true type: string DocumentIDPathParameter: description: The documentId returned previously from an earlier call to /check or /entity or /document format: uuid in: path name: documentId required: true type: string EntityIDPathParameter: description: The entityId returned previously from an earlier call to /check or /entity format: uuid in: path name: entityId required: true type: string EntityRiskQueryParameter: description: | The risk override setting for an entity. This value will be used until a verify result updates a real risk factor. Valid values are: - "low" - "medium" - "high" - "unacceptable" - "significant" enum: - low - medium - high - unacceptable - significant in: query name: risk required: false type: string ForceFlagQueryParameter: description: | Force the verification to run, overriding any data aging or past check in: query name: force required: false type: boolean IndustryPathParameter: description: | Specify which industry the industry-specific process will come from. Valid values are: - "electricity": Electricity specific functions. - "gas": Gas specific functions. - "gaming": Gaming specific functions. - "gambling": Gambling specific functions. - "cryptocurrency": Cryptocurrency specific functions. enum: - electricity - utility - gas - gaming - gambling - cryptocurrency in: path name: industry required: true type: string IndustryProcessPathParameter: description: | Specify the industry-specific process to be performed Valid values are: - Electricity specific functions: - scan (scan and extract account holder data) - compare (scan, then generate plan comparison) - Gas specific functions: - scan (scan and extract account holder data) - compare (scan, then generate plan comparison) - Gambling specific functions: - blacklist (add entity to industry blacklist) - deblacklist (remove entity to industry blacklist) - Cryptocurrency specific functions: - blacklist (add entity to industry blacklist) - deblacklist (remove entity to industry blacklist) Note: Trying to use a process not tied to an industry will generate an error response. So no silly business. enum: - scan - compare - consent - switch - blacklist - deblacklist in: path name: industryProcess required: true type: string NoInvalidateQueryParameter: description: | Disable check result invalidation for this update request. in: query name: noInvalidate required: false type: boolean NoPushQueryParameter: description: | If set to true, then no SMS/email will be pushed. It will be up to the API caller to manage the delivery of the link. in: query name: nopush required: false type: boolean NotificationIDPathParameter: description: This is a Customer/ChildCustomer specific ID (UUID) that is used to help identify Frankie as a known notifying service. This ID is configured on the Frankie side along with the rest of the customer path as the endpoint for us to push notifications to. format: uuid in: path name: notificationId required: true type: string OriginalIdQueryParameter: description: | Specify the Id of the matching blacklisted entity or single data-point. in: query name: originalId required: false type: string OtherIDPathParameter: description: An entityId returned previously from an earlier call to /check or /entity. Used when an operation requires two entityIds format: uuid in: path name: otherId required: true type: string PTMPhaseQueryParameter: description: | Set the Push To Mobile phase. Currently supported values: - 2 in: query name: phase required: false type: integer PayloadEncodingQueryParameter: description: | Specifies the type of the payload field in the retrieved response. Default is 'string'. enum: - string - object in: query name: payload type: string PlanLimitQueryParameter: default: 30 description: The maximum number of plans to return in: query name: planLimit required: false type: integer ReasonFlagQueryParameter: description: | Set the reason for blacklisting. Valid values are: - "NO_REASON_SUPPLIED" - "FABRICATED_IDENTITY" - "IDENTITY_TAKEOVER" - "FALSIFIED_ID_DOCUMENTS" - "STOLEN_ID_DOCUMENTS" - "MERCHANT_FRAUD" - "NEVER_PAY_BUST_OUT" - "CONFLICTING_DATA_PROVIDED" - "MONEY_MULE" - "FALSE_FRAUD_CLAIM" - "FRAUDULENT_3RD_PARTY" - "COMPANY_TAKEOVER" - "FICTITIOUS_EMPLOYER" - "COLLUSIVE_EMPLOYER" - "OVER_VALUATION_OF_ASSETS" - "FALSIFIED_EMPLOYMENT_DETAILS" - "MANIPULATED_IDENTITY" - "SYNDICATED_FRAUD" - "INTERNAL_FRAUD" - "BANK_FRAUD" - "UNDISCLOSED_DATA" - "FALSE_HARDSHIP" - "SMR_REPORT_LODGED" - "2X_SMR_REPORTS_LODGED" in: query name: reason required: false type: string ReasonWlFlagQueryParameter: description: | Set the reason for watchlisting. Valid values are: - "WAS_BLACKLISTED" in: query name: reason required: false type: string RequestIDPathParameter: description: | This will be the same RequestId that was sent in the 202 acceptance response. format: string in: path name: requestId required: true type: string ResultLevelPathParameter: 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. enum: - simple - summary - full in: path name: resultLevel required: true type: string SetEntityStatusQueryParameter: description: | The status of an entity. Valid values are: - "wait": Waiting for new details from entity. - "fail": Manually fail the onboarding process. - "archived": Hide entity from on onboarding. - "clear": Remove any of the above manual states as well as any manual risk. - "inactive": Hide entity and prevent any further operations on it. Cannot be cleared. enum: - wait - fail - archived - clear - inactive in: query name: set required: false type: string SetFlagQueryParameter: description: | Set the value of an entity flag. in: query name: set required: true type: boolean UndoQueryParameter: description: | Undo a prior operation. in: query name: undo required: false type: boolean responses: respErr400BadRequest: description: Bad request. One or more request fields is either missing or incorrect. Details are in the error response. schema: $ref: "#/definitions/ErrorObject" respErr401Unauthorized: 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) schema: $ref: "#/definitions/ErrorObject" respErr404CannotReturnResponse: 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. schema: $ref: "#/definitions/ErrorObject" respErr405NotAllowed: 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. schema: $ref: "#/definitions/ErrorObject" respErr415UnsupportedMediaType: description: For requests with payloads, an unsupported Content-Type was specified. The Frankie Financial API only supports a content type of application/json. schema: $ref: "#/definitions/ErrorObject" respErr422Unprocessable: 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 utility comparison, or similar industry/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. schema: $ref: "#/definitions/ErrorObject" respErr429TooManyRequests: description: The API client is making too many concurrent requests, and some are being throttled. Throttled requests can be retried after a short delay. schema: $ref: "#/definitions/ErrorObject" respErr500UnexpectedError: description: Unexpected error. Something went wrong during the checking process. schema: $ref: "#/definitions/ErrorObject" respErr503NoSourcesAvailable: description: All of the ID sources configured by the customer are unavailable, or there is no available document processor. schema: $ref: "#/definitions/ErrorObject" respOk200AcceptedOwnershipQuery: description: | !!!! This response will never be sent synchronously !!!! This is what you will find in the payload of a retrieved response should the ownership query succeed. schema: $ref: "#/definitions/OrganisationCheckResponseObject" respOk200RetrieveResponse: 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. schema: $ref: "#/definitions/RetrievedResponseObject" respOk200SuccessBusinessReportsResponse: description: The request was valid and was successfully processed. The report was run and the results have been attached. schema: $ref: "#/definitions/BusinessReportResponseDetails" respOk200SuccessCheckEntity: 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. schema: $ref: "#/definitions/CheckEntityCheckResultObject" respOk200SuccessDocument: 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 document object as it stands now. No docScan file data will be returned unless the /full variant is requested. schema: $ref: "#/definitions/DocumentResultObject" respOk200SuccessDocumentChecks: 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 results of all checks carried out upon this document. schema: $ref: "#/definitions/DocumentChecksResultObject" respOk200SuccessDocumentCompare: 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 results of the document comparison process. schema: $ref: "#/definitions/DocumentCompareResultObject" respOk200SuccessDocumentDelete: description: | The request was valid and able to be processed in some fashion. Returns a simple status to indicate that the deletion has taken place. schema: $ref: "#/definitions/BasicStatusResultObject" respOk200SuccessDocumentScan: 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 results of the document scanning process. schema: $ref: "#/definitions/DocumentScanResultObject" respOk200SuccessDocumentSearch: description: | The request was valid and able to be processed in some fashion. Returns a list of potentially matching documents or document references, along with a confidence level in the match. schema: $ref: "#/definitions/DocumentSearchResultObject" respOk200SuccessDocumentVerify: 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 results of the document verification process. schema: $ref: "#/definitions/DocumentVerifyResultObject" respOk200SuccessEntity: 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. schema: $ref: "#/definitions/EntityResultObject" respOk200SuccessEntityDelete: description: | The request was valid and able to be processed in some fashion. Returns a simple status to indicate that the deletion has taken place. schema: $ref: "#/definitions/BasicStatusResultObject" respOk200SuccessEntityIDV: 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. Also returned is the applicantId and token to be in the IDV process. schema: $ref: "#/definitions/EntityIDVResultObject" respOk200SuccessEntitySearch: description: | 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. schema: $ref: "#/definitions/EntitySearchResultObject" respOk200SuccessIndustryUtilityConsent: 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 results directly from the service provider. Returns the results of the provision of explicit informed consent directly from the service provider. schema: $ref: "#/definitions/DocumentIndustryUtilityConsentResultObject" respOk200SuccessIndustryUtilityDocument: 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 results of the utility comparison directly from the service provider. schema: $ref: "#/definitions/DocumentIndustryUtilityProcessResultObject" respOk200SuccessIndustryUtilitySwitch: 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 results directly from the service provider. Returns the results of the utility switch over directly from the service provider. schema: $ref: "#/definitions/DocumentIndustryUtilitySwitchResultObject" respOk200SuccessInternationalBusinessProfileResponse: description: The request was valid and was successfully processed. The search has been carried out and the results are attached. schema: $ref: "#/definitions/InternationalBusinessProfileResponse" respOk200SuccessInternationalBusinessSearchResponse: description: The request was valid and was successfully processed. The search has been carried out and the results are attached. schema: $ref: "#/definitions/InternationalBusinessSearchResponse" respOk202AcceptedCheckOrganisation: 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. schema: $ref: "#/definitions/AcceptedEntityResultObject" respOk202AcceptedDocument: 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. schema: $ref: "#/definitions/AcceptedDocumentResultObject" respOk202AcceptedEntity: 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. schema: $ref: "#/definitions/AcceptedEntityResultObject" respOk202AcceptedOwnershipQuery: 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. schema: $ref: "#/definitions/AcceptedEntityResultObject" respSystem200OK: description: The system is fine. No issues, and everyone gets a puppy. But only if a Customer ID is supplied, otherwise, no puppy for you. Also, try asking nicely. schema: $ref: "#/definitions/PuppyObject" respSystem500NotGood: description: The system is presently unavailable, or running in a severely degraded state. Check the error message for details schema: $ref: "#/definitions/ErrorObject" 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: Industry-specific operations on documents and entities. name: Industry - 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: /business/international/profile: post: description: | Using the Company Code retrieved from the search response (see above) you can pull back the details of the company. The Frankie platform will save the details of the response as an ORGANISATION type entity with the profile attached as a report which you can potentially re-retrieve later if you wish. operationId: InternationalBusinessProfile parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - description: | The country, cxompany code and optional registry of the organisation to be queried. in: body name: organisation required: true schema: $ref: "#/definitions/InternationalBusinessProfileCriteria" responses: "200": $ref: "#/responses/respOk200SuccessInternationalBusinessProfileResponse" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "405": $ref: "#/responses/respErr405NotAllowed" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" "503": $ref: "#/responses/respErr503NoSourcesAvailable" summary: Retrieve a business profile from any country (AUS included). tags: - Business /business/international/search: post: description: | Search for a given business name or business number across international business registers. The search will return a list of matching companies that you can then potentially query using the international profile query (see below). Each search result will have a CompanyCode that you use to retrieve the specific company details using the profile function. This process will not save any details from the search results. operationId: InternationalBusinessSearch parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - description: | The country, name or business number of the organisation to be queried. in: body name: organisation required: true schema: $ref: "#/definitions/InternationalBusinessSearchCriteria" responses: "200": $ref: "#/responses/respOk200SuccessInternationalBusinessSearchResponse" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "405": $ref: "#/responses/respErr405NotAllowed" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" "503": $ref: "#/responses/respErr503NoSourcesAvailable" summary: Search for a business from any country (AUS included). tags: - Business /business/ownership/query: post: description: | Process a request for ownership details for an Australian organisation. See below for more generic international queries. At a minimum, you just need to supply an ACN or ABN and we can retrieve the rest. You also have the option of supplying company name, type (as per ABR types) and both ABN/ACN and we'll attempt to verfy that that data matches what is on record before attempting any further verification and validation. KYC/AML for a selection of entities associated with an organisation and/or the organisation itself can optionally be run, but not by default. To enable KYC/AML checks one or more entity categories must be provided. If such a list of entity categories is given then default checks based on configuration will be run for those categories. If a check type is also provided in the request then that type will be used for entities representing individual entities, and the AML subset of that check will be used for organisations if any. Specifying a check type without an entity category will result in an error. NOTE: This query will always run asynchronously and you will only ever be returned a 202 ACCEPT response, or an error. Results will be pushed using the Push Notification API below and you will be able to retrieve the results using the Retrieve API. We have supplied the 200 response in the definition below only so what will be sent to you when you later retrieve the details. More details on how to use this API and interpret the results can be found here: https://apidocs.frankiefinancial.com/docs/which-function-to-use operationId: BusinessOwnershipQuery parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/BusinessCheckTypeQueryParameter" - $ref: "#/parameters/BusinessEntityCategoriesQueryParameter" - $ref: "#/parameters/BusinessCheckResultLevelQueryParameter" - $ref: "#/parameters/BusinessValidationParameter" - $ref: "#/parameters/BusinessGenerateReportQueryParameter" - $ref: "#/parameters/BusinessIncludeHistoricalQueryParameter" - $ref: "#/parameters/BusinessOnlyProfileQueryParameter" - description: | The organisation to be queried. An entity object that must have an organisation object with at least one organisation number. in: body name: query required: true schema: $ref: "#/definitions/OwnershipQuery" responses: "200": $ref: "#/responses/respOk200AcceptedOwnershipQuery" "202": $ref: "#/responses/respOk202AcceptedOwnershipQuery" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "405": $ref: "#/responses/respErr405NotAllowed" "422": $ref: "#/responses/respErr422Unprocessable" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" "503": $ref: "#/responses/respErr503NoSourcesAvailable" summary: Create Business Entity and Query UBO (AUS Only) tags: - Business /business/reports: post: description: | NOTE: Australian companies ONLY. Create or find and update an ORGANISATION type entity, then run the requested reports. Reports include: - Credit Report - Credit Score At a minimum, you just need to supply an ACN and/or ABN and an entity type set to ORGANISATION. Alternatively the entity ID of an existing ORGANISATION entity gan be given in the request body Note: these reports are different to the Ultimate Beneficial Owner and Business Detail requests - these reports are independent data and analysis over and above company information and verification details. You can request multiple reports to be run at once and they will be returned as a group (where feasible). If a report can only be generated over time, then a temporary response will be returned and a webhook notification will be pushed later once the report has been completed. operationId: RunBusinessReports parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/BusinessReportTypesQueryParameter" - description: | The organisation to be queried. An entity object that must have be an ORGANISATION type with at least one organisation number (ABN or ACN). in: body name: organisation required: true schema: $ref: "#/definitions/EntityObject" responses: "200": $ref: "#/responses/respOk200SuccessBusinessReportsResponse" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "405": $ref: "#/responses/respErr405NotAllowed" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" "503": $ref: "#/responses/respErr503NoSourcesAvailable" summary: Run Report(s) against a new or existing organisation entity (AUS Only). tags: - Business "/business/{entityId}/verify": post: description: | Run KYC/AML for a selection of entities associated with an organisation and/or the organisation itself based on a previous ownership query. By default AML will be checked for just the organisation itself. If a list of entity categories is given then default checks based on configuration will be run for those categories. If a check type is also provided in the request then that type will be used for entities representing individual entities, and the AML subset of that check will be used for organisations if any. If no ownership query has been run, then this operation will return an error. operationId: CheckOrganisation parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/EntityIDPathParameter" - $ref: "#/parameters/BusinessCheckTypeQueryParameter" - $ref: "#/parameters/BusinessEntityCategoriesQueryParameter" - $ref: "#/parameters/BusinessCheckResultLevelQueryParameter" - $ref: "#/parameters/BusinessGenerateReportQueryParameter" responses: "202": $ref: "#/responses/respOk202AcceptedCheckOrganisation" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "405": $ref: "#/responses/respErr405NotAllowed" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" "503": $ref: "#/responses/respErr503NoSourcesAvailable" summary: Run KYC/AML Checks on Organisation and/or Associated Individuals. tags: - Business /document: post: description: | Create a document object. A document object can be used to simply store data around a given identity or similar document. You can attach scans, PDFs, photos, videos, etc to the objectif you wish and these may be processed later (using the /scan function) to extract useful information. Or you can manually supply the extracted information if you choose. Document objects can be used to create an entity, based on extracted or supplied data; or it may be attached to an existing entity, either directly or through an ID check. operationId: CreateDocument parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - in: body name: document schema: $ref: "#/definitions/IdentityDocumentObject" responses: "200": $ref: "#/responses/respOk200SuccessDocument" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "415": $ref: "#/responses/respErr415UnsupportedMediaType" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" summary: Create New Document. tags: - Document /document/new/compare: post: description: | Creates a new document from the "toDocument" parameter (usual rules apply in that it must be a valid document, with no existing documentId). The compareDocument can be an existing documentId, or it too can be new as well. * If existing (i.e. a valid DocumentId is supplied), it will be updated with any new data supplied before being sent to the comparison process. * If new, then a new document will be created too, and the ID returned in the result. The document scans are then sent for processing and comparison, such as comparing a selfie-video against a drivers licence photo. * NOTE: This is NOT the verification process (see /document/verify) * NOTE: This is NOT the OCR data extraction process either (see /document/scan) operationId: CompareDocument parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/BackgroundHeader" - description: | Contains the document (compareDocument) we want to compare (toDocument) in: body name: ComparisonSet required: true schema: $ref: "#/definitions/ComparisonSet" responses: "200": $ref: "#/responses/respOk200SuccessDocumentCompare" "202": $ref: "#/responses/respOk202AcceptedDocument" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "405": $ref: "#/responses/respErr405NotAllowed" "415": $ref: "#/responses/respErr415UnsupportedMediaType" "422": $ref: "#/responses/respErr422Unprocessable" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" "503": $ref: "#/responses/respErr503NoSourcesAvailable" summary: Create Document and Compare to Original. tags: - Document /document/new/scan: post: description: | Create a document object. This is then processed to extract useful information and create an entity; or it may be attached to an entity, either directly or through an ID check. The service will attempt to extract relevant data from any/all uploaded images/documents and will place those in the extraData KVP block. operationId: CreateScanDocument parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/BackgroundHeader" - in: body name: document schema: $ref: "#/definitions/IdentityDocumentObject" responses: "200": $ref: "#/responses/respOk200SuccessDocumentScan" "202": $ref: "#/responses/respOk202AcceptedDocument" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "415": $ref: "#/responses/respErr415UnsupportedMediaType" "422": $ref: "#/responses/respErr422Unprocessable" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" summary: Create and OCR Scan Document. tags: - Document /document/new/utility/process/compare: post: description: | Create a document object. This is then processed to extract useful information, just like a normal OCR scan. The service will then push the document through an industry specific comparison process, where the details are used to find a better plan, based on the bill. 100's of datapoints are accurately extracted from the uploaded document. This data is then used to compare the bill against the whole market. A personalised comparison is returned that is a best fit for the customer's energy profile. * NOTE: It is expected that the type of document being uploaded will be a PDF and the idType is UTILITY_BILL. (These values will be set automatically if not supplied). You can optionally include the utility name (e.g. Origin Energy) in the idSubType if you wish. operationId: CreateProcessIndustryUtilityDocument parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/BackgroundHeader" - $ref: "#/parameters/PlanLimitQueryParameter" - in: body name: document schema: $ref: "#/definitions/IdentityDocumentObject" responses: "200": $ref: "#/responses/respOk200SuccessIndustryUtilityDocument" "202": $ref: "#/responses/respOk202AcceptedDocument" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "415": $ref: "#/responses/respErr415UnsupportedMediaType" "422": $ref: "#/responses/respErr422Unprocessable" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" summary: Create Document and Run Utility Price Comparison. tags: - Industry /document/new/verify: post: description: | Send the document to an external service to have the detailed verified. For example, we could send through the details of a drivers licence to be checked against a national database. * NOTE: This is NOT the OCR data extraction process (see /document/scan) * NOTE: This is NOT the comparison process (see /document/compare) operationId: VerifyDocument parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/BackgroundHeader" - description: | The document and (possibly) its associated scans to be verified. There is also an entity object (normally stripped back to it's bare minimum) that can be used to provide supporting data, such as name, address, etc. The entity object may be empty/ in: body name: processDocument required: true schema: $ref: "#/definitions/DocumentVerify" responses: "200": $ref: "#/responses/respOk200SuccessDocumentVerify" "202": $ref: "#/responses/respOk202AcceptedDocument" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "405": $ref: "#/responses/respErr405NotAllowed" "415": $ref: "#/responses/respErr415UnsupportedMediaType" "422": $ref: "#/responses/respErr422Unprocessable" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" "503": $ref: "#/responses/respErr503NoSourcesAvailable" summary: Create and Verify Document. tags: - Document /document/search: post: description: | Search for an existing document that matches the criteria supplied There are of course limits to what can be searched upon. For a document search to work, you must supply at a minimum: * idType * country * idNumber The service will return a list of matching documents with confidence levels. If you are the "owner" of the document - i.e. the same CustomerID and CustomerChildID (if relevant) - then the full details of the document will be returned, except for the contents of any attached scans. If you are not the owner of the document, then just the ID and confidence level is returned. You can still use this ID to retrieve any check results (see GET /document/{documentId}/checks) Note: At this time, we cannot perform searches on document scans. But, you can supply extraData KVPs if they're known. These will help doublecheck search results with ambiguous results. operationId: SearchDocument parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - description: | A document object with the parameters you wish to search on. in: body name: searchDocument required: true schema: $ref: "#/definitions/IdentityDocumentObject" responses: "200": $ref: "#/responses/respOk200SuccessDocumentSearch" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "405": $ref: "#/responses/respErr405NotAllowed" "415": $ref: "#/responses/respErr415UnsupportedMediaType" "422": $ref: "#/responses/respErr422Unprocessable" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" "503": $ref: "#/responses/respErr503NoSourcesAvailable" summary: Search For a Document !! EXPERIMENTAL !! tags: - Document "/document/{documentId}": delete: description: | Mark this document as deleted. It will then become effectively invisible to all queries, but will be available in anonymised form for a past check. operationId: DeleteDocument parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/BackgroundHeader" - $ref: "#/parameters/DocumentIDPathParameter" responses: "200": $ref: "#/responses/respOk200SuccessDocumentDelete" "202": $ref: "#/responses/respOk202AcceptedDocument" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" summary: Delete Document. tags: - Document get: description: | Query the current status and details of a given documentId. operationId: QueryDocument parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/DocumentIDPathParameter" responses: "200": $ref: "#/responses/respOk200SuccessDocument" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" summary: Retrieve Document Details tags: - Document post: description: | Using a previously uploaded but incomplete document, you can optionally supply updated details (such as corrections on a previous scan), along with one or more additional ID scans (e.g. additional pages). operationId: UpdateDocument parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/BackgroundHeader" - $ref: "#/parameters/DocumentIDPathParameter" - $ref: "#/parameters/NoInvalidateQueryParameter" - description: The document to be updated in: body name: document required: true schema: $ref: "#/definitions/IdentityDocumentObject" responses: "200": $ref: "#/responses/respOk200SuccessDocument" "202": $ref: "#/responses/respOk202AcceptedDocument" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "405": $ref: "#/responses/respErr405NotAllowed" "415": $ref: "#/responses/respErr415UnsupportedMediaType" "422": $ref: "#/responses/respErr422Unprocessable" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" "503": $ref: "#/responses/respErr503NoSourcesAvailable" summary: Update Existing Document. tags: - Document "/document/{documentId}/checks": get: description: | Get the complete list of all checks that have been performed upon a given document, including the checks that have been performed by others (in those cases you just get the id, status and date run, none of the details). operationId: QueryDocumentChecks parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/BackgroundHeader" - $ref: "#/parameters/DocumentIDPathParameter" responses: "200": $ref: "#/responses/respOk200SuccessDocumentChecks" "202": $ref: "#/responses/respOk202AcceptedDocument" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "405": $ref: "#/responses/respErr405NotAllowed" "422": $ref: "#/responses/respErr422Unprocessable" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" summary: | Retrieve Document Verification Check Details. tags: - Document "/document/{documentId}/compare": post: description: | Send the attached document scans to an external service for processing and comparison, such as comparing a selfie-video against a drivers licence photo. * NOTE: This is NOT the verification process (see /document/verify) * NOTE: This is NOT the OCR data extraction process either (see /document/scan) operationId: UpdateCompareDocument parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/BackgroundHeader" - $ref: "#/parameters/DocumentIDPathParameter" - description: | Contains the document (compareDocument) we want to compare (toDocument). In this case, the toDocument should be left blank, and is assumed to be "this" document in: body name: ComparisonSet required: true schema: $ref: "#/definitions/ComparisonSet" responses: "200": $ref: "#/responses/respOk200SuccessDocumentCompare" "202": $ref: "#/responses/respOk202AcceptedDocument" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "405": $ref: "#/responses/respErr405NotAllowed" "415": $ref: "#/responses/respErr415UnsupportedMediaType" "422": $ref: "#/responses/respErr422Unprocessable" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" "503": $ref: "#/responses/respErr503NoSourcesAvailable" summary: Update Document and Compare to Original. tags: - Document "/document/{documentId}/full": get: description: | Query the current status and details of a given documentId. Also returns all document file data, not just the metadata. operationId: QueryDocumentFull parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/DocumentIDPathParameter" responses: "200": $ref: "#/responses/respOk200SuccessDocument" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" summary: Retrieve Document and Scan Data tags: - Document "/document/{documentId}/scan": post: description: | Using a previously uploaded but potentially incomplete document, you can optionally supply updated details (such as corrections on a previous scan), along with one or more additional ID scans (e.g. additional pages). Includes a follow-on action as well initiating OCR processing proceedures immediately. The service will attempt to extract relevant data from any/all uploaded images/documents and will place those in the extraData KVP block. operationId: UpdateScanDocument parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/BackgroundHeader" - $ref: "#/parameters/DocumentIDPathParameter" - description: | The entity to be optionally updated, then processed. If updating a document, you only need to populate the fields you're actually adding/updating. in: body name: document required: true schema: $ref: "#/definitions/IdentityDocumentObject" responses: "200": $ref: "#/responses/respOk200SuccessDocumentScan" "202": $ref: "#/responses/respOk202AcceptedDocument" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "405": $ref: "#/responses/respErr405NotAllowed" "415": $ref: "#/responses/respErr415UnsupportedMediaType" "422": $ref: "#/responses/respErr422Unprocessable" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" "503": $ref: "#/responses/respErr503NoSourcesAvailable" summary: Update and OCR Scan Document tags: - Document "/document/{documentId}/utility/process/compare": post: description: | Using a previously uploaded but incomplete document, you can optionally supply updated details or simply request that the document be re-processed through the industry comparison service. 100's of datapoints are accurately extracted from the uploaded document. This data is then used to compare the bill against the whole market. A personalised comparison is returned that is a best fit for the customer's energy profile. * NOTE: It is expected that the type of document being uploaded will be a PDF and the idType is UTILITY_BILL. (These values will be set automatically if not supplied). You can optionally include the utility name (e.g. Origin Energy) in the idSubType if you wish. operationId: UpdateProcessIndustryUtilityDocument parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/BackgroundHeader" - $ref: "#/parameters/DocumentIDPathParameter" - $ref: "#/parameters/PlanLimitQueryParameter" - in: body name: document schema: $ref: "#/definitions/IdentityDocumentObject" responses: "200": $ref: "#/responses/respOk200SuccessIndustryUtilityDocument" "202": $ref: "#/responses/respOk202AcceptedDocument" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "415": $ref: "#/responses/respErr415UnsupportedMediaType" "422": $ref: "#/responses/respErr422Unprocessable" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" summary: Update Document and Run Utility Price Comparison. tags: - Industry "/document/{documentId}/utility/process/consent": post: description: | Using a previously uploaded and processed document, the user must provide explicit consent before being able to call the /switch function. Before entering into a contract with a new energy retailer, consumers are first obliged to review the retailer's contractual terms and conditions, confirm they understand these terms as well as give explicit, informed consent (EIC) for the switch to occur. This API call retrieves all information that must be displayed in order for a compliant EIC to be captured from a consumer. * NOTE: as part of this call, you must provide a previously returned corellationId that is associated with this document and the returned plan options. Failure to do so will result in an error response. operationId: UpdateProcessIndustryUtilityDocumentConsent parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/BackgroundHeader" - $ref: "#/parameters/DocumentIDPathParameter" - in: body name: consentRequest schema: $ref: "#/definitions/EICRequest" responses: "200": $ref: "#/responses/respOk200SuccessIndustryUtilityConsent" "202": $ref: "#/responses/respOk202AcceptedDocument" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "415": $ref: "#/responses/respErr415UnsupportedMediaType" "422": $ref: "#/responses/respErr422Unprocessable" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" summary: Provide Explicit Consent to Switch Utility Plans. tags: - Industry "/document/{documentId}/utility/process/switch": post: description: | Using a previously uploaded and processed document, the user must provide explicit consent before being able to call the /switch function. The bill payer has uploaded their current bill, selected a new plan, accepted the terms and conditions and given their consent for the switch to occur. This API call will finalise the switch request and send all the customers data along with the requested plan to the selected retailer. * NOTE: as part of this call, you must provide a previously returned corellationId that is associated with this document and the returned plan options. Failure to do so will result in an error response. operationId: UpdateProcessIndustryUtilityDocumentSwitch parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/BackgroundHeader" - $ref: "#/parameters/DocumentIDPathParameter" - in: body name: switchRequest schema: $ref: "#/definitions/SwitchRequest" responses: "200": $ref: "#/responses/respOk200SuccessIndustryUtilitySwitch" "202": $ref: "#/responses/respOk202AcceptedDocument" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "415": $ref: "#/responses/respErr415UnsupportedMediaType" "422": $ref: "#/responses/respErr422Unprocessable" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" summary: Initiate Switching of Utility Plan. tags: - Industry "/document/{documentId}/verify": post: description: | Using a previously uploaded but potentially incomplete document, you can optionally supply updated details (such as corrections on a previous scan), along with one or more additional ID scans (e.g. additional pages). Includes a follow-on action as well initiating verification proceedures immediately. Sends the updated document to an external service to have the detailed verified. For example, we could send through the details of a drivers licence to be checked against a national database. * NOTE: This is NOT the OCR data extraction process (see /document/scan) * NOTE: This is NOT the comparison process (see /document/compare) operationId: UpdateVerifyDocument parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/BackgroundHeader" - $ref: "#/parameters/DocumentIDPathParameter" - description: | The document and (possibly) its associated scans to be verified. There is also an optional entity object (normally stripped back to it's bare minimum) that can be used to provide supporting data, such as name, address, etc. The entity object may be empty, and is not processed or stored in any way. in: body name: processDocument required: true schema: $ref: "#/definitions/DocumentVerify" responses: "200": $ref: "#/responses/respOk200SuccessDocumentVerify" "202": $ref: "#/responses/respOk202AcceptedDocument" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "405": $ref: "#/responses/respErr405NotAllowed" "415": $ref: "#/responses/respErr415UnsupportedMediaType" "422": $ref: "#/responses/respErr422Unprocessable" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" "503": $ref: "#/responses/respErr503NoSourcesAvailable" summary: Update and Verify Document. tags: - Document /entity: post: 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 and these may be processed later (using the /scan function) to extract useful information. Or you can manually supply the information if you choose. Entity objects can be used to run a check, using the data held in the records. operationId: CreateEntity parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - in: body name: entity schema: $ref: "#/definitions/EntityObject" responses: "200": $ref: "#/responses/respOk200SuccessEntity" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "415": $ref: "#/responses/respErr415UnsupportedMediaType" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" summary: Create New Entity. tags: - Entity /entity/new/idvalidate/getToken: post: description: | Create an entity object and if successful, obtain a token for use in an ID Validation service SDK (web or native app) At a minimum, you will need to supply: - the entity familyName. - the entity givenName For best results, you should gather the DoB, address, ID document details as well before calling the initProcess function. SPECIAL NOTE 1: Tokens have a limited lifespan, typically only 1 hour. Make sure you've used it or you will need to create another using update version of this function. SPECIAL NOTE 2: This function will need to be followed up with a call to /entity/{id}/idvalidate/initProcess once you've collected all your data in your app/web capture process. operationId: CreateEntityGetIDVToken parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - description: The entity and required data to generate an IDV token in: body name: entityIDVDetails required: true schema: $ref: "#/definitions/EntityIDVDetailsObject" responses: "200": $ref: "#/responses/respOk200SuccessEntityIDV" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "405": $ref: "#/responses/respErr405NotAllowed" "415": $ref: "#/responses/respErr415UnsupportedMediaType" "422": $ref: "#/responses/respErr422Unprocessable" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" "503": $ref: "#/responses/respErr503NoSourcesAvailable" summary: Create Entity and Get IDV Token tags: - Entity /entity/new/verify/pushToMobile: post: description: | Create an entity object and begin the process of verification after pushing a message to a mobile number. The entity will receive a link on their mobile and will then be guided through a series of steps to capture and OCR scan their ID, and perform a selfie comparison. We'll then attempt to verify the data received and push a notification back to the calling customer. At a minimum, you will need to supply the name and a MOBILE_PHONE document type. SPECIAL NOTE: This will only ever return a 202 response if successfully accepted. You will need to ensure your account is configured for push notifications. Contact developer supprt to arrange this. operationId: CreateCheckEntityPushToMobile parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/BackgroundHeader" - $ref: "#/parameters/NoPushQueryParameter" - description: The entity and any associated / additional information to be checked in: body name: entityDetails required: true schema: $ref: "#/definitions/EntityCheckDetailsObject" responses: "202": $ref: "#/responses/respOk202AcceptedEntity" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "405": $ref: "#/responses/respErr405NotAllowed" "415": $ref: "#/responses/respErr415UnsupportedMediaType" "422": $ref: "#/responses/respErr422Unprocessable" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" "503": $ref: "#/responses/respErr503NoSourcesAvailable" summary: Create Entity and Push Self-Verification Link tags: - Entity "/entity/new/verify/{checkType}/{resultLevel}": post: 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 and these may be processed later (using the /scan function) to extract useful information. Or you can manually supply the information if you choose. 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: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/BackgroundHeader" - $ref: "#/parameters/CheckTypeParameter" - $ref: "#/parameters/ResultLevelPathParameter" - description: The entity and any associated / additional information to be checked in: body name: entityDetails required: true schema: $ref: "#/definitions/EntityCheckDetailsObject" responses: "200": $ref: "#/responses/respOk200SuccessCheckEntity" "202": $ref: "#/responses/respOk202AcceptedEntity" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "405": $ref: "#/responses/respErr405NotAllowed" "415": $ref: "#/responses/respErr415UnsupportedMediaType" "422": $ref: "#/responses/respErr422Unprocessable" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" "503": $ref: "#/responses/respErr503NoSourcesAvailable" summary: Create and Verify Entity tags: - Entity /entity/search: post: description: | 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) Note: This functionality must be enabled by Frankie administrators. Please contact your sales representative if you wish to discuss this. operationId: SearchEntity parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - description: | An entity object with the parameters you wish to search on. in: body name: searchEntity required: true schema: $ref: "#/definitions/EntityObject" responses: "200": $ref: "#/responses/respOk200SuccessEntitySearch" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "405": $ref: "#/responses/respErr405NotAllowed" "422": $ref: "#/responses/respErr422Unprocessable" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" "503": $ref: "#/responses/respErr503NoSourcesAvailable" summary: Search for Entity tags: - Entity "/entity/{entityId}": delete: description: | Marks the entity as deleted in the system, and no further operations or general queries may be executed against it by the Customer. If another customer is presently relying on this data, it will still be available to them (but only in the partially anonymised form they originally had. An entity and its related data is only completely deleted from the database when either: - a) There are no more references to it (i.e. it has been DELETEd by all Customers relying on the data), and 12 months have passed. - b) The actual consumer who owns the data makes a direct request. If this occurs, then all subscribing Customers will be notified that this entity has been removed and they will need to contact them if needed in order to update their own records again. operationId: DeleteEntity parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/BackgroundHeader" - $ref: "#/parameters/EntityIDPathParameter" responses: "200": $ref: "#/responses/respOk200SuccessEntityDelete" "202": $ref: "#/responses/respOk202AcceptedEntity" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" summary: Delete Entity tags: - Entity get: description: | Query the current status and details of a given entityId. operationId: QueryEntity parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/EntityIDPathParameter" responses: "200": $ref: "#/responses/respOk200SuccessEntity" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" summary: Retrieve Entity Details tags: - Entity post: description: | Using a previously uploaded but incomplete Entity, you can optionally supply updated details (such as corrections on a previous address), along with one or more additional ID docs/scans (e.g. new documents to parse, etc). operationId: UpdateEntity parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/BackgroundHeader" - $ref: "#/parameters/EntityIDPathParameter" - $ref: "#/parameters/NoInvalidateQueryParameter" - description: The entity to be updated in: body name: entity required: true schema: $ref: "#/definitions/EntityObject" responses: "200": $ref: "#/responses/respOk200SuccessEntity" "202": $ref: "#/responses/respOk202AcceptedEntity" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "405": $ref: "#/responses/respErr405NotAllowed" "415": $ref: "#/responses/respErr415UnsupportedMediaType" "422": $ref: "#/responses/respErr422Unprocessable" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" "503": $ref: "#/responses/respErr503NoSourcesAvailable" summary: Update Existing Entity. tags: - Entity "/entity/{entityId}/check/{checkId}/{checkClass}": post: description: | Internal only Update a given set of KYC and/or AML check result statuses in order to force a re-evaluation of the overall check result. operationId: UpdateCheckClassResults parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/EntityIDPathParameter" - $ref: "#/parameters/CheckIDPathParameter" - $ref: "#/parameters/CheckClassPathParameter" - description: The check result status change details to apply in: body name: checkResultUpdate required: true schema: $ref: "#/definitions/CheckResultUpdateObject" responses: "200": $ref: "#/responses/respOk200SuccessCheckEntity" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "405": $ref: "#/responses/respErr405NotAllowed" "422": $ref: "#/responses/respErr422Unprocessable" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" summary: Update Check Result States (Batch) tags: - Entity "/entity/{entityId}/check/{checkId}/{checkClass}/{checkClassId}": post: description: | Internal only Update a given KYC or AML check result status in order to force a re-evaluation of the overall check result. operationId: UpdateCheckClassResult parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/EntityIDPathParameter" - $ref: "#/parameters/CheckIDPathParameter" - $ref: "#/parameters/CheckClassPathParameter" - $ref: "#/parameters/CheckClassIDPathParameter" - $ref: "#/parameters/CheckClassActionQueryParameter" - $ref: "#/parameters/UndoQueryParameter" responses: "200": $ref: "#/responses/respOk200SuccessCheckEntity" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "405": $ref: "#/responses/respErr405NotAllowed" "422": $ref: "#/responses/respErr422Unprocessable" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" summary: Update Check Result State tags: - Entity "/entity/{entityId}/checks": get: description: | Get the complete list of all checks that have been performed upon a given entity and its documents, including the checks that have been performed by others (in those cases you just get the id, status and date run, none of the details). operationId: QueryEntityChecks parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/EntityIDPathParameter" - $ref: "#/parameters/AllDataQueryParameter" responses: "200": $ref: "#/responses/respOk200SuccessCheckEntity" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" summary: | Retrieve Entity Verication Check Details tags: - Entity "/entity/{entityId}/flag/blacklist": post: description: | Mark the entity as blacklisted or not with the '?set=' query parameter as 'true' or 'false'. operationId: BlacklistEntity parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/EntityIDPathParameter" - $ref: "#/parameters/SetFlagQueryParameter" - $ref: "#/parameters/ReasonFlagQueryParameter" - $ref: "#/parameters/BlockedByQueryParameter" - $ref: "#/parameters/AttributeQueryParameter" - $ref: "#/parameters/OriginalIdQueryParameter" responses: "200": $ref: "#/responses/respOk200SuccessEntity" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" summary: Set Entity Blacklist State. tags: - Flag "/entity/{entityId}/flag/duplicate/{otherId}": post: description: | Resolve the state of a pair of duplicate entities with the '?set=' query parameter as 'true' or 'false'. Setting duplicate to 'true' will make entityId invisible for most purposes and otherId will continue to function as normal. Setting duplicate to 'false' means the two entities are in fact separate but similar and they will both continue to exist independently but will no longer be identified as duplicates of eachother. operationId: FlagDuplicateEntity parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/EntityIDPathParameter" - $ref: "#/parameters/OtherIDPathParameter" - $ref: "#/parameters/SetFlagQueryParameter" responses: "200": $ref: "#/responses/respOk200SuccessEntity" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" summary: Resolve Duplicate States. tags: - Flag "/entity/{entityId}/flag/monitor": post: description: | Mark the entity as being monitored or not with the '?set=' query parameter as 'true' or 'false'. operationId: EntityMonitoring parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/EntityIDPathParameter" - $ref: "#/parameters/SetFlagQueryParameter" responses: "200": $ref: "#/responses/respOk200SuccessEntity" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" summary: Set Entity Ongoing AML Monitoring Status. tags: - Flag "/entity/{entityId}/flag/watchlist": post: description: | Mark the entity as watchlisted or not with the '?set=' query parameter as 'true' or 'false'. operationId: WatchlistEntity parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/EntityIDPathParameter" - $ref: "#/parameters/SetFlagQueryParameter" - $ref: "#/parameters/ReasonWlFlagQueryParameter" - $ref: "#/parameters/CommentQueryParameter" responses: "200": $ref: "#/responses/respOk200SuccessEntity" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" summary: Set Entity Watchlist State. tags: - Flag "/entity/{entityId}/full": get: description: | Query the current status and details of a given entityId. Also returns all attached document file data, not just the metadata. Equivalent to a get /document/{documentId}/full) operationId: QueryEntityFull parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/EntityIDPathParameter" responses: "200": $ref: "#/responses/respOk200SuccessEntity" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" summary: | Retrieve Entity Details and Document Scan Data tags: - Entity "/entity/{entityId}/idvalidate/getToken": post: description: | Update an entity object and if successful, obtain a token for use in an ID Validation service SDK (web or native app) At a minimum, the entity will need to have a name. For best results, you should gather the DoB, address, ID document details as well before calling the initProcess function. SPECIAL NOTE 1: Tokens have a limited lifespan, typically only 1 hour. Make sure you've used it or you will need to create another using update version of this function. SPECIAL NOTE 2: This function will need to be followed up with a call to /entity/{id}/idvalidate/initProcess once you've collected all your data in your app/web capture process. operationId: UpdateEntityGetIDVToken parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/EntityIDPathParameter" - description: The entity to update and required data to generate an IDV token in: body name: entityIDVDetails required: true schema: $ref: "#/definitions/EntityIDVDetailsObject" responses: "200": $ref: "#/responses/respOk200SuccessEntityIDV" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "405": $ref: "#/responses/respErr405NotAllowed" "415": $ref: "#/responses/respErr415UnsupportedMediaType" "422": $ref: "#/responses/respErr422Unprocessable" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" "503": $ref: "#/responses/respErr503NoSourcesAvailable" summary: Update Entity and Get IDV Token tags: - Entity "/entity/{entityId}/idvalidate/initProcess": post: description: | Update an entity object and if successful, start the process of downloading the captured data and processing the reports and results of the ID validation process. At a minimum, the entity will need to have a name. For best results, you should gather the DoB, address, ID document details as well before calling this initProcess function, or supply the details as part of this update. operationId: UpdateEntityInitIDVProcess parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/EntityIDPathParameter" - description: The entity to update in: body name: entityDetails required: true schema: $ref: "#/definitions/EntityCheckDetailsObject" responses: "200": $ref: "#/responses/respOk200SuccessEntityIDV" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "405": $ref: "#/responses/respErr405NotAllowed" "415": $ref: "#/responses/respErr415UnsupportedMediaType" "422": $ref: "#/responses/respErr422Unprocessable" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" "503": $ref: "#/responses/respErr503NoSourcesAvailable" summary: Update Entity and Initiate IDV Process tags: - Entity "/entity/{entityId}/status": post: description: | Internal only Add a special internal 'entity result' to superceed any previous real checks until the next one. operationId: UpdateEntityState parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/EntityIDPathParameter" - $ref: "#/parameters/SetEntityStatusQueryParameter" - $ref: "#/parameters/EntityRiskQueryParameter" - $ref: "#/parameters/CommentQueryParameter" responses: "200": $ref: "#/responses/respOk200SuccessCheckEntity" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "405": $ref: "#/responses/respErr405NotAllowed" "422": $ref: "#/responses/respErr422Unprocessable" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" summary: Update Entity States tags: - Entity "/entity/{entityId}/verify/pushToMobile": post: description: | Update an existing entity object and begin the process of verification after pushing a message to a mobile number. The entity will receive a link on their mobile and will then be guided through a series of steps to capture and OCR scan their ID, and perform a selfie comparison. We'll then attempt to verify the data received and push a notification back to the calling customer. At a minimum, you will need to supply the name and a MOBILE_PHONE document type. If you wish to skip the detail capture and jump straight to the ID and selfie capture, the append the call with the ?phase=2 parameter. SPECIAL NOTE: This will only ever return a 202 response if successfully accepted. You will need to ensure your account is configured for push notifications. Contact developer supprt to arrange this. operationId: UpdateCheckEntityPushToMobile parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/BackgroundHeader" - $ref: "#/parameters/EntityIDPathParameter" - $ref: "#/parameters/NoPushQueryParameter" - $ref: "#/parameters/PTMPhaseQueryParameter" - description: The entity and any associated / additional information to be checked in: body name: entityDetails required: true schema: $ref: "#/definitions/EntityCheckDetailsObject" responses: "202": $ref: "#/responses/respOk202AcceptedEntity" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "405": $ref: "#/responses/respErr405NotAllowed" "415": $ref: "#/responses/respErr415UnsupportedMediaType" "422": $ref: "#/responses/respErr422Unprocessable" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" "503": $ref: "#/responses/respErr503NoSourcesAvailable" summary: Update Entity and Push Self-Verification Link tags: - Entity "/entity/{entityId}/verify/{checkType}/{resultLevel}": post: description: | Take the details and documents provided in the entity, 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 presently attached to the entity will also be verified (if requested) 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: UpdateCheckEntity parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/BackgroundHeader" - $ref: "#/parameters/EntityIDPathParameter" - $ref: "#/parameters/CheckTypeParameter" - $ref: "#/parameters/ResultLevelPathParameter" - $ref: "#/parameters/ForceFlagQueryParameter" - $ref: "#/parameters/NoInvalidateQueryParameter" - description: The entity to be checked in: body name: entityDetails required: true schema: $ref: "#/definitions/EntityCheckDetailsObject" responses: "200": $ref: "#/responses/respOk200SuccessCheckEntity" "202": $ref: "#/responses/respOk202AcceptedEntity" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "405": $ref: "#/responses/respErr405NotAllowed" "415": $ref: "#/responses/respErr415UnsupportedMediaType" "422": $ref: "#/responses/respErr422Unprocessable" "429": $ref: "#/responses/respErr429TooManyRequests" "500": $ref: "#/responses/respErr500UnexpectedError" "503": $ref: "#/responses/respErr503NoSourcesAvailable" summary: Update Entity and Verify Details tags: - Entity "/retrieve/response/{requestId}": get: description: | If you've received a notification that you previously backgrounded transaction has completed, or you wish to re-retrive a result from an earlier transaction, then you can simply request the result from our encrypted cache The response will return the original HTTP code, along with the payload that would have been returned in the original request. operationId: RetrieveResult parameters: - $ref: "#/parameters/CustomerIDHeader" - $ref: "#/parameters/CustomerChildIDHeader" - $ref: "#/parameters/RequestIDPathParameter" - $ref: "#/parameters/PayloadEncodingQueryParameter" responses: "200": $ref: "#/responses/respOk200RetrieveResponse" "400": $ref: "#/responses/respErr400BadRequest" "401": $ref: "#/responses/respErr401Unauthorized" "404": $ref: "#/responses/respErr404CannotReturnResponse" "500": $ref: "#/responses/respErr500UnexpectedError" summary: (Re)retrieve Response Result. tags: - Retrieve /ruok: get: description: Simple check to see if the service is running smoothly. operationId: StatusCheck parameters: - $ref: "#/parameters/AskingNicelyQueryParameter" responses: "200": $ref: "#/responses/respSystem200OK" "500": $ref: "#/responses/respSystem500NotGood" security: [] summary: Service Status tags: - Status "/your/configured/path/{requestId}": post: description: | Whenever you request that a transaction be put into the background, there needs to be a mechanism for notifying you that the request has been completed. This notification will push you the high-level details of the result, and you can then query the results at your leisiure. The same notification process will also be used to push alerts to your system. This means that RequestIDs may not match your records operationId: notifyResult parameters: - $ref: "#/parameters/RequestIDPathParameter" - in: body name: notifcationResult schema: $ref: "#/definitions/NotificationResultObject" responses: "200": description: The Customer has accepted the notification and we don't need to retry sending it. "400": description: The notification represents a type of notification the customer was not expecting, or can accept. No retry. "500": description: The Customer cannot accept the notification at this time. Please resend again later security: [] summary: Push Notification Payload tags: - Push Notification definitions: AMLResultSet: description: Wrapper object to contain a single set of AML check results. 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. items: $ref: "#/definitions/backgroundCheckResultObjectContainer" type: array 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. items: $ref: "#/definitions/backgroundCheckResultObjectContainer" type: array 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. items: $ref: "#/definitions/backgroundCheckResultObjectContainer" type: array 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. items: $ref: "#/definitions/backgroundCheckResultObjectContainer" type: array x-omitempty: true groupDetails: $ref: "#/definitions/backgroundCheckResultObjectContainer" type: object AMLScreeningResult: description: | The results of any AML/Adverse media screening undertaken properties: check_result: description: The overall result enum: - NOT_SCREENED - CLEAR - POSSIBLE_HIT type: string media_hit_count: description: The number of adverse media hits. example: 0 type: integer type: object AcceptedDocumentResultObject: 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. 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). format: uuid type: string 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. example: 84a9a860-68ae-4d7d-9a53-54a1116d5051 format: uuid type: string function: description: | Short description of the function called. type: string requestId: $ref: "#/definitions/RequestIDObject" type: object 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. 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). format: uuid type: string 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. example: 84a9a860-68ae-4d7d-9a53-54a1116d5051 format: uuid type: string 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: "#/definitions/RequestIDObject" type: object ActivityDTO: properties: Code: type: string Description: type: string type: object ActivityDeclarationDTO: properties: Declaration: type: string DeclarationDescription: type: string Language: type: string type: object 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. properties: address: $ref: "#/definitions/AddressObject" checkResult: $ref: "#/definitions/generalCheckResultArray" type: object AddressDTO: properties: AddressInOneLine: type: string AddressLine1: type: string AddressLine2: type: string AddressLine3: type: string AddressLine4: type: string AddressLine5: type: string CityTown: type: string Country: type: string Email: type: string FaxNumber: type: string Line: $ref: "#/definitions/ArrayOfAddressLineDTO" Postcode: type: string RegionState: type: string TelephoneNumber: type: string Type: type: string TypeCode: type: string WebsiteUrl: type: string type: object AddressLineDTO: properties: Line: type: string Type: type: string TypeCode: type: string type: object AddressObject: 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. format: uuid type: string addressType: $ref: "#/definitions/enumAddressType" buildingName: description: The name of the building, apartment block, condo, etc example: Tower of Babel type: string 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 example: TST type: string endDate: description: | The date this address was no longer used (if available). Used mostly with business addresses. format: date type: string 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. example: 42a Test Eagle Road, Testville, TST 123-TST, Testalia type: string postalCode: description: The post code of the address. example: 123-TST type: string region: description: The county, province, cantonment example: Test County type: string startDate: description: | The date this address first because active. Used mostly with business addresses. format: date type: string state: description: The state. Use local abbreviations, such as VIC(toria) or TX (Texas) example: TS type: string 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://apidocs.frankiefinancial.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. example: Test Eagle West type: string streetNumber: description: | The number on the street. Generally a number, but can also be alphanumeric (e.g. 3A) example: 42a type: string streetType: description: The street "type" - e.g. Road, St, Ave, Circuit, etc example: Road type: string 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. example: Testburb type: string town: description: The town/village/suburb/city example: Testville type: string unitNumber: description: Unit/Apartment/Flat/Suite/etc number example: Suite 1006 type: string required: - country type: object ArrayOfActivityDTO: properties: ActivityDTO: items: $ref: "#/definitions/ActivityDTO" type: array type: object ArrayOfActivityDeclarationDTO: properties: ActivityDeclarationDTO: items: $ref: "#/definitions/ActivityDeclarationDTO" type: array type: object ArrayOfAddressDTO: properties: Addresses: items: $ref: "#/definitions/AddressDTO" type: array type: object ArrayOfAddressLineDTO: properties: AddressLineDTO: items: $ref: "#/definitions/AddressLineDTO" type: array type: object ArrayOfCapitalDTO: properties: CapitalDTO: items: $ref: "#/definitions/CapitalDTO" type: array type: object ArrayOfCompanyDTO: properties: CompanyDTO: items: $ref: "#/definitions/CompanyDTO" type: array type: object ArrayOfDirector: properties: Director: items: $ref: "#/definitions/Director" type: array type: object ArrayOfDirectorship: properties: Directorship: items: $ref: "#/definitions/Directorship" type: array type: object ArrayOfPSCDetails: properties: PSCDetails: items: $ref: "#/definitions/PSCDetails" type: array type: object ArrayOfShareholderDetails: properties: ShareholderDetails: items: $ref: "#/definitions/ShareholderDetails" type: array type: object ArrayOfString: properties: AddressLine: items: type: string type: array type: object ArrayOfString1: properties: AddressLine: items: type: string type: array type: object ArrayOfUSOfficerDTO: properties: USOfficerDTO: items: $ref: "#/definitions/USOfficerDTO" type: array type: object BasicStatusResultObject: properties: requestId: $ref: "#/definitions/RequestIDObject" statusMsg: description: | Simple message describing the final status of the process. Only to be used in success case responses. Otherwise, use the ErrorObject. example: Thingy has been successfully processed. type: string required: - requestId - statusMsg type: object BeneficialOwnerObject: properties: entityId: description: | The entityId of the owner. format: uuid type: string percentageHeld: properties: beneficially: type: number jointly: type: number nonBeneficially: type: number total: type: number type: object type: object Benefits: description: Plan benefits to be displayed to customer properties: discounts: description: Discounts available for this plan items: properties: condition: description: Conditions applied to discount example: Discount applies to GST exclusive usage and supply charges, and not to fees and other charges such as late payment fees or Greenpower. type: string name: description: Name of the discount. example: Guaranteed discount on total bill(usage and supply) type: string value: description: Value of the discount. This can either be a dollar amount (starting with $) or a percentage (ending with %) example: 13% type: string type: object type: array incentives: description: Inventives available for this plan items: properties: name: description: Name of the incentive example: $50 Welcome credit (GST incl) type: string value: description: Description of incentive example: We'll provide the welcome credit for each new supply address you sign up via www.accurassi.com, as an offset against the charges on your first electricity bill (excluding a final bill). Terms and conditions apply. type: string type: object type: array name: description: Name of this section when rendering example: Benefits type: string required: - name - discounts - incentives type: object BusinessDetails: description: | The details of the company being checked properties: ABN: type: string ACN: type: string ARBN: type: string anzsic_code: type: string asic_company_type: type: string business_names: items: type: string type: array date_registered_with_asic: format: date type: string entity_id: description: | Frankie's unique identifier for the business. Uses a non-versioned UUID format example: 84a9a860-68ae-4d7d-9a53-54a1116d5051 format: uuid type: string giin: type: string place_of_business: $ref: "#/definitions/AddressObject" public_company: type: boolean registered_name: type: string registered_office: $ref: "#/definitions/AddressObject" regulatory_information: $ref: "#/definitions/RegulatoryInformation" state_registered_with_asic: type: string stock_exchange_data: $ref: "#/definitions/StockExchangeData" trading_names: items: type: string type: array required: - registered_name - ABN - ACN - ARBN - giin - anzsic_code type: object BusinessReportDetailsObject: description: | The metadata details of the report generated . properties: reportDateTime: description: | The ISO UTC date and time the report was generated format: date-time type: string reportId: description: If the report provider generated an ID or recipt number for the report, it goes here type: string reportName: description: The name of the requested report type: string reportProvider: description: | The name of the service provider that generated the report. type: string reportRun: description: | Whether the report was successfully run or not type: boolean reportStatus: description: | Any details of what is happening with the report of not run. Will be one of: - OK (the report was run) - LATER (the report will be sent later as a response notification) - An error message as to why the report did not work type: string type: object BusinessReportResponseDetails: description: | Results of the entity create or update along with the results of the requested reports. properties: checkId: description: | Unique identifier for the report operation. format: uuid type: string entity: $ref: "#/definitions/EntityObject" description: The entity after it has been added/updated in the service reports: description: | The collection of requested business reports. items: $ref: "#/definitions/BusinessReportResponseObject" type: array requestId: $ref: "#/definitions/RequestIDObject" type: object BusinessReportResponseObject: description: | Container to hold the details of a report response The actual report object will depend on the requested report. properties: details: $ref: "#/definitions/BusinessReportDetailsObject" report: description: | The requested report object. This will be one of: - ReportCreditScore - ReportCreditReport type: object x-omitempty: true type: object BusinessReportResultObject: description: | The positive result of a report generation request if any. properties: documentId: format: uuid type: string location: format: uri type: string scanDocId: format: uuid type: string type: object CapitalDTO: properties: Ammount: type: string Currency: type: string Type: type: string TypeCode: type: string type: object CapitalReserves: properties: capitalreserves: type: string networth: type: string paidupequity: type: string profitlossreserve: type: string reserves: type: string revalutationreserve: type: string shareholderfunds: type: string sundryreserves: type: string type: object 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://apidocs.frankiefinancial.com/docs/understanding-checksummary-results 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). items: $ref: "#/definitions/ProcessResultObject" type: array x-omitempty: true checkResultsListSummaries: description: Contains a list of all checkSummary records (one for each check) items: $ref: "#/definitions/ProcessResultObject" type: array x-omitempty: true checkRisk: $ref: "#/definitions/ProcessResultObject" checkSummary: $ref: "#/definitions/ProcessResultObject" deviceCheckResults: description: | We can perform a number of device checks on an entity, such as those from ThreatMetrix and/or BioCatch. If one of these checks was incorporated into the ID check, then these will appear here. items: $ref: "#/definitions/ProcessResultObject" type: array x-omitempty: true 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). items: $ref: "#/definitions/ProcessResultObject" type: array x-omitempty: true entity: $ref: "#/definitions/EntityObject" entityProfileResult: $ref: "#/definitions/EntityProfileResultObject" entityResult: description: | This will hold all of the check results that were performed against the properties: addressesCheck: description: Collection of address objects. items: $ref: "#/definitions/AddressCheckResultObject" type: array x-omitempty: true adverseMediaCheck: description: | !!!!! DEPRECATED !!!!! Please use the multi-result AMLResultSets structure instead. Note: This single check result structure will be retired in v1.3 !!!!! 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. items: $ref: "#/definitions/backgroundCheckResultObject" type: array x-omitempty: true amlResultSets: description: | An array of Collections of PEP/Sanctions/WL/Media objects, as AML providers can return multiple results items: $ref: "#/definitions/AMLResultSet" type: array x-omitempty: true dateOfBirthCheck: $ref: "#/definitions/DOBCheckResultObject" entityId: description: | Unique ID for the entity. example: 84a9a860-68ae-4d7d-9a53-54a1116d5051 format: uuid type: string genderCheck: $ref: "#/definitions/GenderCheckResultObject" identityDocsCheck: description: Collection of identity documents (photos, scans, selfies, etc), and their check results items: $ref: "#/definitions/IdentityDocumentCheckResultObject" type: array x-omitempty: true nameCheck: $ref: "#/definitions/PersonalNameCheckResultObject" pepCheck: description: | !!!!! DEPRECATED !!!!! Please use the multi-result AMLResultSets structure instead. Note: This single check result structure will be retired in v1.3 !!!!! 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. items: $ref: "#/definitions/backgroundCheckResultObject" type: array x-omitempty: true sanctionsCheck: description: | !!!!! DEPRECATED !!!!! Please use the multi-result AMLResultSets structure instead. Note: This single check result structure will be retired in v1.3 !!!!! 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. items: $ref: "#/definitions/backgroundCheckResultObject" type: array x-omitempty: true watchlistCheck: description: | !!!!! DEPRECATED !!!!! Please use the multi-result AMLResultSets structure instead. Note: This single check result structure will be retired in v1.3 !!!!! 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. items: $ref: "#/definitions/backgroundCheckResultObject" type: array x-omitempty: true type: object fraudCheckResults: $ref: "#/definitions/FraudCheckResultObject" manualCheckResults: description: | Collection of check results for the manual KYC. An array of one entry with the manual check result. items: $ref: "#/definitions/ProcessResultObject" type: array x-omitempty: true requestId: $ref: "#/definitions/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). items: $ref: "#/definitions/ProcessResultObject" type: array type: object 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. example: 54a1116d-68ae-4d7d-9a53-505184a9a860 format: uuid type: string CheckResultUpdateObject: description: | Details of the status changes to be made to a check result. properties: checkClassIds: items: type: string type: array x-omitempty: true comment: type: string status: $ref: "#/definitions/enumCheckResultManualStatus" required: - comment type: object CodeDescription: description: A common pairing of a short code and a long description. properties: code: type: string description: type: string type: object CompanyDTO: properties: Addresses: $ref: "#/definitions/ArrayOfAddressDTO" Aliases: $ref: "#/definitions/ArrayOfString" Code: type: string CompanyID: type: string Date: type: string Function: type: string LegalForm: type: string LegalStatus: type: string MoreKey: type: string Name: type: string Official: type: boolean RegistrationAuthority: type: string RegistrationAuthorityCode: type: string Source: type: string VirtualID: type: string type: object CompanyProfileDTO: properties: Activity: $ref: "#/definitions/ArrayOfActivityDTO" ActivityDeclaration: $ref: "#/definitions/ArrayOfActivityDeclarationDTO" Addresses: $ref: "#/definitions/ArrayOfAddressDTO" AgentAddress: type: string AgentName: type: string Aliases: $ref: "#/definitions/ArrayOfString" AppointmentDateOfOfficial: type: string Capital: $ref: "#/definitions/ArrayOfCapitalDTO" Code: type: string CompanyNameInEnglish: type: string Date: type: string Email: type: string FaxNumber: type: string FiscalCode: type: string FoundationDate: type: string Functions: $ref: "#/definitions/ArrayOfString" Headquarters: type: string KeyFigures: $ref: "#/definitions/ArrayOfString" LastAnnualAccountDate: type: string LegalForm: type: string LegalFormDeclaration: type: string LegalFormDetails: $ref: "#/definitions/LegalFormDTO" LegalStatus: type: string MailingAddress: type: string Name: type: string Official: type: boolean RegistrationAuthority: type: string RegistrationAuthorityCode: type: string RegistrationDate: type: string RegistrationNumber: type: string SigningDeclaration: type: string SigningDeclarationDescription: type: string SigningLanguage: type: string Source: type: string StateOfIncorporation: type: string TelephoneNumber: type: string VatNumber: type: string VirtualId: type: string WebsiteURL: type: string directorAndShareDetails: $ref: "#/definitions/DirectorAndShareDetails" officers: $ref: "#/definitions/ArrayOfUSOfficerDTO" type: object ComparisonError: properties: comparisonDate: description: Timestamp of when the attempted comparison took place example: 2019-10-18T07:09:21.882+11:00 format: date/time type: string correlationId: description: The correlationId as passed in the request example: d290f1ee-6c54-4b01-90e6-d701748f0851 format: uuid type: string errorCode: description: | * `1000` - Document not recognised (i.e. not valid pdf or image) * `1001` - Bill is not SME or Domestic * `1004` - Bill is gas (if to be excluded) * `1005` - Template Not Found – The document was a pdf but service did not recognise the uploaded document against any of it’s templates * `1008` - Unsupported distributor – bill is from jurisdiction that is unsupported * `1009` - Unsupported distributor – bill is from jurisdiction that is unsupported * `1030` - Invoice from date is missing * `1031` - Invoice to date is missing * `1033` - Supply address is missing * `1039` - NMI is missing * `1041` - Bill is a predictive plan making comparison hard * `1044` - Bill is on embedded network * `1045` - Incompatible charge item – manual comparison needed * `1062` - C&I Bill loaded * `1080` - API failed to reconcile bill usually meaning that not all cost items were picked up enum: - 1000 - 1001 - 1004 - 1005 - 1008 - 1009 - 1030 - 1031 - 1033 - 1039 - 1041 - 1044 - 1045 - 1062 - 1080 example: 1039 type: integer message: description: Description of error that can be displayed as user feedback. e.g. "Uploaded document not a PDF" example: NMI is missing type: string version: description: Version of the API on which the error took place. This value should be reported with any issue raised. example: 200.132bfab type: string required: - comparisonDate - correlationId - errorCode - message - version type: object ComparisonResponse: properties: comparisonDate: description: Timestamp of when the comparison took place example: 2019-10-18T07:09:21.882+11:00 format: date/time type: string correlationId: description: The correlationId as passed in the request example: d290f1ee-6c54-4b01-90e6-d701748f0851 format: uuid type: string currentBillData: $ref: "#/definitions/CurrentBillData" defaultOffer: $ref: "#/definitions/DefaultOffer" marketDisclosure: description: Optional disclaimer statment properties: name: description: Name of this section when rendering example: Market Disclosure type: string value: description: Disclaimer text example: The energy plans compared on this site are not representative of all plans available in the market. We do not compare all brands in the market, or all products offered by all brands. type: string type: object maximumSaving: description: What is the maximum saving that can be achieved if the user switches to a new plan. This number may be negative if the user is already on the best plan for their usage and no saving can be found. example: 6.95 type: number plans: description: Array of plans, sorted from best to worst saving, for the uploaded bill items: $ref: "#/definitions/Plan" type: array version: description: Version of the API on which the comparison took place. This value should be reported with any issue raised. example: 200.132bfab type: string required: - comparisonDate - correlationId - currentBillData - defaultOffer - maximumSaving - plans - version type: object ComparisonSet: description: | This is the document that we want to compare to the original toDocument. In the case of a selfie-check against a drivers licence: * compareDocument will be the the selfie * toDocument will be the drivers licence photo properties: compareDocument: $ref: "#/definitions/IdentityDocumentObject" toDocument: $ref: "#/definitions/IdentityDocumentObject" type: object Conditions: description: Plan conditions to be displayed to customer properties: name: example: Conditions type: string value: items: $ref: "#/definitions/NameValue" type: array required: - name - value type: object Contract: description: Plan contract details to be displayed to customer properties: name: description: Name of this section when rendering example: Contract Details type: string value: description: Contract details for this plan items: $ref: "#/definitions/NameValue" type: array required: - name - value type: object CourtDetailsObject: description: Officer court details as returned from an ASIC report. properties: applicationNumber: type: string applicationYear: maximum: 2999 minimum: 1000 type: integer country: type: string state: type: string type: $ref: "#/definitions/CodeDescription" type: object CourtJudgement: properties: action: description: The name of the court judgement that was handed down title: Court Action type: string actionDate: description: The date of the court ruling format: date-time title: Action Date type: string createdDate: description: The date the court judgement was received and published format: date-time title: Created Date type: string judgementAmount: description: |- The amount the defendant was ordered by the court to pay to the plaintiff format: float title: Judgement Amount type: number location: description: The location of the court judgment title: Location type: string natureOfClaim: description: Nature of the claim title: Nature of Claim type: string natureOfClaimDesc: description: Additional information regarding the nature of the claim title: Nature of Claim Description type: string plaintiff: description: The person or company that is taking the defendant to court title: The Plaintiff Name type: string proceedingNumber: description: Court judgement referencing identifier title: Court Proceeding Number type: string state: description: The state jurisdiction of the court judgement title: State type: string type: object CreditScoreHistory: properties: date: format: date-time type: string score: type: integer type: object CreditScoreObject: properties: creditScoreHistory: description: Shows the credit score for every month over the last year for this business items: $ref: "#/definitions/CreditScoreHistory" title: Credit Score History type: array currentCreditScore: description: |- The score ultimately ranks entities based on their riskiness and is designed to assist you in making more informed and consistent credit decisions. The score is based between 0 and 850 index points with a higher score considered lower risk while lower scores are deemed to be riskier entities. It should be used in partnership with your internal credit procedures and policies. Please note that the score and recommendation should be used in partnership with your company's internal credit procedures and policies. The score should not be used as the sole reason in making a decision about the entity. 0 = Critical (ACN deregistered or ABN cancelled) 1 - 125 = Entity has a critical status and significant adverse information present. Trading eligibility must be considered.) 126 - 250 = Very High (Entity has a critical status and significant adverse information present. Trading eligibility must be considered) 251 - 450 = High (Entity has a below average creditworthiness score and some adverse information may be present. Trade with caution, monitor closely and consider your payment terms) title: The Credit Score is a statistically based score indicating an entity's credit worthiness. type: integer type: object CurrentBillData: description: Data from uploaded bill properties: accountAddress: description: Account (Billing) address. example: Level 3, 9 Help Street, Chatswood, NSW, 2067 type: string accountName: description: Customer name. example: John Smith type: string accountNumber: description: Customer account number example: 4813 741 128 type: string actualPlanTotalCost: description: Recalculated cost of the plan based on users comsumption and plan rates including discounts, rebates, concessions etc... Additional fees such as credit card processing fees are ignored. example: 884.598 type: number billDateFrom: description: Start date for billing period example: 2018-11-03T00:00:00.000+11:00 format: date/time type: string billDateTo: description: End date for billing period example: 2019-02-08T00:00:00.000+11:00 format: date/time type: string days: description: Number of days in billing period (billDateTo - billDateFrom) example: 93 type: integer discount: description: Total value of all unconditional discounts applied to the bill example: 0 type: number fuelType: description: | * `E` - Electricity enum: - E example: E type: string nmi: description: National Meter identifier (NMI) example: "41035337484" type: string periods: description: Rates and charges for each period on the bill items: $ref: "#/definitions/Period" type: array retailer: $ref: "#/definitions/Retailer" solar: description: Array of rates and charges for solar on the bill, by period. If no solar is present on the uploaded bill this object will not be present. items: properties: rate: description: Solar rate from bill type: number value: description: Solar value from bill type: number type: object type: array supplyAddress: description: Supply address. This may differ from account address if bill payers address is different from account address. example: Level 3, 9 Help Street, Chatswood, NSW, 2067 type: string required: - accountAddress - accountName - accountNumber - actualPlanTotalCost - billDateFrom - billDateTo - days - discount - fuelType - nmi - periods - retailer - supplyAddress type: object DOBCheckResultObject: properties: checkResult: $ref: "#/definitions/generalCheckResultArray" dob: $ref: "#/definitions/DOBObject" type: object DOBObject: 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 example: AUS type: string dateOfBirth: description: Date of Birth in YYYY-MM-DD format example: 1978-11-12 format: date type: string locality: description: | Place of birth other than country If locality is given, then country must also be provided. example: Brisbane type: string yearOfBirth: description: Year of birth or "unknown". This will be autoextracted if dateOfBirth is supplied. example: "1978" type: string type: object DefaultOffer: description: A comparison to the default offer (VDO/DMO) must displayed for each plan. This object contains the title and the message for that presentation. Please refer to the layout guidelines for more information. properties: name: description: Title/Header for the default offer when presented to the user. enum: - Default Market Offer (DMO) - Victorial Default Offer (VDO) example: Default Market Offer (DMO) type: string value: description: Text containing the default offer comparison with the current plan example: |- For an average household in the AUSGRID network using 3,900kWh/year on a flat rate tariff. Amounts do not include any concessions or rebates, feed in tariffs, or green energy charges. Amounts include all other benefits (including discounts) that you're eligible for, and GST (unless otherwise stated). Your actual bill will vary depending on your actual usage, tariff type and distributor. type: string type: object DeviceCheckDetailsObject: description: | Contains any/all details we want to pass on to the device/biometric 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. 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. enum: - SIGNUP - LOGIN - PAYMENT - CONFIRMATION - _ 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) items: $ref: "#/definitions/KeyValuePairObject" type: array x-omitempty: true checkSessionKey: description: the unique session based ID that will be checked against the service. type: string checkType: description: | Describes the type of check service we need to verify with. Choices are: - DEVICE: Services that will be checking device characteristics - BIOMETRIC: Services that will be checking biomentric characteristics enum: - DEVICE - BIOMETRIC type: string type: object Director: properties: address1: type: string address2: type: string address3: type: string address4: type: string address5: type: string address6: type: string birthdate: type: string directorNumber: type: string directorships: $ref: "#/definitions/ArrayOfDirectorship" name: type: string nationality: type: string postcode: type: string title: type: string type: object DirectorAndShareDetails: properties: PersonsOfSignificantControl: $ref: "#/definitions/ArrayOfPSCDetails" capitalReserves: $ref: "#/definitions/CapitalReserves" directors: $ref: "#/definitions/ArrayOfDirector" shareHolderSummary: $ref: "#/definitions/ShareholderSummary" shareHolders: $ref: "#/definitions/ArrayOfShareholderDetails" type: object Directorship: properties: appointedDate: type: string companyName: type: string companyNumber: type: string companyStatus: type: string function: type: string type: object DisplayMarkUp: properties: attribute: description: Comma seperated list of attributes to apply to value when rendering. enum: - bold type: string children: description: Children of element. This data structure is recursive with a DisplayMarkup element having 0 or more DisplayMarkup children items: $ref: "#/definitions/DisplayMarkUp" type: array confirmation: description: Does this statement need to be confirmed (with a checkbox)? Confirmation can be mandatory or optional. When the confirmation element is present a key element must also be present. The keys of all confirmed statements must be sent in the switch request. The absence of any mandatory confirmation will result in an error response from the switch request. enum: - optional - mandatory type: string key: description: For elements that require confirmation, the key of each element that the user has accepted must be send in the switch request. The absence of any mandatory confirmation will result in an error response from the switch request. example: understand_and_agree type: string name: description: Text to display as header/title of value. example: Billing Address type: string parameters: additionalProperties: description: The parameters object will contain a key/value pair for each data binding present in the value. The key will match the name of the data binding without the enclosing curly brackets. For example, If "{{Terms and Conditions}}" is present in the value, a value with the key "Terms and Conditions" will be present in the parameters. properties: name: description: Name of the parameter example: Product Details type: string type: description: |- Type of parameter * `link` - The 'value' contains a link to external content. The user should be able click on this link to view the content. * `mailto` - The 'value' contains an email address. The user should be able click on this address to send open their email client. enum: - link - mailto example: link type: string value: description: Value of this parameter example: https://www.accurassi.com type: string type: object description: Optional element which has a keyvalue pair associated with every data binding contained in the value element of the current object. type: object type: description: Type of component to be used for rendering enum: - text - unorderedlist - orderedlist type: string value: description: Data to be rendered. This data can contain data bindings (contained in {{ }}). If present in the string the parameters object will contain a key with the same name and the associated data (e.g a link).

{
  "type": "text",
  "value": "I accept the {{Terms and Conditions}}.",
  "parameters": {
    "Terms and Conditions": {
      "type": "link",
      "value": "https://www.accurassi.com.au/sample-terms-and-conditions/"
    }
  }
}
example: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis auctor erat ligula, faucibus mattis felis vestibulum et type: string type: object DocumentChecksResultObject: description: Contains the results of a given document upload. properties: checkResults: $ref: "#/definitions/IdentityDocumentCheckResultObject" requestId: $ref: "#/definitions/RequestIDObject" required: - requestId type: object DocumentCompareResultObject: description: Contains the results of a given document upload. properties: documentComparisonResults: $ref: "#/definitions/DocumentComparisonResultObject" requestId: $ref: "#/definitions/RequestIDObject" required: - requestId - documentComparisonResults type: object DocumentComparisonResultObject: description: Contains the details of a comparison between two documents properties: compareDocumentId: description: | This is a direct copy from the compareDocument object passed in the request. You MUST supply this. example: 84a9a860-68ae-4d7d-9a53-54a1116d5051 format: uuid type: string processResult: $ref: "#/definitions/ProcessResultObject" toDocumentId: description: | This is a direct copy from the toDocument object passed in the request. You MUST supply this. example: 84a9a860-68ae-4d7d-9a53-54a1116d5051 format: uuid type: string type: object DocumentIndustryUtilityConsentResultObject: description: Utility industry explicit consent response object. Used to wrap up industry-specific resultsets. properties: documentId: description: The document that was used to generate these results. example: 84a9a860-68ae-4d7d-9a53-54a1116d5051 format: uuid type: string industryProcess: example: elecConsentResult type: string requestId: $ref: "#/definitions/RequestIDObject" utilityConsentResult: description: | The utility consent service can return either an error response or a result. One of error or result will be returned in this case, the other will either be a nil value, or not supplied. properties: error: $ref: "#/definitions/EICError" result: $ref: "#/definitions/EICResponse" type: object type: object DocumentIndustryUtilityProcessResultObject: description: Utility industry comparison process result object. Used to wrap up industry-specific resultsets. properties: documentId: description: The document that was used to generate these results. example: 84a9a860-68ae-4d7d-9a53-54a1116d5051 format: uuid type: string industryProcess: example: elecCompareResult type: string requestId: $ref: "#/definitions/RequestIDObject" utilityCompareResult: description: | The utility comparison service can return either an error response or a result. One of error or result will be returned in this case, the other will either be a nil value, or not supplied. properties: error: $ref: "#/definitions/ComparisonError" result: $ref: "#/definitions/ComparisonResponse" type: object type: object DocumentIndustryUtilitySwitchResultObject: description: Utility industry comparison process result object. Used to wrap up industry-specific resultsets. properties: documentId: description: The document that was used to generate these results. example: 84a9a860-68ae-4d7d-9a53-54a1116d5051 format: uuid type: string industryProcess: example: elecSwitchResult type: string requestId: $ref: "#/definitions/RequestIDObject" utilitySwitchResult: description: | The utility switching service can return either an error response or a result. One of error or result will be returned in this case, the other will either be a nil value, or not supplied. properties: error: $ref: "#/definitions/SwitchError" result: $ref: "#/definitions/SwitchResponse" type: object type: object DocumentResultObject: description: Contains the results of a given document upload. properties: document: $ref: "#/definitions/IdentityDocumentObject" requestId: $ref: "#/definitions/RequestIDObject" required: - requestId - document type: object DocumentScanResultObject: description: | The result of a scan will contain 4 parts * The requestid - that's always there, and is the same that was passed in in the header. * The results of the process and the meta data around it, including confidence levels, service used and the like * extractedDocument - this will be an updated version of the document object passed in for scanning with results of the scan inserted. You can subsequently update this data as needed (say after confirmation with the end-consumer) through the various update functions. * Any additional data extracted from the service that does not fit into the standard identity document fields will be placed into the extraData KVPs. * extractedEntity - the service will attempt to create the basics of an entity's name, address, DoB, gender from the data returned from the scan. You can then use this entity data to create a new entity for a wider check if needed. * Note if you plan on doing this, make sure you include the extractedDocument reference in the "new" entity. * EXTRA SPECIAL NOTE: If no useful data was returned in the scan, extractedDocument will be left unchanged, and extractedEntity will be left out properties: extractedDocument: $ref: "#/definitions/IdentityDocumentObject" extractedEntity: $ref: "#/definitions/EntityObject" processResult: $ref: "#/definitions/ProcessResultObject" requestId: $ref: "#/definitions/RequestIDObject" required: - requestId - processResult type: object DocumentSearchResultListItem: description: Contains the individual search results for a document. properties: confidence: $ref: "#/definitions/SearchResultConfidenceObject" document: $ref: "#/definitions/IdentityDocumentObject" type: object DocumentSearchResultObject: description: Contains the results of a given document search. properties: documentSearchResults: description: | The list of (potentially) matching documents with confidence levels. If you are the "owner" of the document - i.e. the same CustomerID and CustomerChildID (if relevant) - then the full details of the document will be returned, except for the contents of any attached scans. If you are not the owner of the document, then just the ID and confidence level is returned. You can still use this ID to retrieve any check results (see GET /document/{documentId}/checks) items: $ref: "#/definitions/DocumentSearchResultListItem" type: array x-omitempty: true requestId: $ref: "#/definitions/RequestIDObject" required: - requestId type: object DocumentVerificationResultObject: description: Contains the details of a check on a given data point properties: documentId: description: This is a direct copy from the document object passed in for verifcation. example: 84a9a860-68ae-4d7d-9a53-54a1116d5051 format: uuid type: string processResult: $ref: "#/definitions/ProcessResultObject" type: object DocumentVerify: description: | This is the document we wish to verify in some way, along with an entity object that contains some/all of the details we wish to verify. For example, if we're attempting to verify a drivers licence, we generally need to pass in a name, address, DoB, etc as well. the entity gives the structure to be able to do this. Note, only the document in the "document" parameter is to be processed. any additional documents found in the entity (there shouldn't be, but given the way this has been defined, there can be) will be ignored. Only the Name, Address, DoB and Gender fields will be potentially used during the verification process. The EntityObject can take one of two forms. - It can be a single entityId - in which case the details will be pulled from the database. If using an existing document, then the entity must also own the document or the request will fail. - You can supply a "single use" entity with fields, etc. In this case the entity details will be used to verify the document, then will be discarded. If you wish to save the entity, use the /entity comments instead to create the entity and attach the document there. properties: document: $ref: "#/definitions/IdentityDocumentObject" entityData: $ref: "#/definitions/EntityObject" type: object DocumentVerifyResultObject: description: Contains the results of a given document upload. properties: documentVerificationResults: $ref: "#/definitions/DocumentVerificationResultObject" requestId: $ref: "#/definitions/RequestIDObject" required: - requestId type: object DriversLicence: properties: expiryDate: description: Expiry date of drivers licence example: 10/2022 format: mm/yyyy type: string number: description: Drivers Licence Number example: "1234567890" type: string state: description: State of Issue example: NSW type: string type: description: Document identifier enum: - driverslicence example: driverslicence type: string required: - type - number - state type: object EICDetails: description: Information for the residents of the property being supplied properties: concessionCard: description: Customer concession card details properties: concessionEvidenceType: description: The type of evidence used to prove eligibility for concessions enum: - Pensioner Concession Card - Gold Repatriation Health Card - Health Care Card - NSW Life Support Rebate Without Concession Card - Queensland Seniors Card example: Health Care Card type: string concessionType: description: Concessions linked to the customer's concession card enum: - Life Support - Medical Cooling - Service to Property Charge - Off-Peak Electricity - Annual Electricity - Transfer Fee Waiver - Excess Electricity - Controlled Load - Low Income Household - Medical Energy - NSW Government Life Support Rebate - Queensland Electricity Rebate - Winter Gas - Excess Gas Consumption example: NSW Government Life Support Rebate type: string customerReferenceNumber: description: Customer Reference Number (CRN) on the concession card example: "123456789" type: string endDate: description: Concession card end expiry date example: 2022-10 format: date pattern: YYYY-MM type: string firstName: description: First name on the concession card example: John type: string lastName: description: Last name on the concession card example: Doe type: string startDate: description: Concession card start date example: 2018-10 format: date pattern: YYYY-MM type: string required: - customerReferenceNumber - concessionEvidenceType - startDate - endDate - firstName - lastName - concessionType type: object vulnerabilities: description: Vulnerability information for residents of the property being supplied properties: dependencyType: description: Is anyone in the property dependent on electricity for life support equipment? enum: - Life Support - Sensitive Load example: Life Support type: string required: - dependencyType type: object type: object EICError: properties: correlationId: description: The correlationId as passed in the request example: d290f1ee-6c54-4b01-90e6-d701748f0851 format: uuid type: string errorCode: description: | * `400` - The request was malformed * `422` - Invalid request parameter enum: - 400 - 422 example: 400 type: integer message: description: Text to provide more details on errorCode example: The request was malformed type: string version: description: Version of the API on which the EIC request took place. This value should be reported with any issue raised. example: 200.132bfab type: string required: - correlationId - errorCode - message - version type: object EICRequest: properties: correlationId: description: Correlation ID as passed to comparison request example: d290f1ee-6c54-4b01-90e6-d701748f0851 format: uuid type: string details: $ref: "#/definitions/EICDetails" planId: description: Unique ID of plan, selected from comparison results example: "123456" format: string type: string required: - correlationId - planId type: object EICResponse: properties: correlationId: description: The correlationId as passed in the request example: d290f1ee-6c54-4b01-90e6-d701748f0851 format: uuid type: string eic: description: Hierarchical list of objects for rendering EIC statement and Terms and Conditions items: $ref: "#/definitions/DisplayMarkUp" type: array plan: $ref: "#/definitions/Plan" version: description: Version of the API on which the EIC request took place. This value should be reported with any issue raised. example: 200.132bfab type: string required: - correlationId - plan - eic - version type: object 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. - deviceCheckDetails: | An optional array of parameters for us to check the device and biometric characteristics against. This may map to a session key or device identifier, along with additional information that we can use to check against services like ThreatMetrix, BioCatch (or whatever has been configured for the Customer) properties: deviceCheckDetails: items: $ref: "#/definitions/DeviceCheckDetailsObject" type: array x-omitempty: true entity: $ref: "#/definitions/EntityObject" required: - entity type: object 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 | | | | | properties: flag: description: Name of the flag type: string value: description: flag value. type: integer x-omitempty: false type: object EntityIDVDetailsObject: description: | Contains all the details we need to create/update an entity and generate an IDV token properties: applicantId: description: | The applicantId previously supplied when creating a token for the first time for an entity. Only required if re-submitting for a fresh token on a previously created applicant. type: string x-omitempty: true applicationId: description: | If this is for a native application SDK, then we need the applicationId as reported by the SDK. This will then be tied to the token so it cannot be used in another application or handset. You must send either an applicationID or a referrer (see below) type: string x-omitempty: true entity: $ref: "#/definitions/EntityObject" referrer: description: | If this is for a web SDK, then you need to supply the referrer domain so that the token can be validated by the IDV service You must send either a referrer or an applicationID (see above) type: string x-omitempty: true required: - entity type: object EntityIDVResultObject: description: Contains the results of a given document entity create/update and IDV token details. properties: applicantId: description: | The applicantId is either the same one that was supplied in the request for a fresh token, or a new one. This ID must be supplied along with the token to your SDK so that it knows who any uploaded documents are for. The latest applicant will also be written to the extraData of the entity as well for safe keeping. Older applicantIds will be overwritten. type: string entity: $ref: "#/definitions/EntityObject" requestId: $ref: "#/definitions/RequestIDObject" supportTwoDocs: description: If the requesting customer can support requesting 2 documents. type: boolean token: description: | Token to be used in the SDK to authenticate the applicant and application/referrer. Tokens are time limited (1 hour) and can only be used with the applicantId supplied. type: string required: - requestId - entity - token - applicantId type: object EntityObject: description: | Describes all of the data being used to verify an entity. properties: addresses: description: Collection of address objects. items: $ref: "#/definitions/AddressObject" type: array x-omitempty: true dateOfBirth: $ref: "#/definitions/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. example: 84a9a860-68ae-4d7d-9a53-54a1116d5051 format: uuid type: string 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. Please contact Frankie developer support if you're unsure as to what valid values are. type: string x-omitempty: true entityType: $ref: "#/definitions/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://apidocs.frankiefinancial.com/docs/entity-extradata-key-value-pairs items: $ref: "#/definitions/KeyValuePairObject" type: array 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. items: $ref: "#/definitions/EntityFlagObject" type: array x-omitempty: true gender: $ref: "#/definitions/enumGender" identityDocs: description: Collection of identity documents (photos, scans, selfies, etc) items: $ref: "#/definitions/IdentityDocumentObject" type: array x-omitempty: true name: $ref: "#/definitions/PersonalNameObject" organisationData: $ref: "#/definitions/OrganisationDataObject" type: object EntityProfileCheckResultMessage: properties: checkClass: description: | The class of checks to which this check type belongs. One of: - kyc - aml - fraud - none example: kyc type: string checkType: description: A single check type that this result message applies to. example: one_plus type: string 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 example: Partial match type: string 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 type: object EntityProfileItemMatchResultObject: description: Match summary for a single checked address or document properties: checked: description: True if an attempt was made to verify example: true type: boolean matchCount: description: The number of distinct sources that matched this address or document example: 5 type: integer matchSources: description: | List of sources that matched. The matchCount will be the number of entries in this list. items: type: string type: array 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. example: gov_id type: string verified: description: True if there is at least one match example: true type: boolean type: object EntityProfileKYCMatchResultObject: description: Summary of all KYC matches 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. example: 2 type: integer matchCountRequired: description: | Number of distinct matches (sources and/or matched government ID documents) required for this set of match types. example: 1 type: integer matchTypes: additionalProperties: properties: checked: description: True if an attempt was made to verify example: true type: boolean 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. example: 1 type: integer 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. items: type: string type: array x-omitempty: true verified: description: True if there is at least one match example: true type: boolean type: object 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 x-omitempty: true verified: description: True if there are enough matches to meet the requirement example: false type: boolean type: object 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. 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: additionalProperties: $ref: "#/definitions/EntityProfileItemMatchResultObject" 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 x-omitempty: true checkId: $ref: "#/definitions/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. items: $ref: "#/definitions/EntityProfileCheckResultMessage" type: array x-omitempty: true checkType: description: Comma separated list of checks required for the entity profile. example: two_plus,id,pep_media type: string creditHeaderFailures: description: List of vendors from failed credit header sources. items: type: string type: array x-omitempty: true documentResults: additionalProperties: $ref: "#/definitions/EntityProfileItemMatchResultObject" 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 x-omitempty: true entityId: description: | Unique ID for the entity. example: 84a9a860-68ae-4d7d-9a53-54a1116d5051 format: uuid type: string issueList: items: type: string type: array x-omitempty: true kycResults: description: Summary of KYC match counts. items: $ref: "#/definitions/EntityProfileKYCMatchResultObject" type: array x-omitempty: true latestCheckDate: description: The date and time of the last check that contributed to this result. example: 2018-11-12T13:14:15Z+10:00 format: date-time type: string 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. example: SDD U18 type: string profileName: description: The name of the profile used for this check. example: Credit type: string resolverRecommended: description: Workflow hint by arrangement with Frankie type: string riskLevel: description: | Risk level. One of: - LOW, - MEDIUM, - HIGH, - UACCEPTABLE - or UNKNOWN example: LOW type: string riskPolicy: description: | Risk policy. Contents depend on account configuration but would typically be one of: - SDD, - CDD, - EDD - or FAIL example: SDD type: string type: object EntityResultObject: description: Contains the results of a given document entity create/update or GET request. properties: entity: $ref: "#/definitions/EntityObject" requestId: $ref: "#/definitions/RequestIDObject" required: - requestId - entity type: object EntitySearchResultListItem: description: Contains the individual search results for an entity. properties: confidence: $ref: "#/definitions/SearchResultConfidenceObject" documentMatchTypes: description: | Array of descriptons of document field matches used to score this search. This is a summary for all the documents for the matched entity. items: example: ID number type: string type: array x-omitempty: true documentNameMismatches: description: | If this entity has any level of name match then this is an array of document IDs for the entity where the document has an entity name and it doesn't match any entity names being sought. items: example: 84a9a860-68ae-4d7d-9a53-54a1116d5051 format: uuid type: string type: array x-omitempty: true entity: $ref: "#/definitions/EntityObject" entityMatchTypes: description: | Array of descriptons of entity field matches used to score this search. items: example: Full name type: string type: array x-omitempty: true type: object EntitySearchResultObject: description: Contains the results of a given entity search. properties: entitySearchResults: description: | 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 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) items: $ref: "#/definitions/EntitySearchResultListItem" type: array x-omitempty: true requestId: $ref: "#/definitions/RequestIDObject" required: - requestId type: object ErrorObject: properties: commit: description: Server version indication example: 2af478ed type: string errorCode: description: Frankie error code example: CORE-5990 type: string errorMsg: description: Will describe the error example: Everything went kaflooey. Stay clam. type: string httpStatusCode: description: | Deprecated: HTTP status code. Same as that which is passed back in the header. example: 501 type: integer issues: items: properties: issue: description: Description of the problem example: Invalid format. Must be YYYY-MM-DD type: string issueLocation: description: Will describe the field or data location of the issue example: dateOfBirth type: string required: - location - issueLocation type: object type: array x-omitempty: true requestId: $ref: "#/definitions/RequestIDObject" required: - requestId - errorCode - errorMsg type: object Fees: description: Plan fees and other charges to be displayed to customer properties: additionalFeeInfo: description: Any additional fee information for the plan example: "" type: string name: description: Name of this section when rendering type: string value: description: Fee information for the plan items: $ref: "#/definitions/NameValueDescription" type: array required: - name - value type: object 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 properties: fraudBackgroundCheckResults: items: $ref: "#/definitions/ProcessResultObject" type: array x-omitempty: true fraudListResults: items: $ref: "#/definitions/ProcessResultObject" type: array x-omitempty: true type: object GenderCheckResultObject: properties: checkResult: $ref: "#/definitions/generalCheckResultArray" gender: $ref: "#/definitions/enumGender" type: object 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. properties: checkResult: $ref: "#/definitions/generalCheckResultArray" idDocument: $ref: "#/definitions/IdentityDocumentObject" type: object IdentityDocumentObject: 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 example: AUS type: string 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. example: "true" readOnly: true type: boolean 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 items: $ref: "#/definitions/ScannedDocumentObject" type: array 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. example: 84a9a860-68ae-4d7d-9a53-54a1116d5051 format: uuid type: string documentStatus: $ref: "#/definitions/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) items: $ref: "#/definitions/KeyValuePairObject" type: array x-omitempty: true idExpiry: description: The expiry date of the document (if known) in YYYY-MM-DD format. example: 2020-02-01 format: date type: string idIssued: description: The issued date of the document (if known) in YYYY-MM-DD format. example: 1972-11-04 format: date type: string idNumber: description: The ID number of the document (if known). example: "123456789" type: string idSubType: description: The sub-type of identity document. Very document specific. type: string idType: $ref: "#/definitions/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. example: "false" readOnly: true type: boolean 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 example: VIC type: string required: - idType - country type: object IndividualData: description: x properties: addresses: description: | List of all found addresses associated with this person items: $ref: "#/definitions/AddressObject" type: array beneficially_held: description: | If describing an (ultimate) beneficial owner, then if any of the shared held are not benefially held, this field will be set to "false" example: true type: boolean date_of_birth: description: RFC3339 formatted date example: 1969-01-01 format: date type: string name: description: | Name of the individual example: JAN MICHAEL VINCENT type: string percent_owned: description: | If describing an (ultimate) beneficial owner, the percentage of the company owned by this Individual format: float type: number role: description: | If this individual has a role as an officeholder, such as director, then this will be described here. May be blank. example: Director type: string screening_result: $ref: "#/definitions/ScreeningResult" required: - percent_owned - beneficially_held - role type: object InsolvencyNotice: properties: date: format: date-time type: string id: type: string lastmod: format: date-time type: string publisher: type: string reportedBy: type: string ruling: type: string title: type: string type: object InternationalBusinessProfileCriteria: description: | Object to supply the country code and company code whose details you wish to retrieve. properties: company_code: description: | This is the company number returned in the search results (InternationalBusinessSearchResponse.Companies.CompanyDTO[n].Code) type: string country: description: | The ISO 3166-1 alpha2 country code of country registry you wish to search. This is consistent for all countries except for: - The United States which requires the state registry to query as well. - As an example, for a Delaware query, the country code would be "US-DE". - A Texas query would use "US-TX" - Canada, which also requires you to supply a territory code too. - A Yukon query would use CA-YU, Manitoba would use CA-MB - You can do an all jurisdiction search with CA-ALL - United Arab Emirates (UAE) - For Abu Dhabi, use "DI" - For Dubai, use "DU" See details here: https://apidocs.frankiefinancial.com/docs/country-codes-for-international-business-queries type: string required: - country type: object InternationalBusinessProfileResponse: description: | This wraps the search response details from Kyckr properties: CompanyProfile: $ref: "#/definitions/CompanyProfileDTO" checkId: description: | Unique ID for the individual check that was run. format: uuid type: string entityId: description: | If the response was successful and we returned a company profile, we save this as an ORGANISATION type entity in our service. We will also save the profile result as a REPORT type document, attached to the entity. example: 84a9a860-68ae-4d7d-9a53-54a1116d5051 format: uuid type: string ibResponseCode: description: service provider response code type: integer ibResponseDetails: type: string ibRetrievalLocation: type: string ibTransactionId: description: service provider ID type: string requestId: $ref: "#/definitions/RequestIDObject" type: object InternationalBusinessSearchCriteria: description: | Object to supply the country code, business name and number, along with an optional registry parameter to search for. properties: country: description: | The ISO 3166-1 alpha2 country code of country registry you wish to search. This is consistent for all countries except for: - The United States which requires the state registry to query as well. - As an example, for a Delaware query, the country code would be "US-DE". - A Texas query would use "US-TX" - Canada, which also requires you to supply a territory code too. - A Yukon query would use CA-YU, Manitoba would use CA-MB - You can do an all jurisdiction search with CA-ALL - United Arab Emirates (UAE) - For Abu Dhabi, use "DI" - For Dubai, use "DU" See details here: https://apidocs.frankiefinancial.com/docs/country-codes-for-international-business-queries type: string organisation_name: description: | Name or name fragment you wish to search for. Note: The less you supply, the more, but less relevant results will be returned. CRITICAL NOTE: This is *NOT* to be used as a progressive search function. You must supply at least one of organisation_name and/or organisation_number. If you supply both, a name search will be conducted first, then the number will be checked against the result set and any remaining results returned. type: string organisation_number: description: | The business number you wish to search on. This should be a unique corporate identifier as per the country registry you're searching. type: string required: - country type: object InternationalBusinessSearchResponse: description: | This wraps the search response details from Kyckr properties: Companies: $ref: "#/definitions/ArrayOfCompanyDTO" ibContinuationKey: type: string ibResponseCode: description: service provider response code type: integer ibResponseDetails: type: string ibTransactionId: description: service provider ID type: string requestId: $ref: "#/definitions/RequestIDObject" type: object IssueListItems: description: | A key/value pair of strings that describe the location of the issue (key) and an issue description (value). Also inclused is a severity properties: issue_description: description: | Human readable description of the issue example: Date of birth not found type: string issue_location: description: | Where the issue occured. It will describe a location in the response structure example: ultimate_beneficial_owner.0.date_of_birth type: string issue_severity: description: | The impact of the issue on the process. Is it just informational, such as a trivial different in a name match? Is it a warning to highlight something that is important, but did not prevent the process from completing? Is it a critical issue that prevented the check from completing successfully? Is it a stop condition that prevented the checks from being run at all? enum: - INFO - WARN - CRIT - STOP type: string type: object KYCScreeningResult: description: | The results of a safe harbour KYC check of an individual properties: address_match_count: description: The number of address matches example: 1 type: integer check_result: description: | The disposition of the 2+2 Safe Harbour check enum: - NOT_SCREENED - PASS - REFER - FAIL example: PASS type: string dob_match_count: description: The number of date of birth matches example: 1 type: integer matching_sources: description: | The is of matching data sources that produced a success match for the person being screened Example given is not indicative of the actual sources available. example: - au-elec - ntd - dvs items: type: string type: array name_match_count: description: The number of name matches example: 2 type: integer required: - name_match_count - dob_match_count - address_match_count type: object KeyValuePairObject: description: Individual key-value pair properties: kvpKey: description: Name of the data example: Extra.Information type: string kvpType: $ref: "#/definitions/enumKVPType" kvpValue: description: Value of the data example: 123-456-789A type: string type: object LegalFormDTO: 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 type: object Loan: properties: abn: type: string acn: type: string amount: type: string companyName: type: string endAt: format: date-time type: string startAt: format: date-time type: string status: type: string termLength: type: integer type: type: string uuid: type: string type: object MedicareCard: properties: cardColor: description: Card color enum: - green - blue - yellow example: green type: string expiryDate: description: Expiry date of drivers licence example: 2022-10 format: yyyy-mm for green cards or yyyy-mm-dd for blue/yellow cards type: string middleName: description: Middle Name on Card type: string number: description: Medicare Card Number example: "1234567890" type: string referenceNumber: description: Medicare Card Reference Number example: "1" type: string type: description: Document identifier enum: - medicare example: medicare type: string required: - type - number - expiryDate type: object MercantileEnquiry: properties: agent: type: string company: type: string createdDate: format: date-time type: string date: format: date-time type: string phone: type: string registeredDate: format: date-time type: string type: object NameValue: description: Name/Value pair properties: name: type: string value: items: type: string type: array required: - name - value type: object NameValueDescription: description: Name/Value pair properties: description: type: string name: type: string value: type: string required: - name - value - description type: object NameValueUnit: properties: name: description: Name of this property. example: Peak Rate type: string unit: description: Unit of measure for this property. example: cents per kW hour type: string value: description: Value of this property. example: "23.94" type: string required: - name - value - unit type: object NonIndividualBeneficialOwner: description: x properties: beneficially_held: description: | If describing an (ultimate) beneficial owner, then if any of the shared held are not benefially held, this field will be set to "false" example: true type: boolean entity_type: description: The ASIC type of the company/entity example: APUB type: string name: description: Name of the company/entity example: Widget Trust Corpoation Inc. type: string percent_owned: description: | If describing an (ultimate) beneficial owner, the percentage of the company owned format: float type: number stock_exchange_data: $ref: "#/definitions/StockExchangeData" required: - percent_owned - beneficially_held type: object NotificationResultObject: 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. 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). format: uuid type: string documentId: description: | Only supplied if the original request was tied to a document. This will be the same ID that was sent in the original acceptance. format: uuid type: string entityCustomerReference: description: | If the entity in entityId above has had an external service ID attached to it in the entity extraData with kvpKey = customer_reference, then this is that kvpValue example: AU0123456 type: string entityId: description: | Only supplied if the original request was tied to an entity. This will be the same ID that was sent in the original acceptance. format: uuid type: string function: description: | Short description of the original function called, or function that was triggered. example: entity.create type: string functionResult: $ref: "#/definitions/enumFunctionStatus" linkReference: description: | URI for resource containing more details about the reason for the notification. example: https://portal.frankiefinancial.io/entity/3fa85f64-5717-4562-b3fc-2c963f66afa6 format: uri type: string message: description: | A brief, human readable message describing the reason for the notification. example: Entity successfully created type: string notificationType: $ref: "#/definitions/enumNotificationType" requestId: $ref: "#/definitions/RequestIDObject" username: description: | The portal username that initiated the operation that led to this notification. If applicable and available. type: string type: object OfficerObject: description: Officer details as returned from an ASIC report. properties: appointmentDate: format: date type: string courtDetails: $ref: "#/definitions/CourtDetailsObject" docNumber: type: string docNumberQualifier: type: string entityId: format: uuid type: string status: type: string type: type: string typeDescription: type: string type: object OrganisationCheckResponseObject: description: | The result of an /business/ownership/query call retrieved via GET /retrieve/response/{requestId} after you receive a notification that the result is ready. properties: flags: description: | Used to set additional information flags for this response. items: $ref: "#/definitions/EntityFlagObject" type: array x-omitempty: true organisationCheckId: description: | Batch identifier for the KYC/AML check results if any. format: uuid type: string organisationCheckResult: $ref: "#/definitions/OrganisationCheckResultObject" ownershipCheckDate: description: | If an ownership result is provided in this response then this is the date and time the service provided that result. format: date-time type: string ownershipCheckId: description: | Unique identifier for the ownership check. format: uuid type: string ownershipQueryError: $ref: "#/definitions/ErrorObject" ownershipQueryResult: $ref: "#/definitions/OwnershipQueryResultObject" reportError: $ref: "#/definitions/ErrorObject" reportResult: $ref: "#/definitions/BusinessReportResultObject" requestId: $ref: "#/definitions/RequestIDObject" uboResponse: $ref: "#/definitions/UBOResponse" type: object OrganisationCheckResultObject: description: | The results of KYC/AML check on a organisation with a prior ownership query. This will be retrived via GET /retrieve/response/{requestId} after you receive a notification that the results are ready. properties: entityCategories: additionalProperties: items: format: uuid type: string type: array description: | A map of the entity categories that were selected for checks and an array of the entity IDs for each. The results for each entity ID will be in either the entityCheckResults or entityCheckErrors maps. Entities may appear in more than one category. type: object x-omitempty: true entityCheckErrors: additionalProperties: $ref: "#/definitions/ErrorObject" description: | A map of outright errors (failure to generate any kind of result). These objects will be referenced by entity ID in the entity category map. type: object x-omitempty: true entityCheckResults: additionalProperties: $ref: "#/definitions/CheckEntityCheckResultObject" description: | List of all entities check results (both individuals and organisations) other than outright errors. These objects will be referenced by entity ID in the entity category map. type: object x-omitempty: true entityId: description: | The entityId of the organisation for which this result was created. format: uuid type: string groupId: description: | The unique ID for grouping all new KYC/AML checks in this result. This is only for Frankie internal use. format: uuid type: string type: object OrganisationDataObject: description: | Organisation details for entities. Returned from an ASIC report. properties: adverseCreditDataPresent: type: boolean class: $ref: "#/definitions/CodeDescription" disclosingEntityIndicator: type: boolean includesNonBeneficiallyHeld: type: boolean kycCustomerType: type: string lastCheckDate: format: date type: string ownershipResolved: type: boolean registeredName: type: string registration: properties: date: format: date type: string previousNumber: type: string state: type: string type: object shareStructure: items: $ref: "#/definitions/ShareStructureObject" type: array x-omitempty: true startDate: format: date type: string status: $ref: "#/definitions/CodeDescription" subclass: $ref: "#/definitions/CodeDescription" type: $ref: "#/definitions/CodeDescription" type: object OwnershipDetailsObject: description: | The ownership details for one organisation. properties: beneficialOwners: description: | The beneficial owners of the company, who aren't necessarily UBO's. items: $ref: "#/definitions/BeneficialOwnerObject" type: array x-omitempty: true officers: description: | Company office holders. items: $ref: "#/definitions/OfficerObject" type: array x-omitempty: true organisation: $ref: "#/definitions/EntityObject" shareholdings: description: | Parcels of shares held by one or more shareholders. items: $ref: "#/definitions/ShareholdingObject" type: array x-omitempty: true ultimateBeneficialOwners: description: | The ultimate beneficial owners of the company. items: $ref: "#/definitions/BeneficialOwnerObject" type: array x-omitempty: true type: object OwnershipQuery: description: | Details of the organisation for which ownership should be queried. This should at least contain the ACN in the externalIds. properties: organisation: $ref: "#/definitions/EntityObject" required: - organisation type: object OwnershipQueryResponseObject: description: | Frankie internal use only. The result of an /business/ownership/query call as returned by a suitable service connector. properties: checkDate: description: | If a result is provided in this response then this is the date and time the service provided that result. format: date-time type: string checkId: format: uuid type: string ownershipQueryResult: $ref: "#/definitions/OwnershipQueryResultObject" providerCheckId: description: | Unique identifier provided by the service. type: string requestId: $ref: "#/definitions/RequestIDObject" type: object OwnershipQueryResultObject: properties: associatedEntities: additionalProperties: $ref: "#/definitions/EntityObject" description: | List of all entities (both individuals and organisations) associated with this ownership result. These objects will be referenced by entityId in the shareholdings and officers lists in the following ownership details. type: object x-omitempty: true blockingEntityIds: description: | List of entity IDs (that should be in the associatedEntities list) who blocked the ultimate beneficial ownership tree traversal. These are likely to be entities that cannot be checked automatically (such as trusts) or who have no UBO's of their own, such as public companies. The presence of data in this array also signifies that the full UBO list is not complete. items: format: uuid type: string type: array x-omitempty: true entityId: description: | The entityId of the organisation for which this result was created. The details will be in the ownershipDetails map with this ID as the key. format: uuid type: string ownershipDetails: additionalProperties: $ref: "#/definitions/OwnershipDetailsObject" description: | A map of entityId to ownershipDetailsObjects with at least one entry being for the root organisation that the overall result relates to. Any remaining entries will be for further results for organisational owners referenced in the root ownershipDetailsObject and so on. type: object x-omitempty: true type: object PSCDetails: properties: Address: type: string CeasedOn: type: string CountryOfResidence: type: string DOBDay: format: int64 type: integer DOBMonth: format: int64 type: integer DOBYear: format: int64 type: integer Kind: type: string Name: type: string Nationality: type: string NatureOfControl: $ref: "#/definitions/ArrayOfString" NotifiedOn: type: string type: object Passport: properties: country: description: Country of Issue example: Australia type: string expiryDate: description: Expiry date of passport example: 10/2022 format: mm/yyyy type: string number: description: Passport Number example: B765435 type: string type: description: Document identifier enum: - passport example: passport type: string required: - type - number - country type: object PaymentDefault: properties: abn: type: string accountAdditionalAbn: type: string accountVerifiedDate: format: date-time type: string amountOutstanding: format: float type: number approvedDate: format: date-time type: string company: type: string defaultSettled: type: boolean doctype: type: string documentType: type: string lastUpdated: format: date-time type: string originalInvoiceDate: format: date-time type: string partPaymentMade: type: boolean partpayment: type: boolean paymentDueDate: format: date-time type: string posterAbn: type: string posterName: type: string settled: type: boolean uploadedDate: format: date-time type: string type: object Period: description: Rates, by period, for the uploaded bill properties: controlledLoad1: $ref: "#/definitions/RateValue" controlledLoad2: $ref: "#/definitions/RateValue" offPeak: $ref: "#/definitions/RateValue" offPeakStep1: $ref: "#/definitions/RateValue" offPeakStep2: $ref: "#/definitions/RateValue" peak: $ref: "#/definitions/RateValue" peakStep1: $ref: "#/definitions/RateValue" peakStep2: $ref: "#/definitions/RateValue" peakStep3: $ref: "#/definitions/RateValue" shoulder: $ref: "#/definitions/RateValue" supplyCharge: $ref: "#/definitions/RateValue" type: object PersonalNameCheckResultObject: properties: checkResult: $ref: "#/definitions/generalCheckResultArray" name: $ref: "#/definitions/PersonalNameObject" type: object PersonalNameObject: 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. example: Jane Cecily Smith type: string familyName: description: Family name / Surname of the individual. example: Smith type: string givenName: description: First / Given name example: Jane type: string honourific: description: Mr/Ms/Dr/Dame/Dato/etc. example: Duchess type: string middleName: description: Middle name(s) / Initials example: Cecily type: string required: - familyName type: object Plan: description: All information associated with a given plan properties: benefits: $ref: "#/definitions/Benefits" conditions: $ref: "#/definitions/Conditions" contract: $ref: "#/definitions/Contract" defaultOfferMessage: description: Default Offer (DMO/VDO) text to be displayed for this plan example: The annualised price of this plan is $1,764 and is 14% less than the Reference Price. type: string directDebitRequired: description: Is payment by direct debit required in order to subscribe to this plan example: false type: boolean discounts: description: Conditional discounts that may be applied to plan. These values can be used to modify the estimatedBaseCost for client-side filtering and reordering. properties: directDebit: description: Direct Debit discount amount example: 43.84 type: number payOnTime: description: Pay On Time discount amount example: 60.23 type: number type: object estimatedBaseCost: description: Estimated cost of this plan, based on the usage from the uploaded bill, with no conditional discounts applied. If this plan offers no conditional discounts the estimatedTotalCost and the estimatedBaseCost will be the same. example: 704.8 type: number estimatedSaving: description: The estimated saving the customer could have realised if they had been on this plan during the billing period example: 179.8 type: number estimatedTotalCost: description: Estimated cost of this plan, based on the usage from uploaded bill, with all conditional discounts applied. example: 704.8 type: number feesAndCharges: $ref: "#/definitions/Fees" greenOptions: $ref: "#/definitions/NameValue" id: description: Unique identifier for this plan. This ID is passed when calling the switch API. example: 100456 type: integer name: description: Name of the plan example: Accurassi Energy All Time Saver type: string payOnTimeRequired: description: Is pay on time required in order to subscribe to this plan example: false type: boolean paymentOptions: $ref: "#/definitions/NameValue" rates: $ref: "#/definitions/Rates" retailer: $ref: "#/definitions/Retailer" type: description: |- The type of energy plan * `SR` - Single Rate * `TOU` - Time Of Use enum: - SR - TOU example: SR type: string url: description: Link to BPID (Basic Plan Information Document (NSW, SA, QLD, ACT)) or EPFS (Energy Price Fact Sheet (VIC)) example: https://www.energymadeeasy.gov.au/offer/1008406?postcode=2067 type: string required: - defaultOfferMessage - directDebitRequired - estimatedBaseCost - estimatedSaving - estimatedTotalCost - id - name - payOnTimeRequired - rates - retailer - type - url type: object ProcessResultObject: description: Stores the generic results of a process (check, scan, compare, verify, etc) properties: checkDate: description: The date and time the item was checked to provide this result. format: date-time type: string checkId: $ref: "#/definitions/CheckIDObject" checkPerformedBy: description: | Service provider that performed the check. Basically the name of the connector, without the leading con_ example: equifax type: string 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 example: DVS type: string 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. example: 70 format: int32 maximum: 100 minimum: -100 type: integer 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 items: $ref: "#/definitions/KeyValuePairObject" type: array x-omitempty: true resultState: $ref: "#/definitions/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 example: 75 maximum: 100 minimum: 0 type: integer type: object PuppyObject: description: All valid customers get a puppy. Otherwise, no puppy for you! properties: asknicely1: type: string asknicely2: type: string asknicely3: type: string asknicely4: type: string asknicely5: type: string asknicely6: type: string asknicely7: type: string commit: description: Server version indication example: 2af478ed type: string puppy: default: true example: true type: boolean required: - puppy type: object RateValue: properties: rate: example: 0.2847 type: number value: example: 305.76 type: number required: - rate - value type: object Rates: description: Plan rates to be displayed to customer properties: name: description: Name of this section when rendering example: Rates type: string value: description: Rates for this plan items: $ref: "#/definitions/NameValueUnit" type: array type: object RegulatoryInformation: properties: licence_details: type: string licence_number: type: string licence_verified: type: boolean regulatory_body: type: string type: object ReportCreditReport: properties: courtJudgements: description: CreditorWatch aggregate data from courts around Australia to provide a summary of court actions against an entity. When available, details of the action include location, case number, state, plaintiff, nature of the claim, action type and dollar amount. items: $ref: "#/definitions/CourtJudgement" title: Court Actions type: array creditEnquiries: description: Credit enquiries provide an indication of the number of times an entity's credit file has been accessed. title: Credit Enquiries type: integer insolvencyNotices: description: |- Insolvency and other published notices are provided by ASIC. These published notices provide details on external administrations, winding up applications (voluntary or by a court) and proposed company deregistrations, amongst other things. The notices contain important contact details and dates for creditors. These notices are provided directly from the ASIC insolvency notices website. If you require further information, visit: https://insolvencynotices.asic.gov.au. items: $ref: "#/definitions/InsolvencyNotice" title: Insolvency Notices type: array loans: items: $ref: "#/definitions/Loan" title: Loans type: array mercantileEnquiries: description: A Mercantile enquiry is an indication that a mercantile agency (or debt collection agency) has conducted an enquiry on this entity for the purpose of debt collection. items: $ref: "#/definitions/MercantileEnquiry" title: Mercantile Enquiries type: array paymentDefaults: description: | A default indicates that the debtor has failed to make a payment for goods or services. Payment Defaults are unique to CreditorWatch and can have one of three statuses: - outstanding - partial payment - settled. items: $ref: "#/definitions/PaymentDefault" title: Payment Defaults type: array type: object ReportCreditScore: properties: creditScore: properties: abn: type: string acn: type: string description: type: string itemCode: type: string scores: $ref: "#/definitions/CreditScoreObject" type: object type: object 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. example: 01BFJA617JMJXEW6G7TDDXNSHX format: ulid type: string Retailer: description: Retailer details properties: email: description: Contact email address for retailer cusomter support/queries example: energy@accurassi.com type: string id: description: Unique identifier for the retailer example: 123456 type: integer name: description: Name of the retailer example: Accurassi Energy Retailer type: string phone: description: Contact phone number for retailer customer support/queries example: +555 13384337 type: string required: - id - name type: object RetrievedResponseObject: description: | When sent a notification or alert, you'll call the /retrive/response/{requestId} function This will return the original response properties: origHTTPstatus: description: | This will be the HTTP response code that was returned originally (200, 404, etc). In the case where you're requesting the result of a callback (previously backgrounded call), then this is the response that would have been sent, had you waited for the call to finish. type: integer payload: additionalProperties: true description: | This is a placeholder field. It will actually be a JSON object that is the payload that would have been returned (or was returned) in the original request. You'll need to process this as if it were the original response, and act accordingly. type: object type: object ScannedDocumentObject: description: the document to be attached and optionally scanned (if supported) 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. example: 2020-06-02 format: date-time type: string 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. example: VGhpcyBpcyBzb21lIGV4YW1wbGUgZGF0YS4gV29vLCBJIGJldCB5b3UgcmVncmV0IHRoZSB0aW1lIHlvdSB3YXN0ZWQgZGVjb2RpbmcgdGhpcywgaHVoPw== format: byte type: string scanDataRetrievalState: $ref: "#/definitions/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. example: 84a9a860-68ae-4d7d-9a53-54a1116d5051 format: uuid type: string 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 example: Important Document - ID1234567.pdf type: string scanMIME: $ref: "#/definitions/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. example: 1 minimum: 0 type: integer scanSide: $ref: "#/definitions/enumScanSide" scanType: $ref: "#/definitions/enumScanType" type: object ScreeningResult: description: | Contains the results (if any) of the KYC and AML/Media checks performed properties: aml_result: $ref: "#/definitions/AMLScreeningResult" kyc_result: $ref: "#/definitions/KYCScreeningResult" type: object SearchResultConfidenceObject: description: | Provides details of the confidence level we have that this is the item we're looking for. properties: level: $ref: "#/definitions/enumSearchResultConfidence" notes: description: | Free-form list of descriptions around any partial matches items: type: string type: array x-omitempty: true score: description: Numeric score on a scale of 0 (none) to 100 (as certain as possible) on which the confidence level is based. Whole integers only. example: 70 format: int32 maximum: 100 minimum: 0 type: integer type: object 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. 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 type: object ShareholderDetails: properties: address: type: string allInfo: type: string currency: type: string id: type: string name: type: string nationality: type: string nominalValue: type: string percentage: type: string shareClass: type: string shareCount: format: int64 type: integer shareType: type: string shareholderType: type: string totalShareCount: format: int64 type: integer totalShareValue: format: int64 type: integer totalShares: format: int64 type: integer type: object ShareholderSummary: properties: shareCapital: type: string type: object ShareholdingObject: description: Details of a shareholding as returned from an ASIC report. properties: beneficiallyOwned: type: boolean docNumber: type: string docNumberQualifier: type: string fullyPaid: type: boolean members: items: format: uuid type: string type: array x-omitempty: true numberHeld: type: integer shareCapitalClassCode: type: string type: object StockExchangeData: description: | If a company is listed, then this object will be populated with whatever data has been determined. properties: approved_exchange: type: boolean exchange: type: string exchange_ticker: type: string supporting_document_links: items: type: string type: array supporting_evidence_in_pdf: type: boolean type: object SuppliedData: description: | The data that was initially supplied to check in the batch file properties: abn: description: | Australian Business Number - MUST be 11 digits. Can be supplied in lieu of the ACN example: 99001234321 type: string acn: description: | Australian Company Number on file - MUST be zero left-padded to 9 digits example: 342225 type: string company_type: description: | The type of company on file. Use the ABR's company types, as given here: https://abr.business.gov.au/Documentation/ReferenceData (entity types) enum: - PRV - PUB type: string customer_reference: description: Your reference number for this company example: WBC000ABC123 type: string name: description: | The name of the company to be verified example: Worldwide Widget Pty. Ltd. type: string required: - name - company_type - acn - abn - customer_reference type: object SuppliedDataMatches: description: | The results of the comparison of the supplied data (above) to that found on file with the ABR. If the value is missing, then the comparison was not run. There will likely be an issue highlighted in the issues_list properties: matched_acn: description: | Did the supplied ACN match the ACN on file with the ABR? Only truly relevant if ABN is supplied as well. example: true type: boolean matched_company_type: description: | Did the supplied company type match the company type on file with the ABR? example: true type: boolean matched_name: description: | Did the supplied name match (or closely match) the name on file with the ABR example: true type: boolean required: - matched_name - matched_acn - matched_company_type type: object SwitchDetails: description: Details required to switch retailers properties: customerDetails: description: Customer's details required to switch retailers properties: address: description: Customer's supply address address. If no address is passed, the supply address as read off the bill will be used example: Level 3, 9 Help Street, Chatswood, NSW 2067 type: string dateOfBirth: description: Customer's date of birth example: 22/04/1983 format: dd/mm/yyyy type: string email: description: Customer's email address example: jane.doe@email.com type: string evidenceOfIdentity: description: | Allows a user to select one of the following forms of ID to validate against: - Passport - Drivers Licence - Medicare card properties: DriversLicence: $ref: "#/definitions/DriversLicence" MedicareCard: $ref: "#/definitions/MedicareCard" Passport: $ref: "#/definitions/Passport" type: object mobile: description: Customer's phone number example: +555 13384337 type: string name: description: Name of customer switching properties: first: description: Customer's first name example: Jane type: string last: description: Customer's last name example: Doe type: string middle: description: Customer's middle name example: Joan type: string title: description: Customers title (e.g. Mr, Mrs, Miss, Dr) example: Miss type: string required: - title - first - last type: object required: - name - email - mobile - dateOfBirth - evidenceOfIdentity type: object required: - customerDetails type: object SwitchError: properties: correlationId: description: The correlationId as passed in the request example: d290f1ee-6c54-4b01-90e6-d701748f0851 format: uuid type: string errorCode: description: | * `400` - The request was malformed * `422` - Invalid request parameter enum: - 400 - 422 example: 400 type: integer message: description: Text to provide more details on errorCode example: The request was malformed type: string version: description: Version of the API on which the switch response took place. This value should be reported with any issue raised. example: 200.132bfab type: string required: - correlationId - errorCode - message - version type: object SwitchRequest: properties: confirmation: description: Array of strings containing all the keys of the elements that required confirmation in the EIC. The absence of any key for a mandatory confirmation will result in an error response. items: description: Key of confirmation item from EIC example: - terms_and_conditions - product_details type: string type: array correlationId: description: Correlation ID as passed to comparison request example: d290f1ee-6c54-4b01-90e6-d701748f0851 format: uuid type: string details: $ref: "#/definitions/SwitchDetails" required: - correlationId - details type: object SwitchResponse: properties: correlationId: description: The correlationId as passed in the request example: d290f1ee-6c54-4b01-90e6-d701748f0851 format: uuid type: string nextSteps: description: Hierarchical list of objects for rendering the next steps items: $ref: "#/definitions/DisplayMarkUp" type: array plan: $ref: "#/definitions/Plan" reference: description: A unique reference for this switch request example: bdacdabc-e3f7-4f6d-93d3-ffa83e419762 format: uuid type: string switchDate: description: Timestamp of switch request example: 2018-11-03T00:00:00.000+11:00 format: date/time type: string version: description: Version of the API on which the switch request took place. This value should be reported with any issue raised. example: 200.132bfab type: string required: - correlationId - reference - switchDate - plan - version type: object UBOResponse: properties: asic_search_timestamp: description: | If an ASIC search was conducted, what was the date/time in RFC-3339 format example: 2016-08-29T09:12:33.001Z format: date-time type: string business_details: $ref: "#/definitions/BusinessDetails" business_screening_result: $ref: "#/definitions/ScreeningResult" error_message: description: | Only populated if there was an error whilst trying to initiate the UBO check. Signifies that no other result data will be supplied type: string issues_list: description: | A list of issues encountered whilst processing the UBO request and subsequent KYC/AML checks. items: $ref: "#/definitions/IssueListItems" type: array non_individual_beneficial_owners: description: | A list of organisations who have been determined to own a (potentially) beneficial interest the company. The presence of non_individual_beneficial_owners indicates that not all individual ultimate beneficial owners could be determined. Examples may include public companies, listed companies, foreign companies, corporate trusts or other entities whose beneficial owners are not readily available. items: $ref: "#/definitions/NonIndividualBeneficialOwner" type: array officeholders: description: | A list of individuals who serve as current office holders the company items: $ref: "#/definitions/IndividualData" type: array supplied_data: $ref: "#/definitions/SuppliedData" supplied_data_matches: $ref: "#/definitions/SuppliedDataMatches" ubo_report: description: | The full URI of the UBO report PDF created as a part of this process (if requested) type: string ultimate_beneficial_owners: description: | A list of individuals who have been determined to own, either directly or indirectly, 25% or more of the company items: $ref: "#/definitions/IndividualData" type: array required: - rowid - request_id - supplied_data type: object USOfficerDTO: properties: Address: type: string BusinessAddress: $ref: "#/definitions/ArrayOfString1" Date: type: string MailingAddress: type: string Name: type: string Title: type: string Type: type: string type: object 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. properties: backgroundCheckType: $ref: "#/definitions/enumBackgroundCheckType" checkDetails: description: Any additional notes that may relate to the state. Free form notes that may contain JSON blobs needing further interpretation. items: $ref: "#/definitions/KeyValuePairObject" type: array x-omitempty: true checkFrequency: $ref: "#/definitions/enumBackgroundCheckFrequency" checkId: $ref: "#/definitions/CheckIDObject" checkPerformedBy: description: | Service provider that performed the check. Basically the name of the connector, without the leading con_ example: equifax type: string 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") example: DVS type: string confidenceLevel: description: Confidence in the current results on a scale of 0 (none) to 100 (as certain as possible). Whole integers only. example: 70 format: int32 maximum: 100 minimum: 0 type: integer currentState: $ref: "#/definitions/enumBackgroundCheckState" firstCheckDate: description: The date and time the item was first checked. example: 2017-11-12T13:14:15Z+10:00 format: date-time type: string latestCheckDate: description: The date and time the item was last checked to provide this result. example: 2018-11-12T13:14:15Z+10:00 format: date-time type: string type: object backgroundCheckResultObjectContainer: description: Wraps up a BCRO with its internal ID. properties: bcro: $ref: "#/definitions/backgroundCheckResultObject" id: description: Internal ID of this BCRO. Use this if you need to set the status. format: uuid type: string type: object 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 enum: - OTHER - RESIDENTIAL - RESIDENTIAL1 - RESIDENTIAL2 - RESIDENTIAL3 - RESIDENTIAL4 - BUSINESS - POSTAL - REGISTERED_OFFICE - PLACE_OF_BUSINESS - OFFICIAL_CORRESPONDANCE example: RESIDENTIAL1 type: string enumBackgroundCheckFrequency: description: How often these checks run. enum: - ADHOC - YEARLY - QUARTERLY - MONTHY - WEEKLY - DAILY example: DAILY type: string 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. enum: - CLEAR - PAST_HITS - POSSIBLE_HIT - ACTIVE_HITS example: CLEAR type: string 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. enum: - PEP - SANCTION - WATCHLIST - MEDIA - GROUP example: PEP type: string enumCheckResultManualStatus: description: | Indicates the status of a check result as set by a user. - "UNKNOWN": The user has not decided so the actual check result applies as normal. - "TRUE_POSITIVE": The check result has been acknowledged as correct but the final effect (accept/reject) has not been decided. - "TRUE_POSITIVE_ACCEPT": The check result is correct but will be ignored. This is also known as 'whitelisting' - "TRUE_POSITIVE_REJECT": The check result is correct and will be used. - "FALSE_POSITIVE": The check result is not applicable and will be ignored. - "STALE": The check result will become invisible, will not be considered and will not count towards due diligence requirements. enum: - UNKNOWN - TRUE_POSITIVE - TRUE_POSITIVE_ACCEPT - TRUE_POSITIVE_REJECT - FALSE_POSITIVE - STALE type: string enumCheckResultState: description: | Check state for an individual data point - "UNCHECKED": Check has not yet been performed - "NOT_SUPPORTED": the requested check type or industry function 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. enum: - UNCHECKED - CHECKING - UNPROCESSABLE - NOT_SUPPORTED - NO_MATCH - CHECKED_PARTIAL_SUCCESS - CHECKED_SUCCESS_WITH_NOTES - CHECKED_SUCCESS_CLEAR - CHECKED_FAILED example: CHECKED_PARTIAL_SUCCESS type: string 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. enum: - INITIALISING - SCAN_IN_PROGRESS - DOC_SCANNED - DOC_CHECKED example: DOC_SCANNED type: string enumEntityType: description: | Indicates the type of an entity. - "INDIVIDUAL": An individual. - "TRUST": A trust. - "ORGANISATION": An organisation. enum: - INDIVIDUAL - TRUST - ORGANISATION type: string enumFunctionStatus: description: | High level indication of the final disposition of a backgrounded function - "COMPLETED": the request completed (not that the final result is a success, just that we completed) - "FAILED": the request failed. - "INCOMPLETE": could not complete the request. enum: - COMPLETED - FAILED - INCOMPLETE example: COMPLETED type: string 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) enum: - U - F - M - O example: F type: string 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 - "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) - "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 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. Special document types - "CHECK_RESULTS": A special document type for specifying results of checks completed other than through Frankie. enum: - OTHER - DRIVERS_LICENCE - PASSPORT - VISA - IMMIGRATION - NATIONAL_ID - TAX_ID - NATIONAL_HEALTH_ID - CONCESSION - 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 - EXTERNAL_ADMIN - CHARGES - PRE_ASIC - ANNUAL_RETURN - REPORT - CHECK_RESULTS example: DRIVERS_LICENCE type: string 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. 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.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: general.string type: string 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 enum: - image/jpeg - image/png - image/gif - image/webp - image/tiff - image/bmp - application/zip - application/x-tar - application/x-rar-compressed - 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 - application/msword - application/vnd.openxmlformats-officedocument.wordprocessingml.document - application/vnd.ms-excel - application/vnd.openxmlformats-officedocument.spreadsheetml.sheet - application/vnd.ms-powerpoint - application/vnd.openxmlformats-officedocument.presentationml.presentation - video/mp4 - video/webm - video/quicktime - video/x-msvideo - video/x-ms-wmv - video/mpeg example: image/png type: string enumNotificationType: description: | Indicates the type of notification being pushed. - "FUNCTION": A request that you previously backgrounded has completed and this is the notification that is it complete (success is another matter) - "RESULT": Like the FUNCTION notification, this tells you that a previously backgrounded request has completed, and that there is a set of results in the payload pointer. - "EVENT": There has been a stateful change in a document, entity or some other piece of data that we are holding/monitoring for you. This is an indication that you may wish to take some action. - "ALERT": Like the EVENT, except that the severity of the notification indicates that action is almost certainly required. enum: - FUNCTION - RESULT - EVENT - ALERT type: string 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. enum: - NORMAL - EXCLUDED - FAILED example: NORMAL type: string enumScanSide: description: Describes if a scan is of the "F"ront or "B"ack of an ID. If not supplied, Front is always assumed. enum: - F - B example: F type: string 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) enum: - PHOTO - VIDEO - AUDIO - PDF - DOC - ZIP example: PDF type: string enumSearchResultConfidence: description: | Defines how close a match we were able to make based on search results. - "LOW": The item does match the minimum criteria given, but is potentially one of a number of possible hits - "MEDIUM": The item matches multiple search criteria, but there is still some potential ambiguity with other hits - "HIGH": Matches all given search criteria, but there were other potential hits - "DEFINITE": Was the only item to match all given search criteria. enum: - LOW - MEDIUM - HIGH - DEFINITE example: HIGH type: string 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. items: $ref: "#/definitions/generalCheckResultObject" type: array generalCheckResultObject: description: Contains the details of a check on a given data point properties: checkProcessResults: $ref: "#/definitions/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". example: Bank type: string type: object