UBO Product

1. Introduction

The Ultimate Beneficial Owner (UBO) product is used for KYC Directors and Owners of legal entities.

The UBO product can also be accessed and used through API calls.

To integrate with the UBO product, as a client you can optionally receive backend notifications, so interaction with the UBO is in your control.

Alternatively ISX can send emails on your behalf.

You can receive UBO notifications on the configured URL from the ISX servers to your notification endpoint.

Operation	Description	Endpoint

Operation	Description	Endpoint
Receive Notification	Notification of UBO event requested via ISX dashboard.	POST https://www.yourserver.com/v1/ubo_notification

The ISX UBO product has 2 notification events:

This occurs when a dashboard operator wants to send a welcome message to the UBO.
This occurs if a UBO has not interacted with the KYC verification process and requires a reminder message.

2. UBO Notification Object

Field	Type	Description	Example

Field	Type	Description	Example
event	String	The event identifier for the notification.	"ubo_welcome",ubo_reminder
profile	Object	The KYC profile of the UBO.
profile.first_name	String	The first name of the UBO.	Joe
profile.last_name	String	The last name of the UBO.	Bloggs
profile.email	String	The email name of the UBO.	joebloggs@email.com
legal_entity	Object	The Legal Entity associated with the UBO.
legal_entity.transaction_amount	String	The amount in cents the UBO will be charged.	2000
legal_entity.transaction_currency	String	The currency of the transaction.	EUR
legal_entity.merchant_id	String	The merchant id where the charge will be attributed.	gateway_r_us
legal_entity.name	String	The name of the legal entity with which the UBO is associated.	Joe Bloggs Fish and Chips
ubo_token	String	The token that can be used to kick off the embed mode of KYC integration on your site.	9016f53d-7b5b-4496-81c2-683fa6dcd69f
ubo_url	String	The URL that the UBO needs to link to start the KYC verification process.	https://verify.isignthis.com/kycstart/9016f53d-7b5b-4496-683fa6dcd69f

Sample JSON Body Notification Object

{
	"event":"ubo_welcome",
	"profile":{
		"first_name":"Joe",
		"last_name":"Bloggs",
		"email":"joebloggs@email.com"
	},
	"legal_entity":{
		"transaction_amount":"2000",
		"transaction_currency":"EUR",
		"merchant_id":"gateway_r_us",
		"name":"Joe Bloggs Fish and Chips"
	},
	"ubo_token":"9016f53d-7b5b-4496-81c2-683fa6dcd69f",
	"ubo_url":"https://verify.isignthis.com/kycstart/9016f53d-7b5b-4496-81c2-683fa6dcd69f"
}

All API calls go through security checks, to validate that data being accessed or altered should only be available for API calls authenticated under the same API Client.

When this check fails, a generic HTTP 404 Not Found error will be returned.

3. Legal Entity Endpoints

Operation	Description	Endpoint

Operation	Description	Endpoint
List Legal Entity	List all Legal Entities under the API client for the API the request was authenticated under.	GET /v1/ubo/entity/list
List Legal Entity Per Merchant	Lists all Legal Entities under the Merchant for the API Client that the API request was authenticated under.	GET /v1/ubo/entity/list/merchant/:merchant_id
Create Legal Entity	Creates the Legal Entity for the API the request was authenticated under.	POST /v1/ubo/entity
Get Legal Entity	Returns Legal Entity Details for the API the request was authenticated under.	GET /v1/ubo/entity/:id
Update Legal Entity	Updates an existing Legal Entity for the API the request was authenticated under.	PUT /v1/ubo/entity/:id
Delete Legal Entity	Deletes an existing Legal Entity, and deletes all existing Beneficiaries stored under that Legal Entity.	DELETE /v1/ubo/entity/:id

4. Beneficiary Endpoints

Operation	Description	Endpoint

Operation	Description	Endpoint
List Beneficiaries	Lists all beneficiaries under the API client for the API the request was authenticated under.	GET /v1/ubo/beneficiary/list/
List Beneficiaries Per Merchant	Lists all Beneficiaries stored under a given merchant.	GET /v1/ubo/beneficiary/list/merchant/:merchant_id
List Beneficiaries Per Entity	Lists all beneficiaries stored under a given legal entity.	GET /v1/ubo/beneficiary/list/entity/:entity_id
Create Beneficiary	Creates a new Beneficiary.	POST /v1/ubo/beneficiary
Get Beneficiary	Returns Beneficiary details.	GET /v1/ubo/beneficiary/:id
Update Beneficiary	Updates an existing Beneficiary.	PUT /v1/ubo/beneficiary/:id
Delete Beneficiary	Deletes an existing Beneficiary.	DELETE /v1/ubo/beneficiary/:id
Generate Tokens	Generates Tokens that can be used to start a KYC transaction to all Beneficiaries designated. They will be assigned Verify URLs to begin the workflow.	POST /v1/ubo/beneficiary/generate_tokens
Flag External Welcome	Flags all Beneficiaries designated as having an external welcome message sent.	POST /v1/ubo/beneficiary/external
Send Welcome	Sends a Welcome Message to start a KYC transaction to all Beneficiaries designated.	POST /v1/ubo/beneficiary/welcome
Reset Beneficiary	Resets a given beneficiary to its initial state.	POST /v1/ubo/beneficiary/reset/:id
Add Beneficiary to Legal Entity	Add’s a list of beneficiaries to a Legal Entity.	POST /v1/ubo/beneficiary/add/:l
Remove Beneficiary from Legal Entity	Remove’s a list of beneficiaries to a Legal Entity.	POST /v1/ubo/beneficiary/remove
Get Beneficiary View Link	Register a user to view the beneficiary details.	POST /v1/ubo/beneficiary/:id/view

5. Environment

We recommend that all our clients test on our production environment.

Production API URL: https://gateway.isignthis.com/v1/

ISX also maintains a sandbox testing environment, which usually runs the latest release candidate of our system.

Integrating with the testing environment is not recommended, as it could prove to be unstable or unreachable at times.

However, if you feel comfortable integrating with a cutting-edge, but possibly unstable version of the system, the ISX relationship management team will provide a staging account for you.

The ISX relationship management team can further detail the pros and cons of working with either environment based on your needs.

6. Authentication

For API operations, you will need an API secret key which will be sent from the ISX relationship management team.

Field Name	Field Value

Field Name	Field Value
From	<api client name>
Authorization	Bearer <API secret key>

Field Name	Field Value

Field Name	Field Value
From	widgets-client.isignthis.com
Authorization	Bearer TEXnkvZCtFucXebHYwrobWhaJhDBTZUs9BpvBTbxWELCCnCQJTKsx6bYNh5fOjEE

The word Bearer must be present in the API token or else an error will result.

7. List Legal Entity

This is the same as the List Beneficiaries request, only it is filtered by the entity they are stored under.

Field	Type	Description	Example

Field	Type	Description	Example
id	String	Unique response identification code.	"76fb860_15a614d9943_9ad"
created_at	String	Creation date of the Legal Entity.	"2017-02-22T00:15:58.808Z"
updated_at	String	Date the Legal Entity was last updated.	"2017-04-26T04:25:57.523Z"
company_name	String	Name of the Company.	"Company XYZ"
transaction_amount	String	The amount of the transaction.	"2000"
transaction_currency	String	The currency of the transaction.	"EUR"
automatic_refund	Boolean	Enabling/Disabling automatic refunds for the Legal Entity.	"TRUE"
automatic_expiry	String	Enabling automatic expiry time in days for the Legal Entity.	"28"
first_reminder	String	Send a reminder email in the configured number of days.	"7"
second_reminder	String	Send a reminder email in the configured number of days.	"21"
contact_name	String	Contact name for the Legal Entity.	"company contact"
contact_email	String	Contact email for the Legal Entity.	"contact@companyXYZ.com"
certificate_common_name	String	The certificate common name for the Legal Entity.	"api client name"
merchant_id	String	The merchant id for the Legal Entity.	"XYZ"

Sample JSON Response

{
	"data":[
		{
			"id":"76fb860_15a614d9943_9ad",
			"created_at":"2017-02-22T00:15:58.808Z",
			"updated_at":"2017-04-26T04:25:57.523Z",
			"company_name":"Company XYZ",
			"transaction_amount":2000,
			"company_number":"12345",
			"legal_entity_number":"67890",
			"transaction_currency":"EUR",
			"automatic_refund":true,
			"automatic_expiry":28,
			"first_reminder":7,
			"second_reminder":21,
			"contact_name":"company contact",
			"contact_email":"contact@companyXYZ.com",
			"certificate_common_name":"api client name",
			"merchant_id":"XYZ"
		}
	]
}

8. List Legal Entity Per Merchant

List Legal Entity Per Merchant is used to retrieve a list of legal entities for a specific merchant.

The response data schema is the same as the generic list endpoint.

9. Create Legal Entity

Create Legal Entity API request is used to create a new legal entity for the API client, that is linked to the API the request was authenticated under.

10. Create Legal Entity Request

Field	Type	Mandatory	Description	Example

Field	Type	Mandatory	Description	Example
company_name	String	Yes	Name of the Company.	"Company Name"
company_country	String	No	The country the company is registered in.	"AU"
company_number	String	No	Unique number assigned to the company.	"12345"
legal_entity_number	String	No	Unique number assigned to the legal entity.	"67890"
transaction_amount	Number	Yes	The amount of the transaction.	"500"
transaction_currency	String	Yes	The currency of the transaction.	"EUR"
automatic_refund	Boolean	No	Enabling/Disabling automatic refunds for the Legal Entity.	"FALSE"
automatic_expiry	Number	Yes	Enabling automatic expiry time in days for the Legal Entity.	"7"
first_reminder	Number	Yes	Send a reminder email in the configured number of days.	"7"
second_reminder	Number	Yes	Send a reminder email in the configured number of days.	"14"
contact_name	String	No	Contact name for the Legal Entity.	"Sample Sampleton"
contact_email	String	No	Contact email for the Legal Entity.	"noreply@isignthis.net"
merchant_id	String	Yes	The merchant id for the Legal Entity.	"ubo_test"

Sample JSON Create Legal Entity Request

{
	"company_name":"Company Name",
	"company_country":"AU",
	"company_number":"12345",
	"legal_entity_number":"67890",
	"transaction_amount":500,
	"transaction_currency":"EUR",
	"automatic_refund":false,
	"automatic_expiry":7,
	"first_reminder":7,
	"second_reminder":14,
	"contact_name":"Sample Sampleton",
	"contact_email":"noreply@isignthis.net",
	"merchant_id":"ubo_test"
}

Example of a successful Legal Entity Creation

11. Get Legal Entity

Get Legal Entity API request is used to return all stored details for the Legal Entities, that is linked to the API the request was authenticated under.

Ensure that the Legal Entity ID is sent through with the request.

If the Legal Entity does not exist, an HTTP 404 Not Found error will be returned.

Field	Type	Description	Example

Field	Type	Description	Example
company_name	String	Name of the Company.	"Company XYZ"
company_country	String	The country the company is registered in.	"AU"
company_number	String	Unique number assigned to the company.	"12345"
legal_entity_number	String	Unique number assigned to the legal entity.	"67890"
transaction_amount	Number	The amount of the transaction.	"2000"
transaction_currency	String	The currency of the transaction.	"EUR"
automatic_refund	Boolean	Enabling/Disabling automatic refunds for the Legal Entity.	"TRUE"
automatic_expiry	Number	Enabling automatic expiry time in days for the Legal Entity.	"28"
first_reminder	Number	Send a reminder email in the configured number of days.	"7"
second_reminder	Number	Send a reminder email in the configured number of days.	"21"
contact_name	String	Contact name for the Legal Entity.	"company contact"
contact_email	String	Contact email for the Legal Entity.	"contact@companyXYZ.com"
merchant_id	String	The merchant id for the Legal Entity.	"XYZ"

Sample JSON Response if the legal entity does exist

Sample JSON Response if the legal entity does not exist

12. Update Legal Entity

Update Legal Entity API request is used to update the details for the Legal Entities, that is linked to the API the request was authenticated under.

Ensure that the Legal Entity ID is sent through with the request.

Field	Type	Description	Example

Field	Type	Description	Example
company_name	String	Name of the Company.	"Company XYZ"
transaction_amount	Number	The amount of the transaction.	"2000"
transaction_currency	String	The currency of the transaction.	"EUR"
automatic_refund	Boolean	Enabling/Disabling automatic refunds for the Legal Entity.	"TRUE"
automatic_expiry	Number	Enabling automatic expiry time in days for the Legal Entity.	"28"
first_reminder	Number	Send a reminder email in the configured number of days.	"7"
second_reminder	Number	Send a reminder email in the configured number of days.	"21"
contact_name	String	Contact name for the Legal Entity.	"company contact"
contact_email	String	Contact email for the Legal Entity.	"contact@companyXYZ.com"
merchant_id	String	The merchant id for the Legal Entity.	"XYZ"

Sample JSON Update Legal Entity Request

Sample JSON Response when the Legal Entity is successfully updated

13. Delete Legal Entity

Delete Legal Entity API request is used to delete the legal entities, that is linked to the API the request was authenticated under.

Ensure that the Legal Entity ID is sent through with the request.

Sample JSON Response when the Legal Entity is successfully updated

14. List Beneficiaries

List Beneficiaries API request is used to retrieve a list of beneficiaries that already exist for API client for the API that the request was authenticated under.

Field	Type	Description	Example

Field	Type	Description	Example
id	String	Unique response identification code.	"76fb860_15a614d9943_9ad"
created_at	String	Creation date of the Legal Entity.	"2017-02-22T00:15:58.808Z"
updated_at	String	Date the Legal Entity was last updated.	"2017-04-26T04:25:57.523Z"
welcome_sent	Boolean	Indicates that the welcome email have been sent for the beneficiary.	"FALSE"
welcome_sent_at	String	The date the welcome email was sent	"2017-04-26T04:25:57.523Z"
external_welcome_sent	Boolean	Indicates that the welcome email sent by the API client.	"FALSE"
external_welcome_sent_at	String	The date the welcome email was sent by the API client.	"2017-04-26T04:25:57.523Z"
entity_ids	Array of String	The legal entity ids which this beneficiary is associated with.	["9999999","12121212"]
first_name	String	The first name of the beneficiary.	"Sample"
last_name	String	The last name of the beneficiary.	"Sampleton"
dob	String	The date of birth of the beneficiary.	"01-07-1992"
mobile	String	The mobile number of the beneficiary.	"+61400000000"
email	String	The email address of the beneficiary.	"noreply@isignthis.com"
address_street_number	String	The address street number of the beneficiary.	"456"
address_street	String	The street address of the beneficiary.	"Victoria Parade"
address_secondary	String	The 2nd address line for the beneficiary.	"Office 2"
address_city	String	The city of the beneficiary.	"East Melbourne"
address_postal_code	String	The postal code of the beneficiary.	"3002"
address_subdivision	String	The subdivision of the beneficiary.	"VIC"
address_country	String	The country of the beneficiary.	"AU"
state	String	The state of the beneficiary.	NEW/WELCOME_SENT/IN_FLIGHT/MANUAL_REVIEW/REJECTED/ACCEPTED/EXPIRED

Sample JSON Response

15. List Beneficiaries Per Merchant

This is the same as the List Beneficiaries request, only it is filtered by the merchant.

16. List Beneficiaries Per Entity

This is the same as the List Beneficiaries request, only it is filtered by the entity they are stored under.

17. Create Beneficiary

Create Beneficiary API request is used to create a new Beneficiary for the API client, that is linked to the API the request was authenticated under.

Ensure you enter the Entity ID for the legal entity that the Beneficiary will be created under.

18. Create Beneficiary Request

Field	Type	Description	Example

Field	Type	Description	Example
entity_id	String	The legal entity id that the beneficiary is associated with.	"9999999"
first_name	String	The first name of the beneficiary.	"Sample"
last_name	String	The last name of the beneficiary.	"Sampleton"
dob	String	The date of birth of the beneficiary.	"01-07-1992"
mobile	String	The mobile number of the beneficiary.	"+61400000000"
email	String	The email address of the beneficiary.	"noreply@isignthis.com"
address_street_number	String	The address street number of the beneficiary.	"456"
address_street	String	The street address of the beneficiary.	"Victoria Parade"
address_secondary	String	The 2nd address line for the beneficiary.	"Office 2"
address_city	String	The city of the beneficiary.	"East Melbourne"
address_postal_code	String	The postal code of the beneficiary.	"3002"
address_subdivision	String	The subdivision of the beneficiary.	"VIC"
address_country	String	The country of the beneficiary.	"AU"
transaction_currency_override	String	Overrides the currency of the legal entity.	"EUR"

Sample JSON Create Beneficiary Request

Example of a successful Beneficiary creation

Example of a validation error on unique email/sms error: HTTP 400

19. Get Beneficiary

Get Beneficiary API request is used to return all stored details for the Beneficiary, that is linked to the Legal Entity the request was authenticated under.

Ensure that the Beneficiary Entity ID is sent through with the request.

Field	Type	Description	Example

Field	Type	Description	Example
id	String	Unique response identification code.	"76fb860_15a614d9943_9ad"
created_at	String	Creation date of the Legal Entity.	"2017-02-22T00:15:58.808Z"
updated_at	String	Date the Legal Entity was last updated.	"2017-04-26T04:25:57.523Z"
welcome_sent	Boolean	Indicates that the welcome email have been sent for the beneficiary.	"FALSE"
entity_ids	Array of String	The legal entity ids which this beneficiary is associated with.	["9999999","12121212"]
first_name	String	The first name of the beneficiary.	"Sample"
last_name	String	The last name of the beneficiary.	"Sampleton"
dob	String	The date of birth of the beneficiary.	"01-07-1992"
mobile	String	The mobile number of the beneficiary.	"+61400000000"
email	String	The email address of the beneficiary.	"noreply@isignthis.com"
address_street_number	String	The address street number of the beneficiary.	"456"
address_street	String	The street address of the beneficiary.	"Victoria Parade"
address_secondary	String	The 2nd address line for the beneficiary.	"Office 2"
address_city	String	The city of the beneficiary.	"East Melbourne"
address_postal_code	String	The postal code of the beneficiary.	"3002"
address_subdivision	String	The subdivision of the beneficiary.	"VIC"
address_country	String	The country of the beneficiary.	"AU"
state	String	The state of the beneficiary.	NEW/WELCOME_SENT/IN_FLIGHT/MANUAL_REVIEW/REJECTED/ACCEPTED/EXPIRED
verify_url	String	The KYC UBO redirect URL	https://www.verify.isignthis.com/kycstart/2d772009-35a5-4090-9a8c-8cc8e12aafc1
token	String	The KYC token used to start the UBO process that can be used in embedded mode	2d772009-35a5-4090-9a8c-8cc8e12aafc1
task	Object	The outstanding task to accept the beneficiaries details	Task object

Sample JSON Response if the beneficiary does exist

Sample JSON Response if the beneficiary does not exist

20. Task Object

Field	Type	Required	Description	Example

Field	Type	Required	Description	Example
id	String	Yes	Task identifier	"4b695352_1609a94e5a4__7f01"
type	String	Yes	Task type. Possible values: KYC_MANUAL_REVIEW, RISK_MANUAL_REVIEW, AML_REVIEW, SCREEN_REVIEW	"KYC_MANUAL_REVIEW"
state	String	Yes	The state of the outstanding task. Possible values: NEW, ASSIGNED	"NEW"
awaiting	String	Yes	The entity that the task is waiting to be actioned by. Possible values: END_USER, OPERATOR	"OPERATOR"
created_at	String	Yes	Task creation date	"2017-12-28T00:48:25.604Z"
updated_at	String	Yes	Task last updated date	"2017-12-28T01:02:34.128Z"
available_actions	Array	Yes	Available actions that can actioned via API. Used as a url value to action a task	["accept", "reject"]

Sample JSON Response

21. Update Beneficiary

Update the Beneficiary API request is used to update the details for the beneficiary, that is linked to the API the request was authenticated under.

Ensure that the Beneficiary ID is sent through with the request.

Field	Type	Description	Example

Field	Type	Description	Example
entity_id	String	The legal entity that the beneficiary is associated with.	"9999999"
first_name	String	The first name of the beneficiary.	"Sample"
last_name	String	The last name of the beneficiary.	"Sampleton"
dob	String	The date of birth of the beneficiary.	"01-07-1992"
mobile	String	The mobile number of the beneficiary.	"+61400000000"
email	String	The email address of the beneficiary.	"noreply@isignthis.com"
address_street_number	String	The address street number of the beneficiary.	"456"
address_street	String	The street address of the beneficiary.	"Victoria Parade"
address_secondary	String	The 2nd address line for the beneficiary.	"Office 2"
address_city	String	The city of the beneficiary.	"East Melbourne"
address_postal_code	String	The postal code of the beneficiary.	"3002"
address_subdivision	String	The subdivision of the beneficiary.	"VIC"
address_country	String	The country of the beneficiary.	"AU"
transaction_currency_override	String	Overrides the currency of the legal entity.	"EUR"

Sample JSON Update Beneficiary Request

Sample JSON Response when the Beneficiary is successfully updated

22. Delete Beneficiary

Delete Beneficiary API request is used to delete the beneficiary that is linked to the API the request was authenticated under.

Ensure that the Beneficiary ID is sent through with the request.

Sample JSON Response when the Beneficiary is successfully updated

23. Generate Tokens

Generates a token for the beneficiary that can be used to initiate a transaction.

The beneficiaries designated will be updated with the verify_url field, which will have a link to the transaction workflow using the generated token.

Sample JSON Generate Token Request

Sample JSON Response when the tokens have been successfully generated

24. Flag External Welcome

Flags Beneficiaries as having received an external welcome message, not initiated from the ISX system.

Sample JSON Response

Sample JSON Response when the beneficiaries have been successfully flagged

25. Send Welcome

Send Welcome API request, sends out a welcome email address to all beneficiaries listed in the request.

Sample JSON Send Welcome Request

Sample JSON Response when the welcome emails have been successfully sent

26. Add Beneficiary to Legal Entity

Adds a batch of Beneficiaries to a Legal Entity.

Sample JSON Reset Beneficiary Request

Sample JSON Response when successful: HTTP 200

27. Remove Beneficiary from Legal Entity

Removes a batch of Beneficiaries from a Legal Entity.

Sample JSON Reset Beneficiary Request

Sample JSON Response when successful: HTTP 200

28. Get Beneficiary View Link

Register a user to view the Beneficiary details.

Request Body

Field	Type	Description	Example

Field	Type	Description	Example
email	String	Email address of the person who will view the beneficiary. The user will be sent an email containing an OTP if they have not been sent one in the last 24 hours.	sample.viewer@isignthis.com

Sample JSON Get View Beneficiary Link Request

Response Body

Field	Type	Description

Field	Type	Description
view_url	String	Link to view beneficiary for the email address provided. The link will expire after 1 hour. If the user has not entered the an OTP in the last 24 hours, they will be required to enter an OTP before viewing the beneficiary.

Sample JSON Response when successful: HTTP 200

29. Account Identifier must be unique for each customer

Account Identifier must be unique for each customer, such as a customer’s CRM customer number.

Email, phone number etc. are not allowed.

The integration must only be implemented within the websites, as per the agreement.