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

{
	"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

https://dev.bronid.com/verify

Request body

{
	"metadata_version": "4",
	/* authentication credentials */
	"metadata_serviceUid": "XL7ULiU6B4QE9Y2iWFZnhtMDKFN2",
	"metadata_secretKey": "api_sec_NJAtNcRtUrPlf7xYDrMNP9URI-ZfN314",

	/* 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.

{
	"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",
			"officialUrl": "https://www.interpol.int/How-we-work/Notices/View-Red-Notices"
		},
		{
			"method": "background",
			"name": "Canada Office of the Superintendent of Financial Institutions (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 of individuals. Just click the "▶ run" button at the bottom to execute the verification.
/* api endpoint */
const apiEndpoint = 'https://dev.bronid.com/verify';

/* request body */
const kycData = {
	/* authentication */
	"metadata_version": "4",
	"metadata_serviceUid": "XL7ULiU6B4QE9Y2iWFZnhtMDKFN2",
	"metadata_secretKey": "api_sec_NJAtNcRtUrPlf7xYDrMNP9URI-ZfN314",
	
	/* 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",
	},
};

console.log('Running request...')

// submit the KYC data to the bronID API
try {
	const response = await fetch(apiEndpoint, {
		method: 'POST',
		headers: {
			'Content-Type': 'application/json',
		},
		body: JSON.stringify(kycData),
	});

	if (!response.ok) {
		const errorData = await response.json();
		console.log('error! click the results to expand them');
		console.log(JSON.stringify(errorData, null, 2));
	} else {
		const bronIdResult = await response.json();
		const printResult = 'bronId API response: ' + JSON.stringify(bronIdResult, null, 2);
		console.log(printResult);
	}
} catch (error) {
	console.log('Fetch error: ', error);
}

	
/* Click “▶ run” to try this code live and run your first KYC. */

KYC of 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.

/* 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

https://dev.bronid.com/verify

Request body

{
	"metadata_version": "4",
	/* authentication credentials */
	"metadata_serviceUid": "XL7ULiU6B4QE9Y2iWFZnhtMDKFN2",
	"metadata_secretKey": "api_sec_NJAtNcRtUrPlf7xYDrMNP9URI-ZfN314",

	/* 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
.

{
	"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",
					"officialUrl": "https://www.interpol.int/How-we-work/Notices/View-Red-Notices"
				},
				{
					"method": "background",
					"name": "Canada Office of the Superintendent of Financial Institutions (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 of private companies. Just click the "▶ run" button at the bottom to execute the verification.
/* api endpoint */
const apiEndpoint = 'https://dev.bronid.com/verify';

/* request body */
const kycData = {
	/* authentication */
	"metadata_version": "4",
	"metadata_serviceUid": "XL7ULiU6B4QE9Y2iWFZnhtMDKFN2",
	"metadata_secretKey": "api_sec_NJAtNcRtUrPlf7xYDrMNP9URI-ZfN314",
	
	/* 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"
			}
		}
	]
};

console.log('Running request...')

// submit the KYC data to the bronID API
try {
	const response = await fetch(apiEndpoint, {
		method: 'POST',
		headers: {
			'Content-Type': 'application/json',
		},
		body: JSON.stringify(kycData),
	});

	if (!response.ok) {
		const errorData = await response.json();
		console.log('error! click the results to expand them');
		console.log(JSON.stringify(errorData, null, 2));
	} else {
		const bronIdResult = await response.json();
		const printResult = 'bronId API response: ' + JSON.stringify(bronIdResult, null, 2);
		console.log(printResult);
	}
} catch (error) {
	console.log('Fetch error: ', error);
}

	
/* Click “▶ run” to try this code live and run your first KYC. */

KYC of 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.

Note on uploading documents

Base64 encoded uploads must be submitted as a Data URI (with data format prefix). Example PDF format:

data:application/pdf;base64,JVBERi0xLjUKJYCBgoMKMSAwIG9i...

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.

// 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

https://dev.bronid.com/verify

Request body

{
	"metadata_version": "4",
	/* authentication credentials */
	"metadata_serviceUid": "XL7ULiU6B4QE9Y2iWFZnhtMDKFN2",
	"metadata_secretKey": "api_sec_NJAtNcRtUrPlf7xYDrMNP9URI-ZfN314",

	/* 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
.

{
	"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",
					"officialUrl": "https://www.interpol.int/How-we-work/Notices/View-Red-Notices"
				},
				{
					"method": "background",
					"name": "Canada Office of the Superintendent of Financial Institutions (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",
					"officialUrl": "https://www.interpol.int/How-we-work/Notices/View-Red-Notices"
				},
				{
					"method": "background",
					"name": "Canada Office of the Superintendent of Financial Institutions (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 of unregulated trusts. Just click the "▶ run" button at the bottom to execute the verification.
/* api endpoint */
const apiEndpoint = 'https://dev.bronid.com/verify';

/* request body */
const kycData = {
	"metadata_version": "4",
	/* authentication */
	"metadata_serviceUid": "XL7ULiU6B4QE9Y2iWFZnhtMDKFN2",
	"metadata_secretKey": "api_sec_NJAtNcRtUrPlf7xYDrMNP9URI-ZfN314",
	
	/* 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"
			}
		}
	]
};

console.log('Running request...')

// submit the KYC data to the bronID API
try {
	const response = await fetch(apiEndpoint, {
		method: 'POST',
		headers: {
			'Content-Type': 'application/json',
		},
		body: JSON.stringify(kycData),
	});

	if (!response.ok) {
		const errorData = await response.json();
		console.log('error! click the results to expand them');
		console.log(JSON.stringify(errorData, null, 2));
	} else {
		const bronIdResult = await response.json();
		const printResult = 'bronId API response: ' + JSON.stringify(bronIdResult, null, 2);
		console.log(printResult);
	}
} catch (error) {
	console.log('Fetch error: ', error);
}

	
// Click “▶ run” to try this code live and run your first KYC.