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

OperationDescriptionEndpoint
Receive NotificationNotification of UBO event requested via iSignThis dashboardPOST 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

FieldTypeDescriptionExample
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 UBOJoe
profile.last_name“String”The last name of the UBOBloggs
profile.email“String”The email name of the UBOjoebloggs@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 charged2000
legal_entity.transaction_currency“String”The currency of the transactionEUR
legal_entity.merchant_id“String”The merchant id where the charge will be attributed togateway_r_us
legal_entity.name“String”The name of the legal entity the UBO is associated withJoe Bloggs Fish and Chips
ubo_token“String”The token that can be used to kick off the embed mode of KYC integration on your site9016f53d-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.

OperationDescriptionEndpoint
List Legal EntityList all Legal Entities under the API client for the API the request was authenticated under.GET /v1/ubo/entity/list
List Legal Entity Per MerchantLists 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 EntityCreates the Legal Entity for the API the request was authenticated under.POST /v1/ubo/entity
Get Legal EntityReturns Legal Entity Details for the API the request was authenticated under.GET /v1/ubo/entity/:id
Update Legal EntityUpdates an existing Legal Entity for the API the request was authenticated under.PUT /v1/ubo/entity/:id
Delete Legal EntityDeletes an existing Legal Entity, and deletes all existing Beneficiaries stored under that Legal Entity.DELETE /v1/ubo/entity/:id

Beneficiary Endpoints

OperationDescriptionEndpoint
List BeneficiariesLists all Beneficiaries under the API client for the API the request was authenticated under.GET /v1/ubo/beneficiary/list/
List Beneficiaries Per MerchantLists all Beneficiaries stored under a given Merchant.GET /v1/ubo/beneficiary/list/merchant/:merchant_id
List Beneficiaries Per EntityLists all Beneficiaries stored under a given Legal Entity.GET /v1/ubo/beneficiary/list/entity/:entity_id
Create BeneficiaryCreates a new Beneficiary.POST /v1/ubo/beneficiary
Get BeneficiaryReturns Beneficiary details.GET /v1/ubo/beneficiary/:id
Update BeneficiaryUpdates an existing Beneficiary.PUT /v1/ubo/beneficiary/:id
Delete BeneficiaryDeletes an existing Beneficiary.DELETE /v1/ubo/beneficiary/:id
Generate TokensGenerates 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 WelcomeFlags all Beneficiaries designated as having an external welcome message sent.POST /v1/ubo/beneficiary/external
Send WelcomeSends a Welcome Message to start a KYC transaction to all Beneficiaries designated.POST /v1/ubo/beneficiary/welcome
Reset BeneficiaryResets a given beneficiary to its initial state.POST /v1/ubo/beneficiary/reset/:id
Add Beneficiary to Legal EntityAdd’s a list of beneficiaries to a Legal EntityPOST /v1/ubo/beneficiary/add/:legal-entity-id
Remove Beneficiary from Legal EntityRemove’s a list of beneficiaries to a Legal EntityPOST /v1/ubo/beneficiary/remove/:legal-entity-id
Get Beneficiary View LinkRegister a user to view the beneficiary detailsPOST /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 NameField Value
From<api client name>
AuthorizationBearer <API secret key>

Field NameField Value
Fromwidgets-client.isignthis.com
AuthorizationBearer TEXnkvZCtFucXebHYwrobWhaJhDBTZUs9BpvBTbxWELCCnCQJTKsx6bYNh5fOjEE

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

FieldTypeDescriptionExample
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 entities for the API client, that is linked to the API the request was authenticated under.

FieldTypeMandatoryDescriptionExample
company_name“String”YesName of the Company."Company Name"
company_country“String”NoThe country the company is registered in."AU"
company_number“String”NoUnique number assigned to the company."12345"
legal_entity_number“String”NoUnique number assigned to the legal entity."67890"
transaction_amount“number”YesThe amount of the transaction."500"
transaction_currency“String”YesThe currency of the transaction."EUR"
automatic_refund“boolean”NoEnabling/Disabling automatic refunds for the Legal Entity."false"
automatic_expiry“number”YesEnabling automatic expiry time in days for the Legal Entity."7"
first_reminder“number”YesSend a reminder email in the configured number of days."7"
second_reminder“number”YesSend a reminder email in the configured number of days."14"
contact_name“string”NoContact name for the Legal Entity."Sample Sampleton"
contact_email“string”NoContact email for the Legal Entity."noreply@isignthis.net"
merchant_id“string”YesThe 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.

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

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

FieldTypeDescriptionExample
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_idsArray 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 filtiered 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

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

FieldTypeDescriptionExample
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_idsArray 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 URLhttps://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 mode2d772009-35a5-4090-9a8c-8cc8e12aafc1
task“object”The outstanding task to accept the beneficiaries detailsTask 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

FieldTypeRequiredDescriptionExample
id“String”YesTask identifer"4b695352_1609a94e5a4__7f01"
type“String”YesTask type. Possible values: KYC_MANUAL_REVIEW, RISK_MANUAL_REVIEW, AML_REVIEW, SCREEN_REVIEW"KYC_MANUAL_REVIEW"
state“String”YesThe state of the outstanding task. Possible values: NEW, ASSIGNED"NEW"
awaiting“String”YesThe entity that the task is waiting to be actioned by. Possible values: END_USER, OPERATOR"OPERATOR"
created_at“String”YesTask creation date"2017-12-28T00:48:25.604Z"
updated_at“String”YesTask last updated date"2017-12-28T01:02:34.128Z"
available_actions“Array”YesAvailable 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.

FieldTypeDescriptionExample
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

FieldTypeDescriptionExample
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

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