KYC integration information

Suggest Edits

Integration Information

To integrate FrankieOne KYC we need to do the following steps:

Create New Entity

We need to create an entity to get an entityID and populate details.

Note: You could do a verify action in this step, or you can do it in two steps. Both options are possible. We do recommend you pass through a customer_reference when creating an entity, which is a unique identifier for your customer.

POST
https://api.kycaml.frankiefinancial.com/compliance/v1.2/entity

API reference: Create New Entity

🚧

Collect the entityID

Ensure to collect the entity ID from the response, to be able to update in subsequent calls.

Update Entity

Update an entity when needed, to avoid creating a new entity every time.

POST
https://api.kycaml.frankiefinancial.io/compliance/v1.2/entity/{entityId}

API reference: Update Existing Entity

Pass through consent capture

The following Extra data elements are important to pass through consent capture as per your obligations to consent. Customer reference is recommended to have alignment between your customer record and the FrankieOne entityID.

        "extraData": [
            {
                "kvpKey": "consent.general",
                "kvpValue": "true",
                "kvpType": "general.bool"
            },
            {
                "kvpKey": "consent.docs",
                "kvpValue": "true",
                "kvpType": "general.bool"
            },
            {
                "kvpKey": "consent.creditheader",
                "kvpValue": "true",
                "kvpType": "general.bool"
            },
            {
                "kvpKey": "consent.under18",
                "kvpValue": "true",
                "kvpType": "general.bool"
            },
            {
                "kvpKey": "customer_reference",
                "kvpValue": "cust_001",
                "kvpType": "id.external"
            }
        ],

❗️

Ensure correct consents are sent

Please ensure you send the correct consents; we do apply logic on our verification checks. For example, if a consent data source and we do not receive the API consent flag for that data source we will likely reject the verification check on that data source, such as credit headers.

For the under18 consent flag please only send this if your customer is under 18 (using DOB). If they are 18 you do not need to send this. Please ensure you read the notes on the consent page and if unclear please ask about consent.

Learn more about consent.

Search for Entity

In case someone is coming back into their preexisting sign up process, you can “search” for existing customers using the customer_reference.

It’s always best to maintain the status of a customer and update existing vs being stateless and creating new entities each time.

POST
https://api.kycaml.frankiefinancial.io/compliance/v1.2/entity/search

Body of the call

{
    "extraData": [
        {
            "kvpKey": "customer_reference",
            "kvpValue": "01FTVQHK4WDZCRV5ABHZDYSQVF",
            "kvpType": "id.external"
        }
    ]
}

API reference: Search for Entity

Update Data

When you need to update the data in your records, you can the FrankieOne API. Follow the instructions in Updating Data Through the API.

Verify Checks

We recommend verifying checks to ensure the latest details are verified. Verifying checks can also be done at the Create or Update stage. If there are no changes to key attributes such as Name, DOB or Address then previous results can still be used. This applies as long as they are still within the reasonable time period (age is a configuration for how long checks last).

API references:
Create and Verify Entity
Update Entity and Verify Details

POST
https://api.kycaml.frankiefinancial.com/compliance/v1.2/entity/{entityid}/verify/profile/full

entityProfile = international, safe_harbour_id

Refer to Standard entity profile verificationStandard entity profile verification for a list of entity profiles available in demo.

We can also set up a custom profile as part of onboarding.

If you would like biometrics, we can also include the additional API calls. To learn more about ID verification (IDV), OCR, and biometrics integrations, vist IDV Service Flows.

Set up webhooks

It’s important to set up webhook notifications as detailed in Notifications - Webhooks

Set up asynchronous Get results

The FrankieOne API will allow both synchronous and asynchronous processes to run in many operations. The choice can be made on a request-by-request basis too.

By default, all functions are synchronous (with some exceptions, see Note below). However, where appropriate you can set a header flag:

X-Frankie-Background: 1

This will indicate to the function that you wish to operate asynchronously. This is not available for all functions (such as GET functions), so check the specific documentation to be sure. To learn more, visit Asynchronous Calls (Background Processes)

Attach support docs

Use the FrankieOne API to Create New Document.

You can also Update Existing Document.:

📘

Use with entityProfile

Pease use with entityProfile that has support docs activated to ensure we check support docs.

Get check results

You can also pull details down at any time using GET on the /entity/{entityId}/checks endpoint. Learn more on how to Retrieve Entity Verification Check Details.

Explanation of key attributes

Name

Attribute: name

      "name": {
           "familyName": "Last",
           "givenName": "Test",
           "middleName": "Two"
      }

In Australia, the document verification service accepts a hyphen as the first name and the single name in the FamilyName field. This can be used for verifying single name applicants in Australia through the portal

To learn more about verifying single name applicants DVS checks in Australia, read Verifying Single Name Applicants.

📘

Note on prompts

Ideally, there should be prompt as per the ID document.

Native Name

Attribute: home_country_givenname, home_country_familyname

Local home country support is available for native script names.

Extra Data KVP on the entity records can be used.

        {
            "kvpKey": "home_country_givenname",
            "kvpValue": "山本"
        },
        {
            "kvpKey": "home_country_familyname",
            "kvpValue": "健太"
        }

Date of birth (DOB)

Attribute: dateOfBirth

Format: yyyy-mm-dd

We would need you to concatenate your DOB, we do have a yearofBirth, but not specifically Day or Month.

 "entity": {
      "dateOfBirth": {
           "dateOfBirth": "1990-01-01"
      }
 }

Email Address

The email address is one of the Identity Docs accepted.

To learn more about using an email address as an identity document, read about Adding an Email Address 

"identityDocs": [
{  "country" : "JPN",
  "idNumber" : "[email protected]",
  "idType" : "EMAIL_ADDRESS"
}

Mobile Phone

A mobile phone number is one of the identity docs accepted.

To learn more about using a mobile phone number as an identity document, read about Adding a Mobile Phone Number 

   "identityDocs": [
    
 {  
    "country" : "JPN",  
    "idNumber" : "+8145313",  
    "idType" : "MSISDN"  
 }

Document

Learn more about the document object at The Document Object.

{
				"country": "JPN",
				"docScan": [
					{
						"scanData": "BASE64 ENCODED DATA",
						"scanDocId": "7cd911d4-d9a1-a784-705f-39a7a97bf26b",
						"scanFilename": "Scanned Documents.pdf",
						"scanMIME": "application/pdf",
						"scanSide": "F"
					}
				],
				"documentId": "9948498d-248b-df9d-fe0f-617709b24081",
				"extraData": [
					{
						"kvpKey": "supporting_docs.label",
						"kvpValue": "House Registration"
					},
					{
						"kvpKey": "supporting_docs.status",
						"kvpValue": "Needs Review"
					}
					
				],
				"idExpiry": "0001-01-01",
				"idIssued": "0001-01-01",
				"idType": "HOUSE_REGISTRATION""
			}

Passport

Name: Requires given, middle and family names as shown on the passport

Date of Birth: Always in YYYY-MM-DD format

ID Type: idType = PASSPORT

Country: AUS

Document Number: idNumber = The passport number

Expiry Date: idExpiry = the expiry date YYYY-MM-DD format

Learn more about the AUS: Passport.

    "identityDocs": [
        {
            "idType": "PASSPORT",
            "country": "AUS",
            "idNumber": "P32516383"
        }
    ],

Learn more about the International: Passport

"identityDocs": [
    {
        "idType": "PASSPORT",
        "idSubType": "",
        "country": "JPN",
        "region": "",
        "idNumber": "ABC-123456789",
        "idExpiry": "2025-10-01"
    },

Drivers Licence

State: region - one of: VIC/NSW/ACT/WA/SA/NT/QLD/TAS - For Australian Drivers Licence

Licence Number: idNumber = The licence number (not document number as given on some state licences - see below)

Document Number: extraData

KvpKey: "document_number",

KvpValue: "nnnnnnn…" This is the new document number being introduced from 1st July 2022 on Australian licences (in NSW).

Learn more about AUS: Driver's Licence

"identityDocs": \[  
            {  
                "idType": "DRIVERS_LICENCE",  
                "country": "AUS",  
                "region": "NSW",  
                "idNumber": "N49187",  
                "extraData": [  
                    {  
                        "KvpKey": "document_number",  
                        "KvpValue": "21631234"  
                    }  
                ]  
            }  
        ]  
"identityDocs": [  
            {  
                "idType": "DRIVERS_LICENCE",  
                "country": "AUS",  
                "region": "ACT",  
                "idNumber": "0123456789"  
            }  
        ],  
"identityDocs": [  
            {  
                "idType": "DRIVERS_LICENCE",  
                "country": "JPN",  
                "idNumber": "0123456789"  
            }  
        ],

Medicare

Name: Requires given, middle initial and family names as shown on the card

Date of Birth: Always in YYYY-MM-DD format

ID Type: idType = NATIONAL_HEALTH_ID

Country: AUS

Number: idNumber = The full card number

Colour: idSubType = G|B|Y (choice of Green Blue or Yellow)

Expiry: idExpiry = YYYY-MM-DD (note: Green cards only have YYYY-MM so you need to append -01 for the -DD)

Reference number: extraData

Example:

  • KvpKey: "reference",
  • KvpValue: "n" ( where n is a number 1< n < 6 )

Middle name/initial on card: (optional) extraData

Example

  • KvpKey: "display_middle_name",
  • KvpValue: "J"

Learn more about AUS: Medicare Card

     "identityDocs": [
        {
            "country": "AUS",
            "idSubType": "B",
            "idNumber": "2952216811",
            "idExpiry":"2021-01-01",
            "idType": "NATIONAL_HEALTH_ID",
            "extraData": [
                {
                    "kvpKey": "reference",
                    "kvpValue": "1",
                    "kvpType": "general.string"
                }
            ]
        }

Address

Long form or structured:

town - in Smart UI label is Suburb

state - VIC/NSW/ACT/WA/SA/NT/QLD/TAS

postalCode - 4 digits

country - AUS

Example:

Japanese:

"addresses": [
    {
        "addressType": "RESIDENTIAL1",
        "buildingName": "",
        "unitNumber": "",
        "streetNumber": "",
        "streetName": "4 Chome-11-2 Minamiazabu",
        "streetType": "",
        "suburb": "",
        "town": "Minato City",
        "region": "",
        "state": "Tokyo",
        "country": "JPN",
        "postalCode": "106-0047",
        "longForm": "4 Chome-11-2 Minamiazabu , Minato City, Tokyo 106-0047"
    }

Unstructured or longform:

    "addresses": [
        {
            "country": "AUS",
            "longForm": " 2 Brown St IPSWICH QLD 4305 AU"
        }
    ],

Frankie has geolocation.

Australian:

    "addresses": [
        {
            "addressType": "RESIDENTIAL1",
            "country": "AUS",
            "longForm": "2/176 Buckwell Drive, HASSALL GROVE New South Wales 2761, Australia",
            "postalCode": "2761",
            "state": "NSW",
            "streetName": "Buckwell",
            "streetNumber": "176",
            "streetType": "Drive",
            "town": "HASSALL GROVE",
            "unitNumber": "2""
        }

National ID

Visit the following pages to learn more about using nation IDs:

Updated 5 months ago