NAV
curl

Introduction

Sandbox Base URL

https://sandbox.hydrogenplatform.com/integration/v1

Production Base URL

https://api.hydrogenplatform.com/integration/v1

The Hydrogen Integration API is designed to extend the core functionality found within the Hydrogen Atom and Hydrogen Molecule products, by leveraging 3rd party data sources and features. The Integration API consists of common interfaces that act as adaptors for individual vendors. This allows developers to integrate Hydrogen data into 3rd party applications, or integrate 3rd party data and functionality into Hydrogen application, without the need to directly integrate with the vendor. For a full list of vendors supported please visit the Integrations page.

The Integration API is built on REST principles, with resource oriented URLs and HTTP response codes. All API responses are returned in JSON format.

Settings

Before interfacing with Hydrogen’s Integration API you must set up your vendor credentials and settings in the admin. Please follow the instructions below before starting.

Vendor Credentials

After you login to the Hydrogen developer portal, choose “Integrations” from the top menu and then choose your development environment. The vendors we currently support will be listed. Add your credentials and turn on the vendors you wish to use. Hydrogen does not currently re-sell any 3rd party APIs so you must sign up for each service independently from ours.

Vendor Settings

Each integration category has settings that can be enabled to make the development experience easier and more robust. Click the “Settings” button on the heading of the category and then save the settings after configuring them.

Vendor Setup

Some vendors require additional setup before a Hydrogen integration will function. Please visit the Integrations page and click on the vendor of your choice for detailed instructions before using any integration.

Authentication

All Hydrogen APIs use the same authentication and authorization. Please refer to the Nucleus API for detailed documentation.

Fields

IDS

All Object IDs are represented in universally unique identifier (UUID) format. A UUID is a string of 32 alphanumeric characters in the format 8-4-4-4-12. An example would be efa289b2-3565-42e6-850b-8dad25727e99.

STRINGS

All strings are limited to 255 characters unless otherwise noted.

DATES

All dates are represented in ISO 8601 format YYYY-MM-DD. An example would be 2018-01-10.

TIMESTAMPS

All object responses will include a create_date and update_date in timestamp format. All timestamps are represented in ISO 8601 format YYYY-MM-DDThh:mm:ssTZD. The “T” appears before the time element and the TZD before the time zone. An example would be 2018-01-10T16:00:30+01:00.

Errors

ERROR CODES

Code Description
400 Bad Request
401 Unauthorized. Occurs when you are using an invalid or expired access token.
403 Forbidden. The request was valid but you are not authorized to access the resource.
404 Not Found. Occurs when you are requesting a resource which doesn’t exist such as an incorrect URL, incorrect ID, or empty result.
429 Too Many Requests. Exceeded the rate limit set. Currently, there is no rate limit on the APIs.
500 Internal Server Error.
503 Service Unavailable. If the API is down for maintenance you will see this error.


STATUS CODES

Code Description
200 Ok. The request was successful.
204 No Content. The request was successful but there is no additional content to send in the response body. This will occur on a successful DELETE.

Versioning

The Integration API is currently in major version 1.0. All features which are not backwards compatible will be pushed as a major version release. Features that we consider to be backwards compatible include the following:

Changelog

Date Change Description
2019-12-19 addition Added Account Aggregation, IAV, KMS and KYC adaptors.

Endpoints

Account Aggregation

Account Aggregation vendors scrape the financial details of a given customer including balances, transactions, and holdings of held away accounts via credentials supplied for credit cards, bank accounts, and investments.

Supported Vendors
Plaid

Coming Soon
MX
Yodlee
Tink
Saltedge

Accounts

Example Request (Plaid)

curl -X POST -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
    -H "Content-Type: application/json" \
    -d '{
            "nucleus_client_id": "0f51f4e6-c94c-4813-a0dc-c21eddfd4e5f",
            "product": "atom",
            "vendor_request": {
                "item_id": "PlnQJy1vKnhPGPLPgPMMIkDo8AxRzac71kwRV"
            }
        }' "https://api.hydrogenplatform.com/integration/v1/aggregation/account"

Example Response (Plaid)

{
    "message": "Success",
    "vendor_name": "plaid",
    "nucleus_aggregation_accounts": [
        {
            "status_code": 200,
            "body": {
                "id": "ab04e2cd-5278-4051-99b3-6d6298e701ec",
                "create_date": "2019-10-18T16:50:23.570+0000",
                "update_date": "2019-10-18T16:50:23.570+0000",
                "account_name": "Plaid Gold Standard 0% Interest Checking",
                "client_id": "0f51f4e6-c94c-4813-a0dc-c21eddfd4e5f",
                "institution_name": "Chase",
                "category": "Banking",
                "subcategory": "Checking",
                "account_number": "1111222233330000",
                "currency_code": "USD",
                "is_active": true,
                "metadata": {},
                "mask": "0000",
                "account_holder": null,
                "is_asset": true,
                "financial_offer_id": null
            }
        }
    ]
}

Create an aggregation account link at the vendor configured for your firm. This service will create a vendor to client mapping for the client within your tenant and store an aggregation_account in Nucleus that can be updated.

HTTP REQUEST

POST /aggregation/account

ARGUMENTS

Field Type Required Description
nucleus_client_id UUID required Client in Nucleus
product string required Hydrogen product used for integration. Value may be atom.
vendor_request JSON required Vendor specific fields needed for integration. Please check the vendor page for instructions.

RESPONSE

Field Description
message A status message explaining the actions that were performed.
vendor_name The name of the vendor used to create the aggregation accounts.
nucleus_aggregation_accounts An array of response objects, with each object corresponding to the aggregation account creation for a different held away account.
     status_code The status code of the API call made to create the aggregation account.
     body The aggregation account object created in Nucleus.

Example Request

curl -X GET -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
    "https://api.hydrogenplatform.com/integration/v1/aggregation/account/464b026e-4346-4c1e-a829-764b7b2a4f1b"

Example Response (Plaid)

{
    "message": "Success",
    "vendor_name": "plaid",
    "nucleus_aggregation_account": {
        "status_code": 200,
        "body": {
            "id": "ab04e2cd-5278-4051-99b3-6d6298e701ec",
            "create_date": "2019-10-18T16:50:24.000+0000",
            "update_date": "2019-10-18T16:50:24.000+0000",
            "account_name": "Plaid Gold Standard 0% Interest Checking",
            "client_id": "0f51f4e6-c94c-4813-a0dc-c21eddfd4e5f",
            "institution_name": "Chase",
            "category": "Banking",
            "subcategory": "Checking",
            "account_number": "1111222233330000",
            "currency_code": "USD",
            "is_active": true,
            "metadata": {},
            "mask": "0000",
            "account_holder": null,
            "is_asset": true,
            "financial_offer_id": null
        }
    }
}

Get the latest details for the aggregation account link from the vendor.

HTTP REQUEST

GET /aggregation/account/{nucleus_aggregation_account_id}

ARGUMENTS

Field Type Required Description
nucleus_aggregation_account_id string required Aggregation account in Nucleus that is linked to the vendor

RESPONSE

Field Description
message A status message explaining the actions that were performed.
vendor_name The name of the vendor used to create the aggregation accounts.
nucleus_aggregation_accounts An array of response objects, with each object corresponding to the aggregation account creation for a different held away account.
     status_code The status code of the API call made to create the aggregation account.
     body The aggregation account object created in Nucleus.

Example Request

curl -X DELETE -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
    "https://api.hydrogenplatform.com/integration/v1/aggregation/account/464b026e-4346-4c1e-a829-764b7b2a4f1b"

Response (204 No Content)

Permanently delink an aggregation account at the vendor.

HTTP REQUEST

DELETE /aggregation/account/{nucleus_aggregation_account_id}

Balances

An aggregation account may have balances stored each day to track the value of the account over time. This calls the vendor aggregation service for balances and updates the Nucleus aggregation_account_balance entity for the aggregation_account_id.

Update an aggregation account balances

Example Request

curl -X GET -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
    "https://api.hydrogenplatform.com/integration/v1/aggregation/balance/464b026e-4346-4c1e-a829-764b7b2a4f1b"

Example Response (Plaid)

{
    "nucleus_aggregation_account_id": "ab04e2cd-5278-4051-99b3-6d6298e701ec",
    "message": "Success",
    "vendor_name": "plaid",
    "nucleus_balance_posted": {
        "id": "b0672811-5554-4c0a-9cb3-e953c5f9e49a",
        "balance": "110.0",
        "secondary_id": null,
        "create_date": "2019-10-18T17:24:12.689+0000",
        "update_date": "2019-10-18T17:24:12.689+0000",
        "is_active": true,
        "currency_code": "USD",
        "available_balance": "100.0",
        "balance_time_stamp": "2019-10-18T17:24:12.648+0000",
        "aggregation_account_id": "ab04e2cd-5278-4051-99b3-6d6298e701ec"
    }
}

Get the latest balance details for the aggregation account from the vendor configured.

HTTP REQUEST

GET /aggregation/balance/{nucleus_aggregation_account_id}

ARGUMENTS

Field Type Required Description
nucleus_aggregation_account_id string required Aggregation account in Nucleus that is linked to the vendor

RESPONSE

Field Description
nucleus_aggregation_account_id The ID of the aggregation account for which a balance record was retrieved.
message A message explaining the actions that were performed.
vendor_name The name of the vendor used to create the aggregation accounts.
nucleus_balance_posted The aggregation account balance object created in Nucleus.

Transactions

An aggregation account may have transactions stored each day to track activity in the account over time.

Update an aggregation account transactions

Example Request

curl -X GET -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
    "https://api.hydrogenplatform.com/integration/v1/aggregation/transaction/464b026e-4346-4c1e-a829-764b7b2a4f1b"

Example Response (Plaid)

{
    "nucleus_aggregation_account_id": "ab04e2cd-5278-4051-99b3-6d6298e701ec",
    "message": "Success",
    "vendor_name": "plaid",
    "nucleus_transactions_posted": [
        {
            "status_code": 200,
            "body": {
                "id": "c18c452d-276f-44e6-93a9-9f91d48b4d55",
                "aggregation_account_id": "ab04e2cd-5278-4051-99b3-6d6298e701ec",
                "transaction_date": "2019-08-19T00:00:00.000+0000",
                "bank_credit": {
                    "transaction_type": "Debit",
                    "amount": 5.4,
                    "merchant": "Uber 063015 SF**POOL**",
                    "category": "Travel",
                    "subcategory": "Rental Car & Taxi",
                    "description": null,
                    "memo": null,
                    "location": {}
                },
                "investment": null,
                "is_excluded_analysis": false,
                "metadata": {},
                "secondary_id": "q3gbvmZPKgc9V939d9xxUKbxd74oaGcdaKqJy",
                "create_date": "2019-10-18T17:31:06.740+0000",
                "update_date": "2019-10-18T17:31:06.740+0000",
                "currency_code": "USD"
            }
        },
        {
            "status_code": 200,
            "body": {
                "id": "21e91ec1-f8f6-4946-a696-79ace6a6070b",
                "aggregation_account_id": "ab04e2cd-5278-4051-99b3-6d6298e701ec",
                "transaction_date": "2019-09-14T00:00:00.000+0000",
                "bank_credit": {
                    "transaction_type": "Debit",
                    "amount": 89.4,
                    "merchant": "SparkFun",
                    "category": "Food & Dining",
                    "subcategory": "General",
                    "description": null,
                    "memo": null,
                    "location": {}
                },
                "investment": null,
                "is_excluded_analysis": false,
                "metadata": {},
                "secondary_id": "rx8gvLMkr8SKnKAKaKddIRxo8Dm159clxRvy9",
                "create_date": "2019-10-18T17:31:07.069+0000",
                "update_date": "2019-10-18T17:31:07.069+0000",
                "currency_code": "USD"
            }
        }
    ]
}

Get the latest transactions activity for the aggregation account from the vendor configured.

HTTP REQUEST

GET /aggregation/transaction/{nucleus_aggregation_account_id}

ARGUMENTS

Field Type Required Description
nucleus_aggregation_account_id string required Aggregation account in Nucleus that is linked to the vendor

RESPONSE

Field Description
nucleus_aggregation_account_id The ID of the aggregation account for which a balance record was retrieved.
message A message explaining the actions that were performed.
vendor_name The name of the vendor used to create the aggregation accounts.
nucleus_transactions_posted An array of objects, each corresponding to a different transaction.
     status_code The status code of the API call made to create the aggregation account.
     body The aggregation account object created in Nucleus.

Holdings

An aggregation investment account may have holdings stored each day to track a portfolio over time.

Update an aggregation account holdings

Example Request

curl -X GET -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
    "https://api.hydrogenplatform.com/integration/v1/aggregation/holding/464b026e-4346-4c1e-a829-764b7b2a4f1b"

Example Response (Plaid)

{
    "nucleus_aggregation_account_id": "2bf63064-f286-4d86-9a15-c32a5b9edd87",
    "message": "Success",
    "vendor_name": "plaid",
    "nucleus_holdings_posted": [
        {
            "status_code": 200,
            "body": {
                "id": "845ef510-9cef-4c85-90f4-e654988812b4",
                "aggregation_account_id": "2bf63064-f286-4d86-9a15-c32a5b9edd87",
                "ticker": "NFLX180201C00355000",
                "ticker_name": "Nflx Feb 01'18 $355 Call",
                "shares": 10000,
                "holding_date": "2019-11-05T00:00:00.000Z",
                "currency_code": "USD",
                "amount": 110,
                "holding_type": "Derivative",
                "asset_class": null,
                "price": 0.011,
                "cost_basis": 0.01,
                "exchange": null,
                "cusip": null,
                "metadata": {},
                "secondary_id": "8E4L9XLl6MudjEpwPAAgivmdZRdBPJuvMPlPb",
                "create_date": "2019-11-05T20:28:31.245Z",
                "update_date": "2019-11-05T20:28:31.245Z"
            }
        },
        {
            "status_code": 200,
            "body": {
                "id": "5f83e111-b515-4c9a-b2a9-972c5b9d3e5f",
                "aggregation_account_id": "2bf63064-f286-4d86-9a15-c32a5b9edd87",
                "ticker": "EWZ",
                "ticker_name": "iShares Inc MSCI Brazil",
                "shares": 5,
                "holding_date": "2019-11-05T00:00:00.000Z",
                "currency_code": "USD",
                "amount": 210.75,
                "holding_type": "ETF",
                "asset_class": null,
                "price": 42.15,
                "cost_basis": 40,
                "exchange": null,
                "cusip": "464286400",
                "metadata": {},
                "secondary_id": "abJamDazkgfvBkVGgnnLUWXoxnomp5up8llg4",
                "create_date": "2019-11-05T20:28:31.535Z",
                "update_date": "2019-11-05T20:28:31.535Z"
            }
        }
    ]
}

Get the latest holdings for the aggregation investment account from the vendor configured.

HTTP REQUEST

GET /aggregation/holding/{nucleus_aggregation_account_id}

ARGUMENTS

Field Type Required Description
nucleus_aggregation_account_id string required Aggregation account in Nucleus that is linked to the vendor

RESPONSE

Field Description
nucleus_aggregation_account_id The ID of the aggregation account for which a balance record was retrieved.
message A message explaining the actions that were performed.
vendor_name The name of the vendor used to create the aggregation accounts.
nucleus_holdings_posted An array of objects, each corresponding to a different holding.
     status_code The status code of the API call made to create the aggregation account.
     body The aggregation account object created in Nucleus.

Property Values

Create a property value

Example Request

curl -X POST -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
    -H "Content-Type: application/json" \
    -d '{
            "nucleus_client_id": "1c2488c5-0d26-4e40-b13a-f7953059ea1d",
            "nucleus_aggregation_account_id":"ce9b7574-1e9a-4f50-90c7-312acac93384"
        }' "https://api.hydrogenplatform.com/integration/v1/property_value"

Example Response (Zillow)

{
    "nucleus_client_id": "1c2488c5-0d26-4e40-b13a-f7953059ea1d",
    "integration_type": "aggregation",
    "product": "atom",
    "vendor_name": "zillow",
    "vendor_response":     {
        "zp_id": "63732464"            
    }
}

Create an aggregation account link for a property you want to track. This calls the vendor aggregation service to retrieve the unique ID for a property, based on the address in an aggregation account which contains the address information of the property, which is needed to retrieve the latest property value.

You will first need to create a Nucleus aggregation_account which has a category value of “Property” along with the following fields in the metadata keys:

address_line1
address_line2
city
state
postalcode
country

HTTP REQUEST

POST /property_value

ARGUMENTS

Field Type Required Description
nucleus_client_id UUID required The ID of the Nucleus client for whom the account verification will be performed.
nucleus_aggregation_account_id UUID required The ID of the aggregation account for which the property value is stored.

RESPONSE

Field Description
nucleus_client_id The ID of the client for which the unique ID for the property was retrieved.
integration_type The integration for which this data is needed. Values could be: aggregation
product The name of the Hydrogen product that is making the call. Values could be: atom
vendor_name The name of the vendor used to retrieve the property value.
vendor_response An array of objects, each corresponding to the details of the property from the vendor aggregation service.

Update a property value

A property will be stored as an Aggregation Account in Nucleus. To update and retrieve the latest balance on the property, please use the same Aggregation Account Balance service passing in the nucleus_aggregation_account_id.

IAV

Instant Account Verification (IAV) scrapes the account and routing numbers of bank accounts via supplied user credentials to confirm the ownership of the account and the validity of the data.

Supported Vendors
Plaid

Coming Soon
MX

Settings
You will be able to set the following settings for IAV in the integrations admin on the developer portal:

  1. Automatically link a bank account on successful IAV

    • By selecting this option, once a bank account has successfully passed IAV, this setting will allow you to automatically create a link to that account so you don’t have to create a link each time you need information for that account or want to perform a one time check of account ownership or a KYC check as well as a one time balance check.

    • By unselecting this option, once a bank account has successfully passed IAV, this setting will require that you make an IAV call every time the account needs to be accessed for information.

  2. Create an aggregation account link for any account that has been verified via IAV to pull in balances, transactions, and holdings. This setting will only work for vendors that have been configured for both IAV and Aggregation.

    • By selecting this option, once a bank account has been verified using IAV, an aggregation account link will be created for the account to allow balances, transactions, and holdings from the account to be stored.

    • By unselecting this option, once a bank account has been verified using IAV, an aggregation account link will need to be created manually for the account to allow balances, transactions, and holdings from the account to be stored.

  3. Restrict accounts pulled back from the integration to a specific currency code

    • By selecting this option, accounts that do not have the same currency code as the currency code specified with this option will not be returned.

    • By unselecting this option, accounts that do not have the same currency code as the currency code specified with this option will be returned as part of the IAV response.

Verify an account

Example Request (Plaid)

curl -X POST -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
  -H "Content-Type: application/json" \
  -d '{
            "nucleus_client_id": "de1f1a2b-5823-436e-9ec1-7d92436d9489",
            "nucleus_account_id": "1628a66d-92fe-485f-825a-e5b376504514",
            "product": "atom",
            "vendor_request": {
                "item_id": "RmxPkjDEpafDomK91nR9TnKJA9qDzWFRqlovL"
            }
      }' "https://api.hydrogenplatform.com/integration/v1/iav"

Example Response (Plaid)

{
    "vendor_name": "plaid",
    "bank_link": {
        "message": "New Bank_Link(s) created successfully.",
        "response": [
            {
                "status_code": 200,
                "nucleus_bank_link": {
                    "id": "d5ffc22c-3c87-41d2-a941-33276fbde847",
                    "create_date": "2019-11-18T19:52:33.259Z",
                    "update_date": "2019-11-18T19:52:33.259Z",
                    "client_id": "de1f1a2b-5823-436e-9ec1-7d92436d9489",
                    "account_id": "1628a66d-92fe-485f-825a-e5b376504514",
                    "bank_account_name": "Plaid Gold Standard 0% Interest Checking",
                    "bank_account_holder": "Samantha Jong",
                    "bank_account_number": "1111222233330000",
                    "mask": "0000",
                    "name": "Chase",
                    "routing": "011401533",
                    "routing_wire": "021000021",
                    "currency_code": "USD",
                    "balance": "110.0",
                    "available_balance": "100.0",
                    "type": "checking",
                    "is_active": true,
                    "is_link_verified": true,
                    "link_verified_date": "2019-11-18",
                    "metadata": {}
                }
            }
        ]
    },
    "aggregation": {
        "message": "New Aggregation account(s) created successfully.",
        "response": [
            {
                "status_code": 200,
                "nucleus_aggregation_account_id": "c0f193cc-5dd1-4eca-91bc-62ff6bac45b9"
            }
        ]
    }
}

Verify the ownership of a client’s bank account and pull back the account and routing numbers into Nucleus to initiate a bank transfer.

HTTP REQUEST

POST /iav

ARGUMENTS

Field Type Required Description
nucleus_client_id UUID required The ID of the Nucleus client for whom the account verification will be performed.
product string required The name of the product which will be making the call to the IAV integration provider. Applicable values include: atom. (As Hydrogen expands its product offering and those products require IAV services, then the list of applicable values will continue to grow.)
vendor_request JSON required Vendor specific fields needed for integration. Please check the vendor page for instructions.
nucleus_account_id UUID optional The ID of the pre-existing Nucleus account to which the bank link should be made.

RESPONSE

Field Description
bank_link The ID of the Nucleus client for whom the account verification will be performed.
    message The message provided back regarding the status of the bank link(s) creation.
    response An array of objects, with each object corresponding to the verification/bank link creation for a different held away account.
        status_code The status code of the API call made to create the bank link.
        nucleus_bank_link The bank link object created in Nucleus, or details of the account verification when the setting to create a bank link is turned off.
aggregation The object containing all information regarding aggregation account(s) created in Nucleus.
    message The message provided back regarding the status of the aggregation account(s) creation.
    response An array of response objects, with each object corresponding to the aggregation account creation for a different held away account.
        status_code The status code of the API call made to create the Nucleus aggregation account.
        nucleus_aggregation_account_id The ID of the aggregation account created in Nucleus.

Update a verified account

Example Request

curl -X GET -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
    "https://api.hydrogenplatform.com/integration/v1/iav/464b026e-4346-4c1e-a829-764b7b2a4f1b"

Example Response

{
    "id": "4ff21db3-97ab-4bbd-9885-be6aec522c44", 
    "create_date": "2018-04-12T17:34:17.000+0000", 
    "update_date": "2018-04-12T17:34:17.000+0000", 
    "account_id": "647c54c3-b649-477e-8cc7-eee56a120dd3", 
    "bank_account_holder": "Jon Linndt", 
    "bank_account_name": "HSBC Checking", 
    "bank_account_number": "111111", 
    "mask": "xx1111", 
    "name": "HSBC", 
    "routing": "111111",
    "routing_wire": "111111-22", 
    "currency_code": "USD", 
    "balance": "1500", 
    "available_balance": "1600", 
    "type": "Checking", 
    "is_active": true, 
    "is_link_verified": true, 
    "link_verified_date": "2018-01-01", 
    "type": "Checking", 
    "metadata": {} 
}

Get the latest balance and available_balance for a verified account that is being used as a Bank Link in Nucleus. The API will return the updated account info in the Bank Link response.

HTTP REQUEST

GET /iav/{nucleus_bank_link_id}

KMS

Key Management Servers (KMS) store public and private key pairs that can be used for blockchain keys or user passwords.

For Molecule, Azure KeyVault is the only available choice for generating blockchain wallets (POST /wallet_key/generate). If the user does not have an Azure KeyVault configured (POST /wallet_key/generate?false), Molecule keys will be generated and stored in the Hydrogen-managed database (Nucleus), or in the AWS Secret Manager, based on the default service configured in the Adaptor.

Supported Vendors
Azure
AWS Secret Manager

Field Type Description
nucleus_client_id UUID The ID of the client in Nucleus that owns the key pair
product string The name of the Hydrogen product. Value may be atom or molecule
wallet_id UUID The ID of the wallet in Molecule that owns the key pair. Required when product = molecule.
key_name string The name of the key such as username to be stored in the KMS vendor. Must be created outside of integration service and then passed into request.
key_value string The value of the key such as password to be stored in the KMS vendor. Must be created outside of integration service and then passed into request.

List all KMS keys

Example Request

curl -X GET -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
    "https://api.hydrogenplatform.com/integration/v1/kms"

Example Response

{
    "content": [
        {
            "id": "b9098040-1fc7-4972-bba1-ef67fae15365",
            "product": "atom",
            "nucleus_client_id": "d296d96f-782e-456f-95b2-9e26cace45e6"
        },
        {
            "id": "9b2da635-ec70-4b46-989e-9338b94c1912",
            "product": "atom",
            "nucleus_client_id": "d296d96f-782e-456f-95b2-9e26cace45e6"
        }
    ],
    "last": false,
    "total_pages": 1,
    "total_elements": 2,
    "sort": [
        {
            "direction": "DESC",
            "property": "updateDate",
            "ignore_case": false,
            "null_handling": "NATIVE",
            "descending": true,
            "ascending": false
        }
    ],
    "first": true,
    "number_of_elements": 3,
    "size": 25,
    "number": 0
}

Get all KMS keys.

HTTP REQUEST

GET /kms

Create keys in the KMS

Example Request

curl -X POST -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
    -H "Content-Type: application/json" \
    -d '{
            "nucleus_client_id":"c06c70b1-aa63-424b-976c-db840fceef5e",
            "product":"atom",
            "key_name":"user123",
            "key_value":"pass123"
        }' "https://api.hydrogenplatform.com/integration/v1/kms"

Example Response

{
    "id": "23cea8f5-cd94-44dc-855f-fc0026b2a857",
    "product": "atom",
    "nucleus_client_id": "c06c70b1-aa63-424b-976c-db840fceef5e"
}

Create keys at a KMS vendor.

HTTP REQUEST

POST /kms

ARGUMENTS

Field Type Required Description
nucleus_client_id UUID required The ID of the client in Nucleus that owns the key pair
product string required The name of the Hydrogen product. Value may be atom or molecule
wallet_id UUID required, conditional The ID of the wallet in Molecule that owns the key pair. Required when product = molecule.
key_name string required The name of the key such as username to be stored in the KMS vendor. Must be created outside of integration service and then passed into request.
key_value string required The value of the key such as password to be stored in the KMS vendor. Must be created outside of integration service and then passed into request.

Update keys in the KMS

Example Request

curl -X PUT -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
    -H "Content-Type: application/json" \
    -d '{
            "nucleus_client_id": "d296d96f-782e-456f-95b2-9e26cace45e6"
        }' "https://api.hydrogenplatform.com/integration/v1/kms/23cea8f5-cd94-44dc-855f-fc0026b2a857"

Example Response

{
    "id": "23cea8f5-cd94-44dc-855f-fc0026b2a857",
    "product": "atom",
    "nucleus_client_id": "d296d96f-782e-456f-95b2-9e26cace45e6"
}

Update keys at a KMS vendor.

HTTP REQUEST

PUT /kms/{kms_id}

ARGUMENTS

Parameter Type Required Description
client_id string required The ID of the client in Nucleus that owns the key pair

Retrieve keys from the KMS

Example Request

curl -X GET -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
    "https://api.hydrogenplatform.com/integration/v1/aggregation/kms/23cea8f5-cd94-44dc-855f-fc0026b2a857"

Example Response

{
    "id": "23cea8f5-cd94-44dc-855f-fc0026b2a857",
    "product": "atom",
    "nucleus_client_id": "d296d96f-782e-456f-95b2-9e26cace45e6",
    "key_name": "user123",
    "key_value": "pass123"
}

Get the latest details for the aggregation account link.

HTTP REQUEST

GET /kms/{kms_id}

Delete keys in the KMS

Example Request

curl -X DELETE -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
    "https://api.hydrogenplatform.com/integration/v1/kms/23cea8f5-cd94-44dc-855f-fc0026b2a857"

Response (204 No Content)

Permanently delete keys at a KMS vendor.

HTTP REQUEST

DELETE /kms/{kms_id}

KYC

Know Your Customer (KYC) vendors check details supplied about a client against government records to confirm the validity of the details.

Supported Vendors
Trulioo

Coming Soon
Onfido
IDology

Settings
You will be able to set the following settings for KYC in the integrations admin on the developer portal:

Atom

Molecule

KYC a client

Example Request

curl -X POST -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
    -H "Content-Type: application/json" \
    -d '{
            "nucleus_client_id": "5f8c6b1b-c032-4fff-9d4f-e0cd3ec6291",
            "product": "atom",
            "kyc_type": "iv"
        }' "https://api.hydrogenplatform.com/integration/v1/kyc"

Example Response

{
    "nucleus_client_id": "5f8c6b1b-c032-4fff-9d4f-e0cd3ec6291c",
    "kyc_status": "match",
    "vendor_name": "trulioo",
    "vendor_request_data": {
        "first_name": "John",
        "last_name": "Smith",
        "middle_name": "Henry",
        "date_of_birth": "1983-03-05",
        "identification_number": "076310691",
        "country_of_residence": null,
        "address": [
            {
                "address_line1": "3 Downtown Street",
                "city": "New York",
                "type": "Home",
                "postalcode": "01191",
                "country": "US",
                "state": "NY"
            }
        ],
        "gender": "male",
        "metadata": {
            "country": "AU",
            "net_worth": "1350000",
            "year_of_expiry": "2021",
            "accredited_investor": "true",
            "month_of_expiry": "4",
            "identification_type": "DRIVERLICENSE",
            "state": "VIC",
            "day_of_expiry": "3"
        }
    },
    "vendor_response": {omitted due to length}
}

Submit a client’s personal details to the KYC vendor configured for identity verification. This service accepts a nucleus_client_id and performs KYC check based on the KYC vendor configured and data found in Nucleus. The required fields will differ by vendor (check vendor page), and a list of all fields sent to the vendor for analysis will be listed in the vendor_request_data object in the response. The following is an example of common fields taken from Nucleus /client:

first_name
last_name
date_of_birth
identification_number
country_of_residence
address

HTTP REQUEST

POST /kyc

ARGUMENTS

Parameter Type Required Description
nucleus_client_id UUID required The ID of the client in Nucleus that will be submitted for KYC
product string required The name of the Hydrogen product. Value may be atom or molecule
kyc_type string required The type of KYC you would like to perform. Supported types currently include iv for Identity Verification.

Retrieve a KYC status

Example Request

curl -X GET -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
    "https://api.hydrogenplatform.com/integration/v1/kyc_status/464b026e-4346-4c1e-a829-764b7b2a4f1b"

Example Response

[
    {
        "nucleus_client_id": "5f8c6b1b-c032-4fff-9d4f-e0cd3ec6291c",
        "kyc_status": "match",
        "kyc_type": "iv",
        "create_date": "2019-10-17T20:04:58.932Z",
        "update_date": "2019-10-17T20:04:58.932Z",
        "product": "atom",
        "vendor_name": "trulioo",
        "vendor_request_data": {omitted due to length},
        "vendor_response": {omitted due to length}
    },
    {
        "nucleus_client_id": "5f8c6b1b-c032-4fff-9d4f-e0cd3ec6291c",
        "kyc_status": "match",
        "kyc_type": "iv",
        "create_date": "2019-10-17T19:37:29.122Z",
        "update_date": "2019-10-17T19:37:29.122Z",
        "product": "atom",
        "vendor_name": "trulioo",
        "vendor_request_data": {omitted due to length},
        "vendor_response": {omitted due to length}
    }
]

Get the KYC details for a client from the vendor configured for KYC. Each KYC performed will be stored as a receipt in Hydrogen.

HTTP REQUEST

GET /kyc_status/{nucleus_client_id}

ARGUMENTS

Parameter Type Required Description
get_latest boolean optional Get only the latest KYC status record for this client. A value of true will return the latest record.
kyc_type string optional The type of KYC for which the client’s KYC status record is being requested. Supported types currently include iv for Identity Verification.

Utils

Token Exchange

Hydrogen offers a service to facilitate token exchange flows. This is valuable for vendors that incorporate both application and client authentication into their workflows. To make this process easier for the developer, Hydrogen offers a generic endpoint to manage token exchange workflows for the following vendors:

Plaid

Using Plaid as an example, you would be required to maintain a server to handle the exchange between an ephemeral public token and a persistent access token, which can be used to retrieve a user’s bank account information. To offload this work from our clients, a developer may instead send their public token directly to the Hydrogen API, which will exchange the token on their behalf and subsequently associate the persistent access_token with their nucleus_client_id.

Example Request (Plaid)

curl -X POST -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
    -H "Content-Type: application/json" \
    -d '{
            "nucleus_client_id": "0f51f4e6-c94c-4813-a0dc-c21eddfd4e5f",
            "integration_type": "iav",
            "product": "atom",
            "vendor_name": "plaid",
            "vendor_request": {
                "public_token": "public-sandbox-e3cbf19e-7372-4c0e-a48d-fdf3a3fc9662",
                "metadata": {
                    "institution": {
                        "name": "Chase",
                        "institution_id": "ins_3"
                    },
                    "account": {
                        "id": "Z1r7gaxNa7uojogP7dDDfJNKQzbbxLFgjwryX",
                        "name": "Plaid Checking",
                        "type": "depository",
                        "subtype": "checking",
                        "mask": "0000"
                    },
                    "account_id": "Z1r7gaxNa7uojogP7dDDfJNKQzbbxLFgjwryX",
                    "accounts": [
                        {
                            "id": "Z1r7gaxNa7uojogP7dDDfJNKQzbbxLFgjwryX",
                            "name": "Plaid Checking",
                            "mask": "0000",
                            "type": "depository",
                            "subtype": "checking"
                        }
                    ],
                    "link_session_id": "9218bf08-e3db-443d-80f6-6440d497b5c8",
                    "public_token": "public-sandbox-e3cbf19e-7372-4c0e-a48d-fdf3a3fc9662"
                }
            }
        }' "https://api.hydrogenplatform.com/integration/v1/token_exchange"

Example Response (Plaid)

{
    "nucleus_client_id": "0f51f4e6-c94c-4813-a0dc-c21eddfd4e5f",
    "integration_type": "iav",
    "product": "atom",
    "vendor_name": "plaid",
    "vendor_response": {
        "institution_name": "Chase",
        "institution_id": "ins_3",
        "account": {
            "id": "Z1r7gaxNa7uojogP7dDDfJNKQzbbxLFgjwryX",
            "name": "Plaid Checking",
            "type": "depository",
            "subtype": "checking",
            "mask": "0000"
        },
        "access_token": "access-sandbox-a760b923-3542-4df4-91db-59e015177caf",
        "item_id": "NxmKwJeGJKu4A436jD11SwKya3aGw4hWJqkzG"
    }
}

HTTP REQUEST

POST /token_exchange

ARGUMENTS

Field Type Required Description
nucleus_client_id UUID required The ID of the client in Nucleus that will be submitted for KYC
product string required The name of the Hydrogen product. Value may be atom or molecule
integration_type string required The type of integration for which the token exchange is being made. Value may be kyc, kms, iav and aggregation.
vendor_name string required The name of the vendor for which the token exchange is being made. Value may be plaid. As Hydrogen expands support for additional integration providers who have token exchanges, those vendors will be added here.
vendor_request string required The vendor-specific request object.

Resources

Transaction Categories

If you choose to use Hydrogen category mappings in the Account Aggregation integration settings, we will use the following which will be mapped to a corresponding label from the vendor. For example, Plaid has a category of “Depository” and a subcategory of “Savings” for transaction data. We have mapped this in our integration service to our new category “Banking” with subcategory “Savings”.

Category: Subcategory
Banking: General
Banking: CD
Banking: Checking
Banking: Savings
Banking: Money Market
Banking: Prepaid
Banking: E-Wallet
Banking: Recurring Deposit
Bills: General
Bills: Utility
Bills: Cable
Bills: Phone
Bills: Internet
Credit Card: General
Loan: General
Loan: Auto
Loan: Mortgage
Loan: Student
Loan: Commercial
Loan: Home Equity
Loan: Personal
Loan: Overdraft
Loan: Line of Credit
Insurance: General
Insurance: Life
Insurance: Annuity
Insurance: Health
Insurance: Auto
Insurance: Property
Investment: General
Investment: 401a
Investment: 401k
Investment: 403b
Investment: 457
Investment: Roth
Investment: Brokerage
Investment: IRA
Investment: SEP IRA
Investment: Simple IRA
Investment: ISA
Investment: Stock Plan
Investment: Education
Investment: Health
Investment: Custodial
Investment: Pension
Investment: Profit Sharing
Investment: Trust
Investment: Income Fund
Investment: Savings Plan
Investment: Other Retirement
Property: General
Property: Residential
Property: Commercial
Property: Industrial
Property: Land
Other: Rewards
Other: General