Quickstart

In this guide, we will go through the verification flow using the bronID API. It will include examples of the API request, API response and runnable examples for each of the cases.

We will cover verifications of:

KYC for individuals

To verify an individual, we need to submit the personal details (such as name, date of birth, address) to the bronID API. Let's use an example where we've collected the details of our user in a JSON object. We can use ok as a middle name to get a verified response in the test environment.

User details

Now we need to submit the user's details to the bronID API. We will submit them to the /verify endpoint, and include the authentication credentials in our API call.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
	"firstName": "Jane",
	"middleName": "ok", /* successful verification test keyword */
	"lastName": "Citizen",
	"gender": "female",
	"dateOfBirth": "20/12/1982",
	"unitNumber": "1",
	"streetNumber": "95",
	"streetName": "Lennox",
	"streetType": "Street",
	"suburb": "CASINO",
	"postcode": "2470",
	"state": "NSW",
	"email": "email@gmail.com"
}

bronID API endpoint

1
https://sandbox.bronid.com/verify

Request body

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
	"metadata_version": "4",
	/* authentication credentials */
	"metadata_serviceUid": "RnbEhVfoQsec7mzehN4xgNA9uoi2",
	"metadata_secretKey": "dev_secret_key",

	/* verification details */
	"type": "individual",
	"fields": {
		"country": "AUS",
		"firstName": "Jane",
		"middleName": "ok",
		"lastName": "Citizen",
		"gender": "female",
		"dateOfBirth": "20/12/1982",
		"unitNumber": "1",
		"streetNumber": "95",
		"streetName": "Lennox",
		"streetType": "Street",
		"suburb": "CASINO",
		"postcode": "2470",
		"state": "NSW",
		"email": "email@gmail.com"
	}
}

API Response

After submitting the data for verification, you will get the verification response. The main parameter of the response is the verificationStatus. In this case, the "verified" response tells us that the verification was successful and we can onboard our customer.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
	"name": "Jane ok Citizen",
	"verificationStatus": "verified", /* the verification was successful */
	"verificationScore": 250,
	"verificationUuid": "2418ab88-d576-4fba-ae1a-2f072fd5cad8",
	"submissionStatus": "submitted",
	"timestamp": 1585197706,
	"inWatchLists": [],
	"outOfWatchLists": [
		{
			"method": "background",
			"name": "International Criminal Police Organization (INTERPOL) Wanted Persons",
			"greenIdCode": "interpolmostwanted",
			"officialUrl": "https://www.interpol.int/How-we-work/Notices/View-Red-Notices"
		},
		{
			"method": "background",
			"name": "Canada Office of the Superintendent of Financial Institutions (OSFI)",
			"greenIdCode": "osfi",
			"officialUrl": "http://www.osfi-bsif.gc.ca/Eng/fi-if/amlc-clrpc/atf-fat/Pages/default.aspx"
		},
		/* ... other watchlists omitted */
}

Click-to-run KYC example - individuals

This is a runnable example of a KYC verification for individuals. Just click the "▶ run" button at the bottom to execute the verification.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
const axios = require('axios');

/* api endpoint */
const apiEndpoint = 'https://sandbox.bronid.com/verify';

/* request body */
const kycData = {
	/* authentication */
	"metadata_version": "4",
	"metadata_serviceUid": "RnbEhVfoQsec7mzehN4xgNA9uoi2",
	"metadata_secretKey": "dev_secret_key",
	
	/* individual details */
	"type": "individual",
	"fields": {
		"country": "AUS",
		"firstName": "Jane",
		"middleName": "ok",
		"lastName": "Citizen",
		"gender": "female",
		"dateOfBirth": "20/10/1980",
		"unitNumber": "1",
		"streetNumber": "95",
		"streetName": "Lennox",
		"streetType": "Street",
		"suburb": "CASINO",
		"postcode": "2470",
		"state": "NSW",
		"email": "email@gmail.com",
	},
};

/* submit the KYC data to the bronID API */
axios
	.post(apiEndpoint, kycData)
	.then(res => {
		/* print the verification results */ 
		console.log('click the results to expand them');
		console.log(JSON.stringify(res.data, null, 2));
	})
	.catch(error => {
		console.error(error)
	})
	
/* Click “▶ run” to try this code live and run your first KYC. */

KYC for private companies

To verify a private company, we need to submit the company details (such as name, company number, registered address) to the bronID API. If there are any shareholders with more than 25% ownership in the company (also called UBOs), we will need to include their details. Let's use an example where we've collected the details of the company in a JSON object.

Company details

Now we need to submit the company details to the bronID API. We will submit them to the /verify endpoint, and include the authentication credentials in our API call.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
/* company details */
{
	"country": "AUS",
	"acn": "123456789",
	"abn": "16123456789",
	"name": "My Company",
	"registeredOffice": "125 York Street, SYDNEY NSW 2000"
}
/* UBO details (>25% ownership) */
{
	"firstName": "Dave",
	"middleName": "ok", /* successful verification test keyword */
	"lastName": "Citizen",
	"gender": "male",
	"dateOfBirth": "20/12/1982",
	"unitNumber": "1",
	"streetNumber": "95",
	"streetName": "Lennox",
	"streetType": "Street",
	"suburb": "CASINO",
	"postcode": "2470",
	"state": "NSW",
	"email": "email@gmail.com",
	"country": "AUS"
}

API endpoint

1
https://sandbox.bronid.com/verify

Request body

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
{
	"metadata_version": "4",
	/* authentication credentials */
	"metadata_serviceUid": "RnbEhVfoQsec7mzehN4xgNA9uoi2",
	"metadata_secretKey": "dev_secret_key",

	/* entity details */
	"type": "privateCompany",
	"fields": {
		"country": "AUS",
		"acn": "123456789",
		"abn": "16123456789",
		"name": "My Company",
		"registeredOffice": "125 York Street, SYDNEY NSW 2000"
	},
	"stakeholders": [
		/* UBO details (>25% ownership) */
		{
			"type": "individual",
			"role": "shareholders",
			"fields": {
				"firstName": "Dave",
				"middleName": "ok",
				"lastName": "Citizen",
				"gender": "male",
				"dateOfBirth": "20/12/1982",
				"unitNumber": "1",
				"streetNumber": "95",
				"streetName": "Lennox",
				"streetType": "Street",
				"suburb": "CASINO",
				"postcode": "2470",
				"state": "NSW",
				"email": "email@gmail.com",
				"country": "AUS"
			}
		}
	]
}

API Response

After submitting the data for verification, you will receive the verification response. The main parameter of the response is the verificationStatus of the private company. There is also another verificationStatus relating to the shareholder. In this case, the "pending" response tells us that the verification is processing and we will receive an update with the final result via webhook. The webhook structure will have the same format, but different values for the verificationStatus.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{
	"name": "My Company",
	"verificationStatus": "pending", /* entity verification status */
	"verificationUuid": "13eee6de-d20f-42d0-b3e2-73bc8fd05e98",
	"timestamp": 1585200856,
	"submissionStatus": "submitted",
	"stakeholders": [
		{
			"name": "Dave ok Citizen",
			"role": "shareholders",
			"id": "317cdfae-2e38-48c6-b443-1f75f488d52e",
			"verificationStatus": "verified", /* UBO verification status */
			"verificationScore": 250,
			"verificationUuid": "0ae5a22c-840d-45c6-aa2a-244950556c45",
			"submissionStatus": "submitted",
			"timestamp": 1585200856,
			"inWatchLists": [],
			"outOfWatchLists": [
				{
					"method": "background",
					"name": "International Criminal Police Organization (INTERPOL) Wanted Persons",
					"greenIdCode": "interpolmostwanted",
					"officialUrl": "https://www.interpol.int/How-we-work/Notices/View-Red-Notices"
				},
				{
					"method": "background",
					"name": "Canada Office of the Superintendent of Financial Institutions (OSFI)",
					"greenIdCode": "osfi",
					"officialUrl": "http://www.osfi-bsif.gc.ca/Eng/fi-if/amlc-clrpc/atf-fat/Pages/default.aspx"
				},
				/* ... other watchlists omitted */
			]
		}
	]
}

Click-to-run KYC example - private company

This is a runnable example of a KYC verification for private companies. Just click the "▶ run" button at the bottom to execute the verification.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
const axios = require('axios');

/* api endpoint */
const apiEndpoint = 'https://sandbox.bronid.com/verify';

/* request body */
const kycData = {
	/* authentication */
	"metadata_version": "4",
	"metadata_serviceUid": "RnbEhVfoQsec7mzehN4xgNA9uoi2",
	"metadata_secretKey": "dev_secret_key",
	
	/* entity details */
	"type": "privateCompany",
	"fields": {
		"country": "AUS",
		"acn": "123456789",
		"abn": "16123456789",
		"name": "My Company",
		"registeredOffice": "125 York Street, SYDNEY NSW 2000"
	},
	/* UBO details (>25% ownership) */
	"stakeholders": [
		{
			"type": "individual",
			"role": "shareholders",
			"fields": {
				"firstName": "Dave",
				"middleName": "ok",
				"lastName": "Citizen",
				"gender": "male",
				"dateOfBirth": "20/10/1980",
				"unitNumber": "1",
				"streetNumber": "95",
				"streetName": "Lennox",
				"streetType": "Street",
				"suburb": "CASINO",
				"postcode": "2470",
				"state": "NSW",
				"email": "email@gmail.com",
				"country": "AUS"
			}
		}
	]
};

/* submit the KYC data to the bronID API */
axios
	.post(apiEndpoint, kycData)
	.then(res => {
		/* print the verification results */ 
		console.log('click the results to expand them');
		console.log(JSON.stringify(res.data, null, 2));
	})
	.catch(error => {
		console.error(error)
	})
	
/* Click “▶ run” to try this code live and run your first KYC. */

KYC for unregulated trusts

To verify an unregulated trust, we need to submit the trust details (such as name, registered address, trust deed) to the bronID API. When verifying an unregulated trust, we have to include the details of the trustee, and potentially of any beneficiaries. Let's use an example where we've collected the details of the trust in a JSON object.

Unregulated trust details

Now we need to submit the trust details to the bronID API. We will submit them to the /verify endpoint, and include the authentication credentials in our API call.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
/* trust details */
{
	"country": "AUS",
	"name": "My Unregulated Trust",
	"unRegulatedTrustType": "familyTrust",
	"registeredOffice": "125 York Street, SYDNEY NSW 2000",
	"uploadTrustDeed": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg=="
}
/* trustee */
{
	"firstName": "Dave",
	"middleName": "ok", /* successful verification test keyword */
	"lastName": "Citizen",
	"gender": "male",
	"dateOfBirth": "20/12/1982",
	"unitNumber": "1",
	"streetNumber": "95",
	"streetName": "Lennox",
	"streetType": "Street",
	"suburb": "CASINO",
	"postcode": "2470",
	"state": "NSW",
	"email": "email@gmail.com",
	"country": "AUS"
}
/* beneficiary */
{
	"firstName": "Jane",
	"middleName": "ok", /* successful verification test keyword */
	"lastName": "Citizen",
	"gender": "female",
	"dateOfBirth": "20/12/1982",
	"unitNumber": "1",
	"streetNumber": "95",
	"streetName": "Lennox",
	"streetType": "Street",
	"suburb": "CASINO",
	"postcode": "2470",
	"state": "NSW",
	"email": "email@gmail.com",
	"country": "AUS"
}

API endpoint

1
https://sandbox.bronid.com/verify

Request body

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
{
	"metadata_version": "4",
	/* authentication credentials */
	"metadata_serviceUid": "RnbEhVfoQsec7mzehN4xgNA9uoi2",
	"metadata_secretKey": "dev_secret_key",

	/* trust details */
	"type": "unRegulatedTrust",
	"fields": {
		"country": "AUS",
		"name": "My Unregulated Trust",
		"unRegulatedTrustType": "familyTrust",
		"registeredOffice": "125 York Street, SYDNEY NSW 2000",
		"uploadTrustDeed": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg=="
	},
	"stakeholders": [
		/* trustee details */
		{
			"type": "individual",
			"role": "trustee",
			"fields": {
				"firstName": "Dave",
				"middleName": "ok",
				"lastName": "Citizen",
				"gender": "male",
				"dateOfBirth": "20/12/1982",
				"unitNumber": "1",
				"streetNumber": "95",
				"streetName": "Lennox",
				"streetType": "Street",
				"suburb": "CASINO",
				"postcode": "2470",
				"state": "NSW",
				"email": "email@gmail.com",
				"country": "AUS"
			}
		},
		/* beneficiary details */
		{
			"type": "individual",
			"role": "beneficiaries",
			"fields": {
				"firstName": "Jane",
				"middleName": "ok",
				"lastName": "Citizen",
				"gender": "female",
				"dateOfBirth": "20/12/1982",
				"unitNumber": "1",
				"streetNumber": "95",
				"streetName": "Lennox",
				"streetType": "Street",
				"suburb": "CASINO",
				"postcode": "2470",
				"state": "NSW",
				"email": "email@gmail.com",
				"country": "AUS"
			}
		}
	]
}

API Response

After submitting the data for verification, you will receive the verification response. The main parameter of the response is the verificationStatus of the unregulated trust. There is also another verificationStatus relating to the trustee and the beneficiary. In this case, the "pending" response tells us that the verification is processing and we will receive an update with the final result via webhook. The webhook structure will have the same format, but different values for the verificationStatus.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
{
	"name": "My Unregulated Trust",
	"verificationStatus": "pending", /* entity verification status */
	"verificationUuid": "72618a1a-7d45-445b-8f6f-03626948459c",
	"timestamp": 1585201451,
	"submissionStatus": "submitted",
	"stakeholders": [
		{
			"name": "Dave ok Citizen",
			"role": "trustee",
			"id": "9d906f3a-79e4-4ecf-a3b8-f6dcbc12d3e2",
			"verificationStatus": "verified", /* trustee verification status */
			"verificationScore": 250,
			"verificationUuid": "799868c5-7bda-4263-b62c-4a1ed17bc051",
			"submissionStatus": "submitted",
			"timestamp": 1585201451,
			"inWatchLists": [],
			"outOfWatchLists": [
				{
					"method": "background",
					"name": "International Criminal Police Organization (INTERPOL) Wanted Persons",
					"greenIdCode": "interpolmostwanted",
					"officialUrl": "https://www.interpol.int/How-we-work/Notices/View-Red-Notices"
				},
				{
					"method": "background",
					"name": "Canada Office of the Superintendent of Financial Institutions (OSFI)",
					"greenIdCode": "osfi",
					"officialUrl": "http://www.osfi-bsif.gc.ca/Eng/fi-if/amlc-clrpc/atf-fat/Pages/default.aspx"
				},
				/* ... other watchlists omitted */
			]
		},
		{
			"name": "Jane ok Citizen",
			"role": "beneficiaries",
			"id": "52e7ad94-ea8c-4694-8b48-01816ae6e190",
			"verificationStatus": "verified", /* beneficiary verification status */
			"verificationScore": 250,
			"verificationUuid": "3953af92-55d4-46a1-9568-495ee904f4f5",
			"submissionStatus": "submitted",
			"timestamp": 1585201451,
			"inWatchLists": [],
			"outOfWatchLists": [
				{
					"method": "background",
					"name": "International Criminal Police Organization (INTERPOL) Wanted Persons",
					"greenIdCode": "interpolmostwanted",
					"officialUrl": "https://www.interpol.int/How-we-work/Notices/View-Red-Notices"
				},
				{
					"method": "background",
					"name": "Canada Office of the Superintendent of Financial Institutions (OSFI)",
					"greenIdCode": "osfi",
					"officialUrl": "http://www.osfi-bsif.gc.ca/Eng/fi-if/amlc-clrpc/atf-fat/Pages/default.aspx"
				},
				/* ... other watchlists omitted */
			]
		}
	]
}

Click-to-run KYC example - unregulated trust

This is a runnable example of a KYC verification for unregulated trusts. Just click the "▶ run" button at the bottom to execute the verification.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
const axios = require('axios');

/* api endpoint */
const apiEndpoint = 'https://sandbox.bronid.com/verify';

/* request body */
const kycData = {
	"metadata_version": "4",
	/* authentication */
	"metadata_serviceUid": "RnbEhVfoQsec7mzehN4xgNA9uoi2",
	"metadata_secretKey": "dev_secret_key",
	
	/* entity details */
	"type": "unRegulatedTrust",
	"fields": {
		"country": "AUS",
		"name": "My Unregulated Trust",
		"unRegulatedTrustType": "familyTrust",
		"registeredOffice": "125 York Street, SYDNEY NSW 2000",
		"uploadTrustDeed": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg=="
	},
	"stakeholders": [
		/* trustee details */
		{
			"type": "individual",
			"role": "trustee",
			"fields": {
				"firstName": "Dave",
				"middleName": "ok",
				"lastName": "Citizen",
				"gender": "male",
				"dateOfBirth": "20/12/1982",
				"unitNumber": "1",
				"streetNumber": "95",
				"streetName": "Lennox",
				"streetType": "Street",
				"suburb": "CASINO",
				"postcode": "2470",
				"state": "NSW",
				"email": "email@gmail.com",
				"country": "AUS"
			}
		},
		/* beneficiary details */
		{
			"type": "individual",
			"role": "beneficiaries",
			"fields": {
				"firstName": "Jane",
				"middleName": "ok",
				"lastName": "Citizen",
				"gender": "female",
				"dateOfBirth": "20/12/1982",
				"unitNumber": "1",
				"streetNumber": "95",
				"streetName": "Lennox",
				"streetType": "Street",
				"suburb": "CASINO",
				"postcode": "2470",
				"state": "NSW",
				"email": "email@gmail.com",
				"country": "AUS"
			}
		}
	]
};

// submit the KYC data to the bronID API
axios
	.post(apiEndpoint, kycData)
	.then(res => {
		// print the verification results 
		console.log('click the results to expand them');
		console.log(JSON.stringify(res.data, null, 2));
	})
	.catch(error => {
		console.error(error)
	})
	
// Click “▶ run” to try this code live and run your first KYC.