Search

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

9016f53d-7b5b-4496-81c2-

683fa6dcd69f
ubo_url “String” The url the UBO needs to link to start the KYC verification process.

https://verify.isignthis.com/

kycstart/9016f53d-7b5b-4496-

81c2-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 404 Not Found response is generated.

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 /v1/ubo/beneficiary/list/me

rchant/:merchant_id
List Beneficiaries Per Entity Lists all Beneficiaries stored under a given Legal Entity.

GET /v1/ubo/beneficiary/list/en

tity/: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/genera

te_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

egal-entity-id
Remove Beneficiary from Legal Entity Remove’s a list of beneficiaries to a Legal Entity

POST /v1/ubo/beneficiary/remove

/:legal-entity-id
Get Beneficiary View Link Register a user to view the beneficiary details

POST /v1/ubo/beneficiary/:id/view

 

Environments

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

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

iSignthis also maintains a staging environment, which usually runs the latest release candidate of our system.

Integrating with the staging 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.

Staging API URL: https://stage-gateway.isignthis.com/v1/

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

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.

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

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

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

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

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

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

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

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

Register a user to view the beneficiary details.

Request Body

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

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

© 2013-2018 iSignthis Ltd (ASX: ISX | FRA: TA8). All rights reserved.