UBO Product
- Home
- UBO Product
The Ultimate Beneficial Owner (UBO) product is used to 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 iSignthis can send emails on your behalf.
Receive UBO notifications on the configured url from ISX servers to your notification endpoint
Operation | Description | Endpoint |
---|---|---|
Receive Notification | Notification of UBO event requested via iSignThis dashboard | POST https://www.yourserver.com/v1/ubo_notification |
The iSignthis UBO product has 2 notification events:
- ubo_welcome: This occurs when a dashboard operator wants to send a welcome message to the UBO.
- ubo_reminder: This occurs if a UBO has not interacted with the KYC verification process and requires a reminder message.
UBO Notification Object
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 the UBO associated with | |
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 to | gateway_r_us |
legal_entity.name | “String” | The name of the legal entity the UBO is associated with | 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 |
|
ubo_url | “String” | The url the UBO needs to link to start the KYC verification process. |
|
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 404 Not Found response is generated.
Legal Entity Endpoints
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 |
Beneficiary Endpoints
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
|
List Beneficiaries Per Entity | Lists all Beneficiaries stored under a given Legal Entity. |
GET
|
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 |
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
|
Flag External Welcome | Flags all Beneficiaries designated as having an external welcome message sent. |
POST |
Send Welcome | Sends a Welcome Message to start a KYC transaction to all Beneficiaries designated. |
POST
|
Reset Beneficiary | Resets a given beneficiary to its initial state. |
POST |
Add Beneficiary to Legal Entity | Add’s a list of beneficiaries to a Legal Entity |
POST
|
Remove Beneficiary from Legal Entity | Remove’s a list of beneficiaries to a Legal Entity |
POST
|
Get Beneficiary View Link | Register a user to view the beneficiary details |
POST
|
Environment
We recommend that all our clients test on our production environment.
Production API URL: https://gateway.isignthis.com/v1/
iSignthis 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 iSignthis technical support team will provide a staging account for you.
The iSignthis technical support team can further detail the pros and cons of working with either environment based on your needs.
Authentication
For API operations, you will need an API secret key which will be sent from technical support.
Field Name | Field Value |
---|---|
From | <api client name> |
Authorization | Bearer <API secret key> |
Field Name | Field Value |
---|---|
From | widgets-client.isignthis.com |
Authorization | Bearer TEXnkvZCtFucXebHYwrobWhaJhDBTZUs9BpvBTbxWELCCnCQJTKsx6bYNh5fOjEE |
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 |
---|---|---|---|
id | “String” | Unique response identification code. | "76fb860_15a614d9943_9ad" |
created_at | “String” | Creation date of the Legal Entity. |
|
updated_at | “String” | Date the Legal Entity was last updated. |
|
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" } ] }
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.
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.
Create Legal Entity Request
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 }
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 a 404 Not found error will be returned.
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 }
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 a 404 Not found error will be returned.
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 }
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.
NOTE: 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 a 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 }
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 |
---|---|---|---|
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. | "1992-07-01" |
mobile | “string” | The mobile number of the beneficiary. | "+61400000000" |
“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. |
|
Sample JSON Response
{ "data": [ { "id": "7b347a8f_15f379955d5__6373", "created_at": "2017-10-20T03:37:22.377Z", "updated_at": "2017-10-20T03:37:22.377Z", "welcome_sent": false, "entity_ids": ["_f6cd2e9_15f35697e3c_2054"], "welcome_sent_at": "2017-12-01T04:41:59.639Z", "external_welcome_sent": true, "external_welcome_sent_at": "2017-12-01T04:41:59.639Z", "transaction_id": "1111-2222-3333-4444", "task_id": "5555-6666-7777-8888", "verify_url": "https://www.verify.isignthis.com/kycstart/example_token", "state": "IN_FLIGHT", "first_name": "Sample", "last_name": "Sampleton", "dob": "1992-07-01", "mobile": "+61400000000", "email": "noreply@isignthis.com", "address_street_number": "456", "address_street": "Victoria Parade", "address_secondary": "Office 2", "address_city": "East Melbourne", "address_postal_code": "3002", "address_subdivision": "VIC", "address_country": "AU", "transaction_currency_override": "EUR" } ] }
List Beneficiaries Per Merchant
This is the same as the List Beneficiaries request, only it is filtered by merchant
List Beneficiaries Per Entity
This is the same as the List Beneficiaries request, only it is filtered by the entitiy they are stored under
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.
Create Beneficiary Request
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. | "1992-07-01" |
mobile | “string” | The mobile number of the beneficiary. | "+61400000000" |
“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
{ "entity_id": "99999", "first_name": "Sample", "last_name": "Sampleton", "dob": "1992-07-01", "mobile": "+61400000000", "email": "noreply@isignthis.com", "address_street_number": "456", "address_street": "Victoria Parade", "address_secondary": "Office 2", "address_city": "East Melbourne", "address_postal_code": "3002", "address_subdivision": "VIC", "address_country": "AU", "transaction_currency_override": "EUR" }
Example of a successful Beneficiary creation
{ "message": "UBO was created successfully", "id": "7b347a8f_15f379955d5__6373", "status": 201 }
Example of a validation error on unique email/sms error – HTTP 400
{ "code": "VALIDATION_ERROR", "message": "Request failed validation", "details": [ { "id": "email", "message": "There already exists an UBO with the email noreply@isignthis.com for this Merchant", "data": { "id": "2603bd74-f11f-11e7-8c3f-9a214cf093ae", "entity_ids": ["99999"], "state": "ACCEPTED", "first_name": "Sample", "last_name": "Sampleton", "dob": "1992-07-01", "mobile": "+61400000000", "email": "noreply@isignthis.com", "address_street_number": "456", "address_street": "Victoria Parade", "address_secondary": "Office 2", "address_city": "East Melbourne", "address_postal_code": "3002", "address_subdivision": "VIC", "address_country": "AU", "transaction_currency_override": "EUR" } } ] }
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.
If the beneficiary does not exist a 404 Not found error will be returned.
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. | "1992-07-01" |
mobile | “string” | The mobile number of the beneficiary. | "+61400000000" |
“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. |
|
verify_url | “string” | The KYC UBO redirect URL |
|
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
{ "id": "7b347a8f_15f379955d5__6373", "created_at": "2017-10-20T03:37:22.377Z", "updated_at": "2017-10-20T03:37:22.377Z", "welcome_sent": false, "entity_ids": [ "_f6cd2e9_15f35697e3c_2054" ], "welcome_sent_at": "2017-12-01T04:41:59.639Z", "external_welcome_sent": true, "external_welcome_sent_at": "2017-12-01T04:41:59.639Z", "transaction_id": "1111-2222-3333-4444", "task_id": "5555-6666-7777-8888", "verify_url": "https://www.verify.isignthis.com/kycstart/2d772009-35a5-4090-9a8c-8cc8e12aafc1", "token": "2d772009-35a5-4090-9a8c-8cc8e12aafc1", "state": "MANUAL_REVIEW", "first_name": "Sample", "last_name": "Sampleton", "dob": "1992-07-01", "mobile": "+61400000000", "email": "noreply@isignthis.com", "address_street_number": "456", "address_street": "Victoria Parade", "address_secondary": "Office 2", "address_city": "East Melbourne", "address_postal_code": "3002", "address_subdivision": "VIC", "address_country": "AU", "transaction_currency_override": "EUR", "task": { "id": "4b695352_1609a94e5a4__7f01", "type": "KYC_MANUAL_REVIEW", "state": "NEW", "awaiting": "OPERATOR", "created_at": "2017-12-28T00:48:25.604Z", "updated_at": "2017-12-28T00:48:25.604Z", "available_actions": [ "accept", "reject" ] } }
Sample JSON Response if the beneficiary does not exist
{ "message": "Not found", "status": 404 }
Task Object
Field | Type | Required | Description | Example |
---|---|---|---|---|
id | “String” | Yes | Task identifer | "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
{ "id": "4b695352_1609a94e5a4__7f01", "type": "KYC_MANUAL_REVIEW", "state": "NEW", "awaiting": "OPERATOR", "created_at": "2017-12-28T00:48:25.604Z", "updated_at": "2017-12-28T00:48:25.604Z", "available_actions": [ "accept", "reject" ] }
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.
If the beneficiary does not exist a 404 Not found error will be returned.
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. | "1992-07-01" |
mobile | “string” | The mobile number of the beneficiary. | "+61400000000" |
“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 Reques
{ "entity_id": "99999", "first_name": "Sample", "last_name": "Sampleton", "dob": "1992-07-01", "mobile": "+61400000000", "email": "noreply@isignthis.com", "address_street_number": "456", "address_street": "Victoria Parade", "address_secondary": "Office 2", "address_city": "East Melbourne", "address_postal_code": "3002", "address_subdivision": "VIC", "address_country": "AU", "transaction_currency_override": "EUR" }
Sample JSON Response when the Beneficiary is successfully updated
{ "message": "UBO updated successfully", "id": "7b347a8f_15f379955d5__6373", "status": 200 }
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.
If the Beneficiary does not exist a 404 Not found error will be returned.
Sample JSON Response when the Beneficiary is successfully updated
{ "message": "UBO deleted successfully", "status": 200 }
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
{ "beneficiary_ids": [ "id_one", "id_two", "id_three" ] }
Sample JSON Response when the tokens have been successfully generated
{ "beneficiaries": [ { "id": "id_one", "created_at": "2017-12-29T02:26:09.903Z", "updated_at": "2017-12-29T02:26:44.744Z", "welcome_sent": false, "external_welcome_sent": false, "verify_url": "https://verify.isignthis.com/kycstart/43b2ace4-bee9-41bd-86a6-c7480324a2e5", "token": "43b2ace4-bee9-41bd-86a6-c7480324a2e5", "state": "NEW", "entity_id": "_29a69067_1609a1c5ddb__7d1d", "first_name": "John", "last_name": "Smith", "email": "d_one@domain.com" }, { "id": "id_two", "created_at": "2017-12-29T02:26:09.903Z", "updated_at": "2017-12-29T02:26:44.744Z", "welcome_sent": false, "external_welcome_sent": false, "verify_url": "https://verify.isignthis.com/kycstart/46abb73d-845b-434c-bc83-22e84cff4e0a", "token": "46abb73d-845b-434c-bc83-22e84cff4e0a", "state": "NEW", "entity_id": "a64fa290-6460-45e6-aaa6", "first_name": "Jack", "last_name": "Smith", "email": "id_two@domain.com" }, { "id": "id_three", "created_at": "2017-12-29T02:26:09.903Z", "updated_at": "2017-12-29T02:26:44.744Z", "welcome_sent": false, "external_welcome_sent": false, "verify_url": "https://verify.isignthis.com/kycstart/f9e9b693-fa52-46c9-91d1-f425847c2939", "token": "f9e9b693-fa52-46c9-91d1-f425847c2939", "state": "NEW", "entity_id": "d66a43e2-9434-4836", "first_name": "Jenny", "last_name": "Smith", "email": "id_three@domain.com" } ], "message": "Generating Welcome Tokens for 3 UBO(s)", "status": 200 }
Flag External Welcome
Flags beneficiaries as having received an external welcome message, not initiated from the iSignthis system.
Sample JSON Response
{ "beneficiary_ids": [ "id_one", "id_two", "id_three" ] }
Sample JSON Response when the beneficiaries have been successfully flagged
{ "beneficiaries": [ { "id": "id_one", "created_at": "2017-12-29T02:26:09.903Z", "updated_at": "2017-12-29T02:26:44.744Z", "welcome_sent": false, "external_welcome_sent": false, "verify_url": "https://verify.isignthis.com/kycstart/43b2ace4-bee9-41bd-86a6-c7480324a2e5", "token": "43b2ace4-bee9-41bd-86a6-c7480324a2e5", "state": "NEW", "entity_id": "_29a69067_1609a1c5ddb__7d1d", "first_name": "John", "last_name": "Smith", "email": "d_one@domain.com" }, { "id": "id_two", "created_at": "2017-12-29T02:26:09.903Z", "updated_at": "2017-12-29T02:26:44.744Z", "welcome_sent": false, "external_welcome_sent": false, "verify_url": "https://verify.isignthis.com/kycstart/46abb73d-845b-434c-bc83-22e84cff4e0a", "token": "46abb73d-845b-434c-bc83-22e84cff4e0a", "state": "NEW", "entity_id": "a64fa290-6460-45e6-aaa6", "first_name": "Jack", "last_name": "Smith", "email": "id_two@domain.com" }, { "id": "id_three", "created_at": "2017-12-29T02:26:09.903Z", "updated_at": "2017-12-29T02:26:44.744Z", "welcome_sent": false, "external_welcome_sent": false, "verify_url": "https://verify.isignthis.com/kycstart/f9e9b693-fa52-46c9-91d1-f425847c2939", "token": "f9e9b693-fa52-46c9-91d1-f425847c2939", "state": "NEW", "entity_id": "d66a43e2-9434-4836", "first_name": "Jenny", "last_name": "Smith", "email": "id_three@domain.com" } ], "message": "Flagging External Welcomes for 3 UBO(s)", "status": 200 }
Send Welcome
Send Welcome API request, sends out a welcome email address to all beneficiaries listed in the request.
Sample JSON Send Welcome Request
{ "beneficiary_ids": [ "id_one", "id_two", "id_three" ] }
Sample JSON Response when the welcome emails have been successfully sent
{ "beneficiaries": [ { "id": "id_one", "created_at": "2017-12-29T02:26:09.903Z", "updated_at": "2017-12-29T02:26:44.744Z", "welcome_sent": false, "external_welcome_sent": false, "verify_url": "https://verify.isignthis.com/kycstart/43b2ace4-bee9-41bd-86a6-c7480324a2e5", "token": "43b2ace4-bee9-41bd-86a6-c7480324a2e5", "state": "NEW", "entity_ids": ["_29a69067_1609a1c5ddb__7d1d"], "first_name": "John", "last_name": "Smith", "email": "d_one@domain.com" }, { "id": "id_two", "created_at": "2017-12-29T02:26:09.903Z", "updated_at": "2017-12-29T02:26:44.744Z", "welcome_sent": false, "external_welcome_sent": false, "verify_url": "https://verify.isignthis.com/kycstart/46abb73d-845b-434c-bc83-22e84cff4e0a", "token": "46abb73d-845b-434c-bc83-22e84cff4e0a", "state": "NEW", "entity_ids": ["a64fa290-6460-45e6-aaa6"], "first_name": "Jack", "last_name": "Smith", "email": "id_two@domain.com" }, { "id": "id_three", "created_at": "2017-12-29T02:26:09.903Z", "updated_at": "2017-12-29T02:26:44.744Z", "welcome_sent": false, "external_welcome_sent": false, "verify_url": "https://verify.isignthis.com/kycstart/f9e9b693-fa52-46c9-91d1-f425847c2939", "token": "f9e9b693-fa52-46c9-91d1-f425847c2939", "state": "NEW", "entity_ids": ["d66a43e2-9434-4836"], "first_name": "Jenny", "last_name": "Smith", "email": "id_three@domain.com" } ], "message": "Sending Welcome for 3 UBO(s)", "status": 200 }
Add Beneficiary to Legal Entity
Adds a batch of beneficiaries to a legal entity.
Sample JSON Reset Beneficiary Request
{ "beneficiary_ids": [ "id_one", "id_two", "id_three" ] }
Sample JSON Response when successful – HTTP 200
{ "beneficiaries": [ { "id": "id_one", "created_at": "2017-12-29T02:26:09.903Z", "updated_at": "2017-12-29T02:26:44.744Z", "welcome_sent": false, "external_welcome_sent": false, "verify_url": "https://verify.isignthis.com/kycstart/43b2ace4-bee9-41bd-86a6-c7480324a2e5", "token": "43b2ace4-bee9-41bd-86a6-c7480324a2e5", "state": "NEW", "entity_ids": ["_29a69067_1609a1c5ddb__7d1d"], "first_name": "John", "last_name": "Smith", "email": "d_one@domain.com" }, { "id": "id_two", "created_at": "2017-12-29T02:26:09.903Z", "updated_at": "2017-12-29T02:26:44.744Z", "welcome_sent": false, "external_welcome_sent": false, "verify_url": "https://verify.isignthis.com/kycstart/46abb73d-845b-434c-bc83-22e84cff4e0a", "token": "46abb73d-845b-434c-bc83-22e84cff4e0a", "state": "NEW", "entity_ids": ["a64fa290-6460-45e6-aaa6"], "first_name": "Jack", "last_name": "Smith", "email": "id_two@domain.com" }, { "id": "id_three", "created_at": "2017-12-29T02:26:09.903Z", "updated_at": "2017-12-29T02:26:44.744Z", "welcome_sent": false, "external_welcome_sent": false, "verify_url": "https://verify.isignthis.com/kycstart/f9e9b693-fa52-46c9-91d1-f425847c2939", "token": "f9e9b693-fa52-46c9-91d1-f425847c2939", "state": "NEW", "entity_ids": ["d66a43e2-9434-4836"], "first_name": "Jenny", "last_name": "Smith", "email": "id_three@domain.com" } ], "message": "Add for 1 UBO(s)" }
Remove Beneficiary from Legal Entity
Removes a batch of beneficiaries from a legal entity.
Sample JSON Reset Beneficiary Request
{ "beneficiary_ids": [ "id_one", "id_two", "id_three" ] }
Sample JSON Response when successful – HTTP 200
{ "beneficiaries": [ { "id": "id_one", "created_at": "2017-12-29T02:26:09.903Z", "updated_at": "2017-12-29T02:26:44.744Z", "welcome_sent": false, "external_welcome_sent": false, "verify_url": "https://verify.isignthis.com/kycstart/43b2ace4-bee9-41bd-86a6-c7480324a2e5", "token": "43b2ace4-bee9-41bd-86a6-c7480324a2e5", "state": "NEW", "entity_ids": ["_29a69067_1609a1c5ddb__7d1d"], "first_name": "John", "last_name": "Smith", "email": "d_one@domain.com" }, { "id": "id_two", "created_at": "2017-12-29T02:26:09.903Z", "updated_at": "2017-12-29T02:26:44.744Z", "welcome_sent": false, "external_welcome_sent": false, "verify_url": "https://verify.isignthis.com/kycstart/46abb73d-845b-434c-bc83-22e84cff4e0a", "token": "46abb73d-845b-434c-bc83-22e84cff4e0a", "state": "NEW", "entity_ids": ["a64fa290-6460-45e6-aaa6"], "first_name": "Jack", "last_name": "Smith", "email": "id_two@domain.com" }, { "id": "id_three", "created_at": "2017-12-29T02:26:09.903Z", "updated_at": "2017-12-29T02:26:44.744Z", "welcome_sent": false, "external_welcome_sent": false, "verify_url": "https://verify.isignthis.com/kycstart/f9e9b693-fa52-46c9-91d1-f425847c2939", "token": "f9e9b693-fa52-46c9-91d1-f425847c2939", "state": "NEW", "entity_ids": ["d66a43e2-9434-4836"], "first_name": "Jenny", "last_name": "Smith", "email": "id_three@domain.com" } ], "message": "Removed for 1 UBO(s)" }
Get Beneficiary View Link
Register a user to view the beneficiary details.
Request Body
Field | Type | Description | Example |
---|---|---|---|
“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
{ "email": "bob.banker@bank.com" }
Response Body
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
{ "view_url": "https://verify.isignthis.com/ubo/view/43b2ace4-bee9-41bd-86a6-c7480324a2e5" }
Account Identifier must be unique for each customer
Acount Identifier must be unique for each customer, such as 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