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

{
	"message":"Created new UBO Legal Entity Successfully",
	"id":"_f6cd2e9_15f35697e3c_2054",
	"status":201
}

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

{
	"id":"99999",
	"created_at":"2017-12-01T04:41:59.639Z",
	"updated_at":"2017-12-01T04:41:59.639Z",
	"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"
}

Sample JSON Response if the legal entity does not exist

{
	"message":"Not found",
	"status":404
}

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.

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

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

Sample JSON Response when the Legal Entity is successfully updated

{
	"message":"UBO Legal Entity successfully updated",
	"id":"76fb860_15a614d9943_9ad",
	"status":200
}

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.

Deleting the Legal Entity will result in deleting all existing Beneficiaries stored under the legal entity.

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.

Sample JSON Response when the Legal Entity is successfully updated

{
	"message":"Entity with 9 UBO(s) deleted",
	"id":"76fb860_15a614d9943_9ad",
	"status":200
}

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