> ## Documentation Index
> Fetch the complete documentation index at: https://docs.frankieone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# KYC integration information

## 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.

```txt HTTP theme={null}
    POST  
    https://api.kycaml.frankiefinancial.com/compliance/v1.2/entity  
```

API reference: [Create New Entity](/docs/v1/api/kyc-api-endpoints/reference/entity/create-entity)

<Info>
  ##### Collect the entityID

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

### Update Entity

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

```txt HTTP theme={null}
    POST   
    https://api.kycaml.frankiefinancial.io/compliance/v1.2/entity/{entityId}  
```

API reference: [Update Existing Entity](/docs/v1/api/kyc-api-endpoints/reference/entity/update-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.

```json theme={null}
            "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"  
                }  
            ],  
```

<Callout icon="bell" color="#FFCA16" iconType="regular">
  ##### 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 don’t 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’re 18 or older you don’t need to send this. Please ensure you read the notes on the consent page and if unclear please ask [about consent](/docs/v1/kyc/kyc-info/consent).
</Callout>

Learn more [about consent](/docs/v1/kyc/kyc-info/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.

```txt HTTP     theme={null}
    
    POST    
    https://api.kycaml.frankiefinancial.io/compliance/v1.2/entity/search  
```

**Body of the call**

```json JSON theme={null}
{  
  "extraData": [  
    {  
      "kvpKey": "customer_reference",  
      "kvpValue": "01FTVQHK4WDZCRV5ABHZDYSQVF",  
      "kvpType": "id.external"  
    }  
  ]  
}  
```

API reference: [Search for Entity](/docs/v1/api/kyc-api-endpoints/reference/entity/search-entity)

### Update Data

When you need to update the data in your records, you can use the FrankieOne 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’re still within the reasonable time period (age is a configuration for how long checks last).

API references:\
[Create and Verify Entity](/docs/v1/api/kyc-api-endpoints/reference/entity/create-check-entity)\
[Update Entity and Verify Details](/docs/v1/api/kyc-api-endpoints/reference/entity/update-check-entity)

```txt HTTP theme={null}
    POST    
    https://api.kycaml.frankiefinancial.com/compliance/v1.2/entity/{entityid}/verify/profile/full  
```

`entityProfile` = `international`, `safe_harbour_id`

Refer to [Standard entity profile verification](/docs/v1/kyc/understanding-entity-profile-kyc-results) 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](/docs/v1/kyc/kyc-info/idv-service-flows).

### Set up webhooks

It’s important to set up webhook notifications as detailed in [Notifications - Webhooks](/docs/v1/api/guide-to-the-api/getting-started/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 isn’t available for all functions (such as GET functions), so check the specific documentation to be sure. To learn more, visit [Asynchronous Calls (Background Processes)](/docs/v1/api/guide-to-the-api/getting-started/asynchronous-calls-backgrounding-processes)

### Attach support docs

Use the FrankieOne API to [Create New Document.](/docs/v1/api/kyc-api-endpoints/reference/document/create-document)

You can also [Update Existing Document.](/docs/v1/api/kyc-api-endpoints/reference/document/update-document):

<Callout icon="thumbtack" color="#1A6CFF" iconType="regular">
  ##### Use with `entityProfile`

  Please use with `entityProfile` that has support docs activated to ensure we check support docs.
</Callout>

### 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](/docs/v1/api/kyc-api-endpoints/reference/entity/query-entity).

## Explanation of key attributes

### Name

Attribute: `name`

```json JSON    theme={null}
    
          "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](/docs/v1/api/guide-to-the-api/data-types/names-with-different-character-sets).

<Callout icon="thumbtack" color="#1A6CFF" iconType="regular">
  ##### Note on prompts

  Ideally, there should be prompt as per the ID document.
</Callout>

### 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.

```json JSON     theme={null}
    
            {  
                "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.

```json JSON theme={null}
     "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](/docs/v1/api/guide-to-the-api/data-types/adding-an-email-address)

```json JSON theme={null}
    "identityDocs": [  
    {  "country" : "JPN",  
      "idNumber" : "6jhjgy6622@gmail.com",  
      "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](/docs/v1/api/guide-to-the-api/data-types/adding-a-mobile-phone-number)

```json JSON theme={null}
       "identityDocs": [  

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

### Document

Learn more about the document object at [The Document Object](/docs/v1/api/guide-to-the-api/common-api-objects-fields/fundamentals-document-object).

```json JSON  theme={null}
    {  

    				"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](/docs/v1/api/guide-to-the-api/common-api-objects-fields/fundamentals-document-object): 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](/docs/v1/introduction/important-notices/au-drivers-license#australian-passports--visas).

```json JSON theme={null}
        "identityDocs": [  
            {  
                "idType": "PASSPORT",  
                "country": "AUS",  
                "idNumber": "P32516383"  
            }  
        ],  
```

Learn more about the [International: Passport](/docs/v1/api/guide-to-the-api/country-specific-id-document-requirements/international-national-id)

```json JSON theme={null}
    "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](/docs/v1/introduction/important-notices/au-drivers-license)

```json JSON theme={null}
    "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](/docs/v1/introduction/important-notices/au-drivers-license#medicare-cards)

```json JSON theme={null}
         "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** :

* `unitNumber`
* `streetNumber`
* `streetName`
* `streetType` - drop down (see [ Street types in our Australia dataset - FAQ](https://addressfinder.com.au/faq/can-you-provide-a-list-of-street-types-au/) for a list) or input

\*\*town \*\*- in Smart UI label is Suburb

\*\*state \*\*- `VIC`/`NSW`/`ACT`/`WA`/`SA`/`NT`/`QLD`/`TAS`

\*\*postalCode \*\*- 4 digits

**country** - AUS

#### **Example** :

**Japanese** :

```json JSON theme={null}
    "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:

```json JSON     theme={null}
    
        "addresses": [  
            {  
                "country": "AUS",  
                "longForm": " 2 Brown St IPSWICH QLD 4305 AU"  
            }  
        ],  
```

Frankie has geolocation.

Australian:

```json JSON theme={null}
    
        "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:

* [CHN: National ID](/docs/v1/api/guide-to-the-api/country-specific-id-document-requirements/chn-national-id)
* [MEX: National ID](/docs/v1/api/guide-to-the-api/country-specific-id-document-requirements/mex-national-id)
* [THA: National ID](/docs/v1/api/guide-to-the-api/country-specific-id-document-requirements/tha-national-id)
* [International: National ID](/docs/v1/api/guide-to-the-api/country-specific-id-document-requirements/international-national-id)