NAV

Nucleus  Proton  Electron

curl java python ruby javascript

Introduction

Sandbox Base URL

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

Production Base URL

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

The Hydrogen Nucleus API provides the digital infrastructure you will need to quickly build and scale your fintech application in banking, savings, wealth, financial wellness, and insurance. This includes the base functionality to authenticate, onboard clients and accounts, and store and process data which all other APIs in the Hydrogen Atom platform will utilize.

All Hydrogen APIs are built on REST principles, with resource oriented URLs and HTTP response codes. All API responses are returned in JSON format. Additional features of the API include filtering, pagination, and data caching.

We provide a free sandbox environment to test our APIs before going into production. Please sign up now to request your keys.

Authentication

API Authentication

After successful registration of your application, you will be provided a client_id and client_secret which will be used to identify your application when calling any Hydrogen API.

We require all API calls to be made over HTTPS connections.

OAuth2 Authorization

Hydrogen uses OAuth 2.0 to facilitate authorization on the API, an industry standard framework for authorization. Two standard type of flows are supported:

  1. Client Credentials
  2. Resource Owner Password Credentials

Client Credentials

The Client Credentials authorization flow consists of exchanging a client_id and client_secret for an access_token to be provided when making calls to the Hydrogen API. This type of authorization is used for the application to access resources about itself rather than a user.

Example Request

curl -X POST -H "Authorization: Basic <Base64 encoded client_id:client_secret>" \
"https://[sandbox][api].hydrogenplatform.com/authorization/v1/oauth/token?grant_type=client_credentials"

Example Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzY29wZSI6WyJ4Il0sImV4cCI6MTU4NjQ3OTcxNCwiYXV0aG9yaXRpZXMiOlsiUk9MRV9TVVBFUl9BRE1JTiJdLCJqdGkiOiIwNDMzZjA1Ni00NWQyLTQ0MjYtODliNi01MjMwMTNiZjdhOGEiLCJjbGllbnRfaWQiOiJUZXN0VXNlciIsImFwcHMiOiJudWNsZXVzLHByb3RvbixlbGVjdHJvbixoeWRybyxpb24saW50ZWdyYXRpb24ifQ.oJHd6pIu2f6zwP4jGe-MIRK0FVCC-82EVrld5kbJoRYtvs_27KM0xZm-VfkfKN8q5qnKyqfWUyS4ptoDhg4UWVuJ3st9Gp6k_EWDFTGVQmxtsn4Sc_c3VTjpW39ZDTQAoGFH4T6yOaIr5FYQaBN17kAt2_ELEyrXwvGG3BVVG-pX3nFnu98meYIoq7pQt-1EMKIOMLWuillO5FuVYgJpy1LFfVIrdlbWKtKB3HTGpKw5oVqa7L978jRBM94WZU2pRGabYBQs4Tzs-qaEdPGF2VuOMKIPj1GTxeFg6pB8e1oyEaC1o-p_-qG3H0Vm0RFKBDoBq8nEnf_U8pHaJ7Ta6w",
  "token_type": "bearer",
  "expires_in": 86400,
  "scope": "create read update delete",
  "apps": "nucleus,proton,electron"
}

All subsequent API calls will then be made like the following example. Replace <access_token> after Bearer with the access_token received above and the [sandbox] or [api] subdomain based on your environment:

curl -X GET -H "Authorization: Bearer <access_token>" \
"https://[sandbox][api].hydrogenplatform.com/nucleus/v1/account"

The client credentials flow is used by your application to obtain permission to act on its own behalf. A call will be made to our OAuth server to exchange your client_id, client_secret, and grant_type=client_credentials for an access_token, which can then be used to make calls to Hydrogen on behalf of the application.

HTTP REQUEST

POST /authorization/v1/oauth/token?grant_type=client_credentials

ARGUMENTS

Parameter Type Required Description
client_id string required Application id for identification, which will be given to you when you are onboarded
client_secret string required Application secret, which will be given to you only once when you are onboarded. Please keep this in a safe place
grant_type string required Must be set to client_credentials

RESPONSE

Field Description
access_token JWT token that will be used for all subsequent API calls
expires_in When the token expires in seconds and will need to be called again. Default is 86400 or 24 hours.
token_type Always will be bearer
scope The scope your user has been granted in the application
apps APIs to which the user has access. Possible values include nucleus, proton, electron, molecule, hydro, integration
jti Unique identifier for the JWT token

Resource Owner Password Credentials

The Resource Owner Password Credentials authorization flow consists of exchanging a username and password specific to a user in addition to your client_id and client_secret for an access_token to be provided when making calls to the Hydrogen API. This type of authorization validates the username and password of a user and is used for the application to access resources about a user.

Example Request

curl -X POST -H "Authorization: Basic <Base64 encoded client_id:client_secret>" \
"https://[sandbox][api].hydrogenplatform.com/authorization/v1/oauth/token?grant_type=password&username={username}&password={password}"

Example Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzY29wZSI6WyJ4Il0sImV4cCI6MTU4NjQ3OTcxNCwiYXV0aG9yaXRpZXMiOlsiUk9MRV9TVVBFUl9BRE1JTiJdLCJqdGkiOiIwNDMzZjA1Ni00NWQyLTQ0MjYtODliNi01MjMwMTNiZjdhOGEiLCJjbGllbnRfaWQiOiJUZXN0VXNlciIsImFwcHMiOiJudWNsZXVzLHByb3RvbixlbGVjdHJvbixoeWRybyxpb24saW50ZWdyYXRpb24ifQ.oJHd6pIu2f6zwP4jGe-MIRK0FVCC-82EVrld5kbJoRYtvs_27KM0xZm-VfkfKN8q5qnKyqfWUyS4ptoDhg4UWVuJ3st9Gp6k_EWDFTGVQmxtsn4Sc_c3VTjpW39ZDTQAoGFH4T6yOaIr5FYQaBN17kAt2_ELEyrXwvGG3BVVG-pX3nFnu98meYIoq7pQt-1EMKIOMLWuillO5FuVYgJpy1LFfVIrdlbWKtKB3HTGpKw5oVqa7L978jRBM94WZU2pRGabYBQs4Tzs-qaEdPGF2VuOMKIPj1GTxeFg6pB8e1oyEaC1o-p_-qG3H0Vm0RFKBDoBq8nEnf_U8pHaJ7Ta6w",
  "token_type": "bearer",
  "expires_in": 86400,
  "scope": "create read update delete",
  "apps": "nucleus,proton,electron",
  "jti": "6118a6c2-92fd-450f-ae1d-198150c0b579"
}

All subsequent API calls will then be made like the following example. Replace <access_token> after Bearer with the access_token received above and the [sandbox] or [api] subdomain based on your environment:

curl -X GET -H "Authorization: Bearer <access_token>" \
"https://[sandbox][api].hydrogenplatform.com/nucleus/v1/account"

The resource owner password credentials flow, or password credentials flow, is used to identify specific users and act according to their permissions. A call will be made to our OAuth server to exchange your client_id and client_secret as well as the user’s username and password, and grant_type=password for a user-specific access_token, which can then be used to make calls to Hydrogen APIs.


HTTP REQUEST

POST /authorization/v1/oauth/token?grant_type=password&username={username}&password={password}

ARGUMENTS

Parameter Type Required Description
client_id string required Application id for identification, which will be given to you when you are onboarded
client_secret string required Application secret, which will be given to you only once when you are onboarded. Please keep this in a safe place
username string required User’s unique username for the application
password string required User’s unique password for the application
grant_type string required Must be set to password

RESPONSE

Field Description
access_token JWT token that will be used for all subsequent API calls
expires_in When the token expires in seconds and will need to be called again. Default is 86400 or 24 hours.
token_type Always will be bearer
scope N/A - this is embedded in the access_token returned
apps APIs to which the user has access. Possible values include nucleus, proton, electron, molecule, hydro, integration
jti Unique identifier for the JWT token

Token Refresh

An access_token will need to be refreshed to continue being authorized for the app. Access tokens are short lived: 24 hours. The Client Credentials grant type doesn’t return a refresh token. When your access_token expires, the app has to simply request a new token which will invalidate the previous token. The token can be deserialized to determine how much longer it is valid.

Client Authentication

You may optionally wish to store user credentials such as usernames and passwords with Hydrogen to permission applications that require a user login. You can set roles for each user to permission the data the user can view or edit. This service may be used in conjunction with the Resource Owner Password Credentials OAuth flow or your own authentication service.

Parameter Type Description
id integer The id of the client within the user administration service
username string User’s unique username for the application. Should be mapped to the username in the Client entity.
password string User’s unique password for the application. All passwords should be passed as plain text and will be encrypted and stored using the Bcrypt algorithm.
authorities string The role for the user. Available values are ROLE_SUPER_ADMIN, ROLE_ADMIN, ROLE_PORTFOLIO_MANAGER, ROLE_MARKETING_MANAGER, ROLE_OPERATIONS, ROLE_SUPPORT, ROLE_ADVISOR, ROLE_CLIENT. To add multiple roles for a client, please comma separate the authorities such as “ROLE_OPERATIONS,ROLE_SUPPORT”. Please view the Authorities resource for more information on each role. To view what endpoints each role permissions, please see this guide
is_account_non_expired boolean Sets the account to be expired if false.
is_account_non_locked boolean Sets the account to be locked if false.
is_credentials_non_expired boolean Sets the credentials to be expired if false.
is_enabled boolean Indicates that the client is enabled if true.
tenant string The name of the tenant instance the user falls under, corresponding to the client_id provided for API Authentication

List all clients in admin

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
"https://[sandbox][api].hydrogenplatform.com/admin/v1/client"

Example Response

{
    "content": [
        {
            "id":29,
            "username": "[email protected]",
            "password": "$2a$10$R0FHWcxDLn4ts65cFMSq2uvt12bWX44PCUwXbhzRWlMYJbHBNHy3i",
            "is_account_non_expired": true,
            "is_account_non_locked": true,
            "is_credentials_non_expired": true,
            "is_enabled": false,
            "authorities": "ROLE_ADMIN",
            "tenant": "TenantName"
        },
        {
            "id": 28,
            "username": "[email protected]",
            "password": "$2a$10$D.239fir3z8x8RTybjmSguiQSdrpV5ktV8pY/g3M5WmNXVPVQwcWm",
            "is_account_non_expired": true,
            "is_account_non_locked": true,
            "is_credentials_non_expired": true,
            "is_enabled": true,
            "authorities": "ROLE_CLIENT",
            "tenant": "TenantName"
        },
        {
            "id": 27,
            "username": "[email protected]",
            "password": "$2a$10$7BYVHGi3zsmRwz83rFDqXedU/Xegckma/h23j1XlumtlkDayfEBGi",
            "is_account_non_expired": true,
            "is_account_non_locked": true,
            "is_credentials_non_expired": true,
            "is_enabled": true,
            "authorities": "ROLE_PORTFOLIO_MANAGER",
            "tenant": "TenantName"
        }
    ],
    "last": false,
    "total_pages": 1,
    "total_elements": 3,
    "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 information for all clients defined for your application. You can filter using any of the parameters except for password.

HTTP REQUEST

GET /admin/v1/client

Create a client in admin

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
       "username": "[email protected]",
       "password": "client123Password",
       "authorities": "ROLE_ADMIN"
    }' "https://[sandbox][api].hydrogenplatform.com/admin/v1/client"

Example Response

{
    "id": 28,
    "username": "[email protected]",
    "password": "$2a$10$D.239fir3z8x8RTybjmSguiQSdrpV5ktV8pY/g3M5WmNXVPVQwcWm",
    "is_account_non_expired": true,
    "is_account_non_locked": true,
    "is_credentials_non_expired": true,
    "is_enabled": true,
    "authorities": "ROLE_CLIENT",
    "tenant": "TenantName"
}

HTTP REQUEST

POST /admin/v1/client

ARGUMENTS

Parameter Type Required Description
username string required User’s unique username for the application. Should be mapped to the username in the Client entity.
password string required User’s unique password for the application. All passwords should be passed as plain text and will be encrypted and stored using the Bcrypt algorithm.
authorities string required The role for the user. Available values are ROLE_SUPER_ADMIN, ROLE_ADMIN, ROLE_PORTFOLIO_MANAGER, ROLE_MARKETING_MANAGER, ROLE_OPERATIONS, ROLE_SUPPORT, ROLE_ADVISOR, ROLE_CLIENT. Please view the Authorities resource for more information on each role. To view what endpoints each role permissions, please see this guide
is_account_non_expired boolean optional Sets the account to be expired if false. Defaults to true.
is_account_non_locked boolean optional Sets the account to be locked if false. Defaults to true.
is_credentials_non_expired boolean optional Sets the credentials to be expired if false. Defaults to true.
is_enabled boolean optional Indicates that the client is enabled if true. Defaults to true.

Retrieve a client in admin

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
  "https://[sandbox][api].hydrogenplatform.com/admin/v1/client/28"

Example Response

{
    "id": 28,
    "username": "[email protected]",
    "password": "$2a$10$D.239fir3z8x8RTybjmSguiQSdrpV5ktV8pY/g3M5WmNXVPVQwcWm",
    "is_account_non_expired": true,
    "is_account_non_locked": true,
    "is_credentials_non_expired": true,
    "is_enabled": true,
    "authorities": "ROLE_CLIENT",
    "tenant": "TenantName"
}

Retrieve the information for a specific client. The unique id must be provided.

HTTP REQUEST

GET /admin/v1/client/{id}

Update a client in admin

Example Request

curl -X PUT -H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
        "is_account_non_locked": false
    }' "https://[sandbox][api].hydrogenplatform.com/admin/v1/client/28"

Example Response

{
    "id": 28,
    "username": "[email protected]",
    "password": "$2a$10$D.239fir3z8x8RTybjmSguiQSdrpV5ktV8pY/g3M5WmNXVPVQwcWm",
    "is_account_non_expired": true,
    "is_account_non_locked": false,
    "is_credentials_non_expired": true,
    "is_enabled": true,
    "authorities": "ROLE_CLIENT",
    "tenant": "TenantName"
}

Update the information for a client. All of the parameters can be updated except for username and tenant.

HTTP REQUEST

PUT /admin/v1/client/{id}

Delete a client in admin

Example Request

curl -X DELETE -H "Authorization: Bearer <access_token>" \
"https://[sandbox][api].hydrogenplatform.com/admin/v1/client/28"

Response (204 No Content)

Permanently delete a client

HTTP REQUEST

DELETE /admin/v1/client/{id}

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. Object IDs do not need to be specified. When using the POST method to create a new object, the ID will be returned as part of the response in the field id:

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 Nucleus 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
2020-04-06 deprecated Deprecated additions field in Client Asset Size, Account Asset Size, and Goal Asset Size responses. Please refer to cash_flow field instead.
2020-04-06 update Added the ability to roundup from an internal account in addition to held away accounts in Roundup Setting. Added the following optional fields: card_program_id to Card; cost_basis and currency_code to Portfolio Holding; currency_code to Funding, Deposit, Withdrawal, and Transfer; currency_code, date_available, and balance to Portfolio Transaction.
2020-04-06 addition Created new entities for Risk Profile, Client Status, Portfolio Goal, Card Program, Question, and Answer. Added the ability to Bulk POST, PUT, and DELETE any entity.
2020-03-27 addition Created new resources for Country, State, Currency and Statistic
2020-03-27 update Added the following optional fields: is_default boolean to Bank Link; is_account, is_client, and is_active booleans to Stage; is_primary boolean and card_image to Card; is_business and is_investment booleans to Aggregation Account; is_recurring boolean and investment.value to Aggregation Account Transaction; cusip and isin to Security, discretionary to Account; is_subledger to Portfolio; asset_size_available to Portfolio Asset Size.
2020-02-26 update Added the following optional fields to Client: total_net_worth, liquid_net_worth, suffix, employment, firm_name, identification_number_type, country_of_citizenship, citizenship_status, image, address.is_primary. Added “prepaid” as an acceptable card_type and card_network as an optional field to Card.
2019-12-19 addition Created new aggregate data views for Account, Client, Portfolio, Goal, Allocation, Aggregation Account, and Advisors. Created new orchestrations for Roundup, Overflow, and Decision Tree. Created new Insurance entities for Coverage, Discount, and Quote.
2019-12-19 update Added the following optional fields: image to Goal; total_expense_ratio to Security; tooltip to Questions and Answers objects in Questionnaire; portfolio_id to Funding, Deposit, and Withdrawal, application_id to Client Response; account_number to Account; bank_link_id to Aggregation Account, metadata to Benchmark and Security, node_map to Financial Offer; is_active to Budget, Account, Financial Offer, Decision Tree, Questionnaire, and Portfolio.
2019-11-04 update Added cash and location maps to Aggregation Account Transaction, gender field to Client, and holding_date field to Aggregation Account Holding.
2019-08-22 update Added ability to link a client_id to a Bank Link and aggregation_accounts to a Budget.
2019-07-11 addition Created new entities for Aggregation Account Transaction, Aggregation Account Holding, Budget, and Financial Offer.
2019-07-11 update Added total_earnings stat to Performance and metadata to remaining services.
2019-03-06 addition Implemented Access Control List (ACL) framework to permission user-specific access to endpoints and data records. Framework includes Authorities, Permission Types, Resource Owner Password Credentials, and User Administration service.
2018-11-30 addition Created new entities for Aggregation Account, Aggregation Account Balance, Score, Client-Hydro, and Goal Track.
2018-11-30 update Added new optional fields to the Client, Bank Link, Withdrawal, and Questionnaire entities.
2018-09-07 addition Created two new orchestration endpoints to subscribe an Account to an allocation and to change the composition of a Model.
2018-09-07 update Added new optional fields goal_amount, accumulation_horizon, decumulation_horizon, client_id, is_active to the Goal entity.

Pagination

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
"https://[sandbox][api].hydrogenplatform.com/nucleus/v1/account?
    page=0&size=10&order_by=id&ascending=true"

Example Response

{
    "content": [
    ],
    "first": true,
    "last": false,
    "number_of_elements": 10,
    "total_elements": 29,
    "total_pages": 3,
    "size": 10,
    "number": 0,
    "sort": [
        {
            "direction": "ASC",
            "property": "id",
            "ignore_case": false,
            "null_handling": "NATIVE",
            "ascending": true,
            "descending": false
        }
]

For API resources that return a large volume of results you may use pagination. When using these “List all” API methods, rather than returning a large list of results, the results will be paginated by default. Please note that pagination is not available on some API resources, specified in the description of the resource.

ARGUMENTS

Parameter Type Description
page
optional
integer Page number for the page that should be returned as the starting page. For example, if this is specified as 0, then the first page of the results will be shown, if it is set as 3 then the third page of the results will be shown, and so on. The default is 0.
size
optional
integer The number or records to be included per page. The default is 25. There is no max value.
order_by
optional
string The field in the response body to order the list by. Default is update_date.
ascending
optional
boolean If true, order the results in ascending order. For an alphabetical result this would be A-Z. If false, order the results in descending order. For an alphabetical result this would be Z-A. Default is false which would order by descending.

Filters

Example Requests

Filter the Account object to pull back all accounts that are a specified account type:

/account?filter=account_type==e4f07fc6-1020-43b8-a1ce-18031671e8e0

Filter the Account object to pull back all accounts that are assigned to a specified goal, which is an object embedded in Account:

/account?filter=goals.goal_id==f87fd7e1-b73d-40b1-9747-74e2b421dd94

Filter all accounts that are assigned to a specified goal, AND are a specified account type:

/account?filter=goals.goal_id==47608aa1-a0f5-4d1b-957a-9dc58da9193f
;account_type==553b8534-c406-4ded-9045-5ee6007c5d91

Every field within an object using the GET method can be filtered except for fields stored under metadata. Filtering is especially useful for calls that return many different fields.

A filter query may consist of one or more logical comparisons:

AND: ; or and
OR: , or or

To group multiple OR statements together, you must add () at the beginning and end of the list of statements

/account?filter=(account_type==553b8534-c406-4ded-9045-5ee6007c5d91,account_type==87e4991b-e2a2-4c14-a3e6-407cbcb01cdf,account_type==b00b6eea-8ab1-4d5a-9c84-4c958d795680);goals.goal_id==47608aa1-a0f5-4d1b-957a-9dc58da9193f

Comparison operators may consist of the following:

Equal to: ==
Not equal to: !=
Less than: =lt= or <
Less than or equal to: =le= or <=
Greater than: =gt= or >
Greater than or equal to: =ge= or >=
In: =in=
Not in: =out=

The basic construct for a filtering query is as follows:

/<endpoint>?filter=<query>

To filter using a simple one word field within an object, the query would be as follows:

/<endpoint>?filter=<fieldname>==<fieldvalue>

To filter using a field with multiple words, enclose the phrase in quotes. The query would be as follows:

/<endpoint>?filter=<fieldname>=="<fieldvalue fieldvalue>"

To filter using a field within an embedded object, the query would be as follows:

/<endpoint>?filter=<objectname>.<fieldname>==<fieldvalue>

To filter using the =in= or =out= options, include a series of comma-separated values wrapped in parentheses, with no spaces between values. The query would be as follows:

/<endpoint>?filter=<fieldname>=in=(<fieldvalue>,<fieldvalue>,<fieldvalue>)

Metadata

Many objects support optional metadata fields, as denoted in the documentation. Metadata is intended to allow developers to extend our API and store custom information that is relevant to their business. Some examples may include:

Metadata may consist of any key-value pair you define such as “Age”:”35” or “City”:”New York”

All metadata that is entered will be returned in the JSON and may consist of up to 255 alphanumeric, string, integer, and boolean characters for each key and each value.

When updating the metadata using any of the PUT endpoints, you should provide both the details you wish to maintain as well as the details you wish to update.

Webhooks

Webhook Management

Atom offer webhooks that you may subscribe to consume 20+ events that may occur within your environment. Webhooks may be useful for building your own alerts service for an application, triggering back office processes, or simply being informed when a new record is created or updated.

You can use the webhook endpoint to manage your active webhook, and what services you want to get notified about.

Field Type Description
id UUID The id of the webhook
url string The url you want to receive the payloads to
secret string Auto generated base64 encoded salt used to hash and verify the sender of the payload. You may either store for each webhook subscription or call the endpoint to retrieve it.
atom_service array The array of Atom services for a webhook to notify
is_active boolean Indicates if this webhook is active
secondary_id string Alternate id that can be used to identify the webhook such as an internal id
create_date timestamp Timestamp for the date and time that the webhook was created
update_date timestamp Timestamp for the date and time that the webhook was last updated

Depending on your atom_service settings, Atom will send a payload to the url of your choice. The list of all available atom_service values is as follows:

Atom Service Description
client POST /client
client_status POST /client_status
client_response POST /client_response
account_status POST /account_status
card POST /card
card_status PUT /card - Update status on card
portfolio_asset_size POST /portfolio_asset_size
portfolio_transaction POST /portfolio_transaction
portfolio_transaction_status PUT /portfolio_transaction - Update status on transaction
portfolio_holding POST /portfolio_holding
aggregation_account POST /aggregation_account
aggregation_account_balance POST /aggregation_account_balance
aggregation_account_transaction POST /aggregation_account_transaction
aggregation_account_transaction_status PUT /aggregation_account_transaction - Update status on transaction
aggregation_account_holding POST /aggregation_account_holding
order_track POST /order_track
funding POST /funding
funding_status PUT /funding - Update funding_status on request
budget POST /budget
document Electron POST /document
notification_client Electron POST /notification_client
audit_log Electron POST /audit_log
support_ticket Electron POST /support_ticket
feature_track Electron POST /feature_track

List all webhooks

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/webhook"

Example Response

{
  "content": [
    {
        "id": "0bd304f4-9996-4676-9c59-dedf486a7f72",
        "url": "https://www.hydrogenplatform.com/callback/client",
        "secret": "cDMzZjNhMGYyZjdhYjk0OTQxY2QwODE4ZDc3aGY5NDhjZGExMDU2Mg==",
        "is_active": true,
        "atom_service": [
            "client",
            "client_status",
            "client_response"
        ],
        "secondary_id": null,
        "create_date": "2019-11-14T16:34:49.000+0000",
        "update_date": "2019-11-14T18:52:44.000+0000"
    },
    {
        "id": "1f6f3345-737a-400f-b5b8-bdb15382f803",
        "url": "https://www.hydrogenplatform.com/callback/budget",
        "secret":"cTMzZjNiMGYyZjlhYjk0OTQxY2QwODE4ZDc5aHQ5NDVjcmExMDU2Mg==",
        "is_active": true,
        "atom_service": ["budget"],
        "secondary_id": null,
        "create_date": "2019-11-14T17:20:21.000+0000",
        "update_date": "2019-11-14T18:52:44.000+0000"
    }
  ],
  "total_pages": 1,
  "total_elements": 2,
  "last": true,
  "first": true,
  "sort": [
    {
      "direction": "ASC",
      "property": "create_date",
      "ignore_case": false,
      "null_handling": "NATIVE",
      "ascending": true,
      "descending": false
    }
  ],
  "number_of_elements": 2,
  "size": 25,
  "number": 0
}

Get information for all webhooks defined for your firm.

HTTP REQUEST

GET /webhook

Create a webhook

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d '{
            "url": "https://www.hydrogenplatform.com/callback/budget",
            "atom_service": ["budget"]
        }' "https://[sandbox][api].hydrogenplatform.com/atom/v1/webhook"

Example Response

{
    "id": "1f6f3345-737a-400f-b5b8-bdb15382f803",
    "url": "https://www.hydrogenplatform.com/callback/budget",
    "secret":"cTMzZjNiMGYyZjlhYjk0OTQxY2QwODE4ZDc5aHQ5NDVjcmExMDU2Mg==",
    "is_active": true,
    "atom_service": ["budget"],
    "secondary_id": null,
    "update_date": "2019-11-14T17:20:21.000+0000",
    "create_date": "2019-11-14T17:20:21.000+0000"
}

One active webhook is allowed for each atom_service. If there already is an active webhook at the time of creating a new active webhook, the old webhook needs to be deactivated.

HTTP REQUEST

POST /webhook

ARGUMENTS

Parameter Type Required Description
url string required The url you want to receive the payloads to. Only http:// or https:// urls allowed
atom_service array required The array of Atom services for a webhook to notify
is_active boolean optional Indicates if this webhook is active. Defaults to true
secondary_id string optional Alternate id that can be used to identify the webhook such as an internal id

Retrieve a webhook

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/atom/v1/webhook/1f6f3345-737a-400f-b5b8-bdb15382f803"

Example Response

{
    "id": "1f6f3345-737a-400f-b5b8-bdb15382f803",
    "url": "https://www.hydrogenplatform.com/callback/budget",
    "secret":"cTMzZjNiMGYyZjlhYjk0OTQxY2QwODE4ZDc5aHQ5NDVjcmExMDU2Mg==",
    "is_active": true,
    "atom_service": ["budget"],
    "secondary_id": null,
    "create_date": "2019-11-14T17:20:21.000+0000",
    "update_date": "2019-11-14T17:20:21.000+0000"
}

Retrieve the information for a specific webhook. The webhook_id must be provided. The endpoint returns the webhook_id and the details for the webhook specified.

HTTP REQUEST

GET /webhook/{webhook_id}

Update a webhook

Example Request

curl -X PUT -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d '{
            "is_active": false
        }' "https://[sandbox][api].hydrogenplatform.com/atom/v1/webhook/1f6f3345-737a-400f-b5b8-bdb15382f803"

Example Response

{
    "id": "1f6f3345-737a-400f-b5b8-bdb15382f803",
    "url": "https://www.hydrogenplatform.com/callback/budget",
    "secret":"cTMzZjNiMGYyZjlhYjk0OTQxY2QwODE4ZDc5aHQ5NDVjcmExMDU2Mg==",
    "is_active": false,
    "atom_service": ["budget"],
    "secondary_id": null,
    "create_date": "2019-11-14T17:20:21.000+0000",
    "update_date": "2019-11-14T18:52:44.000+0000"
}

Update a webhook for your firm. The webhook_id must be provided. To obtain the appropriate webhook_id, use the GET /webhook endpoint to view all of the webhooks for your firm and their current information.

HTTP REQUEST

PUT /webhook/{webhook_id}

Delete a webhook

Example Request

curl -X DELETE -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/webhook/1f6f3345-737a-400f-b5b8-bdb15382f803"

Response (204 No Content)

Permanently delete a webhook for your firm. The webhook_id must be provided. To obtain the appropriate webhook_id, use the GET /webhook endpoint to view all of the webhooks for your firm. This deletes the webhook_id and the details for the webhook record.

HTTP REQUEST

DELETE /webhook/{webhook_id}

Webhook Security

Example Header Payload

{
    "content-length": "621",
    "accept": "application/json, application/*+json",
    "x-hydrogen-signature": "headers=date content-type content-length content,algorithm=HMAC_SHA_256,signature=YTE3ZjdjZGQ0NDc4MDQ5NmZiOGMyNDg0MzliZWI0MDhkNjU4OGVhZTkxMDM1ZTE4Y2M2MmYxZTM3OWNlODFlMg==",
    "x-hydrogen-service": "portfolio_transaction",
    "date": "2020-03-30 16:41:15",
    "content-type": "application/json",
    "user-agent": "Java/1.8.0_242"
}

Example Hashing

Hash using the SHA-256 algorithm with your secret key created for the service. Take the result and Base64 encode and then compare to the signature in the header

2020-03-30 16:41:15 application/json 621 {
    "id": "099961da-7f41-4309-950f-2b51689a0033",
    "create_date": "2018-01-01T9:00:03.000+0000",
    "update_date": "2018-01-05T21:56:03.000+0000",
    "date": "2018-01-02T00:00:00.000+0000",
    "date_available": null,
    "is_read": false,
    "price": 1,
    "quantity": 9000,
    "currency_code": null,
    "amount": null,
    "balance": null,
    "merchant": null,
    "category": null,
    "subcategory": null,
    "description": null,
    "memo": null,
    "status": null,
    "location": {},
    "security_id": "9679fd84-f6d5-44f9-bba9-a5fcb1b8b028",
    "transaction_code_id": "a65929b6-b0a9-46e5-858a-121f0b10f4fb",
    "portfolio_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
    "account_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
    "model_id": "feb846da-a06d-402e-a3bb-abc7260f7138"
}

To securely receive the webhook payload you should verify that the request was made by Hydrogen.

The headers of every payload will include a x-hydrogen-signature that includes a Base64 encoded signature of the following data which has been HMAC SHA-256 hashed using the secret for the webhook:

date content-type content-length content

Each field should be separated by a space. The content will be the json payload of the response body that gets posted.

Using the secret that was received when the webhook was created above, you will then create a Hash-based message authentication code (HMAC) with the SHA-256 algorithm. The result can then be Base64 encoded and compared to the signature in the header. If the two match then you have successfully verified the validity of the webhook.

Bulk

Bulk POST, PUT, and DELETE data on any entity up to 100 entries at a time. Requests will be sent into a messaging queue and processed asynchronously so you may still perform other processes while this is occurring. You will be able to receive a status report of the bulk operation via a separate service explained below.

Bulk Create

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d '{
        [
          {
            "security_id":"832712b9-3b84-46c6-8a6b-1765697269b4",
            "price":10.20,
            "date": "2019-12-01"
          },
          {
            "security_id":"832712b9-3b84-46c6-8a6b-1765697269b4",
            "price":10.22,
            "date": "2020-01-01"
          },
          {
            "security_id":"832712b9-3b84-46c6-8a6b-1765697269b4",
            "price":10.21,
            "date": "2020-02-01"
          },
          {
            "security_id":"832712b9-3b84-46c6-8a6b-1765697269b4",
            "price":10.23,
            "date": "2020-03-01"
          },
          {
            "security_id":"832712b9-3b84-46c6-8a6b-1765697269b4",
            "price":10.25,
            "date": "2020-04-01"
          }
        ]
      }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/bulk/security_price"

Example Response

{
    "id": "356dddbc-cfe5-469c-8988-46afe85651f9",
    "create_date": "2020-04-05T00:08:12.944Z",
    "update_date": "2020-04-05T00:08:12.944Z",
    "status": "Not Started"
}

Perform a bulk POST operation on a set of data. The fields required by the entity to create the data must be provided. Each payload should be comma separated. The endpoint returns the status and the id which can be used to retrieve the status of the request.

HTTP REQUEST

POST /bulk/{entity}

Bulk Update

Example Request

curl -X PUT -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d '{
        [
          {
            "id": "78ba9652-3125-4bf4-ba0d-3f95955e9fc4",
            "price": 10.30
          },
          {
            "id": "b2b04268-bc31-4ddc-8b1e-2736c106ed38",
            "price": 10.40
          },
          {
            "id": "ada79898-a59c-4ec7-a77c-bc8a66340feb",
            "price": 10.50
          },
          {
            "id": "f49ae877-c7e9-43f2-95f5-34f79d0cdb78",
            "price": 10.60
          }
        ]
      }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/bulk/security_price"

Example Response

{
    "id": "a16038ef-5fa9-4d6f-bc4c-1c2f40914d3a",
    "create_date": "2020-04-05T00:51:22.564Z",
    "update_date": "2020-04-05T00:51:22.564Z",
    "status": "Not Started"
}

Perform a bulk PUT operation on a set of data. The unique id of each record that you wish to update must be provided in the body. To obtain the appropriate id, use the GET /{entity} endpoint to view all available ids and their current information. The details to be updated must also be provided. The endpoint returns the status and the id which can be used to retrieve the status of the request.

HTTP REQUEST

PUT /bulk/{entity}

Bulk Delete

Example Request

curl -X DELETE -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d '{
        [
          {
            "id": "78ba9652-3125-4bf4-ba0d-3f95955e9fc4"
          },
          {
              "id": "b2b04268-bc31-4ddc-8b1e-2736c106ed38"
          },
          {
              "id": "ada79898-a59c-4ec7-a77c-bc8a66340feb"
          },
          {
              "id": "f49ae877-c7e9-43f2-95f5-34f79d0cdb78"
          }
        ]
      }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/bulk/security_price"

Example Response

{
    "id": "5bfe10bf-416b-4e46-ab76-514a61ae83fc",
    "create_date": "2020-04-05T00:58:26.106Z",
    "update_date": "2020-04-05T00:58:26.106Z",
    "status": "Not Started"
}

Perform a bulk DELETE operation on a set of data. The unique id of each record that you wish to update must be provided in the body. To obtain the appropriate id, use the GET /{entity} endpoint to view all available ids and their current information. The endpoint returns the status and the id which can be used to retrieve the status of the request.

HTTP REQUEST

DELETE /bulk/{entity}

Bulk Status

Example Request

curl -X GET -H "Authorization: Bearer ce77358c-1e00-4e75-8deb-bd35c4ad8e65" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/bulk/status/356dddbc-cfe5-469c-8988-46afe85651f9"

Example Response (Complete - Success)

{
    "id": "5bfe10bf-416b-4e46-ab76-514a61ae83fc",
    "status": "Complete",
    "success": [
        {
            "id": "78ba9652-3125-4bf4-ba0d-3f95955e9fc4",
            "status_code": 204
        },
        {
            "id": "f49ae877-c7e9-43f2-95f5-34f79d0cdb78",
            "status_code": 204
        },
        {
            "id": "b2b04268-bc31-4ddc-8b1e-2736c106ed38",
            "status_code": 204
        },
        {
            "id": "ada79898-a59c-4ec7-a77c-bc8a66340feb",
            "status_code": 204
        }
    ],
    "error": []
}

Example Response (Complete - Error)

{
    "id": "356dddbc-cfe5-469c-8988-46afe85651f9",
    "status": "Complete",
    "success": [],
    "error": [
        {
            "security_id": "832712b9-3b84-46c6-8a6b-1765697269b4",
            "price": 10.20,
            "error_message": "The following field is required and missing data:date.",
            "status_code": 400
        },
        {
            "security_id": "832712b9-3b84-46c6-8a6b-1765697269b4",
            "price": 10.23,
            "error_message": "The following field is required and missing data:date.",
            "status_code": 400
        },
        {
            "security_id": "832712b9-3b84-46c6-8a6b-1765697269b4",
            "price": 10.21,
            "error_message": "The following field is required and missing data:date.",
            "status_code": 400
        }
    ]
}

Example Response (Not Started)

{
    "id": "8c3c23a8-78a1-46ce-8afa-3751ec72110a",
    "status": "Not Started",
    "progress": "0 of 50 processed."
}

Example Response (In Progress)

{
    "id": "8c3c23a8-78a1-46ce-8afa-3751ec72110a",
    "status": "In Progress",
    "progress": "25 of 50 processed."
}

Get the status of a bulk operation. The unique bulk_id must be provided along with the entity that the bulk operation was submitted for. To obtain the appropriate bulk_id, please save the id that you receive in the response after performing the bulk request.

HTTP REQUEST

GET /bulk/status/{bulk_id}

General & Onboarding

Account

Account Management

Accounts are created below clients to represent an account on your firm’s platform, such as a bank account. One or more portfolios can be created below an account and map to models. Accounts will subscribe to an allocation for investment accounts. This will determine the composition of the portfolios and models below the account. Generally, an account will subscribe to an allocation for each goal that is associated with the account. An account may also be associated with one or more goals.

Field Type Description
id UUID The id for the account
name string Name of the account
account_type_id UUID The id of the account type for the account. Account types are defined by your firm
account_number string Account number for the account. Differs from the id for the account which is auto generated.
managed boolean Indicates if the account is managed by a 3rd party such as an advisor or self-directed by the client. Defaults to true, or that it’s managed
discretionary boolean Indicates if the account is discretionary or non-discretionary. A discretionary account gives a 3rd party such as an advisor access to perform transactions in an account with no permission, while a non-discretionary account requires permission for every transaction. Defaults to true, or that it’s discretionary account
clients map List of clients associated with the account and their association type as well as signature data
      client_id UUID The id of a client associated with the account
      client_account_association_type string The role of the client as it relates to the account defined by your firm. Roles may be joint, owner, trustee, viewer, or admin. Automatically grants the FULL_AUTHORITY permission type to clients mapped to the account with the client_account_association_type of owner, joint, trustee or admin and the INQUIRY_ACCESS permission type to clients mapped to the account with the client_account_association_type of viewer
      signature_data longtext Stored signature for the client on the account such as a Base30 or Base64 string
goals map List of goals mapped to the account with information such as target amount and horizon. You may also store goals data under the goal entity, which is recommended if a goal can be assigned to multiple accounts. This map only stores goals attributes, to assign an account to a goal use the account-allocation service.
      goal_id UUID The id of a goal mapped to the account
      goal_amount double Monetary amount provided by the client as the target amount to be reached within the goal horizon. May be used in conjunction with the Proton API.
      accumulation_horizon double Time horizon of the goal during the accumulation phase, in years. May be used in conjunction with the Proton API.
      decumulation_horizon double Time horizon of the goal during the decumulation phase, in years. If the goal is an accumulation goal, then this can be 0 or omitted entirely. May be used in conjunction with the Proton API.
currency_code string Alphabetic currency code for the base currency of the account, limited to 3 characters. See currency codes
is_active boolean Indicates if the account is active. Defaults to true which indicates that it is currently active.
metadata map Custom information associated with the entity in the format key:value
See Metadata
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

List all accounts

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/account"

Example Response

{
    "content": [
        {
            "id": "099961da-7f41-4309-950f-2b51689a0033",
            "create_date": "2017-01-03T00:00:00.000+0000",
            "update_date": "2017-01-05T00:00:00.000+0000",
            "secondary_id": "7289243787238",
            "managed": true,
            "discretionary": true,
            "name": "Joint Investment Account",
            "account_type_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
            "account_number": null,
            "clients": [
                {
                    "client_id": "099961da-7f41-4309-950f-2b51689a0033",
                    "client_account_association_type": "joint"
                }
            ],
            "goals": [
                {
                    "goal_id": "099961da-7f41-4309-950f-2b51689a0033",
                    "goal_amount": 200000,
                    "accumulation_horizon": 35,
                    "decumulation_horizon": 25
                }
            ],
            "currency_code": "USD",
            "is_active": true,
            "metadata": {}
        },
        {
            "id": "107516c3-9035-4811-af7c-501be5a1fe26",
            "create_date": "2017-02-14T00:00:00.000+0000",
            "update_date": "2017-02-15T09:00:00.000+0000",
            "secondary_id": null,
            "managed": false,
            "discretionary": true,
            "name": "Goals Account",
            "account_type_id": "39770e8d-890d-485b-822e-5a1578f26d47",
            "account_number": null,
            "clients": [
                {
                    "client_id": "107516c3-9035-4811-af7c-501be5a1fe26",
                    "client_account_association_type": "owner"
                }
            ],
            "goals": [
                {
                    "goal_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
                    "goal_amount": 40000,
                    "accumulation_horizon": 10,
                }
            ],
            "is_active": true,
            "metadata": {}
        }
    ],
    "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": 2,
    "size": 25,
    "number": 0
}

Get information for all accounts for all clients defined for your firm. You can filter using a unique client_id to view the accounts for a client. To identify the appropriate client_id, use the GET /client endpoint to see all clients defined for your firm. Note that the information for the clients associated with the account, the goals information, and the metadata information are stored as nested objects within the account object.

HTTP REQUEST

GET /account

Create an account

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
      "secondary_id": "7289243787238",
      "name": "Investment Account 60",
      "account_type_id": "eb3d7f60-a133-4ca9-815f-3677bcdc23a3",
      "clients": [
        {
            "client_id": "199a8c08-cdd5-4c8c-8abf-535447cea11b",
            "client_account_association_type": "owner"
        }
      ],
      "goals": [
        {
            "goal_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
            "goal_amount": 100000,
            "accumulation_horizon": 15
        }
      ]
    }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/account"

Example Response

{
    "id": "199a8c08-cdd5-4c8c-8abf-535447cea11b",
    "create_date": "2017-03-01T00:00:00.000+0000",
    "secondary_id": "7289243787238",
    "managed": true,
    "discretionary": true,
    "name": "Investment Account 60",
    "account_type_id": "eb3d7f60-a133-4ca9-815f-3677bcdc23a3",
    "account_number": null,
    "clients": [
        {
            "client_id": "199a8c08-cdd5-4c8c-8abf-535447cea11b",
            "client_account_association_type": "owner"
        }
    ],
    "goals": [
        {
            "goal_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
            "goal_amount": 100000,
            "accumulation_horizon": 15
        }
    ],
    "is_active": true,
    "metadata": {}
}

Create an account under a client. In order to create an account, the client must have already registered and the client_id must be provided. To identify the appropriate client_id, use the GET /client endpoint to see all clients for your firm. The client can be an internal user. The endpoint returns an account_id that can then be mapped to other entities such as goal, allocation, and portfolio or used to create funding requests.

HTTP REQUEST

POST /account

ARGUMENTS

Parameter Type Required Description
name string required Name of the account
account_type_id UUID required The id of the account type for the account. Account types are defined by your firm
account_number string optional Account number for the account. Differs from the id for the account which is auto generated.
managed boolean optional Indicates if the account is managed by a 3rd party such as an advisor or self-directed by the client. Defaults to true, or that it’s managed
discretionary boolean optional Indicates if the account is discretionary or non-discretionary. A discretionary account gives a 3rd party such as an advisor access to perform transactions in an account with no permission, while a non-discretionary account requires permission for every transaction. Defaults to true, or that it’s discretionary account
clients map optional List of clients associated with the account and their association type as well as signature data
      client_id UUID required The id of a client associated with the account
      client_account_association_type string required The role of the client as it relates to the account defined by your firm. Roles may be joint, owner, trustee, viewer, or admin. Automatically grants the FULL_AUTHORITY permission type to clients mapped to the account with the client_account_association_type of owner, joint, trustee or admin and the INQUIRY_ACCESS permission type to clients mapped to the account with the client_account_association_type of viewer
      signature_data longtext optional Stored signature for the client on the account such as a Base30 or Base64 string
goals map optional List of goals mapped to the account with information such as target amount and horizon. You may also store goals data under the goal entity, which is recommended if a goal can be assigned to multiple accounts. This map only stores goals attributes, to assign an account to a goal use the account-allocation service.
      goal_id UUID required The id of a goal mapped to the account
      goal_amount double optional Monetary amount provided by the client as the target amount to be reached within the goal horizon. May be used in conjunction with the Proton API. Option to also store under the goal entity
      accumulation_horizon double optional Time horizon of the goal during the accumulation phase, in years. May be used in conjunction with the Proton API. Option to also store under the goal entity
      decumulation_horizon double optional Time horizon of the goal during the decumulation phase, in years. If the goal is an accumulation goal, then this can be 0 or omitted entirely. May be used in conjunction with the Proton API. Option to also store under the goal entity
currency_code string optional Alphabetic currency code for the base currency of the account, limited to 3 characters. See currency codes
is_active boolean optional Indicates if the account is active. Defaults to true which indicates that it is currently active.
metadata map optional Custom information associated with the account in the format key:value
See Metadata
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Subscribe an account

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d ' {
            "current_weight" : "50",
            "strategic_weight": "50",
            "date": "2018-06-28",
            "allocation_id": "cb831ad5-18d0-48b3-9d8e-8db318b51895",
            "goal_id": "a65929b6-b0a9-46e5-858a-121f0b10f4fb"
         }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/account/dbebf51f-d325-4cdd-b043-78958e29bdce/subscribe"

Example Response

[
    {
        "id": "ab70c3e0-beec-4165-b08e-eef78e3f3962",
        "create_date": "2018-06-28T18:17:23.579+0000",
        "update_date": "2018-06-28T18:17:23.579+0000",
        "description": "High Income Stock",
        "name": "High-Income Stock",
        "percentage": 25,
        "account_id": "dbebf51f-d325-4cdd-b043-78958e29bdce",
        "model_id": "62fd0a9f-4bac-4b1d-94d2-2c5ea2adca3d",
        "metadata": {}
    },
    {
        "id": "54c97821-910c-4199-9f8d-7ba94a56a80d",
        "create_date": "2018-06-28T18:17:23.579+0000",
        "update_date": "2018-06-28T18:17:23.579+0000",
        "description": "Tactical Industrial Stock",
        "name": "Industrial Stocks",
        "percentage": 25,
        "account_id": "dbebf51f-d325-4cdd-b043-78958e29bdce",
        "model_id": "778b8996-6579-46d9-86ce-a097f189ac7f",
        "metadata": {}
    },
    {
        "id": "d206b198-960a-4e8c-a9e3-83958b5ccb96",
        "create_date": "2018-06-28T18:17:23.579+0000",
        "update_date": "2018-06-28T18:17:23.579+0000",
        "description": "Dynamic ESG Nasdaq Stock",
        "name": "Concentrated Aggressive SRI Core",
        "percentage": 50,
        "account_id": "dbebf51f-d325-4cdd-b043-78958e29bdce",
        "model_id": "88d8f74a-0959-410c-8d01-09cf8f7fe55d",
        "metadata": {}
    }
]

After creating an account, you may create portfolios for the account to track a client’s investment, savings, or insurance products. The composition of each portfolio is determined by the models in each allocation that the portfolio is subscribed to. This endpoint combines the following three actions into one workflow:

1) Create a relationship between an account and an allocation
2) Retrieve the allocation’s model composition
3) Create portfolios for the account that subscribe to models in the allocation

The endpoint takes in an account_id in the URL and the same parameters as the POST /account_allocation endpoint and returns ids for the portfolios created. The details for the portfolios such as the name and description are taken from the corresponding model.

HTTP REQUEST

POST /account/{account_id}/subscribe

ARGUMENTS

Parameter Type Required Description
current_weight double required Current percentage of the account’s total value that should be directed towards the allocation; ex. 20 representing 20%. The current weights for all allocations below an account must add up to 100. If the allocation is the only one, enter 100
strategic_weight double required Strategic percentage of the account’s total value that should be directed towards the allocation; ex. 20 representing 20%. The strategic weights for all allocations below an account must add up to 100. If the allocation is the only one, enter 100
date date required Date of the account-allocation mapping used for historical tracking
allocation_id UUID required The id of the allocation that is part of the account-allocation mapping
goal_id UUID optional The id of the goal that is associated with this account-allocation mapping

RESPONSE

Field Type Description
id UUID The id of the portfolio
name string Name of the portfolio such as “Stock”
account_id UUID The id of the account to which the portfolio belongs
model_id UUID The id of the model to which the portfolio subscribes
percentage double Weight of the portfolio as a percentage of an account based on the weight of the portfolio’s model within the account’s allocation; ex. 20 representing 20%. If the account only has one portfolio input 100
description string Description for the portfolio such as “Stock Portfolio”
metadata map Custom information associated with the portfolio in the format key:value. See Metadata
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

Retrieve an account

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/account/199a8c08-cdd5-4c8c-8abf-535447cea11b"

Example Response

{
    "id": "199a8c08-cdd5-4c8c-8abf-535447cea11b",
    "create_date": "2017-03-01T00:00:00.000+0000",
    "update_date": "2018-01-05T00:00:00.000+0000",
    "managed": true,
    "discretionary": true,
    "name": "Investment Account 60",
    "account_type_id": "eb3d7f60-a133-4ca9-815f-3677bcdc23a3",
    "account_number": null,
    "clients": [
        {
            "client_id": "199a8c08-cdd5-4c8c-8abf-535447cea11b",
            "client_account_association_type": "owner"
        }
    ],
    "goals": [
        {
            "goal_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
            "goal_amount": 100000,
            "accumulation_horizon": 15
        }
    ],
    "is_active": true,
    "metadata": {}
}

Retrieve the information for a specific account associated with a client. The unique account_id must be provided. The endpoint returns the account_id and details for the account specified. Note that the information for the clients associated with the account, the goals information, and the metadata information are stored as nested objects within the account object.

HTTP REQUEST

GET /account/{account_id}

Update an account

Example Request

curl -X PUT -H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
      "name": "Investment Account 60",
      "account_type_id": "eb3d7f60-a133-4ca9-815f-3677bcdc23a3",
      "clients": [
        {
            "client_id": "199a8c08-cdd5-4c8c-8abf-535447cea11b",
            "client_account_association_type": "owner"
        }
      ],
      "goals": [
        {
            "goal_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
            "goal_amount": 100000,
            "accumulation_horizon": 15
        }
      ]
    }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/account/199a8c08-cdd5-4c8c-8abf-535447cea11b"

Example Response

{
    "id": "199a8c08-cdd5-4c8c-8abf-535447cea11b",
    "create_date": "2017-03-01T00:00:00.000+0000",
    "update_date": "2018-01-05T00:00:00.000+0000",
    "managed": true,
    "discretionary": true,
    "name": "Investment Account 60",
    "account_type_id": "eb3d7f60-a133-4ca9-815f-3677bcdc23a3",
    "account_number": null,
    "clients": [
        {
            "client_id": "199a8c08-cdd5-4c8c-8abf-535447cea11b",
            "client_account_association_type": "owner"
        }
    ],
    "goals": [
        {
            "goal_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
            "goal_amount": 100000,
            "accumulation_horizon": 15
        }
    ],
    "is_active": true,
    "metadata": {}
}

Update the information for an account. The unique account_id must be provided. To obtain the appropriate account_id, use the GET /account endpoint to view all accounts defined for your firm and their current information. The details to be updated must also be provided. The endpoint returns the account_id and the details for the account. If you wish to mark the account as closed without permanently deleting it, use this endpoint to update the managed field to false.

HTTP REQUEST

PUT /account/{account_id}

Delete an account

Example Request

curl -X DELETE -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/account/199a8c08-cdd5-4c8c-8abf-535447cea11b"

Response (204 No Content)

Permanently delete an account under a client. The unique account_id must be provided. To obtain the appropriate account_id, use the GET /account endpoint to view all accounts defined for your firm. This deletes the account_id and all account record information. If you wish to mark the account as closed without permanently deleting it, use the PUT /account endpoint to update the managed field to false.

HTTP REQUEST

DELETE /account/{account_id}

Account Allocation

Accounts can subscribe to one or more allocations, which can be tracked over time. An account may also optionally map to a goal for goals based investing applications. The account-allocation mapping indicates what percentage of an account’s funds should be directed towards an allocation.

Field Type Description
id UUID The id for the account-allocation mapping
allocation_id UUID The id of the allocation that is part of the account-allocation mapping
current_weight double Current percentage of the account’s total value that should be directed towards the allocation; ex. 20 representing 20%. The current weights for all allocations assigned to an account must add up to 100 on a given date. If the allocation is the only one, enter 100.
strategic_weight double Strategic percentage of the account’s total value that should be directed towards the allocation; ex. 20 representing 20%. The strategic weights for all allocations assigned to an account must add up to 100 on a given date. If the allocation is the only one, enter 100, which is the recommended option. Please check with your back office if you are able to hold multiple allocations within an account.
account_id UUID The id of the account that is part of the account-allocation mapping
date date Date of the account-allocation mapping used for historical tracking
goal_id UUID The id of the goal that is associated with this account-allocation mapping for goals based investing applications. Goals may also be assigned and tracked via portfolios under the account, which is recommended for banking or non 1:1 relationships.

List all account allocations

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/account_allocation"

Example Response

{
    "content": [
        {
            "id": "000183ac-2288-4564-a76b-119f4694be98",
            "current_weight": 100,
            "date": "2016-01-01",
            "strategic_weight": 100,
            "allocation_id": "7d0ae4cc-94f6-4fde-88e5-507888f9f6c6",
            "goal_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
            "account_id": "dbebf51f-d325-4cdd-b043-78958e29bdce"
        },
        {
            "id": "0007b32a-5765-48d6-afd0-2d990818bced",
            "current_weight": 50,
            "date": "2017-01-01",
            "strategic_weight": 50,
            "allocation_id": "88eed960-dad5-4954-a4ba-bd120b0e8dfb",
            "goal_id": "2a7a6cb7-ef71-4fe8-9169-2678f3799657",
            "account_id": "1dfb2510-486b-47d7-89b3-c48a24c0e584"
        },
        {
            "id": "000bca42-8461-4248-a5ff-a5d1f5716e27",
            "current_weight": 50,
            "date": "2017-01-01",
            "strategic_weight": 50,
            "allocation_id": "39770e8d-890d-485b-822e-5a1578f26d47",
            "goal_id": "2a7a6cb7-ef71-4fe8-9169-2678f3799657",
            "account_id": "1dfb2510-486b-47d7-89b3-c48a24c0e584"
        }
    ],
    "last": false,
    "total_pages": 1,
    "total_elements": 3,
    "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 information for all account-allocation mappings for all accounts defined for your firm. You can filter using a unique account_id to view the allocations mapping to an account. To identify the appropriate account_id, use the GET /account endpoint to see all accounts defined for your firm.

HTTP REQUEST

GET /account_allocation

Create an account allocation

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
      "current_weight": 100,
      "date": "2016-01-01",
      "strategic_weight": 100,
      "allocation_id": "7d0ae4cc-94f6-4fde-88e5-507888f9f6c6",
      "goal_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
      "account_id": "dbebf51f-d325-4cdd-b043-78958e29bdce"
   }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/000183ac-2288-4564-a76b-119f4694be98"

Example Response

{
    "id": "000183ac-2288-4564-a76b-119f4694be98",
    "current_weight": 100,
    "date": "2016-01-01",
    "strategic_weight": 100,
    "allocation_id": "7d0ae4cc-94f6-4fde-88e5-507888f9f6c6",
    "goal_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
    "account_id": "dbebf51f-d325-4cdd-b043-78958e29bdce"
}

Create an account-allocation mapping for an account. This indicates how much of the account’s funds should be directed towards the allocation specified. The account_id and the allocation_id must be provided. To obtain the appropriate account_id use the GET /account endpoint to view all accounts for your firm. To obtain the appropriate allocation_id use the GET /allocation endpoint to view all allocations defined by your firm. The endpoint returns an account_allocation_id used to manage the account-allocation mapping.

HTTP REQUEST

POST /account_allocation

ARGUMENTS

Parameter Type Required Description
allocation_id UUID required The id of the allocation that is part of the account-allocation mapping
current_weight double required Current percentage of the account’s total value that should be directed towards the allocation; ex. 20 representing 20%. The current weights for all allocations below an account must add up to 100 on a given date. If the allocation is the only one, enter 100
strategic_weight double required Strategic percentage of the account’s total value that should be directed towards the allocation; ex. 20 representing 20%. The strategic weights for all allocations below an account must add up to 100 on a given date. If the allocation is the only one, enter 100, which is recommended. Please check with your back office if you are able to hold multiple allocations within an account.
account_id UUID required The id of the account that is part of the account-allocation mapping
date date required Date of the account-allocation mapping used for historical tracking
goal_id UUID optional The id of the goal that is associated with this account-allocation mapping for goals based investing applications. Goals may also be assigned and tracked via portfolios under the account, which is recommended for banking or non 1:1 relationships.

Retrieve an account allocation

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/account_allocation/000183ac-2288-4564-a76b-119f4694be98"

Example Response

{
    "id": "000183ac-2288-4564-a76b-119f4694be98",
    "current_weight": 100,
    "date": "2016-01-01",
    "strategic_weight": 100,
    "allocation_id": "7d0ae4cc-94f6-4fde-88e5-507888f9f6c6",
    "goal_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
    "account_id": "dbebf51f-d325-4cdd-b043-78958e29bdce"
}

Retrieve the information for a specific account-allocation mapping for an account. The unique account_allocation_id must be provided. The endpoint returns the account_allocation_id and details for the account-allocation mapping specified.

HTTP REQUEST

GET /account_allocation/{account_allocation_id}

Update an account allocation

Example Request

curl -X PUT -H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
        "current_weight": 100,
        "date": "2016-01-01",
        "strategic_weight": 100,
        "allocation_id": "7d0ae4cc-94f6-4fde-88e5-507888f9f6c6",
        "goal_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
        "account_id": "dbebf51f-d325-4cdd-b043-78958e29bdce"
    }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/account_allocation/000183ac-2288-4564-a76b-119f4694be9"

Example Response

{
    "id": "000183ac-2288-4564-a76b-119f4694be98",
    "current_weight": 100,
    "date": "2016-01-01",
    "strategic_weight": 100,
    "allocation_id": "7d0ae4cc-94f6-4fde-88e5-507888f9f6c6",
    "goal_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
    "account_id": "dbebf51f-d325-4cdd-b043-78958e29bdce"
}

Update the information for an account-allocation mapping. The unique account_allocation_id must be provided. To obtain the appropriate account_allocation_id, use the GET /account_allocation endpoint to view all account-allocation mappings and their current information. The details to be updated must also be provided. The endpoint returns the account_allocation_id and the details for the account-allocation mapping.

HTTP REQUEST

PUT /account_allocation/{account_allocation_id}

Delete an account allocation

Example Request

curl -X DELETE -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/account_allocation/000183ac-2288-4564-a76b-119f4694be9"

Response (204 No Content)

Permanently delete an account-allocation mapping for an account. The unique account_allocation_id must be provided. To obtain the appropriate account_allocation_id, use the GET /account_allocation endpoint to view all account-allocation mappings. This deletes the account_allocation_id and the association between an account and an allocation.

HTTP REQUEST

DELETE /account_allocation/{account_allocation_id}

Account Activity

List all account asset sizes

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/account/50b4d384-986d-4892-a30a-bc4c146d25a9/asset_size"

Example Response

[
    {
        "date": "2018-02-03",
        "currency_code": "USD",
        "value": 20000,
        "value_available": null,
        "additions": 0,
        "cash_flow": 0
    },
    {
        "date": "2018-02-10",
        "currency_code": "USD",
        "value": 20543,
        "value_available": null,
        "additions": 500,
        "cash_flow": 500
    }
]

Get a list of asset sizes by date for an account. Asset size records are created at the portfolio level and aggregated to yield the account asset size(s). The unique account_id must be provided. To obtain the appropriate account_id, use the GET /account endpoint to view the accounts defined for your firm. The endpoint returns a list of asset sizes by date for the account. Additional parameters available to narrow down what is returned include date range, only obtaining the latest record, and sorting by different units of time (eg. annually, quarterly, monthly, daily).

HTTP REQUEST

GET /account/{account_id}/asset_size

ARGUMENTS

Parameter Type Required Description
get_latest boolean optional Retrieve only the latest asset size. Defaults to false if not set
sort_type string optional Sort the asset sizes by D Daily, M Monthly, Q Quarterly, Y Yearly. Defaults to D Daily if not set. Must be capital letters
start_date date optional Start date for the data. Defaults to the first date if not set
end_date date optional End date for the data. Defaults to the last date if not set
exclude_subledger boolean optional If set to “true”, excludes portfolios under accounts where is_subledger = “true” to not double count assets of subaccounts. Defaults to “false” which includes all portfolios under an account.

RESPONSE

Field Type Description
date date Date for the asset size record. Displays the latest record if more than one entry exists for the given date.
currency_code string Alphabetic currency code for the asset size. See currency codes
value double Monetary value of the account on the particular date
value_available double Available monetary value of the account on the particular date
additions double DEPRECATED, please use cash_flow instead. Amount added to the account value since the last asset size date, usually via deposit.
cash_flow double Amount added to the account or withdrawn from the account since the last asset size date. Value is used for performance calculations. Value may be positive or negative.

List all account holdings

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/account/50b4d384-986d-4892-a30a-bc4c146d25a9/holding"

Example Response

[
    {
        "date": "2018-02-03",
        "security_id": "d6496a5a-a17e-4682-8c8e-7933ce6ca3c6",
        "weight": 10,
        "currency_code": "USD",
        "amount": 2000,
        "cost_basis": null,
        "shares": 20
    },
    {
        "date": "2018-02-03",
        "security_id": "24c3f327-20ac-4302-8330-6cf19de9a353",
        "weight": 2,
        "currency_code": "USD",
        "amount": 400,
        "cost_basis": null,
        "shares": 40
    },
    {
        "date": "2018-02-03",
        "security_id": "cc5a6c52-32a5-4cd8-98db-4541c9b29add",
        "weight": 30,
        "currency_code": "USD",
        "amount": 6000,
        "cost_basis": null,
        "shares": 6
    },
    {
        "date": "2018-02-03",
        "security_id": "3c416c11-1e43-4031-bc0a-e9dc3677f15a",
        "weight": 30,
        "currency_code": "USD",
        "amount": 6000,
        "cost_basis": null,
        "shares": 60
    },
    {
        "date": "2018-02-03",
        "security_id": "59add370-01cf-42a0-bee8-ad75065df603",
        "weight": 28,
        "currency_code": "USD",
        "amount": 5600,
        "cost_basis": null,
        "shares": 50
    }
]

Get information for all the securities that are currently being held by an account. Holding records are created at a portfolio level and aggregated to show the holdings of the account. The unique account_id must be provided. To obtain the appropriate account_id, use the GET /account endpoint to view the accounts defined for your firm. The endpoint returns a list of security_ids and details for each security holding. Additional parameters available to narrow down what is returned include date range and only obtaining the latest record.

HTTP REQUEST

GET /account/{account_id}/holding

ARGUMENTS

Parameter Type Required Description
start_date date optional Start date for the data. Defaults to the first date if not set
end_date date optional End date for the data. Defaults to the last date if not set
get_latest boolean optional Retrieve only the latest asset size. Defaults to false if not set

RESPONSE

Field Type Description
date date Date for the security holding. Displays the latest record if more than one entry exists for the given date.
security_id UUID The id for the security included in the holding record
weight double The weight of the security as a percentage of the account’s total monetary value; ex. 20 representing 20%
currency_code string Alphabetic currency code for the amount. See currency codes
amount double Monetary value of the shares in the holding record
cost_basis double Monetary value that the security was originally purchased for, used for tax purposes
shares double Number of shares in the holding record

List all account transactions

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/account/50b4d384-986d-4892-a30a-bc4c146d25a9/transaction"

Example Response

{
  "content": [
    {
        "id": "50b4d384-986d-4892-a30a-bc4c146d25a9",
        "date": "2018-01-31T00:00:00.000+0000",
        "date_available": null,
        "is_read": true,
        "portfolio_id": "c193de6e-564d-4b2d-893d-0307e92279b7",
        "model_id": "19ef73a9-8dd9-4df0-970e-c3f57c6f8d38",
        "price": 432.2,
        "quantity": 0.5,
        "currency_code": null,
        "amount": null,
        "balance": null,
        "merchant": null,
        "category": null,
        "subcategory": null,
        "description": null,
        "memo": null,
        "status": null,
        "location": {},
        "security_id": "088c1dc6-6750-411d-8679-dfeeaa7241e3",
        "transaction_code_id": "f5af397b-7d22-433f-b01e-8202184a6386",
        "create_date": "2018-01-25T09:00:00.000+0000",
        "update_date": "2018-02-15T09:00:00.000+0000"
    },
    {
        "id": "97c771ac-64b7-461e-a5b3-7d93169dc58b",
        "date": "2018-01-31T00:00:00.000+0000",
        "date_available": null,
        "is_read": true,
        "portfolio_id": "c193de6e-564d-4b2d-893d-0307e92279b7",
        "model_id": "19ef73a9-8dd9-4df0-970e-c3f57c6f8d38",
        "price": 132.2,
        "quantity": 4,
        "currency_code": null,
        "amount": null,
        "balance": null,
        "merchant": null,
        "category": null,
        "subcategory": null,
        "description": null,
        "memo": null,
        "status": null,
        "location": {},
        "security_id": "59add370-01cf-42a0-bee8-ad75065df603",
        "transaction_code_id": "f5af397b-7d22-433f-b01e-8202184a6386",
        "create_date": "2018-01-25T09:00:00.000+0000",
        "update_date": "2018-02-15T09:00:00.000+0000"
    }
  ],
  "total_pages": 1,
  "total_elements": 2,
  "last": true,
  "sort": [
    {
        "direction": "DESC",
        "property": "id",
        "ignore_case": false,
        "null_handling": "NATIVE",
        "descending": true,
        "ascending": false
    }
  ],
  "first": true,
  "number_of_elements": 2,
  "size": 25,
  "number": 2
}

Get the information for all transactions for an account. Transactions represent buy or sell orders for securities. Transaction records are created at a portfolio level and all transactions for each portfolio below an account are returned to show the account’s transaction activity. The unique account_id must be provided. To obtain the appropriate account_id, use the GET /account endpoint to view the accounts defined for your firm. The endpoint returns a list of transaction_ids and details for each transaction. See the Order section for more information. Additional parameters available to narrow down what is returned include a date range.

HTTP REQUEST

GET /account/{account_id}/transaction

ARGUMENTS

Parameter Type Required Description
start_date date optional Start date for the data. Defaults to the first date if not set
end_date date optional End date for the data. Defaults to the last date if not set

RESPONSE

Field Type Description
id UUID The id for the transaction record
date timestamp Timestamp when the transaction occurred
date_available timestamp Timestamp when the transaction becomes available
is_read boolean Indicates if the transaction has been read. Defaults to false which indicates it has not been read
portfolio_id UUID The id for the portfolio that the transaction falls under
model_id UUID The id for the model to which the portfolio that the transaction falls under subscribes
price double Price at which security was bought or sold included in the transaction
quantity double Quantity of shares of the security purchased
currency_code string Alphabetic currency code for the amount. See currency codes
amount double Amount of the transaction
balance double Updated balance of the portfolio as a result of the transaction
merchant string The merchant for the transaction such as the merchant posted for a credit card charge
category string Category of the transaction
subcategory string Subcategory of the transaction
description string Description of the transaction
memo string Memo attached to the transaction
status string Status of the transaction
location map Location where the transaction occurred
      address_line1 string Primary information for the street address, such as the street and building number
      address_line2 string Secondary information for the street address, such as a suite or apartment number
      city string City for the address
      state string State, province, or sub-country region for the address
      postalcode string Alphanumeric postal code or zip code for the address
      country string Country for the address using the ISO ALPHA-2 Code. See country codes
      latitude double Latitude of the location where the transaction occurred
      longitude double Longitude of the location where the transaction occurred
security_id UUID The id of the security included in the transaction
transaction_code_id UUID The id referring to the transaction code, defined by your firm
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the transaction record was created
update_date timestamp Timestamp for the date and time that the transaction record was last updated

Get aggregate account data

Aggregates account data for a given account. This includes data on the clients that are associated to the account, account asset size & holdings, allocations associated with the account, and latest deposits & withdrawals. This view is useful when constructing account dashboards.

Field Type Description
account_id UUID The id of the account
account_name string Name of the account
account_type_id UUID The id of the account type for the account. Account types are defined by your firm
account_type_name string Name of the account type
account_asset_size double Latest account asset size
account_asset_size_date date Date of the account_asset_size record
clients array List of client(s)
      client_id UUID The id of the client
      client_first_name string First name of the client
      client_last_name string Last name of the client
      client_account_association string The role of the client as it relates to the account
deposits array Array of deposits for the account. Returns only the latest 3 records
      deposit_id UUID ID of the deposit record
      deposit_amount double Amount of the deposit
      deposit_received_date timestamp Date and time that the deposit was received into the account
      deposit_direction string Label to indicate the direction of the transaction such as “Incoming” or “Outgoing”
withdrawals array Array of withdrawals made from the client’s account. Returns only the latest 3 records
      withdrawal_id UUID ID of the withdrawal record
      withdrawal_amount double Amount that was withdrawn
      withdrawal_date date Date the withdrawal was made
      withdrawal_direction string Label to indicate the direction of the transaction such as “Incoming” or “Outgoing”
allocations array List of latest allocation(s) associated with the account
      allocations_id UUID ID of the allocation that is part of the account-allocation mapping
      allocation_name string Name of the allocation
      allocation_description string Description of the allocation
      allocation_category string Category of the allocation
      allocation_secondary_id UUID Alternate ID of the allocation
      account_allocation_id UUID ID of the account-allocation mapping
      account_allocation_date UUID Date of the account-allocation mapping
account_holdings array List of latest holdings(s) associated with the account
      date date Date for the security holding
      security_id UUID The id for the security included in the holding record
      weight double The weight of the security as a percentage of the account’s total monetary value; ex. 20 representing 20%
      amount double Monetary value of the shares in the holding record
      shares double Number of shares in the holding record

HTTP REQUEST

GET /account/{account_id}/account_overview

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/account/6f4a3f64-5bba-4bbf-8fe6-6815db272dc8/account_overview"

Example Response

{
    "client_id": "0797efda-cf8b-4661-9cb4-d1e8966a3dcd",
    "client_first_name": "Oscar",
    "client_last_name": "Martinez",
    "client_asset_size_date": "2019-09-13",
    "client_asset_size": 362242.82649700006,
    "accounts": [
        {
            "account_id": "4d7efcea-2f85-4442-8268-c0c1e82ca618",
            "account_name": "Investment",
            "account_type": "Investment",
            "account_secondary_id": "Test Data",
            "account_asset_size": 38725.07924,
            "account_asset_size_date": "2019-09-13",
            "account_created_date": "2019-09-26T22:31:16.000+0000",
            "account_updated_date": "2019-09-26T22:31:16.000+0000"
        },
        {
            "account_id": "6f4a3f64-5bba-4bbf-8fe6-6815db272dc8",
            "account_name": "Saving Account",
            "account_type": "Saving",
            "account_secondary_id": "Test Data",
            "account_asset_size": 37117.77597,
            "account_asset_size_date": "2019-09-13",
            "account_created_date": "2019-09-26T22:31:17.000+0000",
            "account_updated_date": "2019-09-26T22:31:17.000+0000"
        },
        {
            "account_id": "7ed09992-89ad-4a27-9bc2-a313cf28d234",
            "account_name": "Investment",
            "account_type": "Investment",
            "account_secondary_id": "Test Data",
            "account_asset_size": 51989.83748,
            "account_asset_size_date": "2019-09-13",
            "account_created_date": "2019-09-26T22:31:15.000+0000",
            "account_updated_date": "2019-09-26T22:31:15.000+0000"
        }
    ],
    "deposits": [
        {
            "deposit_id": "3eb0c7a7-63a5-4f6f-a3c9-52f470fcf636",
            "deposit_amount": 9000.0,
            "deposit_account_id": "f450e1f9-ee02-44a2-b947-d7bcb4ee07f1",
            "deposit_account_name": "Investment",
            "deposit_received_date": "2019-01-25T00:00:00.000+0000",
            "deposit_direction": "Inbound"
        },
        {
            "deposit_id": "52b28035-deed-4dba-99ba-503bd1f0c1c9",
            "deposit_amount": 5000.0,
            "deposit_account_id": "f450e1f9-ee02-44a2-b947-d7bcb4ee07f1",
            "deposit_account_name": "Investment",
            "deposit_received_date": "2017-08-30T00:00:00.000+0000",
            "deposit_direction": "Inbound"
        },
        {
            "deposit_id": "89dde3ae-4aa1-4088-880b-f7f1e63a8bc9",
            "deposit_amount": 1000.0,
            "deposit_account_id": "f450e1f9-ee02-44a2-b947-d7bcb4ee07f1",
            "deposit_account_name": "Investment",
            "deposit_received_date": "2019-08-27T00:00:00.000+0000",
            "deposit_direction": "Inbound"
        }
    ],
    "withdrawals": [
        {
            "withdrawal_id": "64b79ec3-cd92-4dc9-92b6-c2bb0c59f8fe",
            "withdrawal_amount": 1000.0,
            "withdrawal_account_id": "4d7efcea-2f85-4442-8268-c0c1e82ca618",
            "withdrawal_account_name": "Investment",
            "withdrawal_date": "2019-08-30",
            "withdrawal_direction": "Outgoing"
        },
        {
            "withdrawal_id": "fb00abc4-f3fe-494a-a830-3a373ce2b8ab",
            "withdrawal_amount": 1000.0,
            "withdrawal_account_id": "f450e1f9-ee02-44a2-b947-d7bcb4ee07f1",
            "withdrawal_account_name": "Investment",
            "withdrawal_date": "2019-09-05",
            "withdrawal_direction": "Outgoing"
        },
        {
            "withdrawal_id": "3c0d9edc-df6e-40ab-9107-e631c51d56de",
            "withdrawal_amount": 500.0,
            "withdrawal_account_id": "7ed09992-89ad-4a27-9bc2-a313cf28d234",
            "withdrawal_account_name": "Investment",
            "withdrawal_date": "2017-04-26",
            "withdrawal_direction": "Outgoing"
        }
    ],
    "allocations": [],
    "account_holdings": []
}

Account Type

Accounts are assigned an account type based on the legal construct of the account. Examples include a “Roth IRA”, “ISA”, or “Revocable Trust.” Account types can be custom set by your firm based on those you accept.

Field Type Description
id UUID The id for the specific account type
name string Name of the account type such as Taxable or Joint
short_name string Abbreviated name for the account type
category string Category grouping that the account type falls under
subcategory string Subcategory grouping under the category that the account type falls under
code string Code defined by your firm for the specific account type
is_active boolean Indicates if his account type is active. Defaults to true which indicates it is active and available to be assigned to accounts
is_taxable boolean Indicates if this account type is taxable. true indicates it is taxable
metadata map Custom information associated with the entity in the format key:value
See Metadata
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

List all account types

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/account_type"

Example Response

{
    "content": [
        {
            "id": "50d76212-0fcd-4d36-8633-e4a52cbcb79f",
            "create_date": "2018-04-13T14:24:43.000+0000",
            "update_date": "2018-04-13T14:24:43.000+0000",
            "category": "Custodial",
            "code": "101",
            "is_active": true,
            "is_taxable": true,
            "name": "Custodial",
            "short_name": "CUST",
            "metadata": {}
        },
        {
            "id": "cb94ee79-1ef4-4d67-9611-97a739523aeb",
            "create_date": "2018-04-13T14:24:43.000+0000",
            "update_date": "2018-04-13T14:24:43.000+0000",
            "category": "Retirement",
            "code": "102",
            "is_active": true,
            "is_taxable": false,
            "name": "Retirement",
            "short_name": "RETIR",
            "metadata": {}
        },
        {
            "id": "f80b5555-7503-4a28-bc4b-d05d62e0e733",
            "create_date": "2018-04-13T14:24:43.000+0000",
            "update_date": "2018-04-13T14:24:43.000+0000",
            "category": "Taxable",
            "code": "103",
            "is_active": true,
            "is_taxable": true,
            "name": "Taxable",
            "short_name": "TXB",
            "metadata": {}
        }
    ],
    "last": false,
    "total_pages": 1,
    "total_elements": 3,
    "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
}

List all account types defined for your firm. Use this endpoint to determine which account_type_id to assign to a new account.

HTTP REQUEST

GET /account_type

Create an account type

Example Request

curl -X POST -H "Authorization: Bearer 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
-H "Content-Type: application/json" \
-d '{
        "category": "Taxable",
        "code": "103",
        "is_taxable": true,
        "name": "Taxable",
        "short_name": "TXB"
    }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/account_type"

Example Response

{
    "id": "f80b5555-7503-4a28-bc4b-d05d62e0e733",
    "create_date": "2018-04-13T14:24:43.000+0000",
    "category": "Taxable",
    "code": "103",
    "is_taxable": true,
    "is_active": true,
    "name": "Taxable",
    "short_name": "TXB",
    "metadata": {}
}

Create a new account type for your firm. The name must be provided and it will default to active. The create_date will default to the current date. The endpoint returns the account_type_id used to manage the account type and to map the account type to an account.

HTTP REQUEST

POST /account_type

ARGUMENTS

Parameter Type Required Description
name string required Name of the account type such as “Taxable” or “Joint”
short_name string optional Abbreviated name for the account type
category string optional Category grouping that the account type falls under
subcategory string optional Subcategory grouping under the category that the account type falls under
code string optional Code defined by your firm for the account type
is_taxable boolean optional Indicates if this account type is taxable. true indicates it is taxable
is_active boolean optional Indicates if this account type is active. Defaults to true which indicates it is active and available to be assigned to accounts
metadata map optional Custom information associated with the entity in the format key:value
See Metadata
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Retrieve an account type

Example Request

curl -X GET -H "Authorization: Bearer 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/account_type/cf80b5555-7503-4a28-bc4b-d05d62e0e733"

Example Response

{
    "id": "f80b5555-7503-4a28-bc4b-d05d62e0e733",
    "create_date": "2018-04-13T14:24:43.000+0000",
    "update_date": "2018-04-13T14:24:43.000+0000",
    "category": "Taxable",
    "code": "103",
    "is_active": true,
    "is_taxable": true,
    "short_name": "TXB",
    "name": "Taxable",
    "metadata": {}
}

Retrieve the information for an account type defined for your firm. The unique account_type_id must be provided. The endpoint returns the account_type_id and the details for the account type specified.

HTTP REQUEST

GET /account_type/{account_type_id}

Update an account type

Example Request

curl -X PUT -H "Authorization: Bearer 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
-H "Content-Type: application/json" \
-d '{
        "category": "Taxable",
        "code": "103",
        "is_active": true,
        "is_taxable": true,
        "short_name": "TXB",
        "name": "Taxable"
    }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/account_type/f80b5555-7503-4a28-bc4b-d05d62e0e733"

Example Response

{
    "id": "f80b5555-7503-4a28-bc4b-d05d62e0e733",
    "create_date": "2018-04-13T14:24:43.000+0000",
    "update_date": "2018-04-13T14:24:43.000+0000",
    "category": "Taxable",
    "code": "103",
    "is_active": true,
    "is_taxable": true,
    "short_name": "TXB",
    "name": "Taxable",
    "metadata": {}
}

Update the information for a possible account type defined for your firm. The unique account_type_id must be provided. To identify the appropriate account_type_id, use the GET /account_type endpoint to view all account types defined for your firm and their current information. The details to be updated must also be provided. The endpoint returns the information for the account_type_id including the updated details. Use this endpoint to mark an account type as inactive instead of deleting it permanently using the DELETE /account_type/{account_type_id} endpoint.

HTTP REQUEST

PUT /account_type/{account_type_id}

Delete an account type

Example Request

curl -X DELETE -H "Authorization: Bearer 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/account_type/f80b5555-7503-4a28-bc4b-d05d62e0e733"

Response (204 No Content)

Permanently delete a possible account type defined for your firm. The unique account_type_id must be provided. To identify the appropriate account_type_id, use the GET /account_type endpoint to view all account types defined for your firm. This permanently deletes the account_type_id and associated information. To mark the account type as inactive without permanently deleting it, use the PUT /account_type/{account_type_id} endpoint to change the indicator for whether or not the account type is active to show that it is inactive.

HTTP REQUEST

DELETE /account_type/{account_type_id}

Account Status

Account statuses correspond to a stage_id and reflects the different stages that an account flows through along a user journey, useful for sign-up funnels. See the Stage section for stage_id.

Field Type Description
id UUID The id for the specific account status record for the account_id provided
account_id UUID The id of the account to which the status belongs
status string Status of the account such as “Signed Up” or “Awaiting Payment”
stage_id UUID Refers to the stage the client is in.
Useful for sign-up funnels
comments string Comments for the client regarding the status of their account
metadata map Custom information associated with the entity in the format key:value
See Metadata
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

List all account statuses

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/account_status"

Example Response

{
    "content": [
        {
            "id": "6db4a470-a00c-40bb-a325-067d0bdb3ddc",
            "create_date": "2018-02-08T16:59:27.000+0000",
            "update_date": "2018-02-08T16:59:27.000+0000",
            "comments": "Invested",
            "status": "Complete",
            "stage_id": "e995d4c1-f989-4733-9867-713966ac9856",
            "account_id": "1d7e1aad-3c79-49fe-bbb9-bd5e239ae1e7",
            "metadata": {}
        },
        {
            "id": "013380bf-7f17-44c1-93c5-892a7ed3498c",
            "create_date": "2017-04-07T00:00:00.000+0000",
            "update_date": "2018-02-08T16:59:27.000+0000",
            "comments": null,
            "status": "Invested",
            "stage_id": "1d7e1aad-3c79-49fe-bbb9-bd5e239ae1e7",
            "account_id": "21098ed9-6439-46ba-abd9-eb6cf28866fb",
            "metadata": {}
        },
        {
            "id": "01b252d3-1412-477f-8d29-6e2ff6e54c81",
            "create_date": "2017-10-05T00:00:00.000+0000",
            "update_date": "2018-02-08T16:59:27.000+0000",
            "comments": null,
            "status": "Complete",
            "stage_id": "2a7a6cb7-ef71-4fe8-9169-2678f3799657",
            "account_id": "4ff21db3-97ab-4bbd-9885-be6aec522c44",
            "metadata": {}
        }
    ],
    "last": false,
    "total_pages": 1,
    "total_elements": 3,
    "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 the account status history information for all accounts defined for your firm. Account status corresponds to a stage_id and reflects the different stages of a user journey, useful in sign-up funnels. You can filter using a unique account_id to view the account_status records for a specific account. To obtain the appropriate account_id, use the GET /account endpoint to view all accounts defined for your firm.

HTTP REQUEST

GET /account_status

Create an account status

Example Request

curl -X POST -H "Authorization: Bearer 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
-H "Content-Type: application/json" \
-d '{
        "comments": "Invested",
        "status": "Complete",
        "stage_id": "e995d4c1-f989-4733-9867-713966ac9856",
        "account_id": "1d7e1aad-3c79-49fe-bbb9-bd5e239ae1e7"
    }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/account_status"

Example Response

{
    "id": "6db4a470-a00c-40bb-a325-067d0bdb3ddc",
    "create_date": "2018-02-08T16:59:27.000+0000",
    "comments": "Invested",
    "status": "Complete",
    "stage_id": "e995d4c1-f989-4733-9867-713966ac9856",
    "account_id": "1d7e1aad-3c79-49fe-bbb9-bd5e239ae1e7",
    "metadata": {}
}

Create an account status record for an account by assigning a stage_id to the account. The unique account_id and stage_id must be provided. To obtain the appropriate account_id, use the GET /account endpoint to view all accounts defined for your firm. To obtain the appropriate stage_id, use the GET /stage endpoint to view all account stages defined for your firm. The create_date defaults to the current date. The endpoint returns an account_status_id which represents a record in the account’s history log.

HTTP REQUEST

POST /account_status

ARGUMENTS

Parameter Type Required Description
account_id UUID required The id of the account to which the status belongs
status string required Status of the account such as “Signed Up” or “Awaiting Payment”
stage_id UUID required Refers to the stage the client is in.
Useful for sign-up funnels
comments string optional Comments for the client regarding the status of their account
metadata map optional Custom information associated with the entity in the format key:value
See Metadata
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Retrieve an account status

Example Request

curl -X GET -H "Authorization: Bearer 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/account_status/6db4a470-a00c-40bb-a325-067d0bdb3ddc"

Example Response

{
    "id": "6db4a470-a00c-40bb-a325-067d0bdb3ddc",
    "create_date": "2018-02-08T16:59:27.000+0000",
    "update_date": "2018-02-08T16:59:27.000+0000",
    "comments": "Invested",
    "status": "Complete",
    "stage_id": "e995d4c1-f989-4733-9867-713966ac9856",
    "account_id": "1d7e1aad-3c79-49fe-bbb9-bd5e239ae1e7",
    "metadata": {}
}

Retrieve the information for a specific account status record for an account. The unique account_status_id must be provided. The endpoint returns details for the account status record specified.

HTTP REQUEST

GET /account_status/{account_status_id}

Update an account status

Example Request

curl -X PUT -H "Authorization: Bearer 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
-H "Content-Type: application/json" \
-d '{
        "comments": "Invested",
        "status": "Complete",
        "stage_id": "e995d4c1-f989-4733-9867-713966ac9856",
        "account_id": "1d7e1aad-3c79-49fe-bbb9-bd5e239ae1e7"
    }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/account_status/6db4a470-a00c-40bb-a325-067d0bdb3ddc"

Example Response

{
    "id": "6db4a470-a00c-40bb-a325-067d0bdb3ddc",
    "create_date": "2018-02-08T16:59:27.000+0000",
    "update_date": "2018-02-08T16:59:27.000+0000",
    "comments": "Invested",
    "status": "Complete",
    "stage_id": "e995d4c1-f989-4733-9867-713966ac9856",
    "account_id": "1d7e1aad-3c79-49fe-bbb9-bd5e239ae1e7",
    "metadata": {}
}

Update an account status record for an account. The unique account_status_id must be provided. To obtain the appropriate account_status_id, use the GET /account_status endpoint to view all account statuses for each account defined for your firm and their current information. The details to be updated must also be provided. The endpoint returns the account_status_id with the details for the account status.

HTTP REQUEST

PUT /account_status/{account_status_id}

Delete an account status

Example Request

curl -X DELETE -H "Authorization: Bearer 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/account_status/6db4a470-a00c-40bb-a325-067d0bdb3ddc"

Response (204 No Content)

Permanently delete an account status record from an account’s history. The account_status_id must be provided. To obtain the appropriate account_status_id, use the GET /account_status endpoint to view all account statuses for each account defined for your firm. This deletes the account_status_id from the account’s history log table and removes the status from the account.

HTTP REQUEST

DELETE /account_status/{account_status_id}

Account Permission

The Account Permission endpoints vary slightly from other Nucleus endpoints as they are not used to manage specific objects, but rather to manage the permission type of a client to an account. All of the authorities except the ROLE_CLIENT authority can access these endpoints.

Field Type Description
account_id UUID The id of the account being granted permissions
clients array List of clients mapped to the account and their permission type
      client_id UUID The id of the client being granted permissions to the account. Must also be included in the clients.client_id field of the account
      permission_type string The permission type for the client. Available values are INQUIRY_ACCESS, LIMITED_AUTHORITY, FULL_AUTHORITY, and POWER_OF_ATTORNEY. Please view the Permission Type resource for more information on each authority. To view what endpoints each authority permissions, please see this guide

List all account permissions

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/account_permission"

Example Response

{
    "content": [
        {
            "account_id": "6fca8ba0-d7e6-42cb-863d-a0f9f794ced5",
            "clients": [
                {
                    "permission_type": "FULL_AUTHORITY",
                    "client_id": "6e8e1cbd-c52d-4be7-a466-b00863999b2c"
                },
                {
                    "permission_type": "INQUIRY_ACCESS",
                    "client_id": "4358f699-8563-46f7-aff4-9817c30ac907"
                }
            ]
        },
        {
            "account_id": "3db529a2-bab7-4ecf-8b7f-bb738a2ed371",
            "clients": [
                {
                    "permission_type": "FULL_AUTHORITY",
                    "client_id": "4358f699-8563-46f7-aff4-9817c30ac907"
                }
            ]
        }
    ],
    "total_elements": 2,
    "total_pages": 1,
    "last": true,
    "first": true,
    "sort": [
        {
            "direction": "DESC",
            "property": "updateDate",
            "ignore_case": false,
            "null_handling": "NATIVE",
            "ascending": false,
            "descending": true
        }
    ],
    "number_of_elements": 2,
    "size": 25,
    "number": 0
}

Get the clients and permission types for all accounts defined for your firm. Account permissions control the actions that a client can take on an account. Only clients with the authority of ROLE_SUPER_ADMIN, ROLE_ADMIN, ROLE_PORTFOLIO_MANAGER, ROLE_MARKETING_MANAGER, ROLE_OPERATIONS, ROLE_SUPPORT, or ROLE_ADVISOR can access this endpoint.

HTTP REQUEST

GET /account_permission

Retrieve an account’s permissions

Example Request

curl -X GET -H "Authorization: Bearer 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/account_permission/f446662e-042d-4a65-b528-f7b8353fb67e"

Example Response

{
    "account_id": "f446662e-042d-4a65-b528-f7b8353fb67e",
    "clients": [
        {
            "permission_type": "LIMITED_AUTHORITY",
            "client_id": "5c13bf69-3331-417a-bce7-88f8172363b5"
        }
    ]
}

Retrieve all the clients and their permission type for a specific account. Only clients with the authority of ROLE_SUPER_ADMIN, ROLE_ADMIN, ROLE_PORTFOLIO_MANAGER, ROLE_MARKETING_MANAGER, ROLE_OPERATIONS, ROLE_SUPPORT, or ROLE_ADVISOR can access this endpoint.

HTTP REQUEST

GET /account_permission/{account_id}

Update an account’s permissions

Example Request

curl -X PUT -H "Authorization: Bearer 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
-H "Content-Type: application/json" \
-d '{
        "client_id": "I5c13bf69-3331-417a-bce7-88f8172363b5",
        "permission_type": "LIMITED_AUTHORITY"
    }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/account_permission/f446662e-042d-4a65-b528-f7b8353fb67e"

Example Response

{
    "account_id": "f446662e-042d-4a65-b528-f7b8353fb67e",
    "clients": [
        {
            "permission_type": "LIMITED_AUTHORITY",
            "client_id": "5c13bf69-3331-417a-bce7-88f8172363b5"
        }
    ]
}

Update the permission type of a client for an account. When a client_id is included in the clients embedded object of a call to the POST /account and PUT /account/{account_id} endpoints, they will automatically be mapped to the account with a permission type based on the client_account_association_type granted to them. If you would like the user to have a different permission type, you can use this endpoint to change it. The account_id is specified in the URL, and the client_id and the updated permission type must be provided in the request body. Only clients with the authority of ROLE_SUPER_ADMIN, ROLE_ADMIN, ROLE_PORTFOLIO_MANAGER, ROLE_MARKETING_MANAGER, ROLE_OPERATIONS, ROLE_SUPPORT, or ROLE_ADVISOR can access this endpoint.

HTTP REQUEST

PUT /account_permission/{account_id}

ARGUMENTS

Parameter Type Required Description
clients array optional List of clients mapped to the account and their permission type
      client_id UUID required The id of the client being granted permissions to the account. Must also be included in the clients.client_id field of the account
      permission_type string required The permission type for the client. Available values are INQUIRY_ACCESS, LIMITED_AUTHORITY, FULL_AUTHORITY, and POWER_OF_ATTORNEY. Please view the Permission Type resource for more information on each authority. To view what endpoints each authority permissions, please see this guide

Delete an account’s permissions

Example Request

curl -X DELETE -H "Authorization: Bearer 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/account_permission/f446662e-042d-4a65-b528-f7b8353fb67e"

Response (204 No Content)

Permanently delete the permissions of an account. The account_id must be provided in the URL. This removes all the clients mapped to the account and their permission types. Only clients with the authority of ROLE_SUPER_ADMIN, ROLE_ADMIN, ROLE_PORTFOLIO_MANAGER, ROLE_MARKETING_MANAGER, ROLE_OPERATIONS, ROLE_SUPPORT, or ROLE_ADVISOR can access this endpoint.

HTTP REQUEST

DELETE /account_permission/{account_id}

Client

Clients represent users (both internal and external users) of your firm’s platform and are critical to further set-ups. For example, accounts are created below clients.

Field Type Description
id UUID The id of the client
username string Username for the client used on the firm’s platform
client_type string Defined client type for the client. Available client types are individual, firm, admin, and advisor, all case sensitive
email string Contact email for the client in the format [email protected]
firm_name string Company name if the client_type = “firm”
title string The title of the client such as “Mr.”, “Ms.”, “Miss”, “Mrs.”, etc.
first_name string First name or given name of the client
middle_name string Middle name of the client
last_name string Last name or surname of the client
suffix string Suffix of the client such as “Jr.” or “Sr.”
phone_number string Phone number associated with the client
date_of_birth date Date of birth of the client in the ISO 8601 format YYYY-MM-DD
identification_number string National identification number for a client such as an SSN in the US, frequently used for Know-Your-Customer (KYC) purposes
identification_number_type string Type of national identification number for a client such as an SSN, TIN, or EIN in the US
country_of_residence string The country of residence of a client, often corresponding to the country issuing the identification number provided above using the ISO ALPHA-2 Code, frequently used for Know-Your-Customer (KYC) purposes. See country codes
country_of_citizenship array The country or countries of citizenship of a client, often corresponding to the country issuing the identification number provided above using the ISO ALPHA-2 Code, frequently used for Know-Your-Customer (KYC). See country codes
citizenship_status string The client’s citizenship status such as “Citizen” or “Resident Alien” in the US
gender string The client’s gender. Available values are female, male, and other.
employment map Employment details for the client
      employment_status string Status of employment. Value may be employed, unemployed, student, retired, self_employed
      job_title string Job title of client such as “Analyst” or “Associate”
      employer string Name of employer such as “Apple” or “Walmart”
      occupation string Occupation of client such as “Medical Services” or “Education”
income integer Annual income for the client
total_net_worth integer Total net worth of the client including the value of their home(s) and any cash and non cash holdings
liquid_net_worth integer Net worth of the client that can easily be converted to cash (cash, stocks, bonds, money market funds, CDs) excluding the value of their home(s) and retirement accounts
is_verified boolean Indicates if the identifying details provided by the client have been verified by a Know-Your-Customer (KYC) vendor. Defaults to false which indicates it is not verified
hydro_id string The Hydro ID associated with the client (if applicable). Corresponds to the Client Hydro entity
is_active boolean Indicates if the client is currently active. Defaults to true which indicates it is active
address map Address details for the client
      address_line1 string Primary information for the street address, such as the street and building number
      address_line2 string Secondary information for the street address, such as a suite or apartment number
      city string City for the address
      state string State, province, or sub-country region for the address
      postalcode string Alphanumeric postal code or zip code for the address
      country string Country for the address using the ISO ALPHA-2 Code. See country codes
      type string Type of address such as “home”, “work”, “billing”, “mailing”, etc. This is used to differentiate between multiple addresses provided
      is_primary boolean Indicates if the address is the primary address for a client. Only one address may be primary for a client_id. If a user sets an address to is_primary = “true” then all other addresses for that client_id will be set to is_primary = “false.” Defaults to false which indicates the address is not primary
metadata map Custom information associated with the client in the format key:value. See Metadata
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

Client Management

List all clients

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/client"

Example Response

{
    "content": [
        {
            "id": "8e1799f0-4429-4939-ae84-7391cff93ba5",
            "create_date": "2019-10-09T20:51:14.000+0000",
            "update_date": "2019-10-09T20:51:14.000+0000",
            "email": "[email protected]",
            "firm_name": null,
            "title": "Mr.",
            "first_name": "Jim",
            "last_name": "Halpert",
            "suffix": null,
            "date_of_birth": "1971-12-27",
            "identification_number": "123-44-5566",
            "identification_number_type": "SSN",
            "phone_number": "987-765-1244",
            "username": "[email protected]",
            "client_type": "individual",
            "address": [],
            "hydro_id": null,
            "country_of_residence": "US",
            "country_of_citizenship": ["US"],
            "citizenship_status": null,
            "employment": {},
            "income": null,
            "gender": "male",
            "total_net_worth": null,
            "liquid_net_worth": null,
            "is_verified": false,
            "is_active": true,
            "metadata": {}
        },
        {
            "id": "8fc301c0-50ef-4803-bb0c-b1dc57ffc85a",
            "create_date": "2019-10-09T20:50:13.000+0000",
            "update_date": "2019-10-09T20:50:13.000+0000",
            "email": "[email protected]",
            "firm_name": null,
            "title": "Mr.",
            "first_name": "Jim",
            "last_name": "Halpert",
            "suffix": null,
            "date_of_birth": "1971-12-27",
            "identification_number": "123-44-5566",
            "identification_number_type": "SSN",
            "phone_number": "987-765-1244",
            "username": "[email protected]",
            "client_type": "individual",
            "address": [],
            "hydro_id": null,
            "country_of_residence": "US",
            "country_of_citizenship": ["US"],
            "citizenship_status": null,
            "employment": {},
            "income": null,
            "gender": "male",
            "total_net_worth": null,
            "liquid_net_worth": null,
            "is_verified": false,
            "is_active": true,
            "metadata": {
                "median_household_income": "10000",
            }
        },
        {
            "id": "bb8394ca-84bd-4679-ac3e-874edeef15cf",
            "create_date": "2019-10-04T15:37:31.000+0000",
            "update_date": "2019-10-04T15:37:31.000+0000",
            "firm_name": null,
            "title": "Mr.",
            "first_name": "John",
            "middle_name": "Henry",
            "last_name": "Smith",
            "suffix": null,
            "date_of_birth": "1983-03-05",
            "identification_number": "076310691",
            "identification_number_type": "SSN",
            "phone_number": null,
            "username": "[email protected]",
            "client_type": "individual",
            "address": [],
            "hydro_id": null,
            "country_of_residence": "US",
            "country_of_citizenship": ["US"],
            "citizenship_status": null,
            "employment": {},
            "income": null,
            "gender": "male",
            "total_net_worth": null,
            "liquid_net_worth": null,
            "is_verified": false,
            "is_active": true,
            "metadata": {}
        }
    ],
    "total_pages": 1,
    "total_elements": 3,
    "last": false,
    "number_of_elements": 25,
    "first": true,
    "sort": [
        {
            "direction": "DESC",
            "property": "updateDate",
            "ignore_case": false,
            "null_handling": "NATIVE",
            "descending": true,
            "ascending": false
        }
    ],
    "size": 25,
    "number": 0
}

Get details for all clients registered with your firm. Note that the address information and the metadata information are nested objects within the client object.

HTTP REQUEST

GET /client

Create a client

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d '{
          "email": "[email protected]",
          "username": "[email protected]",
          "client_type": "individual",
          "title": "Mrs.",
          "first_name": "Angela",
          "last_name": "Martin",
          "phone_number": "987-765-1244",
          "date_of_birth": "1971-12-27",
          "identification_number": "123-44-5566",
          "identification_number_type": "SSN",
          "country_of_residence": "US",
          "country_of_citizenship": ["US"],
          "gender": "female",
          "is_verified": true,
          "hydro_id": "10lm4nz",
          "is_active": true,
          "metadata": {
            "median_household_income": "10000",
          }
      }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/client"

Example Response

{
    "id": "11291d9b-fce0-4536-b4be-311f1a35c11f",
    "create_date": "2019-10-10T12:41:18.768+0000",
    "update_date": "2019-10-10T12:41:18.768+0000",
    "email": "[email protected]",
    "firm_name": null,
    "title": "Mrs.",
    "first_name": "Angela",
    "last_name": "Martin",
    "suffix": null,
    "date_of_birth": "1971-12-27",
    "identification_number": "123-44-5566",
    "identification_number_type": "SSN",
    "phone_number": "987-765-1244",
    "username": "[email protected]",
    "client_type": "individual",
    "address": [],
    "hydro_id": "10lm4nz",
    "country_of_residence": "US",
    "country_of_citizenship": ["US"],
    "citizenship_status": null,
    "gender": "female",
    "employment": {},
    "income": null,
    "total_net_worth": null,
    "liquid_net_worth": null,
    "is_verified": true,
    "is_active": true,
    "metadata": {
        "median_household_income": "10000"
    }
}

Create a new client, or register a new user, with your firm. The create_date will default to the current date. The endpoint returns a unique client_id that is used to manage the specific client and referenced in other endpoints.

HTTP REQUEST

POST /client

ARGUMENTS

Parameter Type Required Description
username string required Username for the client used on the firm’s platform
client_type string required Defined client type for the client. Available client types are individual, firm, admin, and advisor, all case sensitive
email string optional Contact email for the client in the format [email protected]
firm_name string optional Company name if the client_type = “firm”
title string optional The title of the client such as “Mr.”, “Ms.”, “Miss”, “Mrs.”, etc.
first_name string optional First name or given name of the client
middle_name string optional Middle name of the client
last_name string optional Last name or surname of the client
suffix string optional Suffix of the client such as “Jr.” or “Sr.”
phone_number string optional Phone number associated with the client
date_of_birth date optional Date of birth of the client in the ISO 8601 format YYYY-MM-DD
identification_number string optional National identification number for a client such as an SSN in the US, frequently used for Know-Your-Customer (KYC) purposes
identification_number_type string optional Type of national identification number for a client such as an SSN, TIN, or EIN in the US
country_of_residence string optional The country of residence of a client, often corresponding to the country issuing the identification number provided above using the ISO ALPHA-2 Code, frequently used for Know-Your-Customer (KYC) purposes. See country codes
country_of_citizenship array optional The country or countries of citizenship of a client, often corresponding to the country issuing the identification number provided above using the ISO ALPHA-2 Code, frequently used for Know-Your-Customer (KYC). See country codes
citizenship_status string optional The client’s citizenship status such as “Citizen” or “Resident Alien” in the US
gender string optional The client’s gender. Available values are female, male, and other.
employment map optional Employment details for the client
      employment_status string optional Status of employment. Value may be employed, unemployed, student, retired, self_employed
      job_title string optional Job title of client such as “Analyst” or “Associate”
      employer string optional Name of employer such as “Apple” or “Walmart”
      occupation string optional Occupation of client such as “Medical Services” or “Education”
income integer optional The total income for the client
total_net_worth integer optional Total net worth of the client including the value of their home(s) and any cash and non cash holdings
liquid_net_worth integer optional Net worth of the client that can easily be converted to cash (cash, stocks, bonds, money market funds, CDs) excluding the value of their home(s) and retirement accounts
is_verified boolean optional Indicates if the identifying details provided by the client have been verified by a Know-Your-Customer (KYC) vendor. Defaults to false which indicates it is not verified
hydro_id string optional The Hydro ID associated with the client (if applicable). Corresponds to the Client Hydro entity
is_active boolean optional Indicates if the client is currently active. Defaults to true which indicates it is active
address map optional Address details for the client
      address_line1 string required Primary information for the street address, such as the street and building number
      address_line2 string optional Secondary information for the street address, such as a suite or apartment number
      city string required City for the address
      state string required State, province, or sub-country region for the address
      postalcode string optional Alphanumeric postal code or zip code for the address
      country string required Country for the address using the ISO ALPHA-2 Code. See country codes
      type string required Type of address such as “home”, “work”, “billing”, “mailing”, etc. This is used to differentiate between multiple addresses provided
      is_primary boolean optional Indicates if the address is the primary address for a client. Only one address may be primary for a client_id. If a user sets an address to is_primary = “true” then all other addresses for that client_id will be set to is_primary = “false.” Defaults to false which indicates the address is not primary
metadata map optional Custom information associated with the client in the format key:value.
See Metadata
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Retrieve a client

Retrieve the information for a client registered with your firm. The unique client_id must be provided. The endpoint returns the client_id and the details for the client. Note that the address information and the metadata information are nested objects within the client object.

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/client/11291d9b-fce0-4536-b4be-311f1a35c11f"

Example Response

{
    "id": "11291d9b-fce0-4536-b4be-311f1a35c11f",
    "create_date": "2019-10-10T12:41:19.000+0000",
    "update_date": "2019-10-10T12:41:19.000+0000",
    "email": "[email protected]",
    "firm_name":null,
    "title": "Mrs.",
    "first_name": "Angela",
    "last_name": "Martin",
    "suffix": null,
    "date_of_birth": "1971-12-27",
    "identification_number": "123-44-5566",
    "identification_number_type": "SSN",
    "phone_number": "987-765-1244",
    "username": "[email protected]",
    "client_type": "individual",
    "address": [],
    "hydro_id": "10lm4nz",
    "country_of_residence": "US",
    "country_of_citizenship": ["US"],
    "citizenship_status": null,
    "gender": "female",
    "employment": {},
    "income": null,
    "total_net_worth": null,
    "liquid_net_worth": null,
    "is_verified": true,
    "is_active": true,
    "metadata": {
        "median_household_income": "10000"
    }
}

HTTP REQUEST

GET /client/{client_id}

Update a client

Example Request

curl -X PUT -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d '{
          "email": "[email protected]",
          "username": "[email protected]",
          "client_type": "individual",
          "title": "Mrs.",
          "first_name": "Angela",
          "last_name": "Schrute",
          "phone_number": "987-765-1244",
          "date_of_birth": "1971-12-27",
          "identification_number": "123-44-5566",
          "identification_number_type": "SSN",
          "country_of_residence": "US",
          "gender": "female",
          "is_verified": true,
          "is_active": true,
          "hydro_id": "10lm4nz",
          "metadata": {
            "median_household_income": "10000",
          },
        }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/client/11291d9b-fce0-4536-b4be-311f1a35c11f"

Example Response

{
    "id": "11291d9b-fce0-4536-b4be-311f1a35c11f",
    "create_date": "2019-10-10T12:41:19.000+0000",
    "update_date": "2019-10-10T12:45:33.037+0000",
    "email": "[email protected]",
    "firm_name": null,
    "title": "Mrs.",
    "first_name": "Angela",
    "last_name": "Schrute",
    "suffix": null,
    "date_of_birth": "1971-12-27",
    "identification_number": "123-44-5566",
    "identification_number_type": "SSN",
    "phone_number": "987-765-1244",
    "username": "[email protected]",
    "client_type": "individual",
    "address": [],
    "hydro_id": "10lm4nz",
    "country_of_residence": "US",
    "country_of_citizenship": ["US"],
    "citizenship_status": null,
    "gender": "other",
    "employment": {},
    "income": null,
    "total_net_worth": null,
    "liquid_net_worth": null,
    "is_verified": true,
    "is_active": true,
    "metadata": {
        "median_household_income": "10000"
    }
}

Update the information for a client registered with your firm. The unique client_id must be provided. To obtain the appropriate client_id, use the GET /client endpoint to view all available client_ids registered with your firm and their current information. The details to be updated must also be provided. The endpoint returns the client_id and the details for the client. If you wish to have the client be no longer available for further activity without permanently deleting it, use this endpoint to mark a client as inactive by changing the is_active field to false.

HTTP REQUEST

PUT /client/{client_id}

Delete a client

Example Request

curl -X DELETE -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/client/11291d9b-fce0-4536-b4be-311f1a35c11f"

Response (204 No Content)

Permanently delete a client registered with your firm. The unique client_id must be provided. To obtain the appropriate client_id, use the GET /client endpoint to view all available client_ids registered with your firm. This deletes the client_id and all the client’s information associated with it. To prevent a client_id from being used for further activity without permanently deleting it, you can use the PUT /client/{client_id} endpoint to mark a client as inactive by changing the is_active field to false.

HTTP REQUEST

DELETE /client/{client_id}

Client Activity

List all client asset sizes

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/client/099961da-7f41-4309-950f-2b51689a0033/asset_size"

Example Response

[
    {
        "date": "2018-02-03",
        "currency_code": "USD",
        "value": 20000,
        "value_available": null,
        "additions": 0,
        "cash_flow": 0
    },
    {
        "date": "2018-02-04",
        "currency_code": "USD",
        "value": 24500,
        "value_available": null,
        "additions": 500,
        "cash_flow": 500
    }
]

Get a list of asset sizes per date for a client. Asset size records are created at the portfolio level and aggregated to yield the client asset size(s). The unique client_id must be provided. To obtain the appropriate client_id, use the GET /client endpoint to view all available client_ids registered with your firm. The endpoint returns a list of asset sizes by date for the client. Additional parameters available to narrow down what is returned include: a date range, only obtaining the latest record, and sorting by different units of time (e.g. annually, quarterly, monthly, daily), etc.

HTTP REQUEST

GET /client/{client_id}/asset_size

ARGUMENTS

Parameter Type Required Description
get_latest boolean optional Retrieve only the latest asset size. Defaults to false if not set
sort_type string optional Sort the asset sizes by D Daily, M Monthly, Q Quarterly, Y Yearly. Defaults to D Daily if not set. Must be capital letters
start_date date optional Start date for the data. Defaults to the first date if not set
end_date date optional End date for the data. Defaults to the last date if not set
exclude_subledger boolean optional If set to “true”, excludes portfolios under accounts where is_subledger = “true” to not double count assets of subaccounts. Defaults to “false” which includes all portfolios under an account.

RESPONSE

Field Type Description
date date Date for the asset size record. Displays the latest record if more than one entry exists for the given date.
currency_code string Alphabetic currency code for the asset size. See currency codes
value double Monetary value of all the client’s accounts on the particular date
value_available double Available monetary value of the account on the particular date
additions double DEPRECATED, please use cash_flow instead. Amount added to the client’s account value since the last asset size date, usually via deposit.
cash_flow double Amount added to the client’s accounts or withdrawn from the accounts since the last asset size date. Value is used for performance calculations. Value may be positive or negative.

List all client holdings

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/client/099961da-7f41-4309-950f-2b51689a0033/holding"

Example Response

[
    {
        "date": "2018-02-03",
        "security_id": "73b5dbcd-0a40-4526-8348-368e17c9575d",
        "weight": 10,
        "currency_code": "USD",
        "amount": 2000,
        "cost_basis": null,
        "shares": 20
    },
    {
        "date": "2018-02-03",
        "security_id": "691c2255-a1a6-451f-b772-cb262725d7e2",
        "weight": 2,
        "currency_code": "USD",
        "amount": 400,
        "cost_basis": null,
        "shares": 4
    },
    {
        "date": "2018-02-03",
        "security_id": "0283c814-db55-4470-8cd8-8b9ae945182f",
        "weight": 30,
        "currency_code": "USD",
        "amount": 6000,
        "cost_basis": null,
        "shares": 60
    },
    {
        "date": "2018-02-03",
        "security_id": "0d652520-7e6a-461d-abe8-56b956c08d2e",
        "weight": 30,
        "currency_code": "USD",
        "amount": 6000,
        "cost_basis": null,
        "shares": 70
    },
    {
        "date": "2018-02-03",
        "security_id": "c090f392-409d-459a-8054-333fe96fb877",
        "weight": 28,
        "currency_code": "USD",
        "amount": 5600,
        "cost_basis": null,
        "shares": 50
    }
]

Get the information for all the securities that are currently being held by a client registered with your firm. Holding records are created at a portfolio level and aggregated to show the holdings of the client. The unique client_id must be provided. To obtain the appropriate client_id, use the GET /client endpoint to view all available client_ids registered with your firm. The endpoint returns a list of security_ids, the security amount, the security weight and the date of the record for all securities the client holds. Additional parameters available to narrow down what is returned include a date range and only obtaining the latest record.

HTTP REQUEST

GET /client/{client_id}/holding

ARGUMENTS

Parameter Type Required Description
start_date date optional Start date for the data. Defaults to the first date if not set
end_date date optional End date for the data. Defaults to the last date if not set
get_latest boolean optional Retrieve only the latest asset size. Defaults to false if not set

RESPONSE

Field Type Description
date date Date for the security holding. Displays the latest record if more than one entry exists for the given date.
security_id UUID The id for the security included in the holding record
weight double The weight of the security as a percentage of the client’s total monetary value; ex. 20 representing 20%
currency_code string Alphabetic currency code for the amount. See currency codes
amount double Monetary value of the shares in the holding record
cost_basis double Monetary value that the security was originally purchased for, used for tax purposes
shares double Number of shares in the holding record

List all client transactions

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/client/099961da-7f41-4309-950f-2b51689a0033/transaction"

Example Response

{
  "content": [
    {
        "id": "efa289b2-3565-42e6-850b-8dad25727e99",
        "date": "2018-01-31T00:00:00.000+0000",
        "date_available": null,
        "is_read": true,
        "portfolio_id": "8ec467e6-6faa-4916-b380-6af0b21a34cc",
        "model_id": "6dbadddc-41ff-4634-a145-16678b422557",
        "price": 200,
        "quantity": 2,
        "currency_code": null,
        "amount": null,
        "balance": null,
        "merchant": null,
        "category": null,
        "subcategory": null,
        "description": null,
        "memo": null,
        "status": null,
        "location": {},
        "security_id": "691c2255-a1a6-451f-b772-cb262725d7e2",
        "transaction_code_id": "f5af397b-7d22-433f-b01e-8202184a6386",
        "create_date": "2018-02-07T19:29:37.000+0000",
        "update_date": "2018-02-012T09:00:00.000+0000"
    },
    {
        "id": "efa289b2-3565-42e6-850b-8dad25727e24",
        "date": "2018-01-31T00:00:00.000+0000",
        "date_available": null,
        "is_read": true,
        "portfolio_id": "8ec467e6-6faa-4916-b380-6af0b21a34cc",
        "model_id": "6dbadddc-41ff-4634-a145-16678b422557",
        "price": 1000,
        "quantity": 6,
        "currency_code": null,
        "amount": null,
        "balance": null,
        "merchant": null,
        "category": null,
        "subcategory": null,
        "description": null,
        "memo": null,
        "status": null,
        "location": {},
        "security_id": "0d652520-7e6a-461d-abe8-56b956c08d2e",
        "transaction_code_id": "f5af397b-7d22-433f-b01e-8202184a6386",
        "create_date": "2017-08-02T04:30:25",
        "update_date": "2017-11-18T09:00:00"
    }
  ],
    "total_pages": 1,
    "total_elements": 2,
    "last": true,
    "sort": [
        {
            "direction": "DESC",
            "property": "id",
            "ignore_case": false,
            "null_handling": "NATIVE",
            "descending": true,
            "ascending": false
        }
    ],
    "first": true,
    "number_of_elements": 2,
    "size": 25,
    "number": 2
}

Get the information for all transactions under a client registered with your firm. Transactions represent buy or sell orders for securities. Transaction records are created at a portfolio level and all transactions for each portfolio below the client’s account(s) are returned to show the client’s transaction activity. The unique client_id must be provided. To obtain the appropriate client_id, use the GET /client endpoint to view all available client_ids registered with your firm. The endpoint returns a list of transaction_ids and details for each transaction. See the Order section for more information. Additional parameters available to narrow down what is returned include a date range.

HTTP REQUEST

GET /client/{client_id}/transaction

ARGUMENTS

Parameter Type Required Description
start_date date optional Start date for the data. Defaults to the first date if not set
end_date date optional End date for the data. Defaults to the last date if not set

RESPONSE

Field Type Description
id UUID The id for the transaction record
date timestamp Timestamp when the transaction occurred
date_available timestamp Timestamp when the transaction becomes available
is_read boolean Indicates if the transaction has been read. Defaults to false which indicates it has not been read
portfolio_id UUID The id of the portfolio that the transaction falls under
model_id UUID Model to which the portfolio that the transaction falls under subscribes
price integer Price for the security included in the transaction at which it was sold or purchased
quantity integer Quantity of shares of the security purchased
currency_code string Alphabetic currency code for the amount. See currency codes
amount double Amount of the transaction
balance double Updated balance of the portfolio as a result of the transaction
merchant string The merchant for the transaction such as the merchant posted for a credit card charge
category string Category of the transaction
subcategory string Subcategory of the transaction
description string Description of the transaction
memo string Memo attached to the transaction
status string Status of the transaction
location map Location where the transaction occurred
      address_line1 string Primary information for the street address, such as the street and building number
      address_line2 string Secondary information for the street address, such as a suite or apartment number
      city string City for the address
      state string State, province, or sub-country region for the address
      postalcode string Alphanumeric postal code or zip code for the address
      country string Country for the address using the ISO ALPHA-2 Code. See country codes
      latitude double Latitude of the location where the transaction occurred
      longitude double Longitude of the location where the transaction occurred
security_id UUID The id of the security included in the transaction
transaction_code_id integer The id referring to the transaction codes defined by your firm
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

Get aggregate client data

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
  "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/client/0797efda-cf8b-4661-9cb4-d1e8966a3dcd/account_overview"

Example Response

{
  "client_id": "0797efda-cf8b-4661-9cb4-d1e8966a3dcd",
  "client_first_name": "Oscar",
  "client_last_name": "Martinez",
  "client_asset_size_date": "2019-09-13",
  "client_asset_size": 362242.82649700006,
  "accounts": [
    {
      "account_id": "4d7efcea-2f85-4442-8268-c0c1e82ca618",
      "account_name": "Investment",
      "account_type": "Investment",
      "account_secondary_id": "Test Data",
      "account_asset_size": 38725.07924,
      "account_asset_size_date": "2019-09-13",
      "account_created_date": "2019-09-26T22:31:16.000+0000",
      "account_updated_date": "2019-09-26T22:31:16.000+0000"
    },
    {
      "account_id": "6f4a3f64-5bba-4bbf-8fe6-6815db272dc8",
      "account_name": "Saving Account",
      "account_type": "Saving",
      "account_secondary_id": "Test Data",
      "account_asset_size": 37117.77597,
      "account_asset_size_date": "2019-09-13",
      "account_created_date": "2019-09-26T22:31:17.000+0000",
      "account_updated_date": "2019-09-26T22:31:17.000+0000"
    },
    {
      "account_id": "7ed09992-89ad-4a27-9bc2-a313cf28d234",
      "account_name": "Investment",
      "account_type": "Investment",
      "account_secondary_id": "Test Data",
      "account_asset_size": 51989.83748,
      "account_asset_size_date": "2019-09-13",
      "account_created_date": "2019-09-26T22:31:15.000+0000",
      "account_updated_date": "2019-09-26T22:31:15.000+0000"
    }
  ],
  "deposits": [
    {
      "deposit_id": "3eb0c7a7-63a5-4f6f-a3c9-52f470fcf636",
      "deposit_amount": 9000.0,
      "deposit_account_id": "f450e1f9-ee02-44a2-b947-d7bcb4ee07f1",
      "deposit_account_name": "Investment",
      "deposit_received_date": "2019-01-25T00:00:00.000+0000",
      "deposit_direction": "Inbound"
    },
    {
      "deposit_id": "52b28035-deed-4dba-99ba-503bd1f0c1c9",
      "deposit_amount": 5000.0,
      "deposit_account_id": "f450e1f9-ee02-44a2-b947-d7bcb4ee07f1",
      "deposit_account_name": "Investment",
      "deposit_received_date": "2017-08-30T00:00:00.000+0000",
      "deposit_direction": "Inbound"
    },
    {
      "deposit_id": "89dde3ae-4aa1-4088-880b-f7f1e63a8bc9",
      "deposit_amount": 1000.0,
      "deposit_account_id": "f450e1f9-ee02-44a2-b947-d7bcb4ee07f1",
      "deposit_account_name": "Investment",
      "deposit_received_date": "2019-08-27T00:00:00.000+0000",
      "deposit_direction": "Inbound"
    }
  ],
  "withdrawals": [
    {
        "withdrawal_id": "64b79ec3-cd92-4dc9-92b6-c2bb0c59f8fe",
        "withdrawal_amount": 1000.0,
        "withdrawal_account_id": "4d7efcea-2f85-4442-8268-c0c1e82ca618",
        "withdrawal_account_name": "Investment",
        "withdrawal_date": "2019-08-30",
        "withdrawal_direction": "Outgoing"
    },
    {
        "withdrawal_id": "fb00abc4-f3fe-494a-a830-3a373ce2b8ab",
        "withdrawal_amount": 1000.0,
        "withdrawal_account_id": "f450e1f9-ee02-44a2-b947-d7bcb4ee07f1",
        "withdrawal_account_name": "Investment",
        "withdrawal_date": "2019-09-05",
        "withdrawal_direction": "Outgoing"
    },
    {
        "withdrawal_id": "3c0d9edc-df6e-40ab-9107-e631c51d56de",
        "withdrawal_amount": 500.0,
        "withdrawal_account_id": "7ed09992-89ad-4a27-9bc2-a313cf28d234",
        "withdrawal_account_name": "Investment",
        "withdrawal_date": "2017-04-26",
        "withdrawal_direction": "Outgoing"
    }
  ]
}

Display the latest client and account data along with recent deposit and withdrawal activity. This view is useful when constructing client dashboards.

HTTP REQUEST

GET /client/{client_id}/account_overview

RESPONSE

Field Type Description
client_id UUID The id of the client
client_first_name string First name of the client
client_last_name string Last name of the client
client_asset_size double Total asset size of client across all accounts
client_asset_size_date date Date of the latest client_asset_size for the given client_id
accounts array List of client’s accounts
      account_id UUID The id of the account
      account_name string Name of the account
      account_type string The type of account
      account_secondary_id string The secondary_id for the account
      account_asset_size double Account asset size that has the same date as client_asset_size
      account_asset_size_date date Date of the asset_size record. Must be the same as the client_asset_size_date
      account_created_date timestamp Timestamp for the date and time the account was created
      account_update_date timestamp Timestamp for the date and time the account was last updated
deposits array Array of deposits for the client. Returns only the latest 3 records
      deposit_id UUID ID of the deposit record
      deposit_amount double Amount of the deposit
      deposit_account_id date Account ID to which the deposit was made
      deposit_account_name string Account name to which the deposit was made
      deposit_received_date timestamp Date and time that the deposit was received into the account
      deposit_direction string Label to indicate the direction of the transaction such as “Incoming” or “Outgoing”
withdrawals array Array of withdrawals made from the client’s accounts. Returns only the latest 3 records
      withdrawal_id UUID ID of the withdrawal record
      withdrawal_amount double Amount that was withdrawn
      withdrawal_account_id UUID account_id that the withdrawal was made from
      withdrawal_account_name string Account name that the withdrawal was made from
      withdrawal_date date Date the withdrawal was made
      withdrawal_direction string Label to indicate the direction of the transaction such as “Incoming” or “Outgoing”

Get aggregate advisor data

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
  "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/client/5297nrga-cf8b-4143-9nf4-d1ekn66r5cgd/advisor_overview"

Example Response

{
  "total_assets_managed": 5000000,
  "total_accounts_managed": 8,
  "total_clients_managed": 4,
  "account_list": [
    {
      "account_type": "retirement",
      "assets_managed": 200000,
      "accounts_managed": 8,
      "clients_managed": 4
    },
    {
      "account_type": "savings",
      "assets_managed": 200000,
      "accounts_managed": 7,
      "clients_managed": 3
    },
    {
      "account_type": "investment",
      "assets_managed": 200000,
      "accounts_managed": 1,
      "clients_managed": 1
    }
  ],
  "client_list": [
    {
      "client_id": "818f182e-1922-40d0-8b70-d68865c8fe4d",
      "first_name": "Jane",
      "last_name": "Doe",
      "date_of_birth": "1971-07-10",
      "age": 48,
      "gender": "female",
      "income": 50000,
      "client_assets": {
        "total_assets": 250000,
        "as_of_date": "2019-07-01"
      },
      "client_account_list": [
        {
          "account_name": "account 1",
          "account_type": "retirement",
          "account_assets": 5024.57,
          "as_of_date": "2019-07-01"
        },
        {
          "account_name": "account 2",
          "account_type": "savings",
          "account_assets": 259275.41,
          "as_of_date": "2019-07-01"
        }
      ]
    },
    {
      "client_id": "23bb0389-aa37-4be5-9dc5-07f21a8f4d32",
      "first_name": "Adam",
      "last_name": "Smith",
      "date_of_birth": "1983-05-02",
      "age": 36,
      "gender": "male",
      "income": 150000,
      "client_assets": {
        "total_assets": 250000,
        "as_of_date": "2019-07-01"
      },
      "client_account_list": [
        {
          "account_name": "account 1",
          "account_type": "retirement",
          "account_assets": 5024.57,
          "as_of_date": "2019-07-01"
        },
        {
          "account_name": "account 2",
          "account_type": "savings",
          "account_assets": 259275.41,
          "as_of_date": "2019-07-01"
        }
      ]
    },
    {
      "client_id": "dd707c48-599c-4edd-8055-04682e583483",
      "first_name": "Kyle",
      "last_name": "Davis",
      "date_of_birth": "1988-05-02",
      "age": 31,
      "gender": "male",
      "income": 230000,
      "client_assets": {
        "total_assets": 250000,
        "as_of_date": "2019-07-01"
      },
      "client_account_list": [
        {
          "account_name": "account 1",
          "account_type": "retirement",
          "account_assets": 5024.57,
          "as_of_date": "2019-07-01"
        },
        {
          "account_name": "account 2",
          "account_type": "investment",
          "account_assets": 259275.41,
          "as_of_date": "2019-07-01"
        }
      ]
    },
    {
      "client_id": "b5f3abe9-bea2-4b31-9416-1080041efac2",
      "first_name": "Jason",
      "last_name": "Williams",
      "date_of_birth": "1980-05-02",
      "age": 39,
      "gender": "male",
      "income": 85000,
      "client_assets": {
        "total_assets": 250000,
        "as_of_date": "2019-07-01"
      },
      "client_account_list": [
        {
          "account_name": "account 1",
          "account_type": "retirement",
          "account_assets": 5024.57,
          "as_of_date": "2019-07-01"
        },
        {
          "account_name": "account 2",
          "account_type": "savings",
          "account_assets": 259275.41,
          "as_of_date": "2019-07-01"
        }
      ]
    }
  ]
}

Displays high-level view of all clients & accounts under the management of the advisor. This view is useful when constructing advisor dashboards.

HTTP REQUEST

GET /client/{client_id}/advisor_overview

RESPONSE

Field Type Description
total_assets_managed double The monetary value of total assets managed by the advisor
total_clients_managed integer Total number of clients managed by the advisor
total_accounts_managed integer Total number of accounts managed by the advisor
account_list array List of all the accounts managed by the advisor
      account_type string The type of account
      assets_managed double The monetary value of the assets under the account type
      clients_managed integer Total number of clients managed under the account type
      accounts_managed integer Total number of accounts managed under the account type
client_list array List of all clients managed by the advisor
      client_id UUID The ID of the client
      first_name string First name of the client
      last_name string Last name of the client
      date_of_birth date Date of birth of the client in the ISO 8601 format YYYY-MM-DD
      age integer Age of the client
      gender string The client’s gender. Available values are female, male, and other
      income double The total income for the client
      client_assets map List of client’s assets
          total_assets double The monetary value of the total assets for the client
          as_of_date date The effective date of the total_assets value
      client_account_list array(map) List of all the accounts for the client
          account_name string The name of the client’s account
          account_type string The type of account
          account_assets double The monetary value of the total assets for the account
          as_of_date date The effective date of the account_assets value

Client Response

When using questionnaires, clients’ answers to the questions are stored as client responses. For example, to customize a firm-defined goal for a client, he or she must provide some information such as his or her time horizon or goal amount. Another example is when profiling a client’s risk tolerance, a specific questionnaire might be used, where the client’s responses help determine the risk profile. Client responses are stored as answer values connected to the question in the questionnaire via an answer_id that represents an answer option to the question. Responses can be stored at a client level or an account level. The answers are often used as variables for calculations relating to a goal such as age, time horizon, risk tolerance, etc.

Field Type Description
id UUID The id of the client response
answer_id UUID The id of the answer provided to link the response to a question
answer_value string Body of the client’s response
client_id UUID The id of the client to whom the response belongs
account_id UUID In the case that the response applies to only one of a client’s accounts and not the client as a whole, the id of the account to which the response belongs
application_id string Create an identifier to group client responses within a unique application session
metadata map Custom information associated with the entity in the format key:value
See Metadata
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

List all client responses

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/client_response"

Example Response

{
  "content": [
    {
      "id": "7960419c-c098-4450-8cc5-866b7385230b",
      "create_date": "2018-02-07T19:29:37.000+0000",
      "update_date": "2018-02-12T09:00:00.000+0000",
      "client_id" : "5736e6f7-5e12-448e-830c-c1f2b9317d48",
      "account_id" : "efa289b2-3565-42e6-850b-8dad25727e99",
      "answer_id" : "cf9de92f-1c59-4188-93af-d7d5cefd0644",
      "answer_value" : "10 Years",
      "application_id": "681928573639178",
      "metadata": {}
    }
  ],
  "total_elements": 1,
  "last": true,
  "total_pages": 1,
  "sort": [
    {
      "direction": "ASC",
      "property": "id",
      "ignore_case": false,
      "null_handling": "NATIVE",
      "ascending": true,
      "descending": false
    }
  ],
  "number_of_elements": 1,
  "first": true,
  "size": 25,
  "number": 0
}

Get all the client responses for questions as part of a questionnaire defined by your firm. The option to provide a unique client_id or account_id is available to filter responses from a specific client, or responses from a specific account. To obtain the appropriate client_id, use the GET /client endpoint to view all clients defined for your firm. To obtain the appropriate account_id, use the GET /account endpoint to view all accounts defined for your firm.

HTTP REQUEST

GET /client_response

Create a client response

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d '{
          "client_id" : "5736e6f7-5e12-448e-830c-c1f2b9317d48",
          "account_id" : "efa289b2-3565-42e6-850b-8dad25727e99",
          "answer_id" : "cf9de92f-1c59-4188-93af-d7d5cefd0644",
          "answer_value" : "10 Years",
          "application_id": "681928573639178"
        }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/client_response"

Example Response

{
    "id": "7960419c-c098-4450-8cc5-866b7385230b",
    "create_date": "2018-02-07T19:29:37.000+0000",
    "client_id" : "5736e6f7-5e12-448e-830c-c1f2b9317d48",
    "account_id" : "efa289b2-3565-42e6-850b-8dad25727e99",
    "answer_id" : "cf9de92f-1c59-4188-93af-d7d5cefd0644",
    "answer_value" : "10 Years",
    "application_id": "681928573639178",
    "metadata": {}
}

Create a new client response for a question as part of a questionnaires. Must provide the answer_id, answer_value and either the client_id, account_id, or both. To obtain the appropriate answer_id, use the GET /questionnaire endpoint to view the question_id and answer_id pairs. The create_date will default to the current date. The endpoint returns a client_response_id used to manage the client’s response to the question.

HTTP REQUEST

POST /client_response

ARGUMENTS

Parameter Type Required Description
answer_id UUID required The id of the answer provided to link the response to a question
answer_value string required Body of the client’s response
client_id UUID required, conditional The id of the client to whom the response belongs. Required if an account_id is not also provided.
account_id UUID required, conditional In the case that the response applies to only one of a client’s accounts and not the client as a whole, the id of the account to which the response belongs. Required if a client_id is not also provided.
application_id string optional Create an identifier to group client responses within a unique application session
metadata map optional Custom information associated with the entity in the format key:value
See Metadata
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Retrieve a client response

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/client_response/7960419c-c098-4450-8cc5-866b7385230b"

Example Response

{
    "id": "7960419c-c098-4450-8cc5-866b7385230b",
    "create_date": "2018-02-07T19:29:37.000+0000",
    "update_date": "2018-02-12T09:00:00.000+0000",
    "client_id" : "5736e6f7-5e12-448e-830c-c1f2b9317d48",
    "account_id" : "efa289b2-3565-42e6-850b-8dad25727e99",
    "answer_id" : "cf9de92f-1c59-4188-93af-d7d5cefd0644",
    "answer_value" : "10 Years",
    "application_id": "681928573639178",
    "metadata": {}
}

Retrieve the information for a client response for a client. The client_response_id must be provided. To obtain the appropriate client_response_id, use the GET /client_response endpoint to view all client responses firm-wide. The endpoint returns the client_response_id and details for the client response.

HTTP REQUEST

GET /client_response/{client_response_id}

Update a client response

Example Request

curl -X PUT -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d '{
            "client_id" : "5736e6f7-5e12-448e-830c-c1f2b9317d48",
            "account_id" : "efa289b2-3565-42e6-850b-8dad25727e99",
            "answer_id" : "cf9de92f-1c59-4188-93af-d7d5cefd0644",
            "answer_value" : "10 Years"
    }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/client_response/7960419c-c098-4450-8cc5-866b7385230b"

Example Response

{
    "id": "7960419c-c098-4450-8cc5-866b7385230b",
    "create_date": "2018-02-07T19:29:37.000+0000",
    "update_date": "2018-02-12T09:00:00.000+0000",
    "client_id": "5736e6f7-5e12-448e-830c-c1f2b9317d48",
    "account_id": "efa289b2-3565-42e6-850b-8dad25727e99",
    "answer_id": "cf9de92f-1c59-4188-93af-d7d5cefd0644",
    "answer_value": "10 Years",
    "application_id": "681928573639178",
    "metadata": {}
}

Update a client response for a client. The client_response_id must be provided. To obtain the appropriate client_response_id, use the GET /client_response endpoint to view all client responses firm-wide and their current information. The details to be updated must also be provided. The endpoint returns the client_response_id and all the details for the client response.

HTTP REQUEST

PUT /client_response/{client_response_id}

Delete a client response

Example Request

curl -X DELETE -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/client_response/7960419c-c098-4450-8cc5-866b7385230b0"

Response (204 No Content)

Permanently delete a client response for a client. The client_response_id must be provided. To obtain the appropriate client_response_id, use the GET /client_response endpoint to view all client responses firm-wide. This deletes the client_response_id and the client response record.

HTTP REQUEST

DELETE /client_response/{client_response_id}

Client Hydro

The Client-Hydro entity represents the relationship between a client in the platform and the client’s Hydro ID. This entity is also used to store attributes relating to integrations with Hydro API capabilities.

Field Type Description
id UUID The id of the client-hydro relationship
client_id UUID The id of the client to whom the Hydro ID belongs
hydro_id string The Hydro ID for the client. Also found under the client object
is_hydro_id_verified boolean Indicator if the client has verified ownership of the Hydro ID provided. Defaults to false which means ownership has not been verified
is_client_raindrop_linked boolean Indicator for whether or not the client has successfully linked their Hydro ID to your Client-side Raindrop application. Defaults to false which indicates it has not been linked
is_client_raindrop_enabled boolean Indicator for whether or not the client has chosen to enable the Hydro Client-side Raindrop service on your application. Defaults to false which indicates the service is not enabled
metadata map Custom information associated with the client-hydro relationship in the format key:value
See Metadata
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

List all client-hydro relationship

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/client_hydro"

Example Response

{
    "content": [
        {
            "id": "d787cf19-d11c-49f2-abf3-f5fec1b101d4",
            "create_date": "2018-07-30T00:00:00.000+0000",
            "update_date": "2018-07-31T00:00:00.000+0000",
            "client_id": "1f9a4b00-0a06-4cfa-8774-3d5485206bda",
            "hydro_id": "10lm4nz",
            "is_hydro_id_verified": true,
            "is_client_raindrop_linked": true,
            "is_client_raindrop_enabled": true,
            "metadata": {}
        },
        {
            "id": "08628a95-5b2c-4070-86eb-fdae95f58cbd",
            "create_date": "2018-11-09T00:00:00.000+0000",
            "update_date": "2018-11-10T00:00:00.000+0000",
            "client_id": "b475b55c-e1a3-4348-87fe-29db0f0a843e",
            "hydro_id": "10lm4nz",
            "is_hydro_id_verified": true,
            "is_client_raindrop_linked": false,
            "is_client_raindrop_enabled": false,
            "metadata": {}
        },
        {
            "id": "90b7b9cd-63d1-470d-b103-d46cfc1db711",
            "create_date": "2018-11-30T00:00:00.000+0000",
            "update_date": "2018-12-01T00:00:00.000+0000",
            "client_id": "643ed0d0-e043-41e9-aa9e-19611e53cdd4",
            "hydro_id": "10lm4nz",
            "is_hydro_id_verified": true,
            "is_client_raindrop_linked": false,
            "is_client_raindrop_enabled": true,
            "metadata": {}
        }

    ],
    "last": false,
    "total_pages": 1,
    "total_elements": 3,
    "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 information for all client-hydro relationships for all clients defined for your firm. You can filter using a unique client_id to view the client-hydro relationships for a client and the client’s Hydro ID information. To identify the appropriate client_id, use the GET /client endpoint to see all clients defined for your firm. Note that the metadata information is stored as a nested object within the client-hydro object.

HTTP REQUEST

GET /client_hydro

Create a client-hydro relationship

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
        "client_id": "04266c1d-62e8-457e-b972-4ef2cfa78399",
        "hydro_id": "10lm4nz",
        "is_hydro_id_verified": true,
        "is_client_raindrop_linked": true,
        "is_client_raindrop_enabled": true
    }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/client_hydro"

Example Response

{
    "id": "d787cf19-d11c-49f2-abf3-f5fec1b101d4",
    "create_date": "2018-07-30T00:00:00.000+0000",
    "client_id": "04266c1d-62e8-457e-b972-4ef2cfa78399",
    "hydro_id": "10lm4nz",
    "is_hydro_id_verified": true,
    "is_client_raindrop_linked": true,
    "is_client_raindrop_enabled": true,
    "metadata": {}
}

Create a client-hydro relationship under a client. The client_id must be provided. To identify the appropriate client_id, use the GET /client endpoint to see all clients for your firm. The endpoint returns an client_hydro_id that can then be used to manage the client-hydro relationship.

HTTP REQUEST

POST /client_hydro

ARGUMENTS

Parameter Type Required Description
client_id UUID required The id of the client to whom the Hydro ID belongs
hydro_id string required The hydro ID for the client. Also found under the client object
is_hydro_id_verified boolean optional Indicator if the client has verified ownership of the Hydro ID provided. Defaults to false which means ownership has not been verified
is_client_raindrop_linked boolean optional Indicator for whether or not the client has successfully linked their Hydro ID to your Client-side Raindrop application. Defaults to false which indicates it has not been linked
is_client_raindrop_enabled boolean optional Indicator for whether or not the client has chosen to enable the Hydro Client-side Raindrop service on your application. Defaults to false which indicates the service is not enabled
metadata map optional Custom information associated with the client-hydro relationship in the format key:value
See Metadata
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Retrieve a client-hydro relationship

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/client_hydro/d787cf19-d11c-49f2-abf3-f5fec1b101d4"

Example Response

{
    "id": "d787cf19-d11c-49f2-abf3-f5fec1b101d4",
    "create_date": "2018-07-30T00:00:00.000+0000",
    "client_id": "1f9a4b00-0a06-4cfa-8774-3d5485206bda",
    "hydro_id": "10lm4nz",
    "is_hydro_id_verified": true,
    "is_client_raindrop_linked": true,
    "is_client_raindrop_enabled": true,
    "metadata": {}
}

Retrieve the information for a specific client-hydro relationship. The unique client_hydro_id must be provided. The endpoint returns the client_hydro_id and details for the client-hydro relationship specified. Note that the metadata information is stored as a nested object within the client-hydro object.

HTTP REQUEST

GET /client_hydro/{client_hydro_id}

Update a client-hydro relationship

Example Request

curl -X PUT -H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
        "client_id": "1f9a4b00-0a06-4cfa-8774-3d5485206bda",
        "hydro_id": "10lm4nz",
        "is_hydro_id_verified": true,
        "is_client_raindrop_linked": false,
        "is_client_raindrop_enabled": false
    }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/client_hydro/d787cf19-d11c-49f2-abf3-f5fec1b101d4"

Example Response

{
    "id": "d787cf19-d11c-49f2-abf3-f5fec1b101d4",
    "create_date": "2018-07-30T00:00:00.000+0000",
    "update_date": "2019-01-30T00:00:00.000+0000",
    "client_id": "1f9a4b00-0a06-4cfa-8774-3d5485206bda",
    "hydro_id": "10lm4nz",
    "is_hydro_id_verified": true,
    "is_client_raindrop_linked": false,
    "is_client_raindrop_enabled": false,
    "metadata": {}
}

Update the information for a client-hydro relationship. The unique client_hydro_id must be provided. To obtain the appropriate client_hydro_id, use the GET /client_hydro endpoint to view all client-hydro relationships defined for your firm and their current information. The details to be updated must also be provided. The endpoint returns the client_hydro_id and the details for the client-hydro relationship.

HTTP REQUEST

PUT /client_hydro/{client_hydro_id}

Delete a client-hydro relationship

Example Request

curl -X DELETE -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/client_hydro/d787cf19-d11c-49f2-abf3-f5fec1b101d4"

Response (204 No Content)

Permanently delete a client-hydro relationship for a Hydro ID and a client. The unique client_hydro_id must be provided. To obtain the appropriate client_hydro_id, use the GET /client_hydro endpoint to view all client-hydro relationships defined for your firm. This deletes the client_hydro_id and all client-hydro relationship record information.

HTTP REQUEST

DELETE /client_hydro/{client_hydro_id}

Client Status

Client statuses correspond to a stage_id and reflects the different stages that a client flows through along a user journey, useful for sign-up funnels. See the Stage section for stage_id.

Field Type Description
id UUID The id for the specific client status record for the client_id provided
client_id UUID The id of the client to which the status belongs
status string Status of the client such as “Signed Up” or “KYC Submitted”
stage_id UUID Refers to the stage the client is in.
Useful for sign-up funnels where an account is not being created.
comments string Comments for the client regarding their status
metadata map Custom information associated with the entity in the format key:value
See Metadata
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

List all client statuses

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/client_status"

Example Response

{
    "content": [
      {
            "id": "6db4a470-a00c-40bb-a325-067d0bdb3ddc",
            "create_date": "2019-02-08T16:59:27.000+0000",
            "update_date": "2019-02-08T16:59:27.000+0000",
            "comments": "Upload your passport",
            "status": "KYC Pending",
            "stage_id": "e995d4c1-f989-4733-9867-713966ac9856",
            "client_id": "1d7e1aad-3c79-49fe-bbb9-bd5e239ae1e7",
            "metadata": {}
      },
      {
            "id": "013380bf-7f17-44c1-93c5-892a7ed3498c",
            "create_date": "2019-04-07T00:00:00.000+0000",
            "update_date": "2019-05-08T16:59:27.000+0000",
            "comments": null,
            "status": "KYC Complete",
            "stage_id": "1d7e1aad-3c79-49fe-bbb9-bd5e239ae1e7",
            "client_id": "21098ed9-6439-46ba-abd9-eb6cf28866fb",
            "metadata": {}
      }
    ],
    "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": 2,
    "size": 25,
    "number": 0
}

Get the client status history information for all clients defined for your firm. Client status corresponds to a stage_id and reflects the different stages of a user journey, useful in sign-up funnels. You can filter using a unique client_id to view the client_status records for a specific client. To obtain the appropriate client_id, use the GET /client endpoint to view all clients defined for your firm.

HTTP REQUEST

GET /client_status

Create a client status

Example Request

curl -X POST -H "Authorization: Bearer 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
-H "Content-Type: application/json" \
-d '{
        "status": "KYC complete",
        "stage_id": "e995d4c1-f989-4733-9867-713966ac9856",
        "account_id": "1d7e1aad-3c79-49fe-bbb9-bd5e239ae1e7"
    }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/client_status"

Example Response

{
    "id": "6db4a470-a00c-40bb-a325-067d0bdb3ddc",
    "create_date": "2018-02-08T16:59:27.000+0000",
    "comments": null,
    "status": "KYC Complete",
    "stage_id": "e995d4c1-f989-4733-9867-713966ac9856",
    "client_id": "1d7e1aad-3c79-49fe-bbb9-bd5e239ae1e7",
    "metadata": {}
}

Create a client status record for a client by assigning a stage_id to the client. The unique client_id and stage_id must be provided. To obtain the appropriate client_id, use the GET /client endpoint to view all clients defined for your firm. To obtain the appropriate stage_id, use the GET /stage endpoint to view all client stages defined for your firm. The create_date defaults to the current date. The endpoint returns an client_status_id which represents a record in the client’s history log.

HTTP REQUEST

POST /client_status

ARGUMENTS

Parameter Type Required Description
client_id UUID required The id of the client to which the status belongs
status string required Status of the client such as “Signed Up” or “KYC Submitted”
stage_id UUID required Refers to the stage the client is in.
Useful for sign-up funnels where an account is not being created.
comments string optional Comments for the client regarding their status
metadata map optional Custom information associated with the entity in the format key:value
See Metadata
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Retrieve a client status

Example Request

curl -X GET -H "Authorization: Bearer 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/client_status/6db4a470-a00c-40bb-a325-067d0bdb3ddc"

Example Response

{
    "id": "6db4a470-a00c-40bb-a325-067d0bdb3ddc",
    "create_date": "2018-02-08T16:59:27.000+0000",
    "update_date": "2018-02-08T16:59:27.000+0000",
    "comments": "Invested",
    "status": "Complete",
    "stage_id": "e995d4c1-f989-4733-9867-713966ac9856",
    "account_id": "1d7e1aad-3c79-49fe-bbb9-bd5e239ae1e7",
    "metadata": {}
}

Retrieve the information for a specific client status record for a client. The unique client_status_id must be provided. The endpoint returns details for the client status record specified.

HTTP REQUEST

GET /client_status/{client_status_id}

Update a client status

Example Request

curl -X PUT -H "Authorization: Bearer 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
-H "Content-Type: application/json" \
-d '{
        "status": "Complete",
        "stage_id": "e995d4c1-f989-4733-9867-713966ac9856",
        "client_id": "1d7e1aad-3c79-49fe-bbb9-bd5e239ae1e7"
    }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/client_status/6db4a470-a00c-40bb-a325-067d0bdb3ddc"

Example Response

{
    "id": "6db4a470-a00c-40bb-a325-067d0bdb3ddc",
    "create_date": "2018-02-08T16:59:27.000+0000",
    "update_date": "2018-02-08T16:59:27.000+0000",
    "comments": null,
    "status": "KYC in Progress",
    "stage_id": "e995d4c1-f989-4733-9867-713966ac9856",
    "client_id": "1d7e1aad-3c79-49fe-bbb9-bd5e239ae1e7",
    "metadata": {}
}

Update a client status record for a client. The unique client_status_id must be provided. To obtain the appropriate client_status_id, use the GET /client_status endpoint to view all client statuses for each client defined for your firm and their current information. The details to be updated must also be provided. The endpoint returns the client_status_id with the details for the client status.

HTTP REQUEST

PUT /client_status/{client_status_id}

Delete a client status

Example Request

curl -X DELETE -H "Authorization: Bearer 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/client_status/6db4a470-a00c-40bb-a325-067d0bdb3ddc"

Response (204 No Content)

Permanently delete a client status record from an client’s history. The client_status_id must be provided. To obtain the appropriate client_status_id, use the GET /client_status endpoint to view all client statuses for each client defined for your firm. This deletes the client_status_id from the client’s history log table and removes the status from the client.

HTTP REQUEST

DELETE /client_status/{client_status_id}

Decision Tree

Decision trees are designed to guide your users in determining the best course of action for them based on their objectives. For example, a decision tree can be used to determine the most suitable allocation for a client’s investment portfolio according to a goal, time horizon, risk profile etc. Decision trees can also be used to guide the order of questionnaire questions; specifically, if the question order is meant to be dynamic and may change based on a client’s responses, then a decision tree needs to be used. Decision trees consist of a series of nodes, which generally represent questionnaire question and answer combinations. These nodes are linked together via node relationships. Each decision tree has an initial node. This node is mapped to a child node via a node relationship. The child node is then mapped to a subsequent child node via another node relationship, and so on. Certain nodes will be end nodes, or “leaves”, and those can be mapped to allocation(s) or models if applicable. These final node relationship in a branch of a decision tree is identified with an is_leaf flag, where true indicates that the child_node in the node relationship is the end node.

Tree Management

Field Type Description
id UUID The id of the decision tree
name string Name of the decision tree
category string A category for the decision tree such as “Onboarding” or “Risk Profile”
subcategory string A subcategory for the decision tree such as “Income-related”
description string Description for the decision tree such as “Tree to allocate clients to taxable portfolios”
is_active boolean Indicates if the tree is active. Defaults to true which indicates that it is currently active
metadata map Custom information associated with the entity in the format key:value
See Metadata
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

List all decision trees

Example Request

curl -X GET -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/decision_tree"

Example Response

{
    "content": [
        {
            "id": "28021071-bece-400b-a0f6-23fb13adfcd3",
            "create_date": "2018-03-26T19:49:47.000+0000",
            "update_date": "2018-03-26T19:49:47.000+0000",
            "name": "Retirement Account Tree",
            "category": "Retirement Profile",
            "subcategory": "Income-related",
            "description": "Decision tree which allocates people looking to open a retirement account",
            "is_active": true,
            "metadata": {}
        },
        {
            "id": "0a5b1bf9-1e22-4eb2-b366-abacefc7a23b",
            "create_date": "2018-03-23T16:31:24.000+0000",
            "update_date": "2018-03-23T16:31:24.000+0000",
            "name": "Retirement Account Tree",
            "category": "Retirement Profile",
            "subcategory": "Income-related",
            "description": "Decision tree which allocates people looking to open a retirement account",
            "is_active": true,
            "metadata": {}
        },
        {
            "id": "0e62f776-b9e9-43cb-8e37-00d8b5133eee",
            "create_date": "2018-03-23T16:24:07.000+0000",
            "update_date": "2018-03-23T16:24:07.000+0000",
            "name": "Retirement Account Tree",
            "category": "Retirement Profile",
            "subcategory": "Income-related",
            "description": "Decision tree which allocates people looking to open a retirement account",
            "is_active": true,
            "metadata": {}
        }
    ],
    "total_pages": 1,
    "total_elements": 3,
    "last": true,
    "first": true,
    "sort": [
        {
          "direction": "DESC",
          "property": "id",
          "ignore_case": false,
          "null_handling": "NATIVE",
          "ascending": false,
          "descending": true
        }
    ],
    "number_of_elements": 1,
    "size": 25,
    "number": 0
}

Get the information for all decision trees defined for your firm. The endpoint returns the id and the description details for each decision tree.

HTTP REQUEST

GET /decision_tree

Create a decision tree

Example Request

curl -X POST -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
      -H "Content-Type: application/json" \
      -d '{
              "name": "Retirement Account Tree",
              "category": "Retirement Profile",
              "subcategory": "Income-related",
              "description": "Decision tree which allocates people looking to open a retirement account"
          }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/decision_tree"

Example Response

{
    "id": "28021071-bece-400b-a0f6-23fb13adfcd3",
    "create_date": "2018-03-26T19:49:47.000+0000",
    "name": "Retirement Account Tree",
    "category": "Retirement Profile",
    "subcategory": "Income-related",
    "description": "Decision tree which allocates people looking to open a retirement account",
    "is_active": true,
    "metadata": {}
}

Create a new decision tree for your firm. The create_date will default to the current date. The endpoint returns a decision_tree_id used to manage the decision tree and assign it to other entities.

HTTP REQUEST

POST /decision_tree

ARGUMENTS

Parameter Type Required Description
name string required Name of the decision tree
category string optional A category for the decision tree such as “Onboarding” or “Risk Profile”
subcategory string optional A subcategory for the decision tree such as “Income-related”
description string optional Description for the decision tree such as “Tree to allocate clients to taxable portfolios”
is_active boolean optional Indicates if the tree is active. Defaults to true which indicates that it is currently active
metadata map optional Custom information associated with the entity in the format key:value
See Metadata
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Retrieve a decision tree

Example Request

curl -X GET -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
      "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/decision_tree/28021071-bece-400b-a0f6-23fb13adfcd3"

Example Response

{
    "id": "28021071-bece-400b-a0f6-23fb13adfcd3",
    "create_date": "2018-03-26T19:49:47.000+0000",
    "update_date": "2018-03-26T19:49:47.000+0000",
    "name": "Retirement Account Tree",
    "category": "Retirement Profile",
    "subcategory": "Income-related",
    "description": "Decision tree which allocates people looking to open a retirement account",
    "is_active": true,
    "metadata": {}
}

Retrieve the information for a decision tree. The decision_tree_id must be provided. This endpoint returns the decision_tree_id and the details for the decision tree specified.

HTTP REQUEST

GET /decision_tree/{decision_tree_id}

Update a decision tree

Example Request

curl -X PUT -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
      -H "Content-Type: application/json" \
      -d '{
              "name": "Retirement Account Tree",
              "category": "Retirement Profile",
              "subcategory": "Income-related",
              "description": "Decision tree which allocates people looking to open a retirement account"
          }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/decision_tree/28021071-bece-400b-a0f6-23fb13adfcd3"

Example Response

{
    "id": "28021071-bece-400b-a0f6-23fb13adfcd3",
    "create_date": "2018-03-26T19:49:47.000+0000",
    "update_date": "2018-03-26T19:49:47.000+0000",
    "name": "Retirement Account Tree",
    "category": "Retirement Profile",
    "subcategory": "Income-related",
    "description": "Decision tree which allocates people looking to open a retirement account",
    "is_active": true,
    "metadata": {}
}

Updated the information for a decision tree. The decision_tree_id must be provided. To obtain the appropriate decision_tree_id, use the GET /decision_tree endpoint to view all decision trees defined for your firm and their current information. The details to be updated must also be provided. This endpoint returns the decision_tree_id and the details for the decision tree.

HTTP REQUEST

PUT /decision_tree/{decision_tree_id}

Delete a decision tree

Example Request

curl -X DELETE -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/decision_tree/28021071-bece-400b-a0f6-23fb13adfcd3"

Response (204 No Content)

Permanently delete a decision tree. The decision_tree_id must be provided. To obtain the appropriate decision_tree_id, use the GET /decision_tree endpoint to view all decision trees defined for your firm. This deletes the decision_tree_id and the details for the decision tree.

HTTP REQUEST

DELETE /decision_tree/{decision_tree_id}

Nodes

Nodes correspond to question and answer combinations along a decision tree that a client must answer, usually as part of a questionnaire. Nodes are linked together in parent-child relationships to create a branch of a decision tree. The first node of a branch is used to map to the first question of a questionnaire. When creating a decision tree, you should create a node corresponding to each question in the questionnaire and the possible answer combinations for the questions before the current question. The last node along the branch is the end node and maps to one or more allocations or models.

Field Type Description
id UUID The id of the node
name string Name of the node
is_first boolean Indicates if this is the first node of the decision tree. Defaults to false meaning it is not the first node
question_id UUID The id of the question that corresponds to this node
metadata map Custom information associated with the entity in the format key:value
See Metadata
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

List all nodes

Example Request

curl -X GET -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/node"

Example Response

{
    "content": [
        {
            "id": "05b9f2e6-aabc-44b5-8e02-f1ab216ebd62",
            "create_date": "2018-03-26T19:50:51.000+0000",
            "update_date": "2018-03-26T19:50:51.000+0000",
            "name": "What is your age?",
            "question_id": "286ddd93-4fed-4e01-b26b-838813212c34",
            "is_first": false,
            "metadata": {}
        },
        {
            "id": "0faa837e-370d-4721-8cbc-e2e167d973d9",
            "create_date": "2018-03-26T19:50:51.000+0000",
            "update_date": "2018-03-26T19:50:51.000+0000",
            "name": "What is your annual income in dollars?",
            "question_id": "286ddd93-4fed-4e01-b26b-838813212c34",
            "is_first": false,
            "metadata": {}
        },
        {
            "id": "1154c13c-0f5b-4c39-80ac-196633169a2e",
            "create_date": "2018-03-26T19:50:51.000+0000",
            "update_date": "2018-03-26T19:50:51.000+0000",
            "name": "What is your risk tolerance?",
            "question_id": "286ddd93-4fed-4e01-b26b-838813212c34",
            "is_first": false,
            "metadata": {}
        }
    ],
    "total_pages": 1,
    "total_elements": 3,
    "last": false,
    "number_of_elements": 25,
    "first": true,
    "sort": [
        {
            "direction": "DESC",
            "property": "updateDate",
            "ignore_case": false,
            "null_handling": "NATIVE",
            "descending": true,
            "ascending": false
        }
    ],
    "size": 25,
    "number": 0
}

List all nodes that are defined for your firm. The endpoint returns the node_id and the details for the node.

HTTP REQUEST

GET /node

Create a node

Example Request

curl -X POST -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
      -H "Content-Type: application/json" \
      -d '{
              "name": "What is your annual income in dollars?",
              "question_id": "286ddd93-4fed-4e01-b26b-838813212c34",
              "is_first": false
          }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/node"

Example Response

{
    "id": "05b9f2e6-aabc-44b5-8e02-f1ab216ebd62",
    "create_date": "2018-03-26T19:50:51.000+0000",
    "name": "What is your annual income in dollars?",
    "question_id": "286ddd93-4fed-4e01-b26b-838813212c34",
    "is_first": false,
    "metadata": {}
}

Create a new node for your firm that can be used in a decision tree and mapped to other nodes. The question_id in the node must be provided. To obtain the appropriate question_id, use the GET /questionnaire/{questionnaire_id} endpoint to view all the question_ids for a questionnaire. The create_date will default to the current date. The endpoint returns a node_id used to map the node to a decision tree and to other nodes.

HTTP REQUEST

POST /node

ARGUMENTS

Parameter Type Required Description
name string required Name of the node
question_id UUID required The id of the question that corresponds to this node
is_first boolean optional Indicates if this is the first node of the decision tree. Defaults to false meaning it is not the first node
metadata map optional Custom information associated with the entity in the format key:value
See Metadata
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Retrieve a node

Example Request

curl -X GET -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
      "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/node/05b9f2e6-aabc-44b5-8e02-f1ab216ebd62"

Example Response

{
    "id": "05b9f2e6-aabc-44b5-8e02-f1ab216ebd62",
    "create_date": "2018-03-26T19:50:51.000+0000",
    "update_date": "2018-03-26T19:50:51.000+0000",
    "name": "What is your annual income in dollars?",
    "question_id": "286ddd93-4fed-4e01-b26b-838813212c34",
    "is_first": false,
    "metadata": {}
}

Retrieve the information for a node. The node_id must be provided. The endpoint returns the node_id and the details for the node specified.

HTTP REQUEST

GET /node/{node_id}

Update a node

Example Request

curl -X PUT -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
      -H "Content-Type: application/json" \
      -d '{
              "name": "What is your annual income in dollars?",
              "question_id": "286ddd93-4fed-4e01-b26b-838813212c34",
              "is_first": false
          }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/node/05b9f2e6-aabc-44b5-8e02-f1ab216ebd62"

Example Response

{
    "id": "05b9f2e6-aabc-44b5-8e02-f1ab216ebd62",
    "create_date": "2018-03-26T19:50:51.000+0000",
    "update_date": "2018-03-26T19:50:51.000+0000",
    "name": "What is your annual income in dollars?",
    "question_id": "286ddd93-4fed-4e01-b26b-838813212c34",
    "is_first": false,
    "metadata": {}
}

Updated the information for a node. The node_id must be provided. To obtain the appropriate node_id, use the GET /node endpoint to view all the nodes defined for your firm and their current information. The details to be updated must also be provided. The endpoint returns the node_id and the details for the node.

HTTP REQUEST

PUT /node/{node_id}

Delete a node

Example Request

curl -X DELETE -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/node/05b9f2e6-aabc-44b5-8e02-f1ab216ebd62"

Response (204 No Content)

Permanently delete a node. The node_id must be provided. To obtain the appropriate node_id, use the GET /node endpoint to view all the nodes defined for your firm. This deletes the node_id and the details for the node.

HTTP REQUEST

DELETE /node/{node_id}

Node Relationships

Node relationships indicate the order in which nodes should follow each other along a decision tree branch. Each node relationship corresponds to the possible path that can be taken after a question based on the response provided by a client. The answer_id in the node relationship is used to identify the client response provided for that answer_id. You must create a node relationship for every required node-to-node flow, eventually leading to the last node of the decision tree, which maps to the corresponding allocation or model.

Field Type Description
id UUID The id of the node relationship
answer_id UUID The id of the answer to a question_id that corresponds to the node relationship
value string Value of the answer
decision_tree_id UUID The id of the decision tree to which the node relationship belongs
node_parent_id UUID The id for the parent node
node_child_id UUID The id for the child node
is_leaf boolean Indicates if the node relationship represents the last point in the decision tree branch. true indicates that the next node is the last node, and that it maps to an allocation or model
metadata map Custom information associated with the entity in the format key:value
See Metadata
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

List all node relationships

Example Request

curl -X GET -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
      "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/node_relationship"

Example Response

{
  "content": [
      {
          "id": "8397d8fd-e80d-48ea-bf79-81f32b12606e",
          "create_date": "2018-03-26T19:54:31.000+0000",
          "update_date": "2018-03-26T19:54:31.000+0000",
          "node_parent_id": "05b9f2e6-aabc-44b5-8e02-f1ab216ebd62",
          "node_child_id": "d5011ba6-50c6-427b-a29c-b7802a2c8660",
          "answer_id": "556cedaa-37ba-4dc7-ad03-0990b9252e1d",
          "value": "high",
          "is_leaf": false,
          "decision_tree_id": "28021071-bece-400b-a0f6-23fb13adfcd3",
          "metadata": {}
      },
      {
          "id": "c7114848-d17f-420e-b73b-53a5b8fca9d9",
          "create_date": "2018-03-26T19:54:31.000+0000",
          "update_date": "2018-03-26T19:54:31.000+0000",
          "node_parent_id": "05b9f2e6-aabc-44b5-8e02-f1ab216ebd62",
          "node_child_id": "df9b27e4-f619-4deb-b207-5635dbb15bb4",
          "answer_id": "0217b35e-36fe-4796-8e7f-61e93e9e6ef5",
          "value": "medium",
          "is_leaf": false,
          "decision_tree_id": "28021071-bece-400b-a0f6-23fb13adfcd3",
          "metadata": {}
      },
      {
          "id": "84f29454-498b-4785-91ac-1f9af0c686c6",
          "create_date": "2018-03-26T19:54:28.000+0000",
          "update_date": "2018-03-26T19:54:28.000+0000",
          "node_parent_id": "05b9f2e6-aabc-44b5-8e02-f1ab216ebd62",
          "node_child_id": "a787a485-555b-4463-af83-d3643a767d96",
          "answer_id": "0217b35e-36fe-4796-8e7f-61e93e9e6ef5",
          "value": "low",
          "is_leaf": true,
          "decision_tree_id": "28021071-bece-400b-a0f6-23fb13adfcd3",
          "metadata": {}
      }
  ],
  "total_pages": 1,
  "last": true,
  "total_elements": 3,
  "first": true,
  "sort": [
    {
      "direction": "DESC",
      "property": "id",
      "ignore_case": false,
      "null_handling": "NATIVE",
      "ascending": false,
      "descending": true
    }
  ],
  "number_of_elements": 1,
  "size": 25,
  "number": 0
}

Get the information for all the node relationships defined for your firm. The endpoint returns a list of UUIDs and the details for all node relationships.

HTTP REQUEST

GET /node_relationship

Create a node relationship

Example Request

curl -X POST -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
      -H "Content-Type: application/json" \
      -d '{
              "node_parent_id": "05b9f2e6-aabc-44b5-8e02-f1ab216ebd62",
              "node_child_id": "d5011ba6-50c6-427b-a29c-b7802a2c8660",
              "answer_id": "556cedaa-37ba-4dc7-ad03-0990b9252e1d",
              "value": "high",
              "is_leaf": false,
              "decision_tree_id": "28021071-bece-400b-a0f6-23fb13adfcd3"
          }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/node_relationship"

Example Response

{
    "id": "8397d8fd-e80d-48ea-bf79-81f32b12606e",
    "create_date": "2018-03-26T19:54:31.000+0000",
    "node_parent_id": "05b9f2e6-aabc-44b5-8e02-f1ab216ebd62",
    "node_child_id": "d5011ba6-50c6-427b-a29c-b7802a2c8660",
    "answer_id": "556cedaa-37ba-4dc7-ad03-0990b9252e1d",
    "value": "high",
    "is_leaf": false,
    "decision_tree_id": "28021071-bece-400b-a0f6-23fb13adfcd3",
    "metadata": {}
}

Create a new node relationship for your firm. The answer_id, the node_id of the parent node, the node_id of the child node and the decision_tree_id must be provided. To obtain the appropriate answer_id, use the GET /questionnaire/{questionnaire_id} endpoint to view all the answer_ids for a questionnaire. To obtain the appropriate node_ids, use the GET /node endpoint to view all the nodes defined for your firm. To obtain the appropriate decision_tree_id, use the GET /decision_tree endpoint to view all the decision trees defined for your firm. The endpoint returns a node_relationship_id used to store the mapping between two nodes, as well as the last node to an allocation or model (if applicable).

HTTP REQUEST

POST /node_relationship

ARGUMENTS

Parameter Type Required Description
answer_id UUID required The id of the answer to a question_id that corresponds to the node relationship
value string required Value of the answer
decision_tree_id UUID required The id of the decision tree to which the node relationship belongs
node_parent_id UUID required The id for the parent node.
node_child_id UUID optional The id for the child node.
is_leaf boolean optional Indicator if the node relationship represents the last point in the decision tree branch. true indicates it is the last point and that is maps to an allocation or model
metadata map optional Custom information associated with the entity in the format key:value
See Metadata
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Retrieve a node relationship

Example Request

curl -X GET -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
      "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/node_relationship/8397d8fd-e80d-48ea-bf79-81f32b12606e"

Example Response

{
    "id": "8397d8fd-e80d-48ea-bf79-81f32b12606e",
    "create_date": "2018-03-26T19:54:31.000+0000",
    "update_date": "2018-03-26T19:54:31.000+0000",
    "node_parent_id": "05b9f2e6-aabc-44b5-8e02-f1ab216ebd62",
    "node_child_id": "d5011ba6-50c6-427b-a29c-b7802a2c8660",
    "answer_id": "556cedaa-37ba-4dc7-ad03-0990b9252e1d",
    "value": "high",
    "is_leaf": false,
    "decision_tree_id": "28021071-bece-400b-a0f6-23fb13adfcd3",
    "metadata": {}
}

Retrieve the information for a node relationship. The node_relationship_id must be provided. The endpoint returns the node_relationship_id and the details for the node relationship specified.

HTTP REQUEST

GET /node_relationship/{node_relationship_id}

Update a node relationship

Example Request

curl -X PUT -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
      -H "Content-Type: application/json" \
      -d '{
              "node_parent_id": "05b9f2e6-aabc-44b5-8e02-f1ab216ebd62",
              "node_child_id": "d5011ba6-50c6-427b-a29c-b7802a2c8660",
              "answer_id": "556cedaa-37ba-4dc7-ad03-0990b9252e1d",
              "value": "high",
              "is_leaf": true,
              "decision_tree_id": "28021071-bece-400b-a0f6-23fb13adfcd3"
        }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/node_relationship/8397d8fd-e80d-48ea-bf79-81f32b12606e"

Example Response

{
    "id": "8397d8fd-e80d-48ea-bf79-81f32b12606e",
    "create_date": "2018-03-26T19:54:31.000+0000",
    "update_date": "2018-03-26T19:54:31.000+0000",
    "node_parent_id": "05b9f2e6-aabc-44b5-8e02-f1ab216ebd62",
    "node_child_id": "d5011ba6-50c6-427b-a29c-b7802a2c8660",
    "answer_id": "556cedaa-37ba-4dc7-ad03-0990b9252e1d",
    "value": "high",
    "is_leaf": true,
    "decision_tree_id": "28021071-bece-400b-a0f6-23fb13adfcd3",
    "metadata": {}
}

Update the information for a node relationship. The node_relationship_id must be provided. To obtain the appropriate node_relationship_id, use the GET /node_relationship endpoint to view all the node relationships defined for your firm and their current information. The details to be updated must also be provided. The endpoint returns the node_relationship_id and the details for the node relationship.

HTTP REQUEST

PUT /node_relationship/{node_relationship_id}

Delete a node relationship

Example Request

curl -X DELETE -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
      "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/node_relationship/8397d8fd-e80d-48ea-bf79-81f32b12606e"

Response (204 No Content)

Permanently delete a node relationship. The node_relationship_id must be provided. To obtain the appropriate node_relationship_id, use the GET /node_relationship endpoint to view all the node relationships defined for your firm. This deletes the node_relationship_id and the details for the node relationship.

HTTP REQUEST

DELETE /node_relationship/{node_relationship_id}

Decision Tree Result

Returns the model_id, allocation_id, insurance_quote_id, or financial_offer_id by traversing the decision tree and finding the corresponding leaf node for the answer_ids provided in the client_response.

HTTP REQUEST

POST /decision_tree_result

ARGUMENTS

Field Type Description
entity_type string The entity to which the answers correspond. The value can be ‘model’, ‘allocation’, ‘insurance_quote’, or ‘financial_offer’
answers map A map of the answers provided in relation to the entity
      answer_id UUID The ID of the answer being provided

RESPONSE

Field Type Description
entity_type string The entity to which the answers correspond. The value can be model_id, allocation_id, insurance_quote_id, or financial_offer_id
entity_id UUID The ID of the entity, as a result of systemically traversing the decision tree

Example Request

curl -X POST -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
      -H "Content-Type: application/json" \
      -d '{
              "entity_type": "model",
              "answers": [
                {
                  "answer_id": "05b9f2e6-aabc-44b5-8e02-f1ab216ebd62",
                  "answer_id": "27h8e5n8-nenl-53y3-9w16-h7qd627jmw38"
                }
              ]
          }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/decision_tree_result"

Example Response

{
  "entity_type": "model_id",
  "entity_id": [
     "05nmkw36-aabc-32d5-8e02-f1ab216mkw62"
   ]
}

Questionnaire

Questionnaires represent a series of questions that a user can answer to help in the selection or customization of a product. For example, it can be an investment risk profile questionnaire that helps determine a client’s risk profile and the appropriate allocations or models for him/her. Questionnaires can also be assigned to goals and represent the questions a client must answer to customize their goal. The answer values provided to questions from a client are stored as client responses. Questions can be answered so that they only apply to a specific account, or they can be answered to apply to a client as a whole so that the client does not have to answer the same question multiple times.

Questionnaire Management

Field Type Description
id UUID The id of the questionnaire
name string Name for the questionnaire
description string Descriptions for additional information on the questionnaire
decision_tree_id UUID The id of the decision tree that corresponds to the questionnaire
type string Type of questionnaire such as “retirement plan”
is_active boolean Indicates if the questionnaire is currently active. Defaults to true which indicates it is active.
questions array List of questions to be answered as well as their respective answers and weights within the questionnaire
      id string The id of the question
      category string A category for the question such as “Onboarding” or “Risk Profile”
      subcategory string A subcategory for the question such as “Income-related”
      title string Title for the question such as the body of the question or a header. Pairs with the description field
      description string Description for the question such as additional question content. Pairs with the title field
      question_type string The type of question structure such as “multiple_choice” or “free_form”
      order_index string The order of the question within the questionnaire or category such as “1”, “2”, “3”
      document string A reference link to a document related to the question
      image string A reference link to an image associated with the question
      weight float The weight of the question as a percentage of the total questionnaire if each question does not contribute equally when calculating the final “score”; ex. 20 representing 20%.
      tooltip string A tooltip to display on the UI explaining the question
      is_account boolean Indicates if the question is answered at an account-level
      metadata map Custom information associated with the question in the format key:value. See Metadata
      answers array Possible answers to the question such as multiple choice options
            id string The id of the answer option
            value string Value for the answer option
            order_index string The order of the answer option within the question or category such as “1”, “2”, “3”
            label string A label to be assigned to the answer option for data labeling purposes
            image string A reference link to an image associated with the answer option
            weight float The weight of the answer option as a percentage or value of the total questionnaire score if each answer does not contribute equally when calculating the final “score”; ex. 20 representing 20% or 20 points
            tooltip string A tooltip to display on the UI explaining the answer
            is_default boolean Indicates the default answer to a question in a questionnaire when the UI is displayed to a user. Defaults to false
            metadata map Custom information associated with the answer options in the format key:value. See Metadata
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

List all questionnaires

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/questionnaire"

Example Response

{
    "content": [
        {
          "id": "29fa5156-cd89-4056-9125-ce2428b05f11",
          "create_date": "2018-01-01T21:56:03.000+0000",
          "update_date": "2018-01-15T21:56:03.000+0000",
          "name": "Onboarding Questionnaire",
          "description": "Basic goals onboarding for accounts",
          "type": "Goals",
          "is_active": true,
          "secondary_id": null,
          "questions": [
              {
                  "id": "df392582-514f-486b-b15b-fecba66a104f",
                  "category": "Onboarding",
                  "subcategory": "Basic",
                  "title": "What is your age?",
                  "question_type": "free_form",
                  "order_index": "1",
                  "document": "http://domain.com/legal_agreement.pdf",
                  "image": "http://domain.com/age_graphic.pdf",
                  "tooltip": null,
                  "weight": 0,
                  "is_account": false,
                  "answers": [
                    {
                        "id": "d31c694f-bcb5-427f-b081-91e64e90229a",
                        "value": ">40",
                        "order_index": 2,
                        "image": "http://domain.com/age_graphic1.pdf",
                        "label": null,
                        "weight": 0,
                        "tooltip": null,
                        "is_default": false,
                        "metadata": {}
                    },
                    {
                        "id": "1e52401f-bfec-410b-bca1-afa5f0be37b5",
                        "value": "0-40",
                        "order_index": 1,
                        "image": "http://domain.com/age_graphic2.pdf",
                        "label": null,
                        "weight": 0,
                        "tooltip": null,
                        "is_default": false,
                        "metadata": {}
                    }
                  ],
                  "metadata": {}
              },
              {
                  "id": "65fabce6-c7a3-464c-99a2-717008f4acfe",
                  "category": "Onboarding",
                  "subcategory": "Basic",
                  "title": "What is your annual income in dollars?",
                  "question_type": "monetary_input",
                  "order_index": "2",
                  "weight": 0,
                  "tooltip": null,
                  "is_account": false,
                  "answers": [
                      {
                          "id": "7d8de5fa-6174-4a30-9e70-8e638a3d5304",
                          "value": ">100,000",
                          "order_index": 2,
                          "image": "http://domain.com/income_graphic1.pdf",
                          "label": "Mass Affluent",
                          "weight": 0,
                          "tooltip": null,
                          "is_default": false,
                          "metadata": {}
                      },
                      {
                          "id": "0ffe04ba-5db0-4a72-9fd1-2ba9479e685a",
                          "value": "0-100,000",
                          "order_index": 1,
                          "image": "http://domain.com/income_graphic2.pdf",
                          "label": "Retail",
                          "weight": 0,
                          "tooltip": null,
                          "is_default": false,
                          "metadata": {}
                      }
                  ],
                  "metadata": {}
              }
            ]
          }
        ],
    "last": true,
    "total_pages": 1,
    "total_elements": 2,
    "number_of_elements": 2,
    "first": true,
    "sort": [
        {
            "direction": "DESC",
            "property": "updateDate",
            "ignore_case": false,
            "null_handling": "NATIVE",
            "ascending": false,
            "descending": true
        }
    ],
    "size": 25,
    "number": 0
}

Get the information for all questionnaires defined for your firm. You can filter using a decision_tree_id to view the questionnaire associated with a specific decision tree. To obtain the appropriate decision_tree_id, use the GET /decision_tree endpoint to view all decision trees defined for your firm. Note that the questions are stored as nested objects within the questionnaire object if they have been submitted. The answers are nested within the question object if they have been submitted too. You may update questions and answers within the questionnaire, or individually in their entities below.

HTTP REQUEST

GET /questionnaire

Create a questionnaire

Example Request

curl -X POST -H "Authorization: Bearer <access_token>"
     -H "Content-Type: application/json"
     -d '{
            "name": "Onboarding Questionnaire",
            "description": "Basic goals onboarding for accounts",
            "type": "Goals",
            "is_active": true
       }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/questionnaire"

Example Response

{
    "id": "29fa5156-cd89-4056-9125-ce2428b05f11",
    "create_date": "2018-01-01T21:56:03.000+0000",
    "update_date": "2018-01-01T21:56:03.000+0000",
    "name": "Onboarding Questionnaire",
    "description": "Basic goals onboarding for accounts",
    "type": "Goals",
    "is_active": true,
    "questions": []
}

Create a new questionnaire for your firm. A name for the questionnaire and the embedded questions and answers must be provided. The endpoint returns a questionnaire_id to manage the questionnaire and assign it to goals.

HTTP REQUEST

POST /questionnaire

ARGUMENTS

Parameter Type Required Description
name string required Name for the questionnaire
description string optional Descriptions for additional information on the questionnaire
decision_tree_id UUID optional The id of the decision tree that corresponds to the questionnaire
type string optional Type of questionnaire such as “retirement plan”
is_active boolean optional Indicates if the questionnaire is currently active. Defaults to true which indicates it is active.
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Retrieve a questionnaire

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/questionnaire/29fa5156-cd89-4056-9125-ce2428b05f11"

Example Response

{
    "id": "29fa5156-cd89-4056-9125-ce2428b05f11",
    "create_date": "2018-01-01T21:56:03.000+0000",
    "update_date": "2018-01-15T21:56:03.000+0000",
    "name": "Onboarding Questionnaire",
    "description": "Basic goals onboarding for accounts",
    "type": "Goals",
    "is_active": true,
    "questions": [
        {
            "id": "df392582-514f-486b-b15b-fecba66a104f",
            "category": "Onboarding",
            "subcategory": "Basic",
            "title": "What is your age?",
            "question_type": "free_form",
            "order_index": "1",
            "document": null,
            "image": "http://domain.com/age_graphic.pdf",
            "weight": 0,
            "tooltip": null,
            "is_account": false,
            "answers": [
                {
                  "id": "d31c694f-bcb5-427f-b081-91e64e90229a",
                  "value": ">40",
                  "order_index": 1,
                  "image": "http://domain.com/age_graphic1.pdf",
                  "label": null,
                  "weight": 0,
                  "tooltip": null,
                  "is_default": false,
                  "metadata": {}
                },
                {
                  "id": "1e52401f-bfec-410b-bca1-afa5f0be37b5",
                  "value": "0-40",
                  "order_index": 1,
                  "image": "http://domain.com/age_graphic2.pdf",
                  "label": null,
                  "weight": 0,
                  "tooltip": null,
                  "is_default": false,
                  "metadata": {}
                }
            ],
            "metadata": {}
        },
        {
            "id": "65fabce6-c7a3-464c-99a2-717008f4acfe",
            "category": "Onboarding",
            "subcategory": "Basic",
            "title": "What is your annual income in dollars?",
            "question_type": "monetary_input",
            "order_index": "2",
            "weight": 0,
            "tooltip": null,
            "is_account": false,
            "answers": [
                {
                  "id": "7d8de5fa-6174-4a30-9e70-8e638a3d5304",
                  "value": ">100,000",
                  "order_index": 2,
                  "image": "http://domain.com/income_graphic1.pdf",
                  "label": "Mass Affluent",
                  "weight": null,
                  "tooltip": null,
                  "is_default": false,
                  "metadata": {}
                },
                {
                  "id": "0ffe04ba-5db0-4a72-9fd1-2ba9479e685a",
                  "value": "0-100,000",
                  "order_index": 1,
                  "image": "http://domain.com/income_graphic2.pdf",
                  "weight": 0,
                  "tooltip": null,
                  "is_default": false,
                  "metadata": {}
                }
            ],
            "metadata": {}
        }
    ]
}

Retrieve the information for a questionnaire for your firm. The questionnaire_id must be provided. The endpoint returns the questionnaire_id and the details for the questionnaire specified.

HTTP REQUEST

GET /questionnaire/{questionnaire_id}

Update a questionnaire

Example Request

curl -X PUT -H "Authorization: Bearer <access_token>"
    -H "Content-Type: application/json"
    -d '{
          "type": "Non Goals"
      }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/questionnaire/29fa5156-cd89-4056-9125-ce2428b05f11"

Example Response

{
    "id": "29fa5156-cd89-4056-9125-ce2428b05f11",
    "create_date": "2018-01-01T21:56:03.000+0000",
    "update_date": "2018-01-15T21:56:03.000+0000",
    "name": "Onboarding Questionnaire",
    "description": "Basic goals onboarding for accounts",
    "type": "Non Goals",
    "is_active": true,
    "questions": []
}

Update a questionnaire for your firm. The questionnaire_id must be provided in the URL. To obtain the appropriate questionnaire_id, use the GET /questionnaire endpoint to view all questionnaires for your firm and their current information. The endpoint returns the questionnaire_id and the details for the questionnaire.

HTTP REQUEST

PUT /questionnaire/{questionnaire_id}

Delete a questionnaire

Example Request

curl -X DELETE -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/questionnaire/429fa5156-cd89-4056-9125-ce2428b05f11"

Response (204 No Content)

Permanently delete a questionnaire for your firm. The questionnaire_id must be provided. To obtain the appropriate questionnaire_id, use the GET /questionnaire endpoint to view all questionnaires for your firm. This deletes the questionnaire_id and the details for the questionnaire.

HTTP REQUEST

DELETE /questionnaire/{questionnaire_id}

Question

Questions can be created and attached to a questionnaire_id using the service below.

Field Type Description
id UUID The id of the question
questionnaire_id UUID The id of the questionnaire this question belongs to. All questions can only be attached to one questionnaire at a time.
title string Title for the question such as the body of the question or a header. Pairs with the description field
description string Description for the question such as additional question content. Pairs with the title field
category string A category for the question such as “Onboarding” or “Risk Profile”
subcategory string A subcategory for the question such as “Income-related”
question_type string The type of question structure such as “multiple_choice” or “free_form”
order_index string The order of the question within the questionnaire or category such as “1”, “2”, “3”
document string A reference link to a document related to the question
image string A reference link to an image associated with the question
weight float The weight of the question as a percentage of the total questionnaire if each question does not contribute equally when calculating the final “score”; ex. 20 representing 20%.
tooltip string A tooltip to display on the UI explaining the question
is_account boolean Indicates if the question is answered at an account-level
      answers array Possible answers to the question such as multiple choice options
            id string The id of the answer option
            value string Value for the answer option
            order_index string The order of the answer option within the question or category such as “1”, “2”, “3”
            label string A label to be assigned to the answer option for data labeling purposes
            image string A reference link to an image associated with the answer option
            weight float The weight of the answer option as a percentage or value of the total questionnaire score if each answer does not contribute equally when calculating the final “score”; ex. 20 representing 20% or 20 points
            tooltip string A tooltip to display on the UI explaining the answer
            is_default boolean Indicates the default answer to a question in a questionnaire when the UI is displayed to a user. Defaults to false
            metadata map Custom information associated with the answer option in the format key:value. See Metadata
metadata map Custom information associated with the question in the format key:value. See Metadata
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

List all questions

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/question"

Example Response

{
    "content": [
        {
          "id": "df392582-514f-486b-b15b-fecba66a104f",
          "create_date": "2018-01-02T21:56:03.000+0000",
          "update_date": "2018-01-02T21:56:03.000+0000",
          "title": "What is your age?",
          "description": null,
          "category": "Onboarding",
          "subcategory": "Basic",
          "question_type": "free_form",
          "order_index": "1",
          "document": null,
          "image": "http://domain.com/age_graphic.pdf",
          "tooltip": null,
          "weight": null,
          "is_account": false,
          "answers": [
            {
              "id": "d31c694f-bcb5-427f-b081-91e64e90229a",
              "value": ">40",
              "order_index": 2,
              "image": "http://domain.com/age_graphic1.pdf",
              "label": null,
              "weight": null,
              "tooltip": null,
              "is_default": false,
              "metadata": {}
            },
            {
              "id": "1e52401f-bfec-410b-bca1-afa5f0be37b5",
              "value": "0-40",
              "order_index": 1,
              "image": "http://domain.com/age_graphic2.pdf",
              "label": null,
              "weight": null,
              "tooltip": null,
              "is_default": false,
              "metadata": {}
            }
          ],
          "metadata": {},
          "secondary_id": null
        },
        {
          "id": "65fabce6-c7a3-464c-99a2-717008f4acfe",
          "create_date": "2018-01-01T21:56:03.000+0000",
          "update_date": "2018-01-15T21:56:03.000+0000",
          "title": "What is your annual income in dollars?",
          "description": null,
          "category": "Onboarding",
          "subcategory": "Basic",
          "question_type": "monetary_input",
          "order_index": "2",
          "weight": null,
          "tooltip": null,
          "is_account": false,
          "answers": [
            {
              "id": "7d8de5fa-6174-4a30-9e70-8e638a3d5304",
              "value": ">100,000",
              "order_index": 2,
              "image": "http://domain.com/income_graphic1.pdf",
              "label": "Mass Affluent",
              "weight": null,
              "tooltip": null,
              "is_default": false,
              "metadata": {}
            },
            {
              "id": "0ffe04ba-5db0-4a72-9fd1-2ba9479e685a",
              "value": "0-100,000",
              "order_index": 1,
              "image": "http://domain.com/income_graphic2.pdf",
              "label": "Retail",
              "weight": null,
              "tooltip": null,
              "is_default": false,
              "metadata": {}
            }
            ],
          "metadata": {},
          "secondary_id": null
        }
      ],
        "last": true,
        "total_pages": 1,
        "total_elements": 2,
        "number_of_elements": 2,
        "first": true,
        "sort": [
            {
                "direction": "DESC",
                "property": "updateDate",
                "ignore_case": false,
                "null_handling": "NATIVE",
                "ascending": false,
                "descending": true
            }
        ],
        "size": 25,
        "number": 0
}

Get the information for all questions defined for your firm. You can filter using a questionnaire_id to view the questions associated with a specific questionnaire. To obtain the appropriate questionnaire_id, use the GET /questionnaire endpoint to view all questionnaire defined for your firm.

HTTP REQUEST

GET /question

Create a question

Example Request

curl -X POST -H "Authorization: Bearer <access_token>"
     -H "Content-Type: application/json"
     -d '{
            "title": "What is your age?",
            "category": "Onboarding",
            "subcategory": "Basic",
            "question_type": "free_form",
            "order_index": "1",
            "image": "http://domain.com/age_graphic.pdf"
      }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/question"

Example Response

{
    "id": "29fa5156-cd89-4056-9125-ce2428b05f11",
    "create_date": "2018-01-01T21:56:03.000+0000",
    "update_date": "2018-01-15T21:56:03.000+0000",
    "title": "What is your age?",
    "description": null,
    "category": "Onboarding",
    "subcategory": "Basic",
    "question_type": "free_form",
    "order_index": "1",
    "document": null,
    "image": "http://domain.com/age_graphic.pdf",
    "weight": null,
    "tooltip": null,
    "is_account": false,
    "answers": [],
    "metadata": {},
    "secondary_id": null
}

Create a new question for your firm. A questionnaire_id must be provided. The endpoint returns a question_id to manage the question.

HTTP REQUEST

POST /question

ARGUMENTS

Parameter Type Required Description
questionnaire_id UUID required The id of the questionnaire this question belongs to. All questions can only be attached to one questionnaire at a time.
title string required Title for the question such as the body of the question or a header. Pairs with the description field
description string optional Description for the question such as additional question content. Pairs with the title field
category string optional A category for the question such as “Onboarding” or “Risk Profile”
subcategory string optional A subcategory for the question such as “Income-related”
question_type string optional The type of question structure such as “multiple_choice” or “free_form”
order_index string optional The order of the question within the questionnaire or category such as “1”, “2”, “3”
document string optional A reference link to a document related to the question
image string optional A reference link to an image associated with the question
weight float optional The weight of the question as a percentage of the total questionnaire if each question does not contribute equally when calculating the final “score”; ex. 20 representing 20%.
tooltip string optional A tooltip to display on the UI explaining the question
is_account boolean optional Indicates if the question is answered at an account-level
metadata map optional Custom information associated with the question in the format key:value. See Metadata
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Retrieve a question

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/question/29fa5156-cd89-4056-9125-ce2428b05f11"

Example Response

{
    "id": "df392582-514f-486b-b15b-fecba66a104f",
    "create_date": "2018-01-01T21:56:03.000+0000",
    "update_date": "2018-01-15T21:56:03.000+0000",
    "title": "What is your age?",
    "description": null,
    "category": "Onboarding",
    "subcategory": "Basic",
    "question_type": "free_form",
    "order_index": "1",
    "document": null,
    "image": "http://domain.com/age_graphic.pdf",
    "weight": null,
    "tooltip": null,
    "is_account": false,
    "answers": [
      {
        "id": "d31c694f-bcb5-427f-b081-91e64e90229a",
        "value": ">40",
        "order_index": 2,
        "image": "http://domain.com/age_graphic1.pdf",
        "label": null,
        "weight": null,
        "tooltip": null,
        "is_default": false,
        "metadata": {}
      },
      {
        "id": "1e52401f-bfec-410b-bca1-afa5f0be37b5",
        "value": "0-40",
        "order_index": 1,
        "image": "http://domain.com/age_graphic2.pdf",
        "label": null,
        "weight": null,
        "tooltip": null,
        "is_default": false,
        "metadata": {}
      }
    ],
    "metadata": {},
    "secondary_id": null
}

Retrieve the information for a question for your firm. The question_id must be provided. The endpoint returns the question_id and the details for the question specified, along with any answers that have been assigned to the question.

HTTP REQUEST

GET /question/{question_id}

Update a question

Example Request

curl -X PUT -H "Authorization: Bearer <access_token>"
    -H "Content-Type: application/json"
    -d '{
          "title": "How old are you?"
      }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/question/29fa5156-cd89-4056-9125-ce2428b05f11"

Example Response

{
    "id": "df392582-514f-486b-b15b-fecba66a104f",
    "create_date": "2018-01-01T21:56:03.000+0000",
    "update_date": "2018-01-15T21:56:03.000+0000",
    "title": "How old are you?",
    "description": null,
    "category": "Onboarding",
    "subcategory": "Basic",
    "question_type": "free_form",
    "order_index": "1",
    "document": null,
    "image": "http://domain.com/age_graphic.pdf",
    "weight": null,
    "tooltip": null,
    "is_account": false,
    "answers": [
      {
        "id": "d31c694f-bcb5-427f-b081-91e64e90229a",
        "value": ">40",
        "order_index": 2,
        "image": "http://domain.com/age_graphic1.pdf",
        "label": null,
        "weight": null,
        "tooltip": null,
        "is_default": false,
        "metadata": {}
      },
      {
        "id": "1e52401f-bfec-410b-bca1-afa5f0be37b5",
        "value": "0-40",
        "order_index": 1,
        "image": "http://domain.com/age_graphic2.pdf",
        "label": null,
        "weight": null,
        "tooltip": null,
        "is_default": false,
        "metadata": {}
      }
    ],
    "metadata": {},
    "secondary_id": null
}

Update a question for your firm. The question_id must be provided in the URL. To obtain the appropriate question_id, use the GET /question endpoint to view all questions for your firm and their current information. The endpoint returns the question_id and the details for the question.

HTTP REQUEST

PUT /question/{question_id}

Delete a question

Example Request

curl -X DELETE -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/question/429fa5156-cd89-4056-9125-ce2428b05f11"

Response (204 No Content)

Permanently delete a question for your firm. The question_id must be provided. To obtain the appropriate question_id, use the GET /question endpoint to view all questions for your firm. This deletes the question_id and the details for the question.

HTTP REQUEST

DELETE /question/{question_id}

Answer

Answers can be created and attached to a question_id using the service below.

Field Type Description
id UUID The id of the answer
question_id UUID The id of the question this answer belongs to. All answers can only be attached to one question at a time.
value string Value for the answer option
order_index string The order of the answer option within the question or category such as “1”, “2”, “3”
label string A label to be assigned to the answer option for data labeling purposes
image string A reference link to an image associated with the answer option
weight float The weight of the answer option as a percentage or value of the total questionnaire score if each answer does not contribute equally when calculating the final “score”; ex. 20 representing 20% or 20 points
tooltip string A tooltip to display on the UI explaining the answer
is_default boolean Indicates the default answer to a question in a questionnaire when the UI is displayed to a user. Defaults to false
metadata map Custom information associated with the question in the format key:value. See Metadata
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

List all answers

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/answer"

Example Response

{
    "content": [
      {
          "id": "d31c694f-bcb5-427f-b081-91e64e90229a",
          "value": ">40",
          "image": "http://domain.com/age_graphic1.pdf",
          "label": null,
          "weight": null,
          "tooltip": null,
          "is_default": false,
          "metadata": {}
      },
      {
          "id": "1e52401f-bfec-410b-bca1-afa5f0be37b5",
          "value": "0-40",
          "image": "http://domain.com/age_graphic2.pdf",
          "label": null,
          "weight": null,
          "tooltip": null,
          "is_default": false,
          "metadata": {}
      }
    ],
    "last": true,
    "total_pages": 1,
    "total_elements": 2,
    "number_of_elements": 2,
    "first": true,
    "sort": [
        {
            "direction": "DESC",
            "property": "updateDate",
            "ignore_case": false,
            "null_handling": "NATIVE",
            "ascending": false,
            "descending": true
        }
    ],
    "size": 25,
    "number": 0
}

Get the information for all answers defined for your firm. You can filter using a question_id to view the answers associated with a specific question. To obtain the appropriate question_id, use the GET /question endpoint to view all questions defined for your firm.

HTTP REQUEST

GET /answer

Create an answer

Example Request

curl -X POST -H "Authorization: Bearer <access_token>"
     -H "Content-Type: application/json"
     -d '{
            "title": "What is your age?",
            "category": "Onboarding",
            "subcategory": "Basic",
            "question_type": "free_form",
            "order_index": "1",
            "image": "http://domain.com/age_graphic.pdf"
      }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/question"

Example Response

{
    "id": "29fa5156-cd89-4056-9125-ce2428b05f11",
    "create_date": "2018-01-01T21:56:03.000+0000",
    "update_date": "2018-01-15T21:56:03.000+0000",
    "title": "What is your age?",
    "description": null,
    "category": "Onboarding",
    "subcategory": "Basic",
    "question_type": "free_form",
    "order_index": "1",
    "document": null,
    "image": "http://domain.com/age_graphic.pdf",
    "weight": null,
    "tooltip": null,
    "is_account": false,
    "metadata": {},
    "secondary_id": null,
    "answers": []
}

Create a new answer for your firm. A question_id must be provided. The endpoint returns a answer_id to manage the question.

HTTP REQUEST

POST /answer

ARGUMENTS

Parameter Type Required Description
question_id UUID required The id of the question this answer belongs to. All answers can only be attached to one question at a time.
value string required Value for the answer option
order_index string optional The order of the answer option within the question or category such as “1”, “2”, “3”
label string optional A label to be assigned to the answer option for data labeling purposes
image string optional A reference link to an image associated with the answer option
weight float optional The weight of the answer option as a percentage or value of the total questionnaire score if each answer does not contribute equally when calculating the final “score”; ex. 20 representing 20% or 20 points
tooltip string optional A tooltip to display on the UI explaining the answer
is_default boolean optional Indicates the default answer to a question in a questionnaire when the UI is displayed to a user. Defaults to false
metadata map optional Custom information associated with the question in the format key:value. See Metadata
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Retrieve an answer

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/answer/29fa5156-cd89-4056-9125-ce2428b05f11"

Example Response

{
    "id": "d31c694f-bcb5-427f-b081-91e64e90229a",
    "value": ">40",
    "image": "http://domain.com/age_graphic1.pdf",
    "label": null,
    "weight": null,
    "tooltip": null,
    "is_default": false,
    "metadata": {}
}

Retrieve the information for an answer for your firm. The answer_id must be provided. The endpoint returns the answer_id and the details for the answer specified.

HTTP REQUEST

GET /answer/{answer_id}

Update an answer

Example Request

curl -X PUT -H "Authorization: Bearer <access_token>"
    -H "Content-Type: application/json"
    -d '{
          "title": "How old are you?"
      }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/answer/29fa5156-cd89-4056-9125-ce2428b05f11"

Example Response

{
    "id": "d31c694f-bcb5-427f-b081-91e64e90229a",
    "value": ">40",
    "image": "http://domain.com/age_graphic1.pdf",
    "label": null,
    "weight": null,
    "tooltip": null,
    "is_default": false,
    "metadata": {}
}

Update an answer for your firm. The answer_id must be provided in the URL. To obtain the appropriate answer_id, use the GET /answer endpoint to view all answers for your firm and their current information. The endpoint returns the answer_id and the details for the answer.

HTTP REQUEST

PUT /answer/{answer_id}

Delete an answer

Example Request

curl -X DELETE -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/answer/429fa5156-cd89-4056-9125-ce2428b05f11"

Response (204 No Content)

Permanently delete an answer for your firm. The answer_id must be provided. To obtain the appropriate answer_id, use the GET /answer endpoint to view all answers for your firm. This deletes the answer_id and the details for the answer.

HTTP REQUEST

DELETE /answer/{answer_id}

Risk Profile

This entity allows the user to store risk profile entities such as “Conservative”, “Moderate”, “Aggressive” and attached each profile to a min and max risk score.

Field Type Description
id UUID The id of the risk profile
name string The name of the risk profile
client_id UUID The ID of the client the risk profile belongs to, used for custom risk profiles of advisors at your firm
category string The category of the risk profile to group common profiles
description string The description of the risk profile
risk_score_min double The minimum risk score this profile is assigned to
risk_score_max double The maximum risk score this profile is assigned to
metadata map Custom information associated with the risk profile in the format key:value
See Metadata
secondary_id string Alternate id that can be used to identify the risk profile such as an internal id
create_date timestamp Timestamp for the date and time that the risk profile was created
update_date timestamp Timestamp for the date and time that the risk profile was last updated

List all risk profiles

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/risk_profile"

Example Response

{
    "content": [
        {
            "id": "ce77358c-1e00-4e75-8deb-bd35c4ad8e65",
            "name": "Conservative",
            "client_id": null,
            "category": null,
            "description": null,
            "risk_score_min": 20,
            "risk_score_max": 40,
            "metadata": {},
            "create_date": "2019-07-16T20:06:03.000+0000",
            "update_date": "2019-08-09T21:09:38.000+0000"
        },
        {
            "id": "c31322b7-f363-478f-93da-56994d08996e",
            "name": "Aggressive",
            "client_id": null,
            "category": null,
            "description": null,
            "risk_score_min": 80,
            "risk_score_max": 100,
            "metadata": {},
            "create_date": "2019-07-16T20:06:03.000+0000",
            "update_date": "2019-08-09T21:09:38.000+0000"
        }
    ],
    "total_pages": 1,
    "total_elements": 2,
    "last": false,
    "number_of_elements": 25,
    "first": true,
    "sort": [
        {
            "direction": "DESC",
            "property": "updateDate",
            "ignore_case": false,
            "null_handling": "NATIVE",
            "descending": true,
            "ascending": false
        }
    ],
    "size": 25,
    "number": 0
}

Get details for all risk profiles created within your firm or filter for a specific client_id.

HTTP REQUEST

GET /risk_profile

Create a risk profile

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d '{
            "name": "Conservative",
            "risk_score_min": 20,
            "risk_score_max": 40
        }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/risk_profile"

Example Response

{
    "id": "ce77358c-1e00-4e75-8deb-bd35c4ad8e65",
    "name": "Conservative",
    "client_id": null,
    "category": "",
    "description": null,
    "risk_score_min": 20,
    "risk_score_max": 40,
    "metadata": {},
    "create_date": "2019-07-16T20:06:03.000+0000",
    "update_date": "2019-08-09T21:09:38.000+0000"
}

Create a new risk profile for your firm. For custom risk profiles used by advisors in your firm, add a client_id to the profile. To assign a risk profile to a Client or Account and track over time, use the Score service. The create_date will default to the current date. The endpoint returns a unique risk_profile_id that is used to manage the specific risk profile and referenced in other endpoints.

HTTP REQUEST

POST /risk_profile

ARGUMENTS

Parameter Type Required Description
name string required The name of the risk profile
client_id UUID optional The ID of the client the risk profile belongs to, used for custom risk profiles of advisors at your firm
category string optional The category of the risk profile to group common profiles
description string optional The description of the risk profile
risk_score_min double optional The minimum risk score this profile is assigned to
risk_score_max double optional The maximum risk score this profile is assigned to
metadata map optional Custom information associated with the risk profile in the format key:value
See Metadata
secondary_id string optional Alternate id that can be used to identify the risk profile such as an internal id

Retrieve a risk profile

Retrieve the information for a risk profile. The unique risk_profile_id must be provided. The endpoint returns the risk_profile_id and the details for the risk profile.

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/risk_profile/ce77358c-1e00-4e75-8deb-bd35c4ad8e65"

Example Response

{
    "id": "ce77358c-1e00-4e75-8deb-bd35c4ad8e65",
    "name": "Conservative",
    "client_id": null,
    "category": "",
    "description": null,
    "risk_score_min": 20,
    "risk_score_max": 40,
    "metadata": {},
    "create_date": "2019-07-16T20:06:03.000+0000",
    "update_date": "2019-08-09T21:09:38.000+0000"
}

HTTP REQUEST

GET /risk_profile/{risk_profile_id}

Update a risk profile

Example Request

curl -X PUT -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d '{
            "risk_score_min": 25
        }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/risk_profile/ce77358c-1e00-4e75-8deb-bd35c4ad8e65"

Example Response

{
    "id": "ce77358c-1e00-4e75-8deb-bd35c4ad8e65",
    "name": "Conservative",
    "client_id": null,
    "category": "",
    "description": null,
    "risk_score_min": 25,
    "risk_score_max": 40,
    "metadata": {},
    "create_date": "2019-07-16T20:06:03.000+0000",
    "update_date": "2019-08-09T21:09:38.000+0000"
}

Update the information for a risk profile. The unique risk_profile_id must be provided. To obtain the appropriate risk_profile_id, use the GET /risk_profile endpoint to view all available risk_profile_ids and their current information. The details to be updated must also be provided. The endpoint returns the risk_profile_id and the details for the risk profile.

HTTP REQUEST

PUT /risk_profile/{risk_profile_id}

Delete a risk profile

Example Request

curl -X DELETE -H "Authorization: Bearer ce77358c-1e00-4e75-8deb-bd35c4ad8e65" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/risk_profile/c31322b7-f363-478f-93da-56994d08996e"

Response (204 No Content)

Permanently delete a risk profile. The unique risk_profile_id must be provided. To obtain the appropriate risk_profile_id, use the GET /risk_profile endpoint to view all available risk_profile_ids. This deletes the risk_profile_id and all the profile information associated with it.

HTTP REQUEST

DELETE /risk_profile/{risk_profile_id}

Score

Score is used to store scores referenced within the application. Scores may be either calculated using the Proton API or obtained from an alternate source. Scores can be stored for key entities including clients, accounts, goals, portfolios, allocations, models, benchmarks and securities. Score types that can be stored include:

1) Risk Score
2) Dimensional Risk Score
3) Diversification Score
4) Portfolio Optimization Score
5) Goal Achievement Score
6) Credit Score
7) Risk Profile

Field Type Description
id UUID The id for the score
score_type string The type of score. Values may be risk_score, dimensional_risk_score, diversification_score, portfolio_optimization_score, goal_achievement_score, credit_score, or risk_profile
score_value string The value of the score, which may be a number, a label, etc.
client_id UUID The id of a client to which the score applies (if client-specific)
account_id UUID The id of an account to which the score applies (if account-specific)
portfolio_id UUID The id of a portfolio to which the score applies (if portfolio-specific)
goal_id UUID The id of a goal to which the score applies (if goal-specific)
allocation_id UUID The id of an allocation to which the score applies (if allocation-specific)
model_id UUID The id of a model to which the score applies (if model-specific)
benchmark_id UUID The id of a benchmark to which the score applies (if benchmark-specific)
security_id UUID The id of a security to which the score applies (if security-specific)
score_time_stamp datetime Date and time for the score
metadata map Custom information associated with the score in the format key:value
See Metadata
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

List all scores

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
  "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/score"

Example Response

{
    "content": [
        {
            "id": "739ecd39-e1ae-4a0b-b266-dd3ddc616163",
            "create_date": "2018-11-01T00:00:00.000+0000",
            "score_type": "risk_score",
            "score_value": "76",
            "client_id": "58f90162-1bd7-4441-a1f2-cbaa4b2e3595",
            "score_time_stamp": "2018-11-01T00:00:00.000+0000",
            "metadata": {
                "questionnaire": "Risk Profile Questionnaire"
            }
        },
        {
            "id": "4675770f-e52b-46e2-ac4b-683adbeb034c",
            "create_date": "2017-01-01T00:00:00.000+0000",
            "score_type": "risk_score",
            "score_value": "85",
            "model_id": "89a510ad-e817-49a3-9af2-0fb59487d9ad",
            "score_time_stamp": "2017-01-01T00:00:00.000+0000",
            "metadata": {}
        }
        {
            "id": "c0b33394-998c-4095-ad98-22551f7dbb1f",
            "create_date": "2018-11-01T00:00:00.000+0000",
            "score_type": "risk_profile",
            "score_value": "Conservative",
            "client_id": "c17cd2e1-5ecc-48e0-8f7c-5cecd9055429",
            "score_time_stamp": "2018-11-01T00:00:00.000+0000",
            "metadata": {
                "questionnaire": "Risk Profile Questionnaire"
            }
        }
    ],
    "last": false,
    "total_pages": 1,
    "total_elements": 3,
    "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 information for all scores stored for your firm. You can filter using one of the unique ids such as the client_id to view the scores for a client or for another particular entity. You can also filter by the value provided for score_time_stamp to find the scores for a specific date or date range. Note that the metadata information for the score is stored as a nested object within the score object.

HTTP REQUEST

GET /score

Create a score

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
          "score_type": "risk_score",
          "score_value": "76",
          "client_id": "58f90162-1bd7-4441-a1f2-cbaa4b2e3595",
          "score_time_stamp": "2018-11-01T00:00:00.000+0000",
          "metadata": {
              "questionnaire": "Risk Profile Questionnaire"
          }
    }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/score"

Example Response

{
    "id": "739ecd39-e1ae-4a0b-b266-dd3ddc616163",
    "create_date": "2018-11-01T00:00:00.000+0000",
    "score_type": "risk_score",
    "score_value": "76",
    "client_id": "58f90162-1bd7-4441-a1f2-cbaa4b2e3595",
    "score_time_stamp": "2018-11-01T00:00:00.000+0000",
    "metadata": {
        "questionnaire": "Risk Profile Questionnaire"
    }
}

Create a score for a client, account, goal, portfolio, allocation, model, benchmark or security. The endpoint returns a score_id that can then be used to manage the score.

HTTP REQUEST

POST /score

ARGUMENTS

Parameter Type Required Description
score_type string required The type of score. Values may be risk_score, dimensional_risk_score, diversification_score, portfolio_optimization_score, goal_achievement_score, credit_score, or risk_profile
score_value string required The value of the score, which may be a number, a label, etc.
client_id UUID optional The id of a client to which the score applies (if client-specific)
account_id UUID optional The id of an account to which the score applies (if account-specific)
portfolio_id UUID optional The id of a portfolio to which the score applies (if portfolio-specific)
goal_id UUID optional The id of a goal to which the score applies (if goal-specific)
allocation_id UUID optional The id of an allocation to which the score applies (if allocation-specific)
model_id UUID optional The id of a model to which the score applies (if model-specific)
benchmark_id UUID optional The id of a benchmark to which the score applies (if benchmark-specific)
security_id UUID optional The id of a security to which the score applies (if security-specific)
score_time_stamp datetime optional Date and time for the score
metadata map optional Custom information associated with the score in the format key:value
See Metadata
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Retrieve a score

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/score/739ecd39-e1ae-4a0b-b266-dd3ddc616163"

Example Response

{
    "id": "739ecd39-e1ae-4a0b-b266-dd3ddc616163",
    "create_date": "2018-11-01T00:00:00.000+0000",
    "score_type": "risk_score",
    "score_value": "76",
    "client_id": "58f90162-1bd7-4441-a1f2-cbaa4b2e3595",
    "score_time_stamp": "2018-11-01T00:00:00.000+0000",
    "metadata": {
        "questionnaire": "Risk Profile Questionnaire"
    }
}

Retrieve the information for a specific score associated with a client, account, goal, portfolio, allocation, model, benchmark or security. The unique score_id must be provided. The endpoint returns the score_id and details for the score specified. Note that the metadata information for the score is stored as a nested object within the score object.

HTTP REQUEST

GET /score/{score_id}

Update a score

Example Request

curl -X PUT -H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
          "score_type": "risk_score",
          "score_value": "80",
          "client_id": "58f90162-1bd7-4441-a1f2-cbaa4b2e3595",
          "score_time_stamp": "2018-11-01T00:00:00.000+0000",
          "metadata": {
              "questionnaire": "Risk Profile Questionnaire"
          }
    }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/score/739ecd39-e1ae-4a0b-b266-dd3ddc616163"

Example Response

{
    "id": "739ecd39-e1ae-4a0b-b266-dd3ddc616163",
    "create_date": "2018-11-01T00:00:00.000+0000",
    "update_date": "2019-11-01T00:00:00.000+0000",
    "score_type": "risk_score",
    "score_value": "80",
    "client_id": "58f90162-1bd7-4441-a1f2-cbaa4b2e3595",
    "score_time_stamp": "2018-11-01T00:00:00.000+0000",
    "metadata": {
        "questionnaire": "Risk Profile Questionnaire"
    }
}

Update the information for a score. The unique score_id must be provided. To obtain the appropriate score_id, use the GET /score endpoint to view all scores stored for your firm and their current information. The details to be updated must also be provided. The endpoint returns the score_id and the details for the score.

HTTP REQUEST

PUT /score/{score_id}

Delete a score

Example Request

curl -X DELETE -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/score/739ecd39-e1ae-4a0b-b266-dd3ddc616163"

Response (204 No Content)

Permanently delete a score. The unique score_id must be provided. To obtain the appropriate score_id, use the GET /score endpoint to view all scores stored for your firm. This deletes the score_id and all score record information.

HTTP REQUEST

DELETE /score/{score_id}

Utils

Common utilities that are used in multiple account and client services.

Stage

Stages indicate what point an account or client is in along a user journey. The stage is often used to provide business insights into the progression through a sign up funnel to track metrics such as drop-off, acquisition cost, and churn.

Field Type Description
id UUID The id of the account stage
name string Name or label of the stage such as Pending Funding or Signed Up
category string Category of the stage to group stages together within a section of an app
description string Description of what the step along the registration process that the stage represents
order_index integer Indicator for where along the process the stage falls. Generally, the higher the order index, the further along the process
is_account boolean Indicates if the stage is for an account and used for tracking an Account Status. Defaults to false which indicates that it is not for an account
is_client boolean Indicates if the stage is for a client and used for tracking a Client Status. Defaults to false which indicates that it is not for a client
is_active boolean Indicates if the stage is active. Defaults to true which indicates that it is currently active.
metadata map Custom information associated with the entity in the format key:value
See Metadata
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

List all stages

Example Request

curl -X GET -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/stage"

Example Response

{
    "content": [
        {
            "id": "099961da-7f41-4309-950f-2b51689a0033",
            "create_date": "2018-02-08T16:59:27.000+0000",
            "update_date": "2018-02-08T16:59:27.000+0000",
            "name": "Started Application",
            "category": null,
            "order_index": 1,
            "is_account": true,
            "is_client": false,
            "is_active": true,
            "metadata": {},
            "secondary_id": null
        },
        {
            "id": "1d7e1aad-3c79-49fe-bbb9-bd5e239ae1e7",
            "create_date": "2018-02-08T16:59:27.000+0000",
            "update_date": "2018-02-08T16:59:27.000+0000",
            "name": "Customized Allocation",
            "category": null,
            "order_index": 2,
            "is_account": true,
            "is_client": false,
            "is_active": true,
            "metadata": {},
            "secondary_id": null
        },
        {
            "id": "2a7a6cb7-ef71-4fe8-9169-2678f3799657",
            "create_date": "2018-02-08T16:59:27.000+0000",
            "update_date": "2018-02-08T16:59:27.000+0000",
            "name": "Funding Submitted",
            "category": null,
            "order_index": 3,
            "is_account": true,
            "is_client": false,
            "is_active": true,
            "metadata": {},
            "secondary_id": null
        },
        {
            "id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
            "create_date": "2018-02-08T16:59:27.000+0000",
            "update_date": "2018-02-08T16:59:27.000+0000",
            "name": "Signed Up",
            "category": null,
            "order_index": 4,
            "is_account": true,
            "is_client": false,
            "is_active": true,
            "metadata": {},
            "secondary_id": null
        },
        {
            "id": "a65929b6-b0a9-46e5-858a-121f0b10f4fb",
            "create_date": "2018-02-08T16:59:27.000+0000",
            "update_date": "2018-02-08T16:59:27.000+0000",
            "name": "Application Accepted",
            "category": null,
            "order_index": 5,
            "is_account": true,
            "is_client": false,
            "is_active": true,
            "metadata": {},
            "secondary_id": null
        },
        {
            "id": "bab849d6-de96-4dc7-a5ea-19be45c52a4e",
            "create_date": "2018-02-08T16:59:27.000+0000",
            "update_date": "2018-02-08T16:59:27.000+0000",
            "name": "Funding in Progress",
            "category": null,
            "order_index": 6,
            "is_account": true,
            "is_client": false,
            "is_active": true,
            "metadata": {},
            "secondary_id": null
        },
        {
            "id": "e995d4c1-f989-4733-9867-713966ac9856",
            "create_date": "2018-02-08T16:59:27.000+0000",
            "update_date": "2018-02-08T16:59:27.000+0000",
            "name": "Funded & Awaiting Investment",
            "category": null,
            "order_index": 7,
            "is_account": true,
            "is_client": false,
            "is_active": true,
            "metadata": {},
            "secondary_id": null
        },
        {
            "id": "eb3d7f60-a133-4ca9-815f-3677bcdc23a3",
            "create_date": "2018-02-08T16:59:27.000+0000",
            "update_date": "2018-02-08T16:59:27.000+0000",
            "name": "Application Submitted",
            "category": null,
            "order_index": 8,
            "is_account": true,
            "is_client": false,
            "is_active": true,
            "metadata": {},
            "secondary_id": null
        },
        {
            "id": "fbc03484-08e8-446d-83aa-6d6cc236355e",
            "create_date": "2018-02-08T16:59:27.000+0000",
            "update_date": "2018-02-08T16:59:27.000+0000",
            "name": "Converted",
            "category": null,
            "order_index": 9,
            "is_account": true,
            "is_client": false,
            "is_active": true,
            "metadata": {},
            "secondary_id": null
        },
        {
            "id": "feb846da-a06d-402e-a3bb-abc7260f7138",
            "create_date": "2018-02-08T16:59:27.000+0000",
            "update_date": "2018-02-08T16:59:27.000+0000",
            "name": "Closed",
            "category": null,
            "order_index": 10,
            "is_account": true,
            "is_client": false,
            "is_active": true,
            "metadata": {},
            "secondary_id": null
        }
    ],
    "last": true,
    "total_pages": 1,
    "total_elements": 10,
    "sort": [
        {
            "direction": "DESC",
            "property": "updateDate",
            "ignore_case": false,
            "null_handling": "NATIVE",
            "descending": true,
            "ascending": false
        }
    ],
    "first": true,
    "number_of_elements": 10,
    "size": 25,
    "number": 0
}

Get the information for all possible account stages defined by your firm that can be assigned to accounts.

HTTP REQUEST

GET /stage

Create a stage

Example Request

curl -X POST -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
    -H "Content-Type: application/json" \
    -d '{
            "name": "Signed Up",
            "order_index": 1,
            "is_account": true
        }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/stage"

Example Response

{
    "id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
    "create_date": "2018-02-08T16:59:27.000+0000",
    "name": "Signed Up",
    "category": null,
    "order_index": 1,
    "is_account": true,
    "is_client": false,
    "is_active": true,
    "metadata": {},
    "secondary_id": null
}

Create and define an account stage that can subsequently be assigned to accounts. The name and description for the account stage must be provided. The endpoint returns the stage_id used to assign the stage to accounts.

HTTP REQUEST

POST /stage

ARGUMENTS

Parameter Type Required Description
name string required Name or label of the account stage such as “Pending Funding” or “Fully Funded”
category string optional Category of the stage to group stages together within a section of an app
description string optional Description of what the step along the registration process that the account stage represents
order_index integer optional Indicator for where along the process the account stage falls. Generally, the higher the order index, the further along the process
is_account boolean optional Indicates if the stage is for an account and used for tracking an Account Status. Defaults to false which indicates that it is not for an account
is_client boolean optional Indicates if the stage is for a client and used for tracking a Client Status. Defaults to false which indicates that it is not for a client
is_active boolean optional Indicates if the stage is active. Defaults to true which indicates that it is currently active.
metadata map optional Custom information associated with the entity in the format key:value
See Metadata
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Retrieve a stage

Example Request

curl -X GET -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/stage/647c54c3-b649-477e-8cc7-eee56a120dd3"

Example Response

{
    "id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
    "create_date": "2018-02-08T16:59:27.000+0000",
    "update_date": "2018-02-08T16:59:27.000+0000",
    "name": "Signed Up",
    "category": null,
    "order_index": 1,
    "is_account": true,
    "is_client": false,
    "is_active": true,
    "metadata": {},
    "secondary_id": null
}

Retrieve the information for a specific account stage that can be assigned to accounts. The unique stage_id must be provided. To obtain the appropriate stage_id, use the GET /stage endpoint to view all stages defined by your firm. The endpoint returns the account stage’s description and name.

HTTP REQUEST

GET /stage/{stage_id}

Update a stage

Example Request

curl -X PUT -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
    -H "Content-Type: application/json" \
    -d '{
            "name": "Signed Up",
            "description": "Initial information provided and client created",
            "order_index": 1
        }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/stage/647c54c3-b649-477e-8cc7-eee56a120dd3"

Example Response

{
    "id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
    "create_date": "2018-02-08T16:59:27.000+0000",
    "update_date": "2018-02-08T16:59:27.000+0000",
    "name": "Signed Up",
    "category": null,
    "description": "Initial information provided and client created",
    "order_index": 1,
    "is_account": true,
    "is_client": false,
    "is_active": true,
    "metadata": {},
    "secondary_id": null
}

Update the information for an account stage. The unique stage_id must be provided. To obtain the appropriate stage_id, use the GET /stage endpoint to view all stages defined by your firm and their current information. The stage’s new description and name must also be provided. The endpoint returns the stage_id and details for the account stage.

HTTP REQUEST

PUT /stage/{stage_id}

Delete a stage

Example Request

curl -X DELETE -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/stage/647c54c3-b649-477e-8cc7-eee56a120dd3"

Response (204 No Content)

Permanently delete an account stage. The unique stage_id must be provided. To obtain the appropriate stage_id, use the GET /stage endpoint to view all stages defined by your firm. This deletes the stage_id and the stage will no longer be able to be assigned to an account as their account status

HTTP REQUEST

DELETE /stage/{stage_id}

Transaction Code

Transaction codes are defined by your firm to identify the type of transaction for all transaction and order records. These codes should be pre-populated for your firm before performing any transactional related services and should match the codes that are expected by your back office. Examples of generic transactions codes include “Customer Payment” or “Cash Dividend”. Transaction codes also indicate whether a record is a buy transaction or a sell transaction for investment orders.

Field Type Description
id UUID The id of the transaction code
transaction_code string Code that identifies the transaction within your firm
transaction_code_description string Short description of the transaction code
transaction_type string Type of transaction code such as “Fee” or “Deposit”
category string Grouping of similar transaction codes
subcategory string Sub-grouping of similar transaction codes
is_buy boolean Indicates if the transaction is to buy securities. Defaults to false which means it is a sell transaction. Used for order generation and rebalancing of investment transactions. If a non-investment transaction then ignore this field.
metadata map Custom information associated with the entity in the format key:value
See Metadata
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

List all transaction codes

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/transaction_code"

Example Response

{
    "content": [
      {
        "id": "099961da-7f41-4309-950f-2b51689a0033",
        "secondary_id": null,
        "category": "Deposits",
        "is_buy": true,
        "subcategory": "Cash",
        "transaction_code": "CDEP",
        "transaction_code_description": "Client Deposits",
        "transaction_type": "Check Returned",
        "metadata": {}
      },
      {
        "id": "1d7e1aad-3c79-49fe-bbb9-bd5e239ae1e7",
        "secondary_id": null,
        "category": "Deposits",
        "is_buy": true,
        "subcategory": "Cash",
        "transaction_code": "CDEP",
        "transaction_code_description": "Client Deposits",
        "transaction_type": "Bill Pay",
        "metadata": {}
      },
      {
        "id": "2a7a6cb7-ef71-4fe8-9169-2678f3799657",
        "secondary_id": null,
        "category": "Deposits",
        "is_buy": true,
        "subcategory": "Cash",
        "transaction_code": "CDEP",
        "transaction_code_description": "Client Deposits",
        "transaction_type": "Wire Returned",
        "metadata": {}
      }
    ],
    "last": true,
    "total_pages": 1,
    "total_elements": 3,
    "sort": [
        {
            "direction": "DESC",
            "property": "",
            "ignore_case": false,
            "null_handling": "NATIVE",
            "descending": true,
            "ascending": false
        }
    ],
    "first": true,
    "number_of_elements": 17,
    "size": 25,
    "number": 0
}

Get the information for all transaction codes defined by your firm. The endpoint returns a list ids and details for each transaction code. You can use this endpoint to determine the appropriate transaction code to use when creating an order record.

HTTP REQUEST

GET /transaction_code

Create a transaction code

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -d '{
            "category": "Deposits",
            "is_buy": true,
            "subcategory": "Cash",
            "transaction_code": "CDEP",
            "transaction_code_description": "Client Deposits"
        }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/transaction_code"

Example Response

{
    "id": "099961da-7f41-4309-950f-2b51689a0033",
    "secondary_id": null,
    "category": "Deposits",
    "is_buy": true,
    "subcategory": "Cash",
    "transaction_code": "CDEP",
    "transaction_code_description": "Client Deposits",
    "transaction_type": "Check Returned",
    "metadata": {}
}

Create a new transaction code for your firm. You must provide the details for the transaction code, including the indicator for whether or not it represents a buy transaction which is used when carrying out orders. The endpoint returns a unique identifier for the transaction code that can be referenced when creating order records.

HTTP REQUEST

POST /transaction_code

ARGUMENTS

Parameter Type Required Description
transaction_code string required Code that identifies the transaction within your firm
transaction_code_description string optional Short description of the transaction code
transaction_type string optional Type of transaction code such as “Fee” or “Deposit”
category string optional Grouping of similar transaction codes
subcategory string optional Sub-grouping of similar transaction codes
is_buy boolean optional Indicates if the transaction is to buy securities. Defaults to false which means it is a sell transaction. Used for order generation and rebalancing of investment transactions. If a non-investment transaction then ignore this field.
metadata map optional Custom information associated with the entity in the format key:value
See Metadata
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Retrieve a transaction code

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/transaction_code/099961da-7f41-4309-950f-2b51689a0033"

Example Response

{
    "id": "099961da-7f41-4309-950f-2b51689a0033",
    "secondary_id": null,
    "category": "Deposits",
    "is_buy": true,
    "subcategory": "Cash",
    "transaction_code": "CDEP",
    "transaction_code_description": "Client Deposits",
    "transaction_type": "Check Returned",
    "metadata": {}
}

Retrieve the information for a transaction code defined by your firm. The trasancation_code_id must be provided. The endpoint returns the details for the transaction code specified.

HTTP REQUEST

GET /transaction_code/{transaction_code_id}

Update a transaction code

Example Request

curl -X PUT -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -d '{
            "category": "Deposits",
            "is_buy": true,
            "subcategory": "Cash",
            "transaction_code": "CDEP-1",
            "transaction_code_description": "Client Deposits",
            "transaction_type": "Check Returned"
        }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/transaction_code/099961da-7f41-4309-950f-2b51689a0033"

Example Response

{
    "id": "099961da-7f41-4309-950f-2b51689a0033",
    "secondary_id": null,
    "category": "Deposits",
    "is_buy": true,
    "subcategory": "Cash",
    "transaction_code": "CDEP-1",
    "transaction_code_description": "Client Deposits",
    "transaction_type": "Check Returned",
    "metadata": {}
}

Update a transaction code for your firm. The transaction_code_id must be provided. To obtain the appropriate transaction_code_id, use the GET /transaction_code endpoint to view all the transaction codes defined for your firm and their current information. The details to be updated must also be provided. The endpoint returns the transaction_code_id and all details for the transaction code.

HTTP REQUEST

PUT /transaction_code/{transaction_code_id}

Delete a transaction code

Example Request

curl -X DELETE -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/transaction_code/099961da-7f41-4309-950f-2b51689a0033"

Response (204 No Content)

Permanently delete a transaction code for your firm. The transaction_code_id must be provided. To obtain the appropriate transaction_code_id, use the GET /transaction_code endpoint to view all the transaction codes defined for your firm. Deletes the transaction_code_id and the transaction code information so that it can no longer be assigned to order records.

HTTP REQUEST

DELETE /transaction_code/{transaction_code_id}

Banking & Wealth

Allocation

Allocation Management

Allocations are a collection of models to which accounts can subscribe. An account may be subscribed to one or more allocations. An allocation may have one or more accounts subscribing to it. For goals based investing/savings, an allocation may map to one goal. Allocations can also map to the nodes of a decision tree to determine which allocation(s) is/are most appropriate for an account.

Field Type Description
id UUID The id of the allocation
name string Name of the allocation
category string Category of the allocation used to group similar allocations
description string Description of the allocation
client_id UUID If the allocation is to be used by a specific client such as an advisor, the id of the client
benchmark_id UUID The id for the benchmark that the allocation should be compared to
inception_date date Date that the allocation first was managed
node_map array List of nodes in a decision tree that map to the allocation
      node_id UUID The id of the last node in the branch of a decision tree that maps to the allocation
metadata map Custom information associated with the allocation in the format key:value. See Metadata
is_active boolean Indicates if this allocation is active. Defaults to true which indicates it is active.
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

PROTON API

The following fields may optionally be used in conjunction with the Proton API. These are usually calculated via an overnight process.

Field Type Description
performance double Historical performance for the allocation, used as an input for simulations.
volatility double Historical volatility for the allocation, used as an input for simulations.

List all allocations

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
  "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/allocation"

Example Response

{
"content": [
    {
        "id": "04907eaa-3f33-49be-a35b-378cdf639fba",
        "category": "Alternative",
        "description": "Venture Fund I, L.P. gives accredited clients the ability to invest in the stock of private companies in the consumer, enterprise, retail, restaurant, and other high growth fields. There is no minimum investment and no management fee or carry charged.",
        "is_active": true,
        "name": "Venture Fund I, L.P.",
        "volatility": 0.054,
        "performance": 0.083,
        "node_map": [],
        "metadata": {}
    },
    {
        "id": "073def0e-6fa0-4e52-badb-6ff2aecbc2b2",
        "category": "Asset Allocation",
        "description": "",
        "is_active": true,
        "name": "Retirement Core 5",
        "volatility": 0.045,
        "performance": 0.078,
        "node_map": [],
        "metadata": {}
    },
    {
        "id": "013380bf-7f17-44c1-93c5-892a7ed3498c",
        "create_date": "2017-02-14T00:00:00.000+0000",
        "update_date": "2017-02-15T09:00:00.000+0000",
        "category": "Social",
        "description": "Dynamically managed diversified socially responsible ETF strategy allocated to U.S. Equities and tax-exempt Fixed Income. The strategy is tailored to investors with a very low risk tolerance, and aims to preserve capital with low turnover.",
        "is_active": true,
        "name": "Tax-Efficient SRI Core 2",
        "volatility": 0.0859,
        "performance": 0.0572,
        "node_map": [
            {
                "node_id": "5aafb611-bae9-481c-9da0-03044af09a7a"
            },
            {
                "node_id": "360baaa9-be8b-4463-bdae-974775cd894f"
            },
            {
                "node_id": "b530b536-4f99-45d3-bdbc-4729992868dc"
            }
        ],
        "metadata": {}
    }
  ],
  "last": true,
  "total_pages": 1,
  "total_elements": 2,
  "first": true,
  "sort": [
    {
        "direction": "DESC",
        "property": "id",
        "ignore_case": false,
        "null_handling": "NATIVE",
        "ascending": false,
        "descending": true
    }
  ],
  "number_of_elements": 2,
  "size": 2,
  "number": 0
}

Get details for all allocations defined for your firm. Note that the decision tree nodes and metadata information are stored as nested objects within the allocation object.

HTTP REQUEST

GET /allocation

Create an allocation

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
    -d '{
            "category": "Social",
            "description": "Dynamically managed diversified socially responsible ETF strategy allocated to U.S. Equities and tax-exempt Fixed Income. The strategy is tailored to investors with a very low risk tolerance, and aims to preserve capital with low turnover.",
            "is_active": true,
            "name": "Tax-Efficient SRI Core 2",
            "volatility": 0.0859,
            "performance": 0.0572,
            "node_map": [
                {
                    "node_id": "5aafb611-bae9-481c-9da0-03044af09a7a"
                },
                {
                    "node_id": "360baaa9-be8b-4463-bdae-974775cd894f"
                },
                {
                    "node_id": "b530b536-4f99-45d3-bdbc-4729992868dc"
                }
            ],
            "metadata": {}
        }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/allocation"

Example Response

{
    "id": "013380bf-7f17-44c1-93c5-892a7ed3498c",
    "create_date": "2017-02-14T00:00:00.000+0000",
    "category": "Social",
    "description": "Dynamically managed diversified socially responsible ETF strategy allocated to U.S. Equities and tax-exempt Fixed Income. The strategy is tailored to investors with a very low risk tolerance, and aims to preserve capital with low turnover.",
    "is_active": true,
    "name": "Tax-Efficient SRI Core 2",
    "volatility": 0.0859,
    "performance": 0.0572,
    "node_map": [
        {
            "node_id": "5aafb611-bae9-481c-9da0-03044af09a7a"
        },
        {
            "node_id": "360baaa9-be8b-4463-bdae-974775cd894f"
        },
        {
            "node_id": "b530b536-4f99-45d3-bdbc-4729992868dc"
        }
    ],
    "metadata": {}
}

Create a new allocation for your firm. The endpoint returns the allocation_id used to manage the allocation and to map an account to the allocation.

HTTP REQUEST

POST /allocation

ARGUMENTS

Parameter Type Required Description
name string required Name of the allocation
category string optional Category for the allocation used to group similar allocations
description string optional Description of the allocation
client_id UUID optional If the allocation is to be used by a specific client such as an advisor, the id of the client
benchmark_id UUID optional The id for the benchmark that the allocation should be compared to
inception_date date optional Date that the allocation first was managed
node_map array optional List of nodes in a decision tree that map to the allocation
      node_id UUID required The id of the last node in the branch of a decision tree that maps to the allocation
metadata map optional Custom information associated with the allocation in the format key:value. See Metadata
is_active boolean optional Indicator if this allocation is active. Default is true which indicates it is active
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

PROTON API ARGUMENTS

The following fields may be optionally used in conjunction with the Proton API.

Field Type Required Description
performance double optional Historical performance for the allocation, used as an input for simulations.
volatility double optional Historical volatility for the allocation, used as an input for simulations.

Retrieve an allocation

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/allocation/013380bf-7f17-44c1-93c5-892a7ed3498c"
}

Example Response

{
    "id": "013380bf-7f17-44c1-93c5-892a7ed3498c",
    "create_date": "2017-02-14T00:00:00.000+0000",
    "update_date": "2017-02-15T09:00:00.000+0000",
    "category": "Social",
    "description": "Dynamically managed diversified socially responsible ETF strategy allocated to U.S. Equities and tax-exempt Fixed Income. The strategy is tailored to investors with a very low risk tolerance, and aims to preserve capital with low turnover.",
    "is_active": true,
    "name": "Tax-Efficient SRI Core 2",
    "volatility": 0.0859,
    "performance": 0.0572,
    "node_map": [
        {
            "node_id": "5aafb611-bae9-481c-9da0-03044af09a7a"
        },
        {
            "node_id": "360baaa9-be8b-4463-bdae-974775cd894f"
        },
        {
            "node_id": "b530b536-4f99-45d3-bdbc-4729992868dc"
        }
    ],
    "metadata": {}
}

Retrieve the information for an allocation defined by your firm. The allocation_id must be provided. The endpoint returns the allocation_id and the details for the allocation specified.

HTTP REQUEST

GET /allocation/{allocation_id}

Update an allocation

HTTP REQUEST

Example Request

curl -X PUT -H "Authorization: Bearer <access_token>" \
    -d '{
            "category": "Social",
            "description": "Dynamically managed diversified socially responsible ETF strategy allocated to U.S. Equities and tax-exempt Fixed Income. The strategy is tailored to investors with a very low risk tolerance, and aims to preserve capital with low turnover.",
            "is_active": true,
            "name": "Tax-Efficient SRI Core 2",
            "volatility": 0.0859,
            "performance": 0.0572,
            "node_map": [
                {
                    "node_id": "5aafb611-bae9-481c-9da0-03044af09a7a"
                },
                {
                    "node_id": "360baaa9-be8b-4463-bdae-974775cd894f"
                },
                {
                    "node_id": "b530b536-4f99-45d3-bdbc-4729992868dc"
                }
            ],
            "metadata": {}
        }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/allocation/013380bf-7f17-44c1-93c5-892a7ed3498c"
}

Example Response

{
    "id": "013380bf-7f17-44c1-93c5-892a7ed3498c",
    "create_date": "2017-02-14T00:00:00.000+0000",
    "update_date": "2017-02-15T09:00:00.000+0000",
    "category": "Social",
    "description": "Dynamically managed diversified socially responsible ETF strategy allocated to U.S. Equities and tax-exempt Fixed Income. The strategy is tailored to investors with a very low risk tolerance, and aims to preserve capital with low turnover.",
    "is_active": true,
    "name": "Tax-Efficient SRI Core 2",
    "volatility": 0.0859,
    "performance": 0.0572,
    "node_map": [
        {
            "node_id": "5aafb611-bae9-481c-9da0-03044af09a7a"
        },
        {
            "node_id": "360baaa9-be8b-4463-bdae-974775cd894f"
        },
        {
            "node_id": "b530b536-4f99-45d3-bdbc-4729992868dc"
        }
    ],
    "metadata": {}
}

Update an allocation defined by your firm. The allocation_id must be provided. To obtain the appropriate allocation_id, use the GET /allocation endpoint to view all of the allocations defined by your firm and their current information. The details to be updated must also be provided. The endpoint returns the allocation_id and the details for the allocation. If you wish to have an allocation no longer be available without permanently deleting it, use this endpoint to mark the is_active field as false.

PUT /allocation/{allocation_id}

Delete an allocation

Example Request

curl -X DELETE -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/allocation/013380bf-7f17-44c1-93c5-892a7ed3498c"
}

Response (204 No Content)

Permanently delete an allocation defined by your firm. The allocation_id must be provided. To obtain the appropriate allocation_id, use the GET /allocation endpoint to view all of the allocations defined by your firm. This deletes the allocation_id and the allocation record. If you wish to have an allocation no longer be available without permanently deleting it, use the PUT /allocation/{allocation_id} endpoint to mark the is_active field as false.

HTTP REQUEST

DELETE /allocation/{allocation_id}

Allocation Composition

Allocation Composition is used to assign models to an allocation with specific weights and track the composition over time.

Field Type Description
id UUID The id of the allocation composition record
allocation_id UUID The id of the allocation for which you are adding a composition record
model_id UUID The id of the model that is assigned to the allocation
current_weight double The current weight of the model as a percentage of the allocation’s total value; ex. 20 representing 20%. The current weights of all the models must add up to 100. If the model is the only one, enter 100
strategic_weight double The strategic weight of the model as a percentage of the allocation’s total value; ex. 20 representing 20%. The strategic weights of all the models must add up to 100. If the model is the only one, enter 100
date date The date for this allocation composition record
metadata map Custom information associated with the entity in the format key:value
See Metadata

PROTON API

The following fields may be optionally used in conjunction with the Proton API.

Field Type Description
core boolean Indicator if the model_id is a core model for core-satellite investing. Defaults to false which means it is not a core model

List all allocation compositions

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/allocation_composition"
}

Example Response

{
    "content": [
        {
            "id": "2b74355b-00eb-460b-a504-822248e50621",
            "create_date": "2018-04-10T20:43:25.000+0000",
            "update_date": "2018-04-10T20:43:25.000+0000",
            "core": false,
            "current_weight": 100,
            "date": "2018-04-10",
            "strategic_weight": 100,
            "model_id": "dbebf51f-d325-4cdd-b043-78958e29bdce",
            "allocation_id": "9d076a5b-c9eb-4637-ab56-296165be3edc",
            "metadata": {}
        },
        {
            "id": "d05b26cc-367d-4c90-9365-cd89af237bbf",
            "create_date": "2018-04-05T20:42:19.000+0000",
            "update_date": "2018-04-05T20:42:19.000+0000",
            "core": false,
            "current_weight": 100,
            "date": "2018-04-05",
            "strategic_weight": 100,
            "model_id": "dbebf51f-d325-4cdd-b043-78958e29bdce",
            "allocation_id": "30708526-cf56-4560-8bd9-19e00417ec4b",
            "metadata": {}
        },
        {
            "id": "48745b11-ae08-4f96-8889-0be02a96bb5e",
            "create_date": "2018-04-05T20:32:25.000+0000",
            "update_date": "2018-04-05T20:32:25.000+0000",
            "core": false,
            "current_weight": 100,
            "date": "2018-04-05",
            "strategic_weight": 100,
            "model_id": "39c40045-df4b-4ebb-8df8-257dfe48c254",
            "allocation_id": "a31fc863-2a9a-48de-86f2-eb376370a64e",
            "metadata": {}
        }
    ],
    "last": false,
    "total_pages": 1,
    "total_elements": 3,
    "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 the allocation composition for all allocations. To view the composition of a specific allocation only, you may filter by the allocation_id.

HTTP REQUEST

GET /allocation_composition

Create an allocation composition

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
    -d '{
            "core": false,
            "current_weight": 100,
            "date": "2018-04-10",
            "strategic_weight": 100,
            "model_id": "dbebf51f-d325-4cdd-b043-78958e29bdce",
            "allocation_id": "9d076a5b-c9eb-4637-ab56-296165be3edc"
        }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/allocation_composition"

Example Response

{
    "id": "2b74355b-00eb-460b-a504-822248e50621",
    "create_date": "2018-04-10T20:43:25.000+0000",
    "core": false,
    "current_weight": 100,
    "date": "2018-04-10",
    "strategic_weight": 100,
    "model_id": "dbebf51f-d325-4cdd-b043-78958e29bdce",
    "allocation_id": "9d076a5b-c9eb-4637-ab56-296165be3edc",
    "metadata": {}
}

Create a new allocation composition record for an allocation. An allocation will be composed of models and weights which you can store over time. The endpoint returns the allocation_composition_id used to manage the allocation composition record.

HTTP REQUEST

POST /allocation_composition

ARGUMENTS

Parameter Type Required Description
allocation_id UUID required The id of the allocation for which you are adding a composition record
model_id UUID required The id of the model that is assigned to the allocation
current_weight double required The current weight of the model as a percentage of the allocation’s total value; ex. 20 representing 20%. The current weights of all the models must add up to 100. If the model is the only one, enter 100
strategic_weight double required The strategic weight of the model as a percentage of the allocation’s total value; ex. 20 representing 20%. The strategic weights of all the models must add up to 100. If the model is the only one, enter 100
date date required The date for this allocation composition record
metadata map optional Custom information associated with the entity in the format key:value
See Metadata

PROTON API ARGUMENTS

The following fields may be optionally used in conjunction with the Proton API.

Parameter Type Required Description
core boolean optional Indicator if the model_id is a core model for core-satellite investing. Defaults to false which means it is not a core model

Retrieve an allocation composition

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/allocation_composition/2b74355b-00eb-460b-a504-822248e50621"
}

Example Response

{
    "id": "2b74355b-00eb-460b-a504-822248e50621",
    "create_date": "2018-04-10T20:43:25.000+0000",
    "update_date": "2018-04-10T20:43:25.000+0000",
    "core": false,
    "current_weight": 100,
    "date": "2018-04-10",
    "strategic_weight": 100,
    "model_id": "dbebf51f-d325-4cdd-b043-78958e29bdce",
    "allocation_id": "9d076a5b-c9eb-4637-ab56-296165be3edc",
    "metadata": {}
}

Retrieve the information of an allocation composition record for an allocation. The allocation_composition_id must be provided. To obtain the appropriate allocation_composition_id for an allocation, use the GET /allocation_composition endpoint and filter by the allocation_id.

HTTP REQUEST

GET /allocation_composition/{allocation_composition_id}

Update an allocation composition

Example Request

curl -X PUT -H "Authorization: Bearer <access_token>" \
    -d '{
            "core": false,
            "current_weight": 100,
            "date": "2018-04-10",
            "strategic_weight": 100,
            "model_id": "dbebf51f-d325-4cdd-b043-78958e29bdce",
            "allocation_id": "9d076a5b-c9eb-4637-ab56-296165be3edc"
        }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/allocation_composition/2b74355b-00eb-460b-a504-822248e50621"

Example Response

{
    "id": "2b74355b-00eb-460b-a504-822248e50621",
    "create_date": "2018-04-10T20:43:25.000+0000",
    "update_date": "2018-04-10T20:43:25.000+0000",
    "core": false,
    "current_weight": 100,
    "date": "2018-04-10",
    "strategic_weight": 100,
    "model_id": "dbebf51f-d325-4cdd-b043-78958e29bdce",
    "allocation_id": "9d076a5b-c9eb-4637-ab56-296165be3edc",
    "metadata": {}
}

Update the information of an allocation composition record for an allocation. The allocation_composition_id must be provided. To obtain the appropriate allocation_composition_id for an allocation, use the GET /allocation_composition endpoint and filter by the allocation_id. The details to be updated must also be provided. The endpoint returns the allocation_composition_id and the details for the updated allocation composition record.

HTTP REQUEST

PUT /allocation_composition/{allocation_composition_id}

Delete an allocation composition

Example Request

curl -X DELETE -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/allocation_composition/2b74355b-00eb-460b-a504-822248e50621"
}

Response (204 No Content)

Permanently delete an allocation composition record for an allocation. The allocation_composition_id must be provided. To obtain the appropriate allocation_composition_id, use the GET /allocation_composition endpoint to view all of the allocation composition records for all allocations. This deletes the allocation_composition_id and the allocation composition record from the allocation.

HTTP REQUEST

DELETE /allocation/{allocation_composition_id}

Allocation Activity

List all allocation asset sizes

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/allocation/8d97c85c-8cbf-4ac1-a5df-f9d2bb6a77e0/asset_size"
}

Example Response

[
    {
        "date": "2016-01-04",
        "value": 1
    },
    {
        "date": "2016-01-05",
        "value": 1.1
    }
]

Get a list of asset sizes by date for a specific allocation. Asset size records are created at a model level, and aggregated to yield the allocation asset size(s). Allocation asset size represents the “growth of a dollar” rather than a monetary amount. The unique allocation_id must be provided. To obtain the appropriate allocation_id, use the GET /allocation endpoint to view all allocations defined for your firm. The endpoint returns a date, an amount value, and the value added since the last asset size date, usually via deposit. Additional parameters available to narrow down what is returned include date range, only obtaining the latest record, and sorting by different units of time (eg. annually, quarterly, monthly, daily).

HTTP REQUEST

GET /allocation/{allocation_id}/asset_size

ARGUMENTS

Parameter Type Required Description
get_latest boolean optional Retrieve only the latest asset size. Defaults to false if not set
sort_type string optional Sort the asset sizes by D Daily, M Monthly, Q Quarterly, Y Yearly. Defaults to D Daily if not set. Must be capital letters
start_date date optional Start date for the data. Defaults to the first date if not set
end_date date optional End date for the data. Defaults to the last date if not set
is_current_weight boolean optional Retrieve allocation asset sizes using the current weight for aggregation. Defaults to true if not set

RESPONSE

Field Type Description
date date Date for this asset size record
value double “Growth of a dollar” within the allocation on the particular date

List all allocation holdings

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
     "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/allocation/8d97c85c-8cbf-4ac1-a5df-f9d2bb6a77e0/holding"
}

Example Response

[
    {
        "current_weight": 15,
        "date": "2018-02-02",
        "strategic_weight": 15,
        "security_id": "b28ca897-6c2a-4e8f-b33f-d143a5e9a988"
    },
    {
        "current_weight": 35,
        "date": "2018-02-02",
        "strategic_weight": 35,
        "security_id": "a3098d24-33bb-4eb9-95dc-f7d091371d00"
    },
    {
        "current_weight": 2,
        "date": "2018-02-02",
        "strategic_weight": 2,
        "security_id": "dd561cf3-540a-4506-bdf9-52b7c86661f6"
    },
    {
        "current_weight": 6,
        "date": "2018-02-02",
        "strategic_weight": 6,
        "security_id": "f617534c-a2bb-49f6-a5c5-6ebcbaa3b274"
    },
    {
        "current_weight": 15,
        "date": "2018-02-02",
        "strategic_weight": 15,
        "security_id": "df82bd37-d390-41b9-9bef-6e599c58a316"
    },
    {
        "current_weight": 27,
        "date": "2018-02-02",
        "strategic_weight": 27,
        "security_id": "46521baf-6037-4595-bf20-66ae9f2703e7"
    }
]

Get the information for all securities assigned to a specific allocation. This represents the securities an allocation should hold, according to the models associated with said allocation. Respective security weights are listed as a percentage of each model’s total holdings. Holding records are created at a model level and aggregated to show the holdings of the allocation. The unique allocation_id must be provided. To obtain the appropriate allocation_id, use the GET /allocation endpoint to view all allocations defined for your firm. The endpoint returns a list of security_ids and the details for all holding records. Additional parameters available to narrow down what is returned include a date range.

HTTP REQUEST

GET /allocation/{allocation_id}/holding

ARGUMENTS

Parameter Type Required Description
start_date date optional Start date for the data. Defaults to the first date if not set
end_date date optional End date for the data. Defaults to the last date if not set

RESPONSE

Field Type Description
security_id UUID The id for the security included in the holding record
current_weight double Current weight of the security as a percentage of the model’s total monetary value; ex. 20 representing 20%
strategic_weight double Strategic weight of the security as a percentage of the model’s total monetary value; ex. 20 representing 20%
date date Date of the holding record

List all allocation transactions

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/allocation/8d97c85c-8cbf-4ac1-a5df-f9d2bb6a77e0/transaction"
}

Example Response

{
    "content": [
        {
            "id": "8d97c85c-8cbf-4ac1-a5df-f9d2bb6a77e0",
            "create_date": "2018-01-25T04:30:25",
            "update_date": "2018-01-26T09:00:00",
            "shares": 150,
            "price": 23.45,
            "date": "2018-01-25",
            "model_id": "b663c459-4bda-4c57-82ea-09d41817fa",
            "security_id": "9c75e982-5554-4725-b23e-43ff53876df6",
            "transaction_code_id": "f5397b-7d22-433f-b01e-8202184a6386",
        }
    ],
    "total_pages": 1,
    "total_elements": 1,
    "last": true,
    "sort": [
      {
        "direction": "DESC",
        "property": "id",
        "ignore_case": false,
        "null_handling": "NATIVE",
        "descending": true,
        "ascending": false
      }
    ],
    "first": true,
    "number_of_elements": 1,
    "size": 25,
    "number": 0
  }

Get the information for all transactions made under an allocation to achieve the composition of the allocation. Transactions represent buy or sell orders for securities. Transaction records are created at a model level and all transactions for each model below the allocation are returned to show the allocation’s transaction activity. Must provide the unique allocation_id. To obtain the appropriate allocation_id, use the GET /allocation endpoint to view all allocations defined for your firm. The endpoint returns a list of transaction_ids and details for each transaction. See the Order section for more information. Additional parameters available to narrow down what is returned include a date range or using the current weight for aggregation.

HTTP REQUEST

GET /allocation/{allocation_id}/transaction

ARGUMENTS

Parameter Type Required Description
start_date date optional Start date for the data. Defaults to the first date if not set
end_date date optional End date for the data. Defaults to the last date if not set

RESPONSE

Field Type Description
id UUID The id of the allocation transaction record
shares double Number of shares of the security purchased as part of the transaction
price double Security price at which the shares were purchased as part of the transaction
date date Date of the allocation transaction
model_id UUID The id of the model that the allocation transaction record falls under
security_id UUID The id of the security included in the allocation transaction
transaction_code_id integer The id referring to the transaction codes defined by your firm
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

Get aggregate allocation data

Displays a breakdown of an allocation such as allocation composition, model holding, and security details. This view is useful when constructing drilldowns of allocations/models for clients.

Field Type Description
allocation_id UUID The id of the allocation
allocation_name string Name of the allocation
allocation_category string Category of the allocation
allocation_description string Description of the allocation
allocation_secondary_id UUID The secondary_id of the allocation
allocation_compositions array Array of allocation compositions
      allocation_composition_id UUID The id of the allocation composition
      allocation_composition_date date The date for this allocation composition record
      model_id UUID The id of the model that is assigned to the allocation
      model_name string Name of the model
      model_category string Category of the model such as “Equities”
      model_description string Description of the model
      model_strategic_weight double Strategic weight of the model as a percentage of the allocation’s total value; ex. 20 representing 20%
      model_current_weight double Current weight of the model as a percentage of the allocation’s total value; ex. 20 representing 20%
      model_currency_code string(3) Currency code for the base currency of the model
      model_secondary_id string Alternate id that can be used to identify the model such as an internal id
      allocation_composition_create_date array Timestamp for the date and time when the composition was created
      allocation_composition_update_date UUID Timestamp for the date and time when the composition was last updated
      model_holdings array Array of model holdings based on model_ids in the allocation_composition. Returns model_holdings that have the latest date.
          model_holding_id UUID The id of the model holding record
          model_holding_date date Date of the model holding
          security_id UUID The ID of the security
          security_name string The name of the security
          security_ticker string Security’s symbol on the exchange where it is traded
          security_asset_class string The asset class of the security such as “Equities” or “Fixed Income”
          security_sector string The sector of the security such as “Technology” or “Pharmaceuticals”
          security_industry string The industry of the security such as “Consumer Tech” or “Enterprise System”
          security_security_class string The security class of the security such as “Stock”, “Mutual Fund”, “ETF”, etc
          security_exchange string The exchange on which the security is traded such as “NYSE”
          security_secondary_id string Alternate ID of the security that can be used to identify the security such as an internal ID
          security_create_date timestamp Timestamp for the date and time when the security was created
          security_update_date timestamp Timestamp for the date and time when the security was last updated
          security_countries array Array of country and weights for the security
              country string Country where the company is located. See country codes
              weight double The weight of the country as a percentage of the security; ex. 20 representing 20%
          security_compositions array In the case that we have a security_id that consists of other securities, we use this array to return that security list. Return records where end_date = NULL.
              security_id UUID The ID of the security
              security_name string The name for the security
              security_ticker string Security’s symbol on the exchange where it is traded
              security_weight double The weight of the country as a percentage of the broader security; ex. 20 representing 20%. The weights of all the components must add up to 100.
              start_date date Date for when the underlying security started being a part of the broader security
              end_date date Date for when the underlying security no longer was a part of the broader security
              security_asset_class string The asset class of the security such as “Equities” or “Fixed Income”
              security_sector string The sector of the security such as “Technology” or “Pharmaceuticals”
              security_industry string The industry of the security such as “Consumer Tech” or “Enterprise System”
              security_security_class string The security class of the security such as “Stock”, “Mutual Fund”, “ETF”, etc
              security_secondary_id string Alternate id of the security that can be used to identify the security such as an internal id
              security_create_date timestamp Timestamp for the date and time when the security was created
              security_update_date timestamp Timestamp for the date and time when the security was last updated
              security_country array Array of originating country and weights for the security included in the composition
                  country string Country where the company is located. See country codes
                  weight double The weight of the country as a percentage of the security; ex. 20 representing 20%

HTTP REQUEST

GET /allocation/{allocation_id}/aggregate_data

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
  "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/allocation/0797efda-cf8b-4661-9cb4-d1e8966a3dcd/aggregate_data"

Example Response

{
  "allocation_id": "088be9e2-ae2e-4d56-83a2-2b67634fa56f",
  "allocation_name": "Medium Risk Global Asset Allocation",
  "allocation_category": "Medium Risk",
  "allocation_description": "Diversified asset allocation giving clients with a medium risk appetite exposure to global assets.",
  "allocation_secondary_id": null,
  "allocation_compositions": [
    {
      "allocation_composition_id": "34932d83-de4a-4a55-9ba3-154e256e9dab",
      "allocation_composition_date": "2026-10-14",
      "model_id": "86bcab43-2e7a-43ec-9ee8-4eb8321a7d34",
      "model_name": "Build Wealth 10 Taxable",
      "model_category": "Aggressive Long-Term Portfolio (Taxable)",
      "model_description": "A long-term portfolio for aggressive investors seeking compelling risk-adjusted returns in a taxable account.",
      "model_strategic_weight": 100.0,
      "model_current_weight": 100.0,
      "model_secondary_id": null,
      "allocation_composition_create_date": "2019-01-04T14:56:07.000Z",
      "allocation_composition_update_date": "2019-01-04T14:56:07.000Z",
      "model_holdings": [
        {
          "model_holding_id": "9721d7f2-5d33-41cd-96f6-5cf2464aaa9a",
          "model_holding_date": "2026-10-14",
          "security_id": "f241e336-3958-4d1f-bbd7-faf39772c3a4",
          "security_name": "Tesla, Inc.",
          "security_ticker": "1546613776467",
          "security_asset_class": "US Equity",
          "security_sector": "Consumer Cyclical",
          "security_industry": "Auto Manufacturers",
          "security_security_class": "stock",
          "security_exchange": "1546613776467",
          "security_secondary_id": null,
          "security_create_date": "2019-01-04T14:56:17.000Z",
          "security_update_date": "2019-01-04T14:56:17.000Z",
          "security_countries": [
            {
                "country": "US",
                "weight": 1.0
            }
          ],
          "security_compositions": [
            {
              "security_id": "000dkk9s-a9d0-sd8f-asd0fg9f",
              "security_name": "Apple",
              "security_ticker": "AAPL",
              "security_weight": 50,
              "start_date": "2018-02-02",
              "end_date": null,
              "security_asset_class": "TECH",
              "security_sector": "Technology",
              "security_industry": "Technology Services",
              "security_security_class": "Stocks",
              "security_secondary_id": "SYSGEN_APPLESTOCK_TIMESTAMP",
              "security_create_date": "2018-02-02T9:00:03.000+0000",
              "security_update_date": "2018-02-02T9:00:03.000+0000",
              "security_country": [
                {
                  "country" : "USA",
                  "weight" : 100
                }
              ]
            },
            {
              "security_id": "0099s9s8d-a9d0-sd8f-asd0fg9f",
              "security_name": "Salesforce",
              "security_ticker": "CRM",
              "security_weight": 50,
              "start_date": "2018-02-02",
              "end_date": null,
              "security_asset_class": "TECH",
              "security_sector": "Technology",
              "security_industry": "Technology Services",
              "security_security_class": "Stocks",
              "security_secondary_id": "SYSGEN_SALESFORCESTOCK_TIMESTAMP",
              "security_create_date": "2018-02-02T9:00:04.000+0000",
              "security_update_date": "2018-02-02T9:00:04.000+0000",
              "security_country": [
                {
                  "country" : "USA",
                  "weight" : 100
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Benchmark

Benchmark Management

A benchmark is assigned a group of securities to act as an index for the performance of some aspect of the market, whether that be the market as a whole or a specific segment of the market. The benchmark essentially acts as a proxy for a client, account, allocation, model, or portfolio that would also hold a group of securities to approximate or measure their performance. A benchmark can also hold just one security to be used as a benchmark security and track its price growth. Benchmarks are required to us the Performance endpoints.

Field Type Description
id UUID The id of the benchmark
name string Name of the benchmark
composition array List of securities and their respective weights as a percentage of the benchmark’s total value
      weight double The weight of the security as a percentage of the benchmark’s total value; ex. 20 representing 20%. The weights of all the securities must add up to 100
      security_id string The id of the security in the benchmark
description string Description of the benchmark such as the market segment that it represents
client_id string The id of the client to which the benchmark belongs, if any
is_active boolean Indicates if the benchmark is active. Defaults to true which means it is active
metadata map Custom information associated with the entity in the format key:value
See Metadata
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

List all benchmarks

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/benchmark"

Example Response

{
    "content": [
        {
            "id": "d79bb3a3-f259-430c-8fa8-a93f87cc3bdf",
            "create_date": "2018-03-27T11:45:08.000+0000",
            "update_date": "2018-03-27T11:45:08.000+0000",
            "description": "80% US Small Cap, 20% US Municipal bonds",
            "is_active": true,
            "name": "80/20 US Benchmark",
            "composition": [
                {
                    "weight": 80,
                    "security_id": "00178f8e-2c0b-4e15-b725-74d53b9533ef"
                },
                {
                    "weight": 20,
                    "security_id": "001067fd-a504-43b0-858c-2a43a26e91e9"
                }
            ],
            "metadata": {}
        },
        {
            "id": "d2e19c41-9c57-4508-a5e8-6dff7f0ffe7d",
            "create_date": "2018-03-27T11:44:22.000+0000",
            "update_date": "2018-03-27T11:44:22.000+0000",
            "description": "60% US Small Cap, 40% US Municipal bonds",
            "is_active": true,
            "name": "60/40 US Benchmark",
            "composition": [
                {
                    "weight": 60,
                    "security_id": "00178f8e-2c0b-4e15-b725-74d53b9533ef"
                },
                {
                    "weight": 40,
                    "security_id": "001067fd-a504-43b0-858c-2a43a26e91e9"
                }
            ],
            "metadata": {}
        }
    ],
    "total_pages": 1,
    "total_elements": 2,
    "last": true,
    "number_of_elements": 2,
    "first": true,
    "sort": [
        {
            "direction": "DESC",
            "property": "updateDate",
            "ignore_case": false,
            "null_handling": "NATIVE",
            "descending": true,
            "ascending": false
        }
    ],
    "size": 25,
    "number": 0
}

Get details for all benchmarks defined for your firm. Note that the composition information is stored as a nested object within the benchmark object.

HTTP REQUEST

GET /benchmark

Create a benchmark

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" -H \
     -d '{
        "description": "80% US Small Cap, 20% US Municipal bonds",
        "name": "80/20 US Benchmark",
        "composition": [
            {
                "weight": 80,
                "security_id": "00178f8e-2c0b-4e15-b725-74d53b9533ef"
            },
            {
                "weight": 20,
                "security_id": "001067fd-a504-43b0-858c-2a43a26e91e9"
            }
        ]
     }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/benchmark"

Example Response

{
    "id": "d79bb3a3-f259-430c-8fa8-a93f87cc3bdf",
    "create_date": "2018-03-27T11:45:08.000+0000",
    "description": "80% US Small Cap, 20% US Municipal bonds",
    "is_active": true,
    "name": "80/20 US Benchmark",
    "composition": [
        {
            "weight": 80,
            "security_id": "00178f8e-2c0b-4e15-b725-74d53b9533ef"
        },
        {
            "weight": 20,
            "security_id": "001067fd-a504-43b0-858c-2a43a26e91e9"
        }
    ],
    "metadata": {}
}

Create a new benchmark for your firm. The name for the benchmark must be provided. The composition of securities and their weights should also be provided as a nested object for the benchmark to be usable. The create_date will default to the current date. The endpoint returns a benchmark_id used to manage the benchmark and assign it to allocations.

HTTP REQUEST

POST /benchmark

ARGUMENTS

Parameter Type Required Description
name string required Name of the benchmark
composition array optional List of securities and their respective weights as a percentage of the benchmark’s total value. It is recommended to provide at least one security_id
      weight double required The weight of the security as a percentage of the benchmark’s total value; ex. 20 representing 20%. The weights of all the securities must add up to 100
      security_id string required The id of the security in the benchmark
description string optional Description of the benchmark such as the market segment that it represents
client_id string optional The id of the client to which the benchmark belongs, if any
is_active boolean optional Indicates if the benchmark is active. Defaults to true which means it is active
metadata map optional Custom information associated with the funding request in the format key:value. See Metadata
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Retrieve a benchmark

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/benchmark/d79bb3a3-f259-430c-8fa8-a93f87cc3bdf"

Example Response

{
    "id": "d79bb3a3-f259-430c-8fa8-a93f87cc3bdf",
    "create_date": "2018-03-27T11:45:08.000+0000",
    "update_date": "2018-03-27T11:45:08.000+0000",
    "description": "80% US Small Cap, 20% US Municipal bonds",
    "is_active": true,
    "name": "80/20 US Benchmark",
    "composition": [
        {
            "weight": 80,
            "security_id": "00178f8e-2c0b-4e15-b725-74d53b9533ef"
        },
        {
            "weight": 20,
            "security_id": "001067fd-a504-43b0-858c-2a43a26e91e9"
        }
    ],
    "metadata": {}
}

Retrieve the information for a benchmark. The benchmark_id must be provided. The endpoint returns the benchmark_id and the details for the benchmark specified.

HTTP REQUEST

GET /benchmark/{benchmark_id}

Update a benchmark

Example Request

curl -X PUT -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" -H \
     -d '{
            "description": "80% US Small Cap, 20% US Municipal bonds",
             "name": "80/20 US Benchmark",
             "composition": [
                 {
                         "weight": 80,
                         "security_id": "00178f8e-2c0b-4e15-b725-74d53b9533ef"
                 },
                 {
                         "weight": 20,
                         "security_id": "001067fd-a504-43b0-858c-2a43a26e91e9"
                 }
             ]
        }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/benchmark/d79bb3a3-f259-430c-8fa8-a93f87cc3bdf"

Example Response

{
    "id": "d79bb3a3-f259-430c-8fa8-a93f87cc3bdf",
    "create_date": "2018-03-27T11:45:08.000+0000",
    "update_date": "2018-03-27T11:45:08.000+0000",
    "description": "80% US Small Cap, 20% US Municipal bonds",
    "is_active": true,
    "name": "80/20 US Benchmark",
    "composition": [
        {
            "weight": 80,
            "security_id": "00178f8e-2c0b-4e15-b725-74d53b9533ef"
        },
        {
            "weight": 20,
            "security_id": "001067fd-a504-43b0-858c-2a43a26e91e9"
        }
    ],
    "metadata": {}
}

Updated the information for a benchmark. The benchmark_id must be provided. To obtain the appropriate benchmark_id, use the GET /benchmark endpoint to view all of the benchmarks defined firm-wide and their current information. The details to be updated and the details to be maintained must also be provided. The endpoint returns the benchmark_id and the details for the benchmark. To mark the benchmark as inactive so that it is no longer used without deleting it, you can use this endpoint to change the is_active field to false.

HTTP REQUEST

PUT /benchmark/{benchmark_id}

Delete a benchmark

Example Request

curl -X DELETE -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/benchmark/d79bb3a3-f259-430c-8fa8-a93f87cc3bdf"

Response (204 No Content)

Permanently delete a benchmark. The benchmark_id must be provided. To obtain the appropriate benchmark_id, use the GET /benchmark endpoint to view all of the benchmarks defined firm-wide. This deletes the benchmark_id and the benchmark record. To mark the benchmark as inactive so that it is no longer used without deleting it, you can use the PUT /benchmark endpoint to change the is_active field to false.

HTTP REQUEST

DELETE /benchmark/{benchmark_id}

Benchmark Activity

List all benchmark asset sizes

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/benchmark/d79bb3a3-f259-430c-8fa8-a93f87cc3bdf/asset_size"

Example Response

[
    {
        "date": "2018-02-03",
        "value": 100.1,
    },
        {
        "date": "2018-02-04",
        "value": 100.2,
    },
        {
        "date": "2018-02-05",
        "value": 100.3,
    }
]

Get a list of asset sizes by date for a benchmark. Asset size records are calculated using the securities and their weights in the composition of the particular benchmark_id and the security prices. Benchmark asset size represents the “growth of a dollar” rather than a monetary amount. The unique benchmark_id must be provided. To obtain the appropriate benchmark_id, use the GET /benchmark endpoint to view the benchmarks defined for your firm. The endpoint returns a list of asset sizes by date for the benchmark. Additional parameters available to narrow down what is returned include date range, only obtaining the latest record, and sorting by different units of time (eg. annually, quarterly, monthly, daily).

HTTP REQUEST

GET /benchmark/{benchmark_id}/asset_size

ARGUMENTS

Parameter Type Required Description
get_latest boolean optional Retrieve only the latest asset size. Defaults to false if not set
sort_type string optional Sort the asset sizes by D Daily, M Monthly, Q Quarterly, Y Yearly. Defaults to D Daily if not set. Must be capital letters
start_date date optional Start date for the data. Defaults to the first date if not set
end_date date optional End date for the data. Defaults to the last date if not set

RESPONSE

Field Type Description
date date Date for this asset size record
value double “Growth of a dollar” within the benchmark on the particular date

Card

Card Program

Card programs are issued and run by a program manager who is responsible for establishing relationships with processors, sponsor banks, card networks.

Field Type Description
id UUID The id of the card program
client_id UUID The id of a client to whom the card program belongs if it’s a business on your platform
name string Name of the card program
card_processor string Name of the card processor for the card program
card_network string Card network for the cards being issued in the program. Value may be visa, mastercard, amex, or discover
card_type string Type of cards being issued in the program. Value may be credit, debit, or prepaid
issuing_bank string Name of the issuing or sponsor bank on the card program
code string Code used to identify the card program
description string Description of the card program
metadata map Custom information associated with the card program in the format key:value
See Metadata
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

List all card programs

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
  "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/card_program"




Example Response

{
    "content": [
        {
            "id": "1692a3c2-65b0-46a0-9a0a-66bc949f7ca1",
            "secondary_id": null,
            "create_date": "2020-01-07T20:54:33.000+0000",
            "update_date": "2020-01-07T20:54:33.000+0000",
            "client_id": "87ef9136-f7e1-4ef0-8dbc-e58bf435d11c",
            "name": "E-Commerce Reloadable Program",
            "card_processor": "EML",
            "card_network": "visa",
            "card_type": "prepaid",
            "issuing_bank": "Metro Bank",
            "code": "A89M4k28",
            "description": null,
            "metadata": {}
        },
        {
            "id": "0233ab54-58a0-4b43-aa65-a1c32f29ad69",
            "secondary_id": null,
            "create_date": "2019-12-20T18:39:44.000+0000",
            "update_date": "2019-12-20T18:39:44.000+0000",
            "client_id": "87ef9136-f7e1-4ef0-8dbc-e58bf435d11c",
            "name": "Banking Program",
            "card_processor": "EML",
            "card_network": "visa",
            "card_type": "debit",
            "issuing_bank": "Metro Bank",
            "code": "L43zn2659",
            "description": null,
            "metadata": {}
        }
    ],
    "last": true,
    "total_pages": 1,
    "total_elements": 2,
    "number_of_elements": 2,
    "first": true,
    "sort": [
        {
            "direction": "DESC",
            "property": "updateDate",
            "ignore_case": false,
            "null_handling": "NATIVE",
            "ascending": false,
            "descending": true
        }
    ],
    "size": 25,
    "number": 0
}

Get information for all card programs stored for your firm.

HTTP REQUEST

GET /card_program

Create a card program

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
      "client_id": "87ef9136-f7e1-4ef0-8dbc-e58bf435d11c",
      "name": "E-Commerce Reloadable Program",
      "card_processor": "EML",
      "card_network": "visa",
      "card_type": "prepaid",
      "issuing_bank": "Metro Bank",
      "code": "A89M4k28"
    }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/card_program"




Example Response

{
    "id": "1692a3c2-65b0-46a0-9a0a-66bc949f7ca1",
    "secondary_id": null,
    "create_date": "2020-01-07T20:54:33.000+0000",
    "update_date": "2020-01-07T20:54:33.000+0000",
    "client_id": "87ef9136-f7e1-4ef0-8dbc-e58bf435d11c",
    "name": "E-Commerce Reloadable Program",
    "card_processor": "EML",
    "card_network": "visa",
    "card_type": "prepaid",
    "issuing_bank": "Metro Bank",
    "code": "A89M4k28",
    "description": null,
    "metadata": {}
}

Create a card program. The endpoint returns a card_program_id that can then be used to manage the program.

HTTP REQUEST

POST /card_program

ARGUMENTS

Parameter Type Required Description
name string required Name of the card program
card_processor string required Name of the card processor on the card program
card_network string required Card network for the cards being issued in the program. Value may be visa, mastercard, amex, or discover
card_type string required Type of cards being issued in the program. Value may be credit, debit, or prepaid
issuing_bank string required Name of the issuing or sponsor bank on the card program
client_id UUID optional The id of a client to whom the card program belongs if it’s a business on your platform
code string optional Code used to identify the card program
description string optional Description of the card program
metadata map optional Custom information associated with the card program in the format key:value
See Metadata
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Retrieve a card program

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/card_program/1692a3c2-65b0-46a0-9a0a-66bc949f7ca1"




Example Response

{
    "id": "1692a3c2-65b0-46a0-9a0a-66bc949f7ca1",
    "secondary_id": null,
    "create_date": "2020-01-07T20:54:33.000+0000",
    "update_date": "2020-01-07T20:54:33.000+0000",
    "client_id": "87ef9136-f7e1-4ef0-8dbc-e58bf435d11c",
    "name": "E-Commerce Reloadable Program",
    "card_processor": "EML",
    "card_network": "visa",
    "card_type": "prepaid",
    "issuing_bank": "Metro Bank",
    "code": "A89M4k28",
    "description": null,
    "metadata": {}
}

Retrieve the information for a specific card program. The endpoint returns the card_program_id and details for the card program specified.

HTTP REQUEST

GET /card_program/{card_program_id}

Update a card program

Example Request

curl -X PUT -H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
      "name": "Online Reloadables"
     }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/card_program/1692a3c2-65b0-46a0-9a0a-66bc949f7ca1"




Example Response

{
    "id": "1692a3c2-65b0-46a0-9a0a-66bc949f7ca1",
    "secondary_id": null,
    "create_date": "2020-01-07T20:54:33.000+0000",
    "update_date": "2020-02-07T20:10:20.000+0000",
    "client_id": "87ef9136-f7e1-4ef0-8dbc-e58bf435d11c",
    "name": "Online Reloadables",
    "card_processor": "EML",
    "card_network": "visa",
    "card_type": "prepaid",
    "issuing_bank": "Metro Bank",
    "code": "A89M4k28",
    "description": null,
    "metadata": {}
}

Update the information for a card program. The unique card_program_id must be provided. To obtain the appropriate card_program_id, use the GET /card_program endpoint to view all cards stored for your firm and their current information. The details to be updated must also be provided. The endpoint returns the card_program_id and the details for the card.

HTTP REQUEST

PUT /card_program/{card_program_id}

Delete a card program

Example Request

curl -X DELETE -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/card_program/0233ab54-58a0-4b43-aa65-a1c32f29ad69"




Response (204 No Content)

Permanently delete a card program. The unique card_program_id must be provided. To obtain the appropriate card_program_id, use the GET /card_program endpoint to view all cards stored for your firm. This deletes the card_program_id and all card record information.

HTTP REQUEST

DELETE /card_program/{card_program_id}

Card Management

Store a debit, credit, or prepaid card that has been issued through an integration.

Field Type Description
id UUID The id of the card
client_id UUID The id of a client to whom the card belongs
account_id UUID The id of the account linked to the card
card_program_id UUID The id of the card program the card belongs to
card_name string Name of the card
institution_name string Name of the institution to issue the card
card_holder_name string Name of the person to whom the card is issued
expiry_date date Expiration date of the card
card_type string Type of card. Value may be credit, debit, or prepaid
card_network string Card network for the card. Value may be visa, mastercard, amex, or discover
card_issuance string Type of card issuance. Value may be physical, virtual, or both
card_image string Link to an image of the card artwork with the card details
mask string Masked version of the card number
currency_code string Alphabetic currency code for the base currency of the card, limited to 3 characters
See currency codes
spending_limit_atm double Spending limit of the card when used for ATM withdrawals
spending_limit_purchase double Spending limit of the card when used for purchases
transaction_limit integer Number of transactions the card is limited to in a given period
credit_limit double Credit limit of the card if it’s a credit card
address array(map) Address details for the card
      address_line1 string Primary information for the street address, such as the street and building number
      address_line2 string Secondary information for the street address, such as a suite or apartment number
      city string City for the address
      state string State, province, or sub-country region for the address
      postalcode string Alphanumeric postal code or zip code for the address
      country string Country for the address using the ISO ALPHA-2 Code.
See country codes
      type string Type of address. Value may be mailing or billing
phone_number string Phone number associated with the card
status string Status of the card such as “pending”, “issued”, or “suspended”
is_primary boolean Indicates if the card is the primary card for a client. Only one card may be primary for a client_id. If a user sets a card to is_primary = “true” then all other cards for that client_id will be set to is_primary = “false.” Defaults to false which indicates the card is not primary
is_active boolean Indicates if the card is currently active. Defaults to true which indicates it is active
metadata map Custom information associated with the card in the format key:value
See Metadata
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

List all cards

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
  "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/card"




Example Response

{
    "content": [
        {
            "id": "1692a3c2-65b0-46a0-9a0a-66bc949f7ca1",
            "secondary_id": null,
            "create_date": "2020-01-07T20:54:33.000+0000",
            "update_date": "2020-01-07T20:54:33.000+0000",
            "client_id": "87ef9136-f7e1-4ef0-8dbc-e58bf435d11c",
            "account_id": null,
            "card_program_id": null,
            "card_name": "Travel Rewards",
            "institution_name": "Citywide Bank",
            "card_holder_name": "Sarah Johnson",
            "expiry_date": "12/31/2030",
            "card_type": "credit",
            "card_network": "visa",
            "card_issuance": "physical",
            "card_image": null,
            "mask": "1752",
            "currency_code": "USD",
            "spending_limit_atm": null,
            "spending_limit_purchase": 3000.00,
            "transaction_limit": null,
            "credit_limit": 5000.00,
            "address": [
                {
                    "address_line1": "354 Halsted Street",
                    "address_line2": "Apt 2",
                    "city": "Chicago",
                    "state": "IL",
                    "postalcode": "60608",
                    "country": "US",
                    "type": "mailing"
                },
                {
                    "address_line1": "483 Morgan Street",
                    "address_line2": "Apt 3",
                    "city": "Chicago",
                    "state": "IL",
                    "postalcode": "60608",
                    "country": "US",
                    "type": "billing"
                }
            ],
            "phone_number": "7739462148",
            "status": null,
            "is_primary": false,
            "is_active": true,
            "metadata": {}
        },
        {
            "id": "0233ab54-58a0-4b43-aa65-a1c32f29ad69",
            "secondary_id": null,
            "create_date": "2019-12-20T18:39:44.000+0000",
            "update_date": "2019-12-20T18:39:44.000+0000",
            "client_id": "87ef9136-f7e1-4ef0-8dbc-e58bf435d11c",
            "account_id": null,
            "card_program_id": null,
            "card_name": "Virtual Visa",
            "institution_name": "Citywide Bank",
            "card_holder_name": "John Smith",
            "expiry_date": "12/31/2025",
            "card_type": "credit",
            "card_network": "visa",
            "card_issuance": "virtual",
            "card_image": null,
            "mask": "6789",
            "currency_code": "USD",
            "spending_limit_atm": null,
            "spending_limit_purchase": 1000.00,
            "transaction_limit": null,
            "credit_limit": 5000.00,
            "address": [
                {
                    "address_line1": "3 Downtown Street",
                    "address_line2": "",
                    "city": "New York",
                    "state": "NY",
                    "postalcode": "01191",
                    "country": "US",
                    "type": "billing"
                }
            ],
            "phone_number": "2123734583",
            "status": null,
            "is_primary": false,
            "is_active": true,
            "metadata": {}
        }
    ],
    "last": true,
    "total_pages": 1,
    "total_elements": 2,
    "number_of_elements": 2,
    "first": true,
    "sort": [
        {
            "direction": "DESC",
            "property": "updateDate",
            "ignore_case": false,
            "null_handling": "NATIVE",
            "ascending": false,
            "descending": true
        }
    ],
    "size": 25,
    "number": 0
}

Get information for all cards stored for your firm. You can filter using one of the unique ids such as the client_id to view the cards for a client or for another particular entity.

HTTP REQUEST

GET /card

Create a card

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
      "client_id": "87ef9136-f7e1-4ef0-8dbc-e58bf435d11c",
      "card_name": "Travel Rewards",
      "institution_name": "Citywide Bank",
      "card_holder_name": "Sarah Johnson",
      "expiry_date": "12/31/2000",
      "card_type": "credit",
      "card_network": "visa",
      "card_issuance": "physical",
      "mask": "1752",
      "currency_code": "USD",
      "spending_limit_purchase": 3000.00,
      "credit_limit": 5000.00,
      "address": [
            {
                "address_line1": "483 Morgan Street",
                "address_line2": "Apt 3",
                "city": "Chicago",
                "state": "NY",
                "postalcode": "60608",
                "country": "US",
                "type": "billing"
            },
            {
                "address_line1": "354 Halsted Street",
                "address_line2": "Apt 2",
                "city": "Chicago",
                "state": "NY",
                "postalcode": "60608",
                "country": "US",
                "type": "mailing"
            }
      ],
      "phone_number": "7739462148"
    }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/card"




Example Response

{
    "id": "1692a3c2-65b0-46a0-9a0a-66bc949f7ca1",
    "secondary_id": null,
    "create_date": "2020-01-07T20:54:32.000+0000",
    "update_date": "2020-01-07T20:54:32.000+0000",
    "client_id": "87ef9136-f7e1-4ef0-8dbc-e58bf435d11c",
    "account_id": null,
    "card_program_id": null,
    "card_name": "Travel Rewards",
    "institution_name": "Citywide Bank",
    "card_holder_name": "Sarah Johnson",
    "expiry_date": "12/31/2000",
    "card_type": "credit",
    "card_network": "visa",
    "card_issuance": "physical",
    "card_image": null,
    "mask": "1752",
    "currency_code": "USD",
    "spending_limit_atm": null,
    "spending_limit_purchase": 3000.00,
    "transaction_limit": null,
    "credit_limit": 5000.00,
    "address": [
      {
          "address_line1": "354 Halsted Street",
          "address_line2": "Apt 2",
          "city": "Chicago",
          "state": "NY",
          "postalcode": "60608",
          "country": "US",
          "type": "mailing"
      },
      {
          "address_line1": "483 Morgan Street",
          "address_line2": "Apt 3",
          "city": "Chicago",
          "state": "NY",
          "postalcode": "60608",
          "country": "US",
          "type": "billing"
      }
    ],
    "phone_number": "7739462148",
    "status": null,
    "is_primary": false,
    "is_active": true,
    "metadata": {}
}

Create a card for a client. The endpoint returns a card_id that can then be used to manage the card.

HTTP REQUEST

POST /card

ARGUMENTS

Parameter Type Required Description
client_id UUID required The id of a client to whom the card belongs
account_id UUID optional The id of the account linked to the card
card_program_id UUID optional The id of the card program the card belongs to
card_name string required Name of the card
institution_name string required Name of the institution to issue the card
card_holder_name string required Name of the person to whom the card is issued
card_type string required Type of card. Value may be credit, debit, or prepaid
card_issuance string required Type of card issuance. Value may be physical, virtual, or both
card_image string optional Link to an image of the card artwork with the card details
card_network string optional Card network for the card. Value may be visa, mastercard, amex, or discover
mask string optional Masked version of the card number
expiry_date date optional Expiration date of the card
currency_code string optional Alphabetic currency code for the base currency of the card, limited to 3 characters
See currency codes
spending_limit_atm double optional Spending limit of the card when used for ATM withdrawals
spending_limit_purchase double optional Spending limit of the card when used for purchases
transaction_limit integer optional Number of transactions the card is limited to in a given period
credit_limit double optional Credit limit of the card if it’s a credit card
address array(map) optional Address details for the card
      address_line1 string required Primary information for the street address, such as the street and building number
      address_line2 string optional Secondary information for the street address, such as a suite or apartment number
      city string required City for the address
      state string required State, province, or sub-country region for the address
      postalcode string optional Alphanumeric postal code or zip code for the address
      country string required Country for the address using the ISO ALPHA-2 Code.
See country codes
      type string required Type of address. Value may be mailing or billing
phone_number string optional Phone number associated with the card
status string optional Status of the card such as pending or issued
is_primary boolean optional Indicates if the card is the primary card for a client. Only one card may be primary for a client_id. If a user sets a card to is_primary = “true” then all other cards for that client_id will be set to is_primary = “false.” Defaults to false which indicates the card is not primary
is_active boolean optional Indicates if the card is currently active. Defaults to true which indicates it is active
metadata map optional Custom information associated with the card in the format key:value
See Metadata
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Retrieve a card

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/card/0233ab54-58a0-4b43-aa65-a1c32f29ad69"




Example Response

{
    "id": "0233ab54-58a0-4b43-aa65-a1c32f29ad69",
    "secondary_id": null,
    "create_date": "2019-12-20T18:39:44.000+0000",
    "update_date": "2019-12-20T18:39:44.000+0000",
    "client_id": "87ef9136-f7e1-4ef0-8dbc-e58bf435d11c",
    "account_id": null,
    "card_program_id": null,
    "card_name": "Virtual Visa",
    "institution_name": "Citywide Bank",
    "card_holder_name": "John Smith",
    "expiry_date": "12/31/2025",
    "card_type": "credit",
    "card_network": "visa",
    "card_issuance": "virtual",
    "card_image": null,
    "mask": "6789",
    "currency_code": "USD",
    "spending_limit_atm": null,
    "spending_limit_purchase": 3000.00,
    "transaction_limit": null,
    "credit_limit": 5000.00,
    "address": [
        {
            "address_line1": "3 Downtown Street",
            "address_line2": "",
            "city": "New York",
            "state": "NY",
            "postalcode": "01191",
            "country": "US",
            "type": "billing"
        }
    ],
    "phone_number": "2123734583",
    "status": null,
    "is_primary": false,
    "is_active": true,
    "metadata": {}
}

Retrieve the information for a specific card associated with a client. The endpoint returns the card_id and details for the card specified.

HTTP REQUEST

GET /card/{card_id}

Update a card

Example Request

curl -X PUT -H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
      "client_id": "87ef9136-f7e1-4ef0-8dbc-e58bf435d11c",
      "card_name": "Virtual Visa",
      "institution_name": "Citywide Bank",
      "card_holder_name": "John Smith",
      "expiry_date": "12/31/2025",
      "card_type": "credit",
      "card_network": "visa",
      "card_issuance": "virtual",
      "mask": "6789",
      "currency_code": "USD",
      "spending_limit_purchase": 10000,
      "credit_limit": 15000,
      "address": [
        {
            "address_line1": "3 Downtown Street",
            "address_line2": "",
            "city": "New York",
            "state": "NY",
            "postalcode": "01191",
            "country": "US",
            "type": "billing"
        }
      ],
      "phone_number": "2123734583",
      "is_active": true
    }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/card/"




Example Response

{
    "id": "0233ab54-58a0-4b43-aa65-a1c32f29ad69",
    "secondary_id": null,
    "create_date": "2019-12-20T18:39:44.000+0000",
    "update_date": "2020-01-07T21:19:30.000+0000",
    "client_id": "87ef9136-f7e1-4ef0-8dbc-e58bf435d11c",
    "account_id": null,
    "card_program_id": null,
    "card_name": "Virtual Visa",
    "institution_name": "Citywide Bank",
    "card_holder_name": "John Smith",
    "expiry_date": "12/31/2025",
    "card_type": "credit",
    "card_network": "visa",
    "card_issuance": "virtual",
    "card_image": null,
    "mask": "6789",
    "currency_code": "USD",
    "spending_limit_atm": null,
    "spending_limit_purchase": 1000.00,
    "transaction_limit": null,
    "credit_limit": 15000.00,
    "address": [
        {
            "address_line1": "3 Downtown Street",
            "address_line2": "",
            "city": "New York",
            "state": "NY",
            "postalcode": "01191",
            "country": "US",
            "type": "billing"
        }
    ],
    "phone_number": "2123734583",
    "status": null,
    "is_primary": false,
    "is_active": true,
    "metadata": {}
}

Update the information for a card. The unique card_id must be provided. To obtain the appropriate card_id, use the GET /card endpoint to view all cards stored for your firm and their current information. The details to be updated must also be provided. The endpoint returns the card_id and the details for the card.

HTTP REQUEST

PUT /card/{card_id}

Delete a card

Example Request

curl -X DELETE -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/card/0233ab54-58a0-4b43-aa65-a1c32f29ad69"




Response (204 No Content)

Permanently delete a card. The unique card_id must be provided. To obtain the appropriate card_id, use the GET /card endpoint to view all cards stored for your firm. This deletes the card_id and all card record information.

HTTP REQUEST

DELETE /card/{card_id}

Funding

Funding Requests

Funding records represent requests to move money to/from a client’s account. All deposits, withdrawals, and transfers to/from the account will always be connected to a funding request.

Field Type Description
id UUID The id for the specific funding request
amount double Amount that is included in the funding request
currency_code string Alphabetic currency code for the request, limited to 3 characters. See currency codes
account_id UUID The id for the account that will be receiving the funding request
description string Description for the request, such as “Initial Funding”
bank_link_id UUID In the case that the funding request relates to a specific bank link, the id of the bank link providing the funds for the funding request
transfer_id UUID In the case that the funding request relates to the transfer of an external account into the account, the id of the transfer
portfolio_id UUID In the case that the funding request relates to a specific portfolio, the id of the portfolio where the funds are moving to/from
support_ticket_id UUID In the case that the funding request is attached to a Support Ticket in the Electron API, the id of the ticket
funding_type string The type of the funding transaction. Value may be bank_transfer, wire_transfer, cash, debit_card, credit_card, check, stock_certificate, digital_wallet, money_order, account_transfer, or other
funding_status string Status of the funding request. Value may be request_received, request_initiated, request_declined, request_cancelled, or request_completed. In the case of a recurring request, the status remains request_received until the end date of the request
frequency_unit string Frequency of the funding request defined by your firm. Value may be one_time, daily, weekly, monthly, quarterly, or annually
frequency integer Number of frequency_unit between each request. For example, if the frequency_unit is weekly and the frequency is 2, this means the funding request occurs every two weeks. Default is 1
start_date date The date that the funding request should start
end_date date In the case that the funding request is recurring, the date that the funding request should stop occurring
last_request_date date The last date a recurring deposit or withdrawal was made to/from an account
next_request_date date The next date a recurring deposit or withdrawal is scheduled to/from an account
is_deposit boolean Indicator if the funding request is a deposit. true indicates it is a deposit, false a withdrawal
is_active boolean Indicates if the funding request is currently active. Defaults to true which indicates it is active
metadata map Custom information associated with the funding request in the format key:value. See Metadata
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

List all funding requests

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/funding"

Example Response

{
    "content": [
    {
        "id": "708689ce-b0fd-4062-9954-6c8dd82707cf",
        "create_date": "2018-04-12T17:30:21.000+0000",
        "update_date": "2018-04-13T17:12:46.000+0000",
        "currency_code": "USD",
        "amount": 2000,
        "account_id": "04907eaa-3f33-49be-a35b-378cdf639fba",
        "description": "recurring funding",
        "frequency_unit": "one_time",
        "start_date": "2018-01-01",
        "end_date": "2019-01-01",
        "is_active": true,
        "is_deposit": true,
        "funding_type": "bank_transfer",
        "funding_status": "request_completed",
        "frequency": 2,
        "metadata": {}
    },
    {
        "id": "43a983e7-c930-443b-a499-53767814b07d",
        "create_date": "2018-03-19T16:06:47.000+0000",
        "update_date": "2018-03-19T16:06:47.000+0000",
        "currency_code": "USD",
        "amount": 2000,
        "account_id": "fbc03484-08e8-446d-83aa-6d6cc236355e",
        "frequency_unit": "monthly",
        "support_ticket_id": "bc2fee77-eb09-4a06-8680-2e2a2a3b0320",
        "start_date": "2018-01-01",
        "is_active": true,
        "is_deposit": true,
        "funding_type": "bank_transfer",
        "funding_status": "request_completed",
        "frequency": 2,
        "metadata": {}
    },
    {
        "id": "9f5d3254-95c5-4c9d-8fad-f47c801bb888",
        "create_date": "2018-02-28T21:58:26.000+0000",
        "update_date": "2018-03-19T16:05:40.000+0000",
        "currency_code": "USD",
        "amount": 2000,
        "account_id": "fbc03484-08e8-446d-83aa-6d6cc236355e",
        "frequency_unit": "monthly",
        "start_date": "2018-01-01",
        "is_active": true,
        "is_deposit": true,
        "funding_type": "bank_transfer",
        "funding_status": "request_completed",
        "frequency": 2,
        "metadata": {}
    }
    ],
    "last": true,
    "total_elements": 3,
    "total_pages": 1,
    "first": true,
    "sort": [
        {
            "direction": "DESC",
            "property": "updateDate",
            "ignore_case": false,
            "null_handling": "NATIVE",
            "ascending": false,
            "descending": true
        }
    ],
    "number_of_elements": 3,
    "size": 25,
    "number": 0
}

Get the information for all funding requests defined for your firm. You can filter using an account_id to return the funding requests for a specific account. Note that the metadata information is stored as a nested object within the order record object.

HTTP REQUEST

GET /funding

Create a funding request

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d '{
            "amount": 2000,
            "currency_code": "USD",
            "account_id": "fbc03484-08e8-446d-83aa-6d6cc236355e",
            "frequency_unit": "monthly",
            "start_date": "2018-01-01",
            "is_active": true,
            "is_deposit": true,
            "funding_type": "bank_transfer",
            "funding_status": "request_completed",
            "frequency": 2
      }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/funding"

Example Response

{
    "id": "9f5d3254-95c5-4c9d-8fad-f47c801bb888",
    "create_date": "2018-02-28T21:58:26.000+0000",
    "currency_code": "USD",
    "amount": 2000,
    "account_id": "fbc03484-08e8-446d-83aa-6d6cc236355e",
    "frequency_unit": "monthly",
    "start_date": "2018-01-01",
    "is_active": true,
    "is_deposit": true,
    "funding_type": "bank_transfer",
    "funding_status": "request_completed",
    "frequency": 2,
    "metadata": {}
}

Create a new funding request for an account. The unique account_id must be provided. To obtain the appropriate account_id, use the GET /account endpoint to view all the accounts defined for your firm. The create_date will default to the current date. The endpoint returns a funding_id used to manage the funding request. Note that the metadata information is stored as a nested object within the order record object.

HTTP REQUEST

POST /funding

ARGUMENTS

Parameter Type Required Description
account_id UUID required The id for the account that will be receiving the funding request
funding_type string required The type of the funding transaction. Value may be bank_transfer, wire_transfer, cash, debit_card, credit_card, check, stock_certificate, digital_wallet, money_order, account_transfer, or other
funding_status string required Status of the funding request. Value may be request_received, request_initiated, request_declined, request_cancelled, or request_completed. In the case of a recurring request, the status remains request_received until the end date of the request
frequency_unit string required Frequency of the funding request defined by your firm. Value may be one_time, daily, weekly, monthly, quarterly, or annually
is_deposit boolean required Indicates if the funding request is a deposit. true indicates it is a deposit, false a withdrawal
start_date date required The date that the funding request should start
end_date date optional In the case that the funding request is recurring, the date that the funding request should stop occurring
last_request_date date optional The last date a recurring deposit or withdrawal was made to/from an account
next_request_date date optional The next date a recurring deposit or withdrawal is scheduled to/from an account
frequency integer optional Number of frequency_unit between each request. For example, if the frequency_unit is weekly and the frequency is 2, this means the funding request occurs every two weeks. Default is 1
description string optional Description for the request, such as “Initial Funding”
currency_code string optional Alphabetic currency code for the request, limited to 3 characters. See currency codes
amount double optional Amount that is included in the funding request
bank_link_id UUID optional In the case that the funding request relates to a specific bank link, the id of the bank link providing the funds for the funding request
transfer_id UUID optional In the case that the funding request relates to the transfer of an external account into the account, the id of the transfer
support_ticket_id UUID optional In the case that the funding request is attached to a Support Ticket in the Electron API, the id of the ticket
portfolio_id UUID optional In the case that the funding request relates to a specific portfolio, the id of the portfolio where the funds are moving to/from
is_active boolean optional Indicates if the funding request is currently active. Defaults to true which indicates it is active.
metadata map optional Custom information associated with the funding request in the format key:value. See Metadata
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Retrieve a funding request

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/funding/9f5d3254-95c5-4c9d-8fad-f47c801bb888"

Example Response

{
    "id": "9f5d3254-95c5-4c9d-8fad-f47c801bb888",
    "create_date": "2018-02-28T21:58:26.000+0000",
    "update_date": "2018-03-19T16:05:40.000+0000",
    "currency_code": "USD",
    "amount": 2000,
    "account_id": "fbc03484-08e8-446d-83aa-6d6cc236355e",
    "frequency_unit": "monthly",
    "start_date": "2018-01-01",
    "is_active": true,
    "is_deposit": true,
    "funding_type": "bank_transfer",
    "funding_status": "request_completed",
    "frequency": 2,
    "metadata": {}
}

Retrieve the information for a funding request for an account. The unique funding_id must be provided. The endpoint returns the details for the funding request specified.

HTTP REQUEST

GET /funding/{funding_id}

Update a funding request

Example Request

curl -X PUT -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -d '{
          "amount": 2000,
          "account_id": "fbc03484-08e8-446d-83aa-6d6cc236355e",
          "frequency_unit": "monthly",
          "start_date": "2018-01-01",
          "is_active": true,
          "is_deposit": true,
          "funding_type": "bank_transfer",
          "funding_status": "request_completed",
          "frequency": 2
        }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/funding/9f5d3254-95c5-4c9d-8fad-f47c801bb888"

Example Response

{
    "id": "9f5d3254-95c5-4c9d-8fad-f47c801bb888",
    "create_date": "2018-02-28T21:58:26.000+0000",
    "update_date": "2018-03-19T16:05:40.000+0000",
    "currency_code": "USD",
    "amount": 2000,
    "account_id": "fbc03484-08e8-446d-83aa-6d6cc236355e",
    "frequency_unit": "monthly",
    "start_date": "2018-01-01",
    "is_active": true,
    "is_deposit": true,
    "funding_type": "bank_transfer",
    "funding_status": "request_completed",
    "frequency": 2,
    "metadata": {}
}

Update the information for a funding request for an account. The unique funding_id must be provided. To obtain the appropriate funding_id, use the GET /funding endpoint to view all funding requests defined for your firm and their current information. The details to be updated must also be provided. The endpoint returns the funding_id and all of the details for the funding request. If you wish to have the funding request no longer occur without permanently deleting it entirely, then use this endpoint to update the end_date field to the date when you wish the funding request to stop occurring. You can also use this endpoint to change the is_active field to false.

HTTP REQUEST

PUT /funding/{funding_id}

Delete a funding request

Example Request

curl -X DELETE -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/funding/9f5d3254-95c5-4c9d-8fad-f47c801bb888"

Response (204 No Content)

Permanently delete a funding request defined for an account. The unique funding_id must be provided. To obtain the appropriate funding_id, use the GET /funding endpoint to view all funding requests for your firm. Deletes the funding_id and the funding request record. If you wish to have the funding request no longer occur without permanently deleting it entirely, then use the PUT /funding/{funding_id} endpoint to update the end_date field to the date when you wish the funding request to stop occurring. You can also use the PUT /funding/{funding_id} endpoint to change the is_active field to false.

HTTP REQUEST

DELETE /funding/{funding_id}

Bank links are established connections between a client’s account on your platform and his or her bank account. They are used to transfer funds from the bank account to the account on your platform.

Field Type Description
id UUID The id for the specific bank link
bank_account_holder string Name of the individual that owns the bank account
bank_account_number string Account number of the bank account
name string Name of the bank for this bank link, e.g. HSBC
routing string Routing number of the bank for this bank link
routing_wire string Routing number of the bank for the bank link used for wire transfers
mask string The masked version of the bank account number for this bank link
bank_account_name string Name of the bank account, e.g. Mike’s HSBC Checking
client_id UUID The id for the client to which the bank link belongs
account_id UUID The id for the account to which the bank link belongs
currency_code string Alphabetic currency code for the base currency of the bank account linked, limited to 3 characters. See currency codes
balance string Current balance of the bank account
available_balance string Available balance of the bank account, usually taking into consideration pending transactions or available overdraft
type string Used to indicate the type of bank account for this bank link such as a ‘savings’ account
is_default boolean Indicates if the bank link is the default link for a client. Only one bank link may be default for a client_id. If a user sets a bank link to is_default = “true” then all other bank links for that client_id will be set to is_default = “false.” Defaults to false which indicates the bank link is not default
is_active boolean Indicates if the bank link is active. Defaults to true which indicates it is active
is_link_verified boolean Indicates if the bank link has been verified. Defaults to false which indicates it has not been verified
link_verified_date date Date and time that the bank link was verified
metadata map Custom information associated with the bank link in the format key:value. See Metadata
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the record was created. Defaults to the current date
update_date timestamp Timestamp for the date and time that the record was last updated

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/bank_link"

Example Response

{
  "content":
  [
    {
      "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_default": false,
      "is_active": true,
      "is_link_verified": true,
      "link_verified_date": "2018-01-01",
      "type": "Checking",
      "metadata": {}
    },
    {
      "id": "425a2f77-b24b-4d93-ba13-a7b6bd01e947",
      "create_date": "2018-04-12T17:34:17.000+0000",
      "update_date": "2018-04-12T17:34:17.000+0000",
      "account_id": "272d9271-be64-4eb8-a3f4-abc57ca547c2",
      "bank_account_holder": "Andrew Williams",
      "bank_account_number": "2552001002",
      "mask": "xxxxxx1002",
      "bank_account_name": "Bank 2 - Checking Account",
      "name": "Bank XYZ2",
      "routing": "5289786002",
      "currency_code": "USD",
      "balance": "36754.04",
      "available_balance": "35754.04",
      "is_default": false,
      "is_active": true,
      "is_link_verified": true,
      "link_verified_date": "2018-02-10",
      "metadata": {}
    },
    {
      "id": "d787cf19-d11c-49f2-abf3-f5fec1b101d4",
      "create_date": "2018-04-09T20:46:14.000+0000",
      "update_date": "2018-04-09T20:46:14.000+0000",
      "account_id": "199a8c08-cdd5-4c8c-8abf-535447cea11b",
      "bank_account_holder": "JB Smith",
      "bank_account_number": "2552001001",
      "mask": "xxxxxx1001",
      "bank_account_name": "Bank XYZ - Checking Account1",
      "name": "Bank XYZ",
      "routing": "5289786000",
      "routing_wire": "5289786011",
      "currency_code": "USD",
      "balance": "36760.00",
      "available_balance": "35760.00",
      "type": "Checking",
      "is_default": false,
      "is_active": true,
      "is_link_verified": true,
      "link_verified_date": "2018-02-10",
      "metadata": {}
    }
  ],
    "total_elements": 3,
    "last": true,
    "total_pages": 1,
    "first": true,
    "sort": [
        {
            "direction": "DESC",
            "property": "updateDate",
            "ignore_case": false,
            "null_handling": "NATIVE",
            "ascending": false,
            "descending": true
        }
    ],
    "number_of_elements": 16,
    "size": 25,
    "number": 0
}

Get all bank links defined for all clients defined for your firm. The endpoint returns a list of UUIDs with details defined for each bank link. You can filter using an account_id to return the bank link(s) for a specific account.

HTTP REQUEST

GET /bank_link

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -d '{
              "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"
          }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/bank_link"

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_default": false,
    "is_active": true,
    "is_link_verified": true,
    "link_verified_date": "2018-01-01",
    "metadata": {}
}

Create a new bank link for an account. The unique account_id must be provided. To obtain the appropriate account_id, use the GET /account endpoint to view all the accounts defined for your firm. The create_date will default to the current date. The endpoint returns a bank_link_id used to manage the bank link going forward.

HTTP REQUEST

POST /bank_link

ARGUMENTS

Parameter Type Required Description
bank_account_holder string required Name of the individual that owns the bank account
bank_account_number string required Account number of the bank account
name string required Name of the bank for the bank link, e.g. HSBC
routing string required Routing number of the bank for the bank link
routing_wire string optional Routing number of the bank for the bank link used for wire transfers
mask string optional The masked version of the bank account number for this bank link
bank_account_name string optional Name of the bank account, e.g. Mike’s HSBC Checking
client_id UUID optional The id for the client to which the bank link belongs
account_id UUID optional The id for the account to which the bank link belongs
currency_code string optional Alphabetic currency code for the base currency of the bank account linked, limited to 3 characters. See currency codes
balance string optional Current balance of the bank account
available_balance string optional Available balance of the bank account, usually taking into consideration pending transactions or available overdraft
type string optional Used to indicate the type of bank account for this bank link such as a ‘savings’ account
is_default boolean optional Indicates if the bank link is the default link for a client. Only one bank link may be default for a client_id. If a user sets a bank link to is_default = “true” then all other bank links for that client_id will be set to is_default = “false.” Defaults to false which indicates the bank link is not default
is_active boolean optional Indicates if the bank link is active. Defaults to true which indicates it is active
is_link_verified boolean optional Indicates if the bank link has been verified. Defaults to false which indicates it has not been verified
link_verified_date date optional Date and time that the bank link was verified
metadata map optional Custom information associated with the bank link in the format key:value. See Metadata
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/bank_link/d787cf19-d11c-49f2-abf3-f5fec1b101d4"

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_default": false,
    "is_active": true,
    "is_link_verified": true,
    "link_verified_date": "2018-01-01",
    "metadata": {}
}

Retrieve the information for a bank link for an account. The unique bank_link_id must be provided. The endpoint returns the details for the bank link specified.

HTTP REQUEST

GET /bank_link/{bank_link_id}

Example Request

curl -X PUT -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -d '{
                "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": "1600",
                "available_balance": "1600",
                "type": "Checking",
                "is_active": true,
                "is_link_verified": true,
                "link_verified_date": "2018-01-01",
                "metadata": {}
           }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/bank_link/d787cf19-d11c-49f2-abf3-f5fec1b101d4"

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": "1600",
    "available_balance": "1600",
    "type": "Checking",
    "is_default": false,
    "is_active": true,
    "is_link_verified": true,
    "link_verified_date": "2018-01-01",
    "metadata": {}
}

Update the information for a bank link for an account. The unique bank_link_id must be provided. To obtain the appropriate bank_link_id, use the GET /bank_link endpoint to view all the bank links defined for your firm and their current information. The details to be updated must also be provided. The endpoint returns the bank_link_id and all of the details for the bank link. If you wish to have a bank link be no longer available for use without permanently deleting it entirely, then use this endpoint to update the is_active field to false.

HTTP REQUEST

PUT /bank_link/{bank_link_id}

Example Request

curl -X DELETE -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/bank_link/d787cf19-d11c-49f2-abf3-f5fec1b101d4"

Response (204 No Content)

Permanently delete a bank link defined for an account. The unique bank_link_id must be provided. To obtain the appropriate bank_link_id, use the GET /bank_link endpoint to view all the bank links defined for your firm. This will delete the bank_link_id and the associated information so that the bank link can no longer be used. If you wish to have the bank link be no longer available for use without permanently deleting it entirely, then use the PUT /bank_link/{bank_link_id} endpoint to update the is_active field to mark the bank_link_id as inactive.

HTTP REQUEST

DELETE /bank_link/{bank_link_id}

Deposit

Deposits represent transactions to add funds to be invested into a client’s account. The transactions are often recurring to continue to increase the funds the client is investing.

Field Type Description
id UUID The id for the specific deposit request
account_id UUID The id for the account that is the destination of the deposit
amount double Amount that is being deposited
currency_code string Alphabetic currency code for the request, limited to 3 characters. See currency codes
funding_id UUID The id of the funding record that maps to this deposit
portfolio_id UUID In the case that the deposit relates to a specific portfolio, the id of the portfolio where the funds are being deposited
invested_date timestamp Date and time that the funds should be pulled from the funding request to be invested
account_number string Bank account number that is the source of the deposit
comments string Comment for the deposit such as “Funded”
direction string Label to indicate the direction of the transaction such as “Incoming” or “Outgoing”
last_request_date timestamp In the case of recurring deposits, the last date and time that the deposit was last requested
received_date timestamp Date and time that the deposit was received into the account
status string Status of the deposit transaction such as “Processing”. Use this field to track the status of the individual deposit if it is associated with a recurring Funding request
status_time_stamp timestamp Date and time that the status of the record was last updated
type string Indicates the payment type such as “check, “wire”, etc.
metadata map Custom information associated with the entity in the format key:value
See Metadata
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

List all deposit requests

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/deposit"

Example Response

{
  "content": [
        {
            "id": "1a2bb85f-c1b4-41d5-9bf3-e23cce54b71c",
            "create_date": "2018-03-19T16:09:38.000+0000",
            "update_date": "2018-03-19T16:09:38.000+0000",
            "currency_code": "USD",
            "amount": 2000,
            "funding_id": "43a983e7-c930-443b-a499-53767814b07d",
            "account_id": "fbc03484-08e8-446d-83aa-6d6cc236355e",
            "comments" : "Add to 2018 IRA",
            "invested_date": "2018-04-02T09:00:00.000+0000",
            "last_request_date": "2018-04-01T09:00:00.000+0000",
            "received_date": "2018-03-01T17:00:00.000+0000",
            "metadata": {}
        },
        {
            "id": "c1df397e-17c0-4fab-a61f-367f7ff90f57",
            "create_date": "2018-03-19T15:16:50.000+0000",
            "update_date": "2018-03-19T16:08:59.000+0000",
            "currency_code": "USD",
            "amount": 2000,
            "funding_id": "43a983e7-c930-443b-a499-53767814b07d",
            "account_id": "fbc03484-08e8-446d-83aa-6d6cc236355e",
            "comments" : "Add to 2018 IRA",
            "invested_date": "2018-03-02T09:00:00.000+0000",
            "last_request_date": "2018-03-01T09:00:00.000+0000",
            "received_date": "2018-03-01T17:00:00.000+0000",
            "metadata": {}
        },
        {
            "id": "08e5f077-0c8c-4831-a4cc-3a7a59e067d2",
            "create_date": "2018-03-19T15:16:47.000+0000",
            "update_date": "2018-03-19T15:16:47.000+0000",
            "currency_code": "USD",
            "amount": 2000,
            "funding_id": "9f5d3254-95c5-4c9d-8fad-f47c801bb888",
            "account_id": "fbc03484-08e8-446d-83aa-6d6cc236355e",
            "comments" : "Add to 2018 IRA",
            "invested_date": "2018-02-01T09:00:00.000+0000",
            "last_request_date": "2018-02-01T09:00:00.000+0000",
            "received_date": "2018-02-01T17:00:00.000+0000",
            "metadata": {}
        }
  ],
  "total_elements": 3,
  "last": true,
  "total_pages": 1,
  "first": true,
  "sort": [
      {
          "direction": "DESC",
          "property": "updateDate",
          "ignore_case": false,
          "null_handling": "NATIVE",
          "ascending": false,
          "descending": true
      }
    ],
    "number_of_elements": 4,
    "size": 25,
    "number": 0
}

Get the information for all deposit requests for all clients. The endpoint returns a list of UUIDs and details for each deposit request. You can filter using the account_id to view deposit requests for a specific account.

HTTP REQUEST

GET /deposit

Create a deposit request

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d '{
            "amount": 2000,
            "funding_id": "9f5d3254-95c5-4c9d-8fad-f47c801bb888",
            "account_id": "fbc03484-08e8-446d-83aa-6d6cc236355e",
            "comments" : "Add to 2018 IRA",
            "invested_date": "2018-02-01T09:00:00.000+0000",
            "last_request_date": "2018-02-01T09:00:00.000+0000",
            "received_date": "2018-02-01T17:00:00.000+0000"
        }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/deposit"

Example Response

{
    "id": "08e5f077-0c8c-4831-a4cc-3a7a59e067d2",
    "create_date": "2018-03-19T15:16:47.000+0000",
    "currency_code": "USD",
    "amount": 2000,
    "funding_id": "9f5d3254-95c5-4c9d-8fad-f47c801bb888",
    "account_id": "fbc03484-08e8-446d-83aa-6d6cc236355e",
    "comments" : "Add to 2018 IRA",
    "invested_date": "2018-02-01T09:00:00.000+0000",
    "last_request_date": "2018-02-01T09:00:00.000+0000",
    "received_date": "2018-02-01T17:00:00.000+0000",
    "metadata": {}
}

Create a new deposit request for an account. The unique account_id for the deposit must be provided. To obtain the appropriate account_id, use the GET /account endpoint to view all the accounts defined for your firm. The create_date will default to the current date. The endpoint returns a unique deposit_id used to manage the deposit request.

HTTP REQUEST

POST /deposit

ARGUMENTS

Parameter Type Required Description
account_id UUID required The id for the account that is the destination of the deposit
amount double required Amount that is being deposited
funding_id UUID required The id of the funding record that maps to this deposit
currency_code string optional Alphabetic currency code for the request, limited to 3 characters. See currency codes
invested_date timestamp optional Date and time that the funds should be pulled from the funding request to be invested
portfolio_id UUID optional In the case that the deposit relates to a specific portfolio, the id of the portfolio where the funds are being deposited
account_number string optional Bank account number that is the source of the deposit
comments string optional Comment for the deposit such as “Funded”
direction string optional Label to indicate the direction of the transaction such as “Incoming” or “Outgoing”
last_request_date timestamp optional In the case of recurring deposits, the last date and time that the deposit was last requested
received_date timestamp optional Date and time that the deposit was received into the account
status string optional Status of the deposit transaction such as “Processing”. Use this field to track the status of the individual deposit if it is associated with a recurring Funding request
status_time_stamp timestamp optional Date and time that the record was last updated
type string optional Indicates the payment type such as “check, “wire”, etc.
metadata map optional Custom information associated with the entity in the format key:value
See Metadata
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Retrieve a deposit request

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/deposit/08e5f077-0c8c-4831-a4cc-3a7a59e067d2"

Example Response

{
    "id": "08e5f077-0c8c-4831-a4cc-3a7a59e067d2",
    "create_date": "2018-03-19T15:16:47.000+0000",
    "update_date": "2018-03-19T15:16:47.000+0000",
    "funding_id": "9f5d3254-95c5-4c9d-8fad-f47c801bb888",
    "currency_code": "USD",
    "amount": 2000,
    "account_id": "fbc03484-08e8-446d-83aa-6d6cc236355e",
    "comments" : "Add to 2018 IRA",
    "invested_date": "2018-02-01T09:00:00.000+0000",
    "last_request_date": "2018-02-01T09:00:00.000+0000",
    "received_date": "2018-02-01T17:00:00.000+0000",
    "metadata": {}
}

Retrieve the information for a deposit request for an account. The unique deposit_id must be provided. The endpoint returns details for the deposit request specified.

HTTP REQUEST

GET /deposit/{deposit_id}

Update a deposit request

Example Request

curl -X PUT -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d '{
            "account_number": "569345",
            "funding_id": "9f5d3254-95c5-4c9d-8fad-f47c801bb888",
            "amount": 2000,
            "account_id": "fbc03484-08e8-446d-83aa-6d6cc236355e",
            "comments" : "Add to 2018 IRA",
            "invested_date": "2018-02-01T09:00:00.000+0000",
            "last_request_date": "2018-02-01T09:00:00.000+0000",
            "received_date": "2018-02-01T17:00:00.000+0000"
        }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/deposit/08e5f077-0c8c-4831-a4cc-3a7a59e067d2"

Example Response

{
    "id": "08e5f077-0c8c-4831-a4cc-3a7a59e067d2",
    "create_date": "2018-03-19T15:16:47.000+0000",
    "update_date": "2018-03-19T15:16:47.000+0000",
    "account_number": "569345",
    "funding_id": "9f5d3254-95c5-4c9d-8fad-f47c801bb888",
    "currency_code": "USD",
    "amount": 2000,
    "account_id": "fbc03484-08e8-446d-83aa-6d6cc236355e",
    "comments" : "Add to 2018 IRA",
    "invested_date": "2018-02-01T09:00:00.000+0000",
    "last_request_date": "2018-02-01T09:00:00.000+0000",
    "received_date": "2018-02-01T17:00:00.000+0000",
    "metadata": {}
}

Update the information for a deposit request for an account. The unique deposit_id must be provided. To obtain the appropriate deposit_id, use the GET /deposit endpoint to view all the bank links defined for your firm and their current information. The details to be updated must also be provided. The endpoint returns the deposit_id and all of the details for the deposit request.

HTTP REQUEST

PUT /deposit/{deposit_id}

Delete a deposit request

Example Request

curl -X DELETE -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/deposit/08e5f077-0c8c-4831-a4cc-3a7a59e067d2"

Response (204 No Content)

Permanently delete a deposit request for an account. The unique deposit_id must be provided. To obtain the appropriate deposit_id, use the GET /deposit endpoint to view all deposit requests defined for your firm. This deletes the deposit_id and deposit request record.

HTTP REQUEST

DELETE /deposit/{deposit_id}

Withdrawal

Withdrawal requests represent transactions to remove funds from a client’s account, usually to deposit in another account on the platform or to transfer to an external account.

Field Type Description
id UUID The id for the specific withdrawal request
account_id UUID The id for the account that is the destination of the withdrawal
amount double Amount that is being withdrawn from the account
currency_code string Alphabetic currency code for the request, limited to 3 characters. See currency codes
funding_id UUID The id of the funding record that maps to this withdrawal
portfolio_id UUID In the case that the withdrawal relates to a specific portfolio, the id of the portfolio where the funds are being withdrawn from
withdrawal_date timestamp Date and time that the withdrawal was made
account_number string Bank account number that is the destination of the withdrawal
comments string Comment for the withdrawal such as “Funded”
direction string Label to indicate the direction of the transaction such as “Incoming” or “Outgoing”
fees string Any fees associated with the withdrawal, especially for an investment account
last_request_date timestamp In the case of recurring withdrawals, the date and time that the withdrawal was last requested
received_date timestamp Date and time that the withdrawal was received
status string Status of the transaction such as “Processing”
status_time_stamp timestamp Date and time that the status of the record was last updated
type string Indicates the payment type such as “check, “wire”, etc.
metadata map Custom information associated with the entity in the format key:value
See Metadata
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

List all withdrawal requests

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/withdrawal"

Example Response

{
  "content": [
      {
        "id": "be07c93a-c0b0-4fb0-97e1-3a0f77b8c969",
        "create_date": "2018-02-07T19:29:37.000+0000",
        "update_date": "2018-02-12T09:00:00.000+0000",
        "account_id": "c368c2f3-da36-480c-9193-bf75adf16274",
        "funding_id": "4cc15366-def0-4b39-b9b7-840a67ff9a88",
        "account_number": "bKU8LQ6gI",
        "currency_code": "USD",
        "amount": 1000.00,
        "comments": "Funds will settle on 2/11/18",
        "fees": "0",
        "last_request_date": "2018-02-10T09:00:00.000+0000",
        "received_date": "2018-02-10T09:00:00.000+0000",
        "status": "In Progress",
        "status_time_stamp": "2018-02-12T09:00:00.000+0000",
        "type": "wire",
        "withdrawal_date": "2018-02-10T10:00:00.000+0000",
        "metadata": {}
      }
  ],
  "last": true,
  "total_pages": 1,
  "total_elements": 1,
  "first": true,
  "sort": [
    {
      "direction": "DESC",
      "property": "id",
      "ignore_case": false,
      "null_handling": "NATIVE",
      "descending": true,
      "ascending": false
    }
  ],
  "number_of_elements": 1,
  "size": 25,
  "number": 0
}

Get the information for all withdrawal requests for all clients. The endpoint returns a list of UUIDs and details for each withdrawal request. You can filter using the account_id to view withdrawal requests for a specific account.

HTTP REQUEST

GET /withdrawal

Create a withdrawal request

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d '{
            "account_id": "c368c2f3-da36-480c-9193-bf75adf16274",
            "funding_id": "4cc15366-def0-4b39-b9b7-840a67ff9a88",
            "account_number": "bKU8LQ6gI",
            "currency_code": "USD",
            "amount": 1000.00,
            "comments": "Funds will settle on 2/12/18",
            "fees": "0",
            "last_request_date": "2018-02-10T09:00:00.000+0000",
            "received_date": "2018-02-10T09:00:00.000+0000",
            "status": "Cleared",
            "status_time_stamp": "2018-02-12T09:00:00.000+0000",
            "type": "wire",
            "withdrawal_date": "2018-02-10T10:00:00.000+0000"
        }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/withdrawal"

Example Response

{
    "id": "be07c93a-c0b0-4fb0-97e1-3a0f77b8c969",
    "create_date": "2018-02-12T09:00:00.000+0000",
    "account_id": "c368c2f3-da36-480c-9193-bf75adf16274",
    "funding_id": "4cc15366-def0-4b39-b9b7-840a67ff9a88",
    "account_number": "bKU8LQ6gI",
    "currency_code": "USD",
    "amount": 1000.00,
    "comments": "Funds will settle on 2/12/18",
    "fees": "0",
    "last_request_date": "2018-02-10T09:00:00.000+0000",
    "received_date": "2018-02-10T09:00:00.000+0000",
    "status": "Cleared",
    "status_time_stamp": "2018-02-12T09:00:00.000+0000",
    "type": "wire",
    "withdrawal_date": "2018-02-10T10:00:00.000+0000",
    "metadata": {}
}

Create a new withdrawal request for an account. The unique account_id for the withdrawal must be provided. To obtain the appropriate account_id, use the GET /account endpoint to view all the accounts defined for your firm. The create_date will default to the current date. The endpoint returns a unique withdrawal_id used to manage the withdrawal request.

HTTP REQUEST

POST /withdrawal

ARGUMENTS

Parameter Type Required Description
account_id UUID required The id for the account that is the destination of the withdrawal
amount double required Amount that is being withdrawn from the account
funding_id UUID required The id of the funding record that maps to this withdrawal
withdrawal_date timestamp required Date and time that the withdrawal was made
currency_code string optional Alphabetic currency code for the request, limited to 3 characters. See currency codes
portfolio_id UUID optional In the case that the withdrawal relates to a specific portfolio, the id of the portfolio where the funds are being withdrawn from
account_number string optional Bank account number that is the destination of the withdrawal
comments string optional Comment for the withdrawal such as “Funded”
direction string optional Label to indicate the direction of the transaction such as “Incoming” or “Outgoing”
fees string optional Any fees associated with the withdrawal, especially for an investment account
last_request_date timestamp optional In the case of recurring withdrawals, the date and time that the withdrawal was last requested
received_date timestamp optional Date and time that the withdrawal was received
status string optional Status of the transaction such as “Processing”
status_time_stamp timestamp optional Date and time that the status of the record was last updated
type string optional Indicates the payment type such as “check, “wire”, etc.
metadata map optional Custom information associated with the entity in the format key:value
See Metadata
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Retrieve a withdrawal request

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/withdrawal/be07c93a-c0b0-4fb0-97e1-3a0f77b8c969"

Example Response

{
    "id": "be07c93a-c0b0-4fb0-97e1-3a0f77b8c969",
    "create_date": "2018-02-07T19:29:37.000+0000",
    "update_date": "2018-02-12T09:00:00.000+0000",
    "account_id": "c368c2f3-da36-480c-9193-bf75adf16274",
    "account_number": "bKU8LQ6gI",
    "currency_code": "USD",
    "amount": 1000.00,
    "comments": "Funds will settle on 2/12/18",
    "fees": "0",
    "last_request_date": "2018-02-10T09:00:00.000+0000",
    "received_date": "2018-02-10T09:00:00.000+0000",
    "status": "Cleared",
    "status_time_stamp": "2018-02-12T09:00:00.000+0000",
    "type": "wire",
    "withdrawal_date": "2018-02-10T10:00:00.000+0000",
    "funding_id": "4cc15366-def0-4b39-b9b7-840a67ff9a88",
    "metadata": {}
}

Retrieve the information for a withdrawal request for an account. The unique withdrawal_id must be provided. The endpoint returns the details for the withdrawal request specified.

HTTP REQUEST

GET /withdrawal/{withdrawal_id}

Update a withdrawal request

Example Request

curl -X PUT -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d '{
            "account_id": "c368c2f3-da36-480c-9193-bf75adf16274",
            "account_number": "bKU8LQ6gI",
            "amount": 1000.00,
            "comments": "Funds will settle on 2/12/18",
            "fees": "0",
            "last_request_date": "2018-02-10T09:00:00.000+0000",
            "received_date": "2018-02-10T09:00:00.000+0000",
            "status": "Cleared",
            "status_time_stamp": "2018-02-12T09:00:00.000+0000",
            "type": "wire",
            "withdrawal_date": "2018-02-10T10:00:00.000+0000",
            "funding_id": "4cc15366-def0-4b39-b9b7-840a67ff9a88"
        }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/withdrawal/be07c93a-c0b0-4fb0-97e1-3a0f77b8c969"

Example Response

{
    "id": "be07c93a-c0b0-4fb0-97e1-3a0f77b8c969",
    "create_date": "2018-02-07T19:29:37.000+0000",
    "update_date": "2018-02-12T09:00:00.000+0000",
    "account_id": "c368c2f3-da36-480c-9193-bf75adf16274",
    "account_number": "bKU8LQ6gI",
    "currency_code": "USD",
    "amount": 1000.00,
    "comments": "Funds will settle on 2/12/18",
    "fees": "0",
    "last_request_date": "2018-02-10T09:00:00.000+0000",
    "received_date": "2018-02-10T09:00:00.000+0000",
    "status": "Cleared",
    "status_time_stamp": "2018-02-12T09:00:00.000+0000",
    "type": "wire",
    "withdrawal_date": "2018-02-10T10:00:00.000+0000",
    "funding_id": "4cc15366-def0-4b39-b9b7-840a67ff9a88",
    "metadata": {}
}

Update the information for a withdrawal request for an account. The unique withdrawal_id must be provided. To obtain the appropriate withdrawal_id, use the GET /withdrawal endpoint to view all withdrawal requests defined for your firm and their current information. The details to be updated must also be provided. The endpoint returns the withdrawal_id and all of the details for the withdrawal request.

HTTP REQUEST

PUT /withdrawal/{withdrawal_id}

Delete a withdrawal request

Example Request

curl -X DELETE -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/withdrawal/be07c93a-c0b0-4fb0-97e1-3a0f77b8c969"

Response (204 No Content)

Permanently delete a withdrawal request from an account. The unique withdrawal_id must be provided. To obtain the appropriate withdrawal_id, use the GET /withdrawal endpoint to view all withdrawal requests defined for your firm. This deletes the withdrawal_id and the withdrawal request record.

HTTP REQUEST

DELETE /withdrawal/{withdrawal_id}

Transfer

External account transfer represent links between an external account (ex. an external retirement investing account such as a Roth IRA) to a client account on your firm’s platform to transfer funds or existing holdings. External account transfers are used for funding purposes similar to bank links.

Field Type Description
id UUID The id for the specific transfer
account_id UUID The id of the account to which the transfer belongs
account_holder string Name of the individual that is the owner of the external account
account_number string Account number for the external account that is the source of the funds
account_type_id UUID The id for the type of the account on your platform
firm_name string Name of the firm that previously held or holds the external account
transfer_all_cash boolean Indicator if the external account should be entirely converted to cash to be transferred.
amount double Amount that is transferred
currency_code string Alphabetic currency code for the request, limited to 3 characters. See currency codes
comment string Comment for the transfer such as “Funded”
dtc_number string Number of the Deposit Trust Company (DTC)’s that held or holds the external account usually in the case of an Individual Retirement Account (IRA) in the United States
roth_five_year integer In the case that the account is a United States Roth IRA account, the year it was opened (e.g. 2010)
status string Status of the transfer such as “Pending”
status_time_stamp timestamp Timestamp for the date and time that the status was last updated
transfer_type string Type of transfer being made. Value may be partial or full
transfer_date date Date that the transfer will be initiated. Defaults to the current date
received_date timestamp Timestamp for the date and time that the transfer was received
metadata map Custom information associated with the entity in the format key:value
See Metadata
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

List all transfer requests

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/transfer"

Example Response

{
    "content": [
        {
            "id": "111d714c-1d1c-47cf-9cb7-760428e86c24",
            "transfer_date": "2019-03-21",
            "create_date": "2018-04-09T21:02:11.000+0000",
            "update_date": "2018-04-09T21:02:11.000+0000",
            "account_holder": "JB Smith",
            "account_number": "5889632503",
            "currency_code": "USD",
            "amount": 13000,
            "comment": "Closed down previous 401k",
            "firm_name": "Vanguard",
            "status": "Pending",
            "status_time_stamp": "2018-04-09T21:02:11.000+0000",
            "transfer_all_cash": true,
            "transfer_type": "full",
            "account_id": "099961da-7f41-4309-950f-2b51689a0033",
            "account_type_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
            "metadata": {}
        },
        {
            "id": "1b19a750-f3c6-46e7-9131-fe11f06314ea",
            "transfer_date": "2018-04-08",
            "received_date": "2018-04-09T20:52:07.000+0000",
            "create_date": "2018-04-09T20:52:07.000+0000",
            "update_date": "2018-04-09T20:52:07.000+0000",
            "account_holder": "John Smith",
            "account_number": "5889632592",
            "currency_code": "USD",
            "amount": 13000,
            "comment": "Closed down previous 401k",
            "firm_name": "Vanguard",
            "status": "Pending",
            "transfer_all_cash": true,
            "transfer_type": "full",
            "account_id": "04907eaa-3f33-49be-a35b-378cdf639fba",
            "account_type_id": "eb3d7f60-a133-4ca9-815f-3677bcdc23a3",
            "metadata": {}
        },
        {
            "id": "93197309-ff29-458a-ac9d-ad24ac2d95c9",
            "transfer_date": "2018-04-08",
            "received_date": "2018-04-09T20:29:04.000+0000",
            "create_date": "2018-04-09T20:29:04.000+0000",
            "update_date": "2018-04-09T20:29:04.000+0000",
            "account_holder": "Dan Lars",
            "account_number": "6009632590",
            "currency_code": "USD",
            "amount": 34000,
            "comment": "Closed down previous 401k",
            "firm_name": "Vanguard",
            "status": "Pending",
            "transfer_all_cash": true,
            "account_id": "107516c3-9035-4811-af7c-501be5a1fe26",
            "account_type_id": "39770e8d-890d-485b-822e-5a1578f26d47",
            "metadata": {}
        }
    ],
    "total_elements": 3,
    "last": true,
    "total_pages": 1,
    "first": true,
    "sort": [
        {
            "direction": "DESC",
            "property": "updateDate",
            "ignore_case": false,
            "null_handling": "NATIVE",
            "ascending": false,
            "descending": true
        }
    ],
    "number_of_elements": 5,
    "size": 25,
    "number": 0
}

Get the information for all external account transfers defined for your firm. The endpoint returns a list of UUIDs and details for each external account transfer. You can filter by account_id to view external account transfers for a specific account.

HTTP REQUEST

GET /transfer

Create a transfer request

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "account_holder": "JB Smith",
        "account_number": "5889632503",
        "currency_code": "USD",
        "amount": 13000,
        "comment": "Closed down previous 401k",
        "firm_name": "Vanguard",
        "dtc_number" : "345928204",
        "status": "Pending",
        "status_time_stamp": "2018-04-09T21:02:11.000+0000",
        "transfer_all_cash": true,
        "transfer_type": "full",
        "transfer_date": "2019-03-21",
        "account_id": "099961da-7f41-4309-950f-2b51689a0033",
        "account_type_id": "647c54c3-b649-477e-8cc7-eee56a120dd3"
     }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/transfer"

Example Response

{
    "id": "111d714c-1d1c-47cf-9cb7-760428e86c24",
    "transfer_date": "2019-03-21",
    "create_date": "2018-04-09T21:02:11.000+0000",
    "account_holder": "JB Smith",
    "account_number": "5889632503",
    "currency_code": "USD",
    "amount": 13000,
    "comment": "Closed down previous 401k",
    "firm_name": "Vanguard",
    "dtc_number" : "345928204",
    "status": "Pending",
    "status_time_stamp": "2018-04-09T21:02:11.000+0000",
    "transfer_all_cash": true,
    "transfer_type": "full",
    "account_id": "099961da-7f41-4309-950f-2b51689a0033",
    "account_type_id": "647c54c3-b649-477e-8cc7-eee56a120dd3"
}

Create a new external account transfer for a client account. The unique account_id must be provided. To obtain the appropriate account_id, use the GET /account endpoint to view all accounts defined for your firm. The create_date will default to the current date. The endpoint returns a unique transfer_id used to manage the deposit request.

HTTP REQUEST

POST /transfer

ARGUMENTS

Parameter Type Required Description
account_id UUID required The id of the account to which the transfer belongs
account_holder string required Name of the individual that is the owner of the external account
account_number string required Account number for the external account that is the source of the funds
account_type_id UUID required The id for the type of the account on your platform
firm_name string required Name of the firm that previously held or holds the external account
transfer_all_cash boolean required Indicator if the external account should be entirely converted to cash to be transferred.
amount double optional Amount that is transferred
currency_code string optional Alphabetic currency code for the request, limited to 3 characters. See currency codes
comment string optional Comment for the transfer such as “Funded”
dtc_number string optional Number of the Deposit Trust Company (DTC)’s that held or holds the external account usually in the case of an Individual Retirement Account (IRA) in the United States
roth_five_year integer optional In the case that the account is a United States Roth IRA account, the year it was opened (e.g. 2010)
status string optional Status of the transfer such as “Pending”
transfer_type string optional Type of transfer being made. Value may be partial or full
transfer_date date optional Date that the transfer will be initiated. Defaults to the current date
metadata map optional Custom information associated with the entity in the format key:value
See Metadata
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Retrieve a transfer request

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/transfer/111d714c-1d1c-47cf-9cb7-760428e86c24"

Example Response

{
    "id": "111d714c-1d1c-47cf-9cb7-760428e86c24",
    "transfer_date": "2019-03-21",
    "create_date": "2018-04-09T21:02:11.000+0000",
    "update_date": "2018-04-09T21:02:11.000+0000",
    "account_holder": "JB Smith",
    "account_number": "5889632503",
    "currency_code": "USD",
    "amount": 13000,
    "comment": "Closed down previous 401k",
    "firm_name": "Vanguard",
    "dtc_number" : "345928204",
    "status": "Pending",
    "status_time_stamp": "2018-04-09T21:02:11.000+0000",
    "transfer_all_cash": true,
    "transfer_type": "full",
    "account_id": "099961da-7f41-4309-950f-2b51689a0033",
    "account_type_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
    "metadata": {}
}

Retrieve the information for an external account transfer for an account. The unique transfer_id must be provided. The endpoint returns the details for the external account transfer specified.

HTTP REQUEST

GET /transfer/{transfer_id}

Update a transfer request

Example Request

curl -X PUT -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d '{
            "account_holder": "JB Smith",
            "account_number": "5889632503",
            "amount": 13000,
            "comment": "Closed down previous 401k",
            "firm_name": "Vanguard",
            "dtc_number" : "345928204",
            "status": "Pending",
            "status_time_stamp": "2018-04-09T21:02:11.000+0000",
            "transfer_all_cash": true,
            "transfer_type": "full",
            "transfer_date": "2019-03-21",
            "account_id": "099961da-7f41-4309-950f-2b51689a0033",
            "account_type_id": "647c54c3-b649-477e-8cc7-eee56a120dd3"
        }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/transfer/111d714c-1d1c-47cf-9cb7-760428e86c24"

Example Response

{
    "id": "111d714c-1d1c-47cf-9cb7-760428e86c24",
    "transfer_date": "2019-03-21",
    "create_date": "2018-04-09T21:02:11.000+0000",
    "update_date": "2018-04-09T21:02:11.000+0000",
    "account_holder": "JB Smith",
    "account_number": "5889632503",
    "currency_code": "USD",
    "amount": 13000,
    "comment": "Closed down previous 401k",
    "firm_name": "Vanguard",
    "dtc_number" : "345928204",
    "status": "Pending",
    "status_time_stamp": "2018-04-09T21:02:11.000+0000",
    "transfer_all_cash": true,
    "transfer_type": "full",
    "account_id": "099961da-7f41-4309-950f-2b51689a0033",
    "account_type_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
    "metadata": {}
}

Update the information for an external account transfer for a client account. The unique transfer_id must be provided. To obtain the appropriate transfer_id, use the GET /transfer endpoint to view all external account transfer requests defined for your firm and their current information. The details to be updated must also be provided. The endpoint returns the transfer_id and all of the details for the external account transfer.

HTTP REQUEST

PUT /transfer/{transfer_id}

Delete a transfer request

Example Request

curl -X DELETE -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/transfer/111d714c-1d1c-47cf-9cb7-760428e86c24"

Response (204 No Content)

Permanently delete an external account transfer from a client account. The unique transfer_id must be provided. To obtain the appropriate transfer_id, use the GET /transfer endpoint to view all external account transfer requests defined for your firm. This deletes the transfer_id and the external account transfer record.

HTTP REQUEST

DELETE /transfer/{transfer_id}

Goal

Goal frameworks are defined firm-wide. Clients can answer a questionnaire created by your firm in order to customize their goals based upon their specific needs. Questionnaires can be assigned to multiple goals, using a questionnaire_id. Client responses to the goal questionnaire are stored and used as variables in future calculations. The progress of each client is tracked in relation to one or more goals that the client has selected. A client may have multiple goals, and each goal may belong to one or more of the client’s accounts.

Field Type Description
id UUID The id of the goal
name string Name of the goal
parent_goal_id UUID In the case that a goal is related to a broader goal, the id of the broader goal
questionnaire_id UUID The id of the group of questions that are used to customize a goal for a client
is_decumulation boolean Indicator for whether or not the goal is a decumulation goal such as saving for retirement. Default is false, indicating that the goal is an accumulation goal. May be used in conjunction with the Proton API.
type string Type of goal used to identify similar goals. Can be used to differentiate between goal templates and client-specific goals
category string Category of the goal used to group goals together. For example, different large purchase goals could have a category of ‘Major Purchase’
client_id UUID If the goal is client-specific (not used by any other client), the id of the client to which it belongs
goal_amount double If the goal is client-specific, the target monetary amount to be reached within the goal horizon. May be used in conjunction with the Proton API. If the goal is not client-specific, please store under the account entity.
accumulation_horizon double If the goal is client-specific, the time horizon of the goal during the accumulation phase, in years. May be used in conjunction with the Proton API. If the goal is not client-specific, please store under the account entity.
decumulation_horizon double If the goal is client-specific, the time horizon of the goal during the decumulation phase, in years. If the goal is an accumulation goal, then this can be 0 or omitted entirely. May be used in conjunction with the Proton API. If the goal is not client-specific, please store under the account entity.
image string Icon or image for the goal either as a URL or file name that you will link to
is_active string Indicates if the goal is active. Defaults to true which indicates it is active
metadata map Custom information associated with the goal in the format key:value. See Metadata
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

Goal Management

List all goals

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/goal"

Example Response

{
  "content": [
      {
          "id": "bab849d6-de96-4dc7-a5ea-19be45c52a4e",
          "create_date": "2018-02-07T19:29:37.000+0000",
          "update_date": "2018-02-12T09:00:00.000+0000",
          "name": "House",
          "parent_goal_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
          "questionnaire_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
          "is_decumulation": false,
          "type": "Client Goal",
          "category": "Large Purchase",
          "client_id": "184b66ff-09d8-4c0d-ad88-c7d7e8376714",
          "goal_amount": 100000,
          "accumulation_horizon": 10,
          "decumulation_horizon": 0,
          "image": null,
          "is_active": true,
          "metadata": {
              "image": "https://www.hydrogenplatform.com/images/demo/house.svg"
          }
      },
      {
          "id": "e995d4c1-f989-4733-9867-713966ac9856",
          "create_date": "2018-02-07T19:29:37.000+0000",
          "update_date": "2018-02-12T09:00:00.000+0000",
          "name": "Car",
          "parent_goal_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
          "questionnaire_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
          "is_decumulation": false,
          "type": "Client Goal",
          "client_id": "184b66ff-09d8-4c0d-ad88-c7d7e8376714",
          "category": "Large Purchase",
          "goal_amount": 10000,
          "accumulation_horizon": 5,
          "decumulation_horizon": 0,
          "image": null,
          "is_active": true,
          "metadata": {
              "image": "https://www.hydrogenplatform.com/images/demo/car-purchase.svg"
          }
      },
      {
          "id": "fbc03484-08e8-446d-83aa-6d6cc236355e",
          "create_date": "2018-02-07T19:29:37.000+0000",
          "update_date": "2018-02-12T09:00:00.000+0000",
          "name": "Vacation",
          "parent_goal_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
          "questionnaire_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
          "is_decumulation": false,
          "type": "Client Goal",
          "client_id": "184b66ff-09d8-4c0d-ad88-c7d7e8376714",
          "category": "Large Purchase",
          "goal_amount": 1000,
          "accumulation_horizon": 3,
          "image": null,
          "is_active": true,
          "metadata": {
              "image": "https://www.hydrogenplatform.com/images/demo/travel.svg"
          }
      },
  ],
  "total_pages": 1,
  "total_elements": 3,
  "last": true,
  "number_of_elements": 3,
  "first": true,
  "sort": [
      {
        "direction": "ASC",
        "property": "id",
        "ignore_case": false,
        "null_handling": "NATIVE",
        "descending": false,
        "ascending": true
      }
  ],
  "size": 25,
  "number": 0
}

Get the details for all goals defined by your firm. Note that the metadata information is stored as a nested object within the goal object.

HTTP REQUEST

GET /goal

Create a goal

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -d '{
            "name": "Car",
            "parent_goal_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
            "questionnaire_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
            "is_decumulation": false,
            "type": "Client Goal",
            "category": "Large Purchase",
            "client_id": "184b66ff-09d8-4c0d-ad88-c7d7e8376714",
            "goal_amount": 100000,
            "accumulation_horizon": 10,
            "decumulation_horizon": 0,
            "metadata": {
              "image": "https://www.hydrogenplatform.com/images/demo/car-purchase.svg"
            }
      }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/goal"

Example Response

{
    "id": "e995d4c1-f989-4733-9867-713966ac9856",
    "create_date": "2018-02-07T19:29:37.000+0000",
    "name": "Car",
    "parent_goal_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
    "questionnaire_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
    "is_decumulation": false,
    "type": "Client Goal",
    "category": "Large Purchase",
    "client_id": "184b66ff-09d8-4c0d-ad88-c7d7e8376714",
    "goal_amount": 100000,
    "accumulation_horizon": 10,
    "decumulation_horizon": 0,
    "image": null,
    "is_active": true,
    "metadata": {
        "image": "https://www.hydrogenplatform.com/images/demo/car-purchase.svg"
    }
}

Create a new goal for your firm that clients can customize for themselves. Must provide the name for the goal and indicate whether or not the goal is a decumulation goal (or accumulation goal). The create_date will default to the current date. The endpoint returns the goal_id used to manage the goal and to map the goal to a client.

HTTP REQUEST

POST /goal

ARGUMENTS

Parameter Type Required Description
name string required Name of the goal
parent_goal_id UUID optional In the case that a goal is related to a broader goal, the id of the broader goal
questionnaire_id UUID optional The id of the group of questions that are used to customize a goal for a client
is_decumulation boolean optional Indicator if the goal is a decumulation goal such as saving for retirement. Default is false, indicating that the goal is an accumulation goal. May be used in conjunction with the Proton API.
type string optional Type of goal used to identify similar goals. Can be used to differentiate between goal templates and client-specific goals
category string optional Category of the goal used to group goals together. For example, different large purchase goals could have a category of ‘Major Purchase’
client_id UUID optional If the goal is client-specific (not used by any other client), the id of the client to which it belongs
goal_amount double optional If the goal is client-specific, the target monetary amount to be reached within the goal horizon. May be used in conjunction with the Proton API. If the goal is not client-specific, please store under the account entity.
accumulation_horizon double optional If the goal is client-specific, the time horizon of the goal during the accumulation phase, in years. May be used in conjunction with the Proton API. If the goal is not client-specific, please store under the account entity.
decumulation_horizon double optional If the goal is client-specific, the time horizon of the goal during the decumulation phase, in years. If the goal is an accumulation goal, then this can be 0 or omitted entirely. May be used in conjunction with the Proton API. If the goal is not client-specific, please store under the account entity.
image string optional Icon or image for the goal either as a URL or file name that you will link to
is_active string optional Indicates if the goal is active. Defaults to true which indicates it is active
metadata map optional Custom information associated with the goal in the format key:value. See Metadata
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Retrieve a goal

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/goal/e995d4c1-f989-4733-9867-713966ac9856"

Example Response

{
    "id": "e995d4c1-f989-4733-9867-713966ac9856",
    "create_date": "2018-02-07T19:29:37.000+0000",
    "update_date": "2018-02-12T09:00:00.000+0000",
    "name": "Car",
    "parent_goal_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
    "questionnaire_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
    "is_decumulation": false,
    "type": "Client Goal",
    "category": "Large Purchase",
    "client_id": "184b66ff-09d8-4c0d-ad88-c7d7e8376714",
    "goal_amount": 100000,
    "accumulation_horizon": 10,
    "decumulation_horizon": 0,
    "image": null,
    "is_active": true,
    "metadata": {
        "image": "https://www.hydrogenplatform.com/images/demo/car-purchase.svg"
      }
}

Retrieve the information for a goal defined for your firm. The goal_id must be provided. The endpoint returns the goal_id and the details for the goal specified.

HTTP REQUEST

GET /goal/{goal_id}

Update a goal

Example Request

curl -X PUT -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -d '{
            "name": "Car",
            "questionnaire_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
            "type": "Goal Template",
            "category": "Large Purchase",
            "is_active": false,
            "metadata": {
                "image": "https://www.hydrogenplatform.com/images/demo/car-purchase.svg"
            }
    }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/goal/e995d4c1-f989-4733-9867-713966ac9856"

Example Response

{
    "id": "e995d4c1-f989-4733-9867-713966ac9856",
    "create_date": "2018-02-07T19:29:37.000+0000",
    "update_date": "2018-02-12T09:00:00.000+0000",
    "name": "Car",
    "questionnaire_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
    "is_decumulation": false,
    "type": "Goal Template",
    "category": "Large Purchase",
    "is_active": false,
    "metadata": {
         "image": "https://www.hydrogenplatform.com/images/demo/car-purchase.svg"
    }
}

Update a goal defined for your firm. The goal_id must be provided. To obtain the appropriate goal_id, use the GET /goal endpoint to view all goals defined for your firm and their current information. The details to be updated must also be provided. The endpoint returns the goal_id and the details for the goal.

HTTP REQUEST

PUT /goal/{goal_id}

Delete a goal

Example Request

curl -X DELETE -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/goal/e995d4c1-f989-4733-9867-713966ac9856"

Response (204 No Content)

Permanently delete a goal for your firm. The goal_id must be provided. To obtain the appropriate goal_id, use the GET /goal endpoint to view all goals defined for your firm. This deletes the goal_id and the goal record so that the goal can no longer be used overall.

HTTP REQUEST

DELETE /goal/{goal_id}

Goal Activity

List all goal asset sizes

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/goal/8d97c85c-8cbf-4ac1-a5df-f9d2bb6a77e0/asset_size?client_id=b4c033db-9d05-4a33-8e28-40650d454487"

Example Response

[
    {
        "date": "2018-02-03",
        "currency_code": "USD",
        "value": 20000,
        "value_available": null,
        "additions": 0,
        "cash_flow": 0
    },
    {
        "date": "2018-02-04",
        "currency_code": "USD",
        "value": 24500,
        "value_available": null,
        "additions": 500,
        "cash_flow": 500
    }
]

Get a list of asset sizes per date for a goal for a specified client. Asset size records are created at a portfolio level and aggregated to yield the goal asset sizes. Goal asset sizes are calculated by applying the goal account weights to the portfolio asset sizes of the portfolios below the accounts contributing to the goal. The goal account weights are based on the account allocation weights multiplied by the allocation composition weights for each account contributing to the goal. The unique goal_id must be provided. To obtain the appropriate goal_id, use the GET /goal endpoint to view all goals defined for your firm. A unique client_id must also be provided to return the asset size data as it relates to a specific client. To obtain the appropriate client_id, use the GET /client endpoint to view all clients defined for your firm. The endpoint returns a date, an amount value, and the funds added to the goal since the last asset size date, usually via deposit. Note that goal asset sizes will generally be estimates meant to be indicative of goal growth but may vary slightly from the asset sizes of the portfolios associated with the goal.

HTTP REQUEST

GET /goal/{goal_id}/asset_size?client_id={client_id}

ARGUMENTS

Parameter Type Required Description
client_id UUID required Id of the client subscribed to the goal
get_latest boolean optional Retrieve only the latest asset size. Defaults to false if not set
sort_type string optional Sort the asset sizes by D Daily, M Monthly, Q Quarterly, Y Yearly. Defaults to D Daily if not set. Must be capital letters
start_date date optional Start date for the data. Defaults to the first date if not set
end_date date optional End date for the data. Defaults to the last date if not set

RESPONSE

Field Type Description
date date Date for the asset size record. Displays the latest record if more than one entry exists for the given date.
currency_code string Alphabetic currency code for the asset size. See currency codes
value double Monetary value of the goal on the particular date
value_available double Available monetary value of the goal on the particular date
additions double DEPRECATED, please use cash_flow instead. Amount added in all the goal’s account since the last asset size date, usually via deposit.
cash_flow double Amount added to the goal’s accounts or withdrawn from the accounts since the last asset size date. Value is used for performance calculations. Value may be positive or negative.

List all goal holdings

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/goal/7960419c-c098-4450-8cc5-866b7385230b/holding?client_id=b4c033db-9d05-4a33-8e28-40650d454487"

Example Response

[
    {
        "date": "2018-02-03",
        "security_id": "29c3f995-bd45-4346-aea2-fd4476568d4c",
        "weight": 10,
        "currency_code": "USD",
        "amount": 2000,
        "cost_basis": null,
        "shares": 20
    },
    {
        "date": "2018-02-03",
        "security_id": "89da9660-3efe-4694-b1a7-0958a4f72f0e",
        "weight": 2,
        "currency_code": "USD",
        "amount": 400,
        "cost_basis": null,
        "shares": 40
    },
    {
        "date": "2018-02-03",
        "security_id": "8f7de7e6-3b32-42ff-97a4-d1260811b099",
        "weight": 30,
        "currency_code": "USD",
        "amount": 6000,
        "cost_basis": null,
        "shares": 6
    },
    {
        "date": "2018-02-03",
        "security_id": "b2870d61-d6e0-4a94-9c1e-7a064af13eca",
        "weight": 30,
        "currency_code": "USD",
        "amount": 6000,
        "cost_basis": null,
        "shares": 60
    },
    {
        "date": "2018-02-03",
        "security_id": "dd3e251e-90e2-4e2d-9f3a-4675be5b172f",
        "weight": 28,
        "currency_code": "USD",
        "amount": 5600,
        "cost_basis": null,
        "shares": 50
    }
]

Get the information for all the securities that are currently being held in portfolios associated with a particular goal. Holding records are created at a portfolio level and used to calculate the holdings of the goal. Goal holdings are calculated by applying the goal account weights to the portfolio holdings of the portfolios below the accounts contributing to the goal. The goal account weights are based on the account allocation] weights multiplied by the allocation composition] weights for each account contributing to the goal. Must provide the unique goal_id. To obtain the appropriate goal_id, use the GET /goal endpoint to view all goals defined for your firm. Option to restrict was is returned by specifying a date range, obtaining the latest holdings, or only retrieving holdings of certain size(s). Endpoint returns the security_id, the security amount, the security weight and the date of the record for all securities the client holds.

HTTP REQUEST

GET /goal/{goal_id}/holding?client_id={client_id}

ARGUMENTS

Parameter Type Required Description
client_id UUID required Id of the client subscribed to the goal
start_date date optional Start date for the data. Defaults to the first date if not set
end_date date optional End date for the data. Defaults to the last date if not set

RESPONSE

Field Type Description
date date Date for the security holding. Displays the latest record if more than one entry exists for the given date.
security_id UUID The id for the security included in the holding record
weight double The weight of the security as a percentage of the client goal’s total monetary value; ex. 20 representing 20%
currency_code string Alphabetic currency code for the amount. See currency codes
amount double Monetary value of the shares in the holding record
cost_basis double Monetary value that the security was originally purchased for, used for tax purposes
shares double Number of shares in the holding record

List all goal transactions

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/goal/7960419c-c098-4450-8cc5-866b7385230b/transaction?client_id=b4c033db-9d05-4a33-8e28-40650d454487"

Example Response

{
  "content": [
    {
        "id": "5736e6f7-5e12-448e-830c-c1f2b9317d48",
        "create_date": "2018-02-07T19:29:37.000+0000",
        "update_date": "2018-02-012T09:00:00.000+0000",
        "date": "2018-01-31T00:00:00.000+0000",
        "date_available": null,
        "is_read": true,
        "portfolio_id": "b4c033db-9d05-4a33-8e28-40650d454487",
        "model_id": "4b61f78e-d80e-452d-8201-b1adb87f5bb4",
        "price": 432.2,
        "quantity": 0.5,
        "currency_code": null,
        "amount": null,
        "balance": null,
        "merchant": null,
        "category": null,
        "subcategory": null,
        "description": null,
        "memo": null,
        "status": null,
        "location": {},
        "security_id": "cf9de92f-1c59-4188-93af-d7d5cefd0644",
        "transaction_code_id": "f5af397b-7d22-433f-b01e-8202184a6386"
    },
    {
        "id": "44842cc6-37e5-44de-a799-f5c869a80726",
        "create_date": "2017-08-02T04:30:25",
        "update_date": "2017-11-18T09:00:00",
        "date": "2018-01-31T00:00:00.000+0000",
        "date_available": null,
        "is_read": true,
        "portfolio_id": "fad85772-ded2-4f12-90f7-28e68afcac6f",
        "model_id": "72ebcdfa-70c7-427b-aebb-0df000b3a0a0",
        "price": 132.2,
        "quantity": 4,
        "currency_code": null,
        "amount": null,
        "balance": null,
        "merchant": null,
        "category": null,
        "subcategory": null,
        "description": null,
        "memo": null,
        "status": null,
        "location": {},
        "security_id": "6d413c-f195-4b83-b101-f3d65da5a637",
        "transaction_code_id": "f5af397b-7d22-433f-b01e-8202184a6386"
    }
  ],
  "total_pages": 1,
  "total_elements": 2,
  "last": true,
  "sort": [
      {
        "direction": "DESC",
        "property": "id",
        "ignore_case": false,
        "null_handling": "NATIVE",
        "descending": true,
        "ascending": false
      }
  ],
  "first": true,
  "number_of_elements": 2,
  "size": 25,
  "number": 2
}

Get the information for all transactions under portfolios associated with a particular goal. Transactions represent buy or sell orders for securities. Transaction records are created at the portfolio level and all transactions for each portfolio below an account contributing to the goal are returned to show the transaction activity for the goal. Must provide the unique goal_id. To obtain the appropriate goal_id, use the GET /goal endpoint to view all goals defined for your firm. Endpoint returns details such as the portfolio_transaction_id, the date for the transaction, the transaction_code_id, the quantity of security, the price of the security, the portfolio_id, the account_id, an indicator for whether or not the transaction has been read, etc. for all transactions. See the Order section.

HTTP REQUEST

GET /goal/{goal_id}/transaction?client_id={client_id}

ARGUMENTS

Parameter Type Required Description
client_id UUID required Id of the client subscribed to the goal
start_date date optional Start date for the data. Defaults to the first date if not set
end_date date optional End date for the data. Defaults to the last date if not set

RESPONSE

Field Type Description
id UUID The id for the transaction record
portfolio_id UUID The id of the portfolio that the transaction record falls under
model_id UUID The id of the model to which the portfolio that the transaction falls under subscribes
security_id UUID The id of the security that was bought or sold in the transaction.
transaction_code_id UUID The id of the transaction code for the type of transaction
date timestamp Timestamp when the transaction occurred
date_available timestamp Timestamp when the transaction becomes available
price double Price at which the security was bought or sold
quantity double Quantity of units of a security that were bought or sold
currency_code string Alphabetic currency code for the amount. See currency codes
amount double Amount of the transaction
balance double Updated balance of the portfolio as a result of the transaction
merchant string The merchant for the transaction such as the merchant posted for a credit card charge
category string Category of the transaction
subcategory string Subcategory of the transaction
description string Description of the transaction
memo string Memo attached to the transaction
status string Status of the transaction
location map Location where the transaction occurred
      address_line1 string Primary information for the street address, such as the street and building number
      address_line2 string Secondary information for the street address, such as a suite or apartment number
      city string City for the address
      state string State, province, or sub-country region for the address
      postalcode string Alphanumeric postal code or zip code for the address
      country string Country for the address using the ISO ALPHA-2 Code. See country codes
      latitude double Latitude of the location where the transaction occurred
      longitude double Longitude of the location where the transaction occurred
is_read boolean Indicates if the transaction has been read. Defaults to false which indicates that it has not been read
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

Get aggregate goal data

Aggregates goal metadata and asset size for a given client. This is useful for clients that have many accounts with multiple goals that are associated across accounts.

Field Type Description
client_id UUID The id of the client
client_first_name string First name of the client
client_last_name string Last name of the client
client_asset_size double Total asset size of client across all accounts
client_asset_size_date date Date of the latest client_asset_size for the given client_id
client_view_goal_data array List of goal details for the client
      goal_id UUID The id of the goal
      goal_name string Name of the goal
      goal_amount double Target monetary amount to be reached within the goal horizon
      is_decumulation boolean Indicator if the goal is a decumulation goal such as saving for retirement. Default is false, indicating that the goal is an accumulation goal
      goal_category string Category of the goal
      goal_type string Type of goal
      accumulation_horizon double Time horizon of the goal during the accumulation phase, in years
      decumulation_horizon double Time horizon of the goal during the decumulation phase, in years. If the goal is an accumulation goal, then this can be 0 or omitted entirely
      goal_create_date timestamp Timestamp for the date and time the goal was created
      goal_update_date timestamp Timestamp for the date and time the goal was last updated
      goal_asset_size_by_goal double Sum of latest asset sizes across all accounts in this goal_id for the client
      goal_asset_size_by_goal_date date Date used for the goal_asset_size_by_goal
      accounts array List of client’s accounts that are associated to this goal_id if tracked under an account
          account_id UUID The id of the account
          account_name string Name of the account
          account_type_id UUID The id of the account type
          account_type_name string Name of the account type
          goal_asset_size_by_account double Latest asset size for the account_id in this goal
          goal_asset_size_by_account_date date Date of goal_asset_size_by_account
      portfolios array List of client’s portfolios that are associated to this goal_id if tracked under a portfolio
          portfolio_id UUID The id of the portfolio
          portfolio_name string Name of the portfolio
          goal_asset_size_by_portfolio double Latest asset size for the portfolio_id in this goal
          goal_asset_size_by_portfolio_date date Date of goal_asset_size_by_portfolio

HTTP REQUEST

GET /client/{client_id}/goal_overview

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
  "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/client/0797efda-cf8b-4661-9cb4-d1e8966a3dcd/goal_overview"

Example Response

{
  "client_id": "0797efda-cf8b-4661-9cb4-d1e8966a3dcd",
  "client_first_name": "Oscar",
  "client_last_name": "Martinez",
  "client_asset_size": 88529.95191999999,
  "client_asset_size_date": "2019-09-13",
  "client_view_goal_data": [
    {
      "goal_id": "2fdafedb-c2d2-4ea5-9301-309193bbbcc7",
      "goal_name": "Retirement Saving",
      "goal_amount": null,
      "is_decumulation": true,
      "goal_category": "Retirement",
      "goal_type": "Tenant Level",
      "accumulation_horizon": null,
      "decumulation_horizon": null,
      "goal_create_date": "2019-09-26T22:31:11.000Z",
      "goal_update_date": "2019-09-26T22:31:11.000Z",
      "goal_asset_size_by_goal": 4426497.596,
      "goal_asset_size_by_goal_date": "2019-09-13",
      "accounts": [
        {
          "account_id": "4d7efcea-2f85-4442-8268-c0c1e82ca618",
          "account_name": "Investment",
          "account_type_id": "9d10a266-c7aa-4bb8-aa81-84e2c5291097",
          "account_type_name": "Investment",
          "goal_asset_size_by_account": 741114.543,
          "goal_asset_size_by_account_date": "2019-09-13"
        },
        {
          "account_id": "f450e1f9-ee02-44a2-b947-d7bcb4ee07f1",
          "account_name": "Investment",
          "account_type_id": "9d10a266-c7aa-4bb8-aa81-84e2c5291097",
          "account_type_name": "Investment",
          "goal_asset_size_by_account": 3685383.053,
          "goal_asset_size_by_account_date": "2019-09-13"
        }
      ]
    }
  ]
}

Goal Track

Goal track is used to store the current status of a goal at a point in time and track the progress over time. The status information stored includes the goal amount, the accumulation and decumulation horizons, the accounts participating in the goal, the current goal balance, and the metrics for whether or not the goal will be achieved such as if the goal is on track to be met. The metrics for whether or not the goal will be achieved can be obtained using the Proton API tool, but this is not required.

Field Type Description
id UUID The id for the goal track record
goal_id UUID The id of a goal to which the goal track record pertains
client_id UUID The id of a client to whom the goal for the goal track record belongs
goal_amount double Target amount for the goal
accumulation_horizon double The time horizon of the goal during the accumulation phase, in years
decumulation_horizon double The time horizon of the goal during the decumulation phase, in years
accounts array List of accounts linked to the goal
      account_id UUID The id of the account linked to the goal
current_investment double The current amount invested toward the goal
on_track boolean Indicator for whether or not the goal is on track to be met. true indicates it is on track (no default)
progress double The goal progress percentage as a decimal
goal_probability double The probability of achieving the goal with the client’s given investments
goal_achievement_score double Probability of achieving the goal in relation to the confidence target of a simulation
projection_balance double The projected balance of the goal
projection_date date The date of the projected balance of the goal
status_time_stamp datetime Date and time to which this goal track record applies, defaults to the current timestamp
metadata map Custom information associated with the goal track record in the format key:value
See Metadata
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

List all goal track records

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
  "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/goal_track"

Example Response

{
    "content": [
      {
        "id": "4e1c4f70-8611-44fa-bac5-f9f390c16852",
        "create_date": "2018-11-14T00:00:00.000+0000",
        "goal_id": "9a1c0a9f-c699-46a2-9710-8b2abe10526c",
        "client_id": "2035f52d-2c5b-4e07-8904-cb037bad7aff",
        "goal_amount": 15000,
        "accumulation_horizon": 12,
        "accounts": [
          {"account_id": "a2579980-71b0-4b2e-a39c-09e529d10267"},
          {"account_id": "1c28dade-8679-4df5-9b9d-c508d04fcb0c"},
        ],
        "current_investment": 5000.00,
        "on_track": true,
        "progress": 0.33333,
        "goal_probability": 0.95,
        "goal_achievement_score": 100,
        "projection_balance": "15002.34",
        "projection_date": "2030-11-20",
        "metadata": {
          "simulation_tool": "proton"
        }
      },
      {
        "id": "277591f3-e5ea-4314-961f-0a9c935223ce",
        "create_date": "2018-11-14T00:00:00.000+0000",
        "goal_id": "7db7ba7d-9bcb-420a-92b6-0e69478f0e08",
        "goal_amount": 5000,
        "accumulation_horizon": 7,
        "accounts": [
          {"account_id": "5392beff-6e2a-4fcf-92c1-024c385dae15"},
        ],
        "current_investment": "1205.51",
        "on_track": true,
        "progress": 0.241102,
        "goal_probability": 0.99,
        "projection_balance": "5100.17",
        "projection_date": "2025-11-20",
        "metadata": {
          "simulation_tool": "proton"
        }
      }
    ],
    "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": 2,
    "size": 25,
    "number": 0
}

Get information for all goal track records stored for your firm. You can filter using a unique client_id, goal_id or account_id to view the goal track records for a client’s goals, a specific goal, or goals tied to an account. Use the endpoints GET /client, GET /goal or GET /account to identify the appropriate client_id, goal_id or account_id. Note that the information for the accounts associated with the goal and the metadata information are stored as nested objects within the goal track object.

HTTP REQUEST

GET /goal_track

Create a goal track record

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
        "goal_id": "9a1c0a9f-c699-46a2-9710-8b2abe10526c",
        "client_id": "2035f52d-2c5b-4e07-8904-cb037bad7aff",
        "goal_amount": 15000,
        "accumulation_horizon": 12,
        "accounts": [
          {"account_id": "a2579980-71b0-4b2e-a39c-09e529d10267"},
          {"account_id": "1c28dade-8679-4df5-9b9d-c508d04fcb0c"}
        ],
        "current_investment": 5000.00,
        "on_track": true,
        "progress": 0.33333,
        "goal_probability": 0.95,
        "goal_achievement_score": 100,
        "projection_balance": "15002.34",
        "projection_date": "2030-11-20",
        "metadata": {
          "simulation_tool": "proton"
        }
    }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/goal_track"

Example Response

{
  "id": "4e1c4f70-8611-44fa-bac5-f9f390c16852",
  "create_date": "2018-11-14T00:00:00.000+0000",
  "goal_id": "9a1c0a9f-c699-46a2-9710-8b2abe10526c",
  "client_id": "2035f52d-2c5b-4e07-8904-cb037bad7aff",
  "goal_amount": 15000,
  "accumulation_horizon": 12,
  "accounts": [
    {"account_id": "a2579980-71b0-4b2e-a39c-09e529d10267"},
    {"account_id": "1c28dade-8679-4df5-9b9d-c508d04fcb0c"}
  ],
  "current_investment": 5000.00,
  "on_track": true,
  "progress": 0.33333,
  "goal_probability": 0.95,
  "goal_achievement_score": 100,
  "projection_balance": "15002.34",
  "projection_date": "2030-11-20",
  "metadata": {
    "simulation_tool": "proton"
  }
}

Create a goal track record for a goal under a client. The client_id and goal_id must be provided. To obtain the appropriate client_id and goal_id, use the GET /client and GET /goal endpoint to view all clients and all goals defined for your firm. The endpoint returns a goal_track_id that can then be used to manage the goal track record.

HTTP REQUEST

POST /goal_track

ARGUMENTS

Parameter Type Required Description
goal_id UUID required The id of a goal to which the goal track record pertains
client_id UUID optional The id of a client to whom the goal for the goal track record belongs
goal_amount double optional Target amount for the goal
accumulation_horizon double optional The time horizon of the goal during the accumulation phase, in years
decumulation_horizon double optional The time horizon of the goal during the decumulation phase, in years
accounts array optional List of accounts linked to the goal
      account_id UUID required The id of the account linked to the goal
current_investment double optional The current amount invested toward the goal
on_track boolean optional Indicator for whether or not the goal is on track to be met. true indicates it is on track (no default)
progress double optional The goal progress percentage as a decimal
goal_probability double optional The probability of achieving the goal with the client’s given investments
goal_achievement_score double optional Probability of achieving the goal in relation to the confidence target of a simulation
projection_balance double optional The projected balance of the goal
projection_date date optional The date of the projected balance of the goal
status_time_stamp datetime optional Date and time to which this goal track record applies, defaults to the current timestamp
metadata map optional Custom information associated with the goal track record in the format key:value
See Metadata
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Retrieve a goal track record

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
  "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/goal_track/4e1c4f70-8611-44fa-bac5-f9f390c16852"

Example Response

{
  "id": "4e1c4f70-8611-44fa-bac5-f9f390c16852",
  "create_date": "2018-11-14T00:00:00.000+0000",
  "goal_id": "9a1c0a9f-c699-46a2-9710-8b2abe10526c",
  "client_id": "2035f52d-2c5b-4e07-8904-cb037bad7aff",
  "goal_amount": 15000,
  "accumulation_horizon": 12,
  "accounts": [
    {"account_id": "a2579980-71b0-4b2e-a39c-09e529d10267"},
    {"account_id": "1c28dade-8679-4df5-9b9d-c508d04fcb0c"}
  ],
  "current_investment": 5000.00,
  "on_track": true,
  "progress": 0.33333,
  "goal_probability": 0.95,
  "goal_achievement_score": 100,
  "projection_balance": "15002.34",
  "projection_date": "2030-11-20",
  "metadata": {
    "simulation_tool": "proton"
  }
}

Retrieve the information for a specific goal track record for a goal under a client. The unique goal_track_id must be provided. The endpoint returns the goal_track_id and details for the goal track record specified. Note that the information for the accounts associated with the goal and the metadata information are stored as nested objects within the goal track object.

HTTP REQUEST

GET /goal_track/{goal_track_id}

Update a goal track record

Example Request

curl -X PUT -H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
        "goal_id": "9a1c0a9f-c699-46a2-9710-8b2abe10526c",
        "client_id": "2035f52d-2c5b-4e07-8904-cb037bad7aff",
        "goal_amount": 15000,
        "accumulation_horizon": 12,
        "accounts": [
          {"account_id": "a2579980-71b0-4b2e-a39c-09e529d10267"},
          {"account_id": "1c28dade-8679-4df5-9b9d-c508d04fcb0c"}
        ],
        "current_investment": 5000.00,
        "on_track": true,
        "progress": 0.33333,
        "goal_probability": 0.95,
        "goal_achievement_score": 100,
        "projection_balance": "15002.34",
        "projection_date": "2030-11-20",
        "metadata": {
          "simulation_tool": "proton"
        }
    }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/goal_track/199a8c08-cdd5-4c8c-8abf-535447cea11b"

Example Response

{
  "id": "4e1c4f70-8611-44fa-bac5-f9f390c16852",
  "create_date": "2018-11-14T00:00:00.000+0000",
  "update_date": "2018-11-16T00:00:00.000+0000",
  "goal_id": "9a1c0a9f-c699-46a2-9710-8b2abe10526c",
  "client_id": "2035f52d-2c5b-4e07-8904-cb037bad7aff",
  "goal_amount": 15000,
  "accumulation_horizon": 12,
  "accounts": [
    {"account_id": "a2579980-71b0-4b2e-a39c-09e529d10267"},
    {"account_id": "1c28dade-8679-4df5-9b9d-c508d04fcb0c"}
  ],
  "current_investment": 5000.00,
  "on_track": true,
  "progress": 0.33333,
  "goal_probability": 0.95,
  "goal_achievement_score": 100,
  "projection_balance": "15002.34",
  "projection_date": "2030-11-20",
  "metadata": {
    "simulation_tool": "proton"
  }
}

Update the information for a goal track record. The unique goal_track_id must be provided. To obtain the appropriate goal_track_id, use the GET /goal_track endpoint to view all goal track records stored for your firm and their current information. The details to be updated must also be provided. The endpoint returns the goal_track_id and the details for the goal track record.

HTTP REQUEST

PUT /goal_track/{goal_track_id}

Delete a goal track record

Example Request

curl -X DELETE -H "Authorization: Bearer <access_token>" \
  "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/goal_track/199a8c08-cdd5-4c8c-8abf-535447cea11b"

Response (204 No Content)

Permanently delete an goal track record for a goal under a client. The unique goal_track_id must be provided. To obtain the appropriate goal_track_id, use the GET /goal_track endpoint to view all goal track records stored for your firm. This deletes the goal_track_id and all goal track record information.

HTTP REQUEST

DELETE /goal_track{goal_track_id}

Model

Model Management

Models correspond to portfolios and determine their composition. Models generally consist of one or more securities and are usually assigned to one or more allocations, though that is not required. An account may have one or more models based on the allocation for the account.

Field Type Description
id UUID The id of the model
name string Name of the model usually used to indicate what is included in the model
category string Category that the model falls under such as “Equities”
description string Description of what types of investments are represented in the model
client_id UUID If the model is to be used by a specific client such as an advisor, the id of the client
benchmark_id UUID The id of the benchmark to compare this model against
node_map list List of the node_ids for the nodes of a decision tree that map to this model
      node_id UUID The id of the last node in the branch of a decision tree that maps to the model
currency_code string Alphabetic currency code for the base currency of the model, limited to 3 characters. See currency codes
is_active boolean Indicates if the model is active. Defaults to true which indicates that it is currently active
metadata map Custom information associated with the model in the format key:value. See Metadata
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time the record was created
update_date timestamp Timestamp for the date and time the record was last updated

PROTON API

The following fields may optionally be used in conjunction with the Proton API.

Field Type Description
downside boolean Indicator if rebalancing type for the model set to Downside Protection. true indicates that it is set for Downside Protection
tax_efficiency_id integer If downside is true, this represents level of restriction on the frequency of trading. Value may be 0 no restriction, 1 low, 2 moderate, 3 high, or 4 very high
period_rebal boolean Indicates if rebalancing type for the model is set to Period Based. true indicates that there is period-based rebalancing
rebalance_period integer If period_rebal is true, frequency of rebalancing period. Value may be 0 never, 1 annually, 2 semi-annually, 3 quarterly, or 4 monthly
drift_rebal boolean Indicates if rebalancing type for the model is set to Drift Based. true indicates that there is drift-base rebalancing
default_drift_factor float If drift_rebal is true, default drift threshold for the model as a decimal percentage. For example, 0.10 would set the model to rebalance when the weights drift 10% from the target weight. This is used if no drift_factor is set at the /model_holding level

List all models

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/model"

Example Response

{
    "content": [
        {
            "id": "013380bf-7f17-44c1-93c5-892a7ed3498c",
            "create_date": "2018-02-02T9:00:03.000+0000",
            "update_date": "2018-02-02T21:56:03.000+0000",
            "secondary_id": "3546728",
            "currency_code": "USD",
            "category": "Alpha Generating",
            "description": "Tactical Industrial Stock",
            "is_active": true,
            "name": "Industrial Stocks",
            "downside": true,
            "tax_efficiency_id": 2,
            "period_rebal": true,
            "rebalance_period": 3,
            "drift_rebal": true,
            "default_drift_factor": 0.10,
            "benchmark_id": null,
            "node_map": [],
            "metadata": {}
        },
        {
            "id": "04907eaa-3f33-49be-a35b-378cdf639fba",
            "create_date": "2018-02-02T9:00:03.000+0000",
            "update_date": "2018-02-02T21:56:03.000+0000",
            "secondary_id": "3546729",
            "category": "Risk Managed",
            "description": "Dynamic ESG Nasdaq Stock",
            "is_active": true,
            "name": "Concentrated Aggressive SRI Core",
            "downside": false,
            "period_rebal": true,
            "rebalance_period": 3,
            "drift_rebal": true,
            "default_drift_factor": 0.10,
            "benchmark_id": null,
            "node_map": [],
            "metadata": {}
        },
        {
            "id": "073def0e-6fa0-4e52-badb-6ff2aecbc2b2",
            "create_date": "2018-02-02T9:00:03.000+0000",
            "update_date": "2018-02-02T21:56:03.000+0000",
            "currency_code": "USD",
            "secondary_id": "3546730",
            "category": "Risk Managed",
            "description": "Dynamic Nasdaq Stock (Tax-Efficient)",
            "is_active": true,
            "name": "Concentrated Aggressive Core [Tax-Efficient]",
            "node_map": [],
            "benchmark_id": null,
            "metadata": {}
        }
  ],
  "total_pages": 1,
  "total_elements": 3,
  "last": true,
  "sort": [
      {
        "direction": "DESC",
        "property": "id",
        "ignore_case": false,
        "null_handling": "NATIVE",
        "descending": true,
        "ascending": false
      }
  ],
  "first": true,
  "number_of_elements": 3,
  "size": 25,
  "number": 1
}

Get details for all models defined for your firm to which portfolios can subscribe. Note that the metadata and node map information are stored as nested objects within the model object.

HTTP REQUEST

GET /model

Create a model

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
   -H "Content-Type: application/json" \
   -d '{
          "category": "Alpha Generating",
          "description": "Tactical Industrial Stock",
          "name": "Industrial Stocks",
          "secondary_id": "3546728"
      }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/model"

Example Response

{
    "id": "013380bf-7f17-44c1-93c5-892a7ed3498c",
    "create_date": "2018-02-02T9:00:03.000+0000",
    "currency_code": "USD",
    "category": "Alpha Generating",
    "description": "Tactical Industrial Stock",
    "is_active": true,
    "name": "Industrial Stocks",
    "secondary_id": "3546728",
    "node_map": [],
    "benchmark_id": null,
    "metadata": {}
}

Create a new model for your firm to which a portfolios can later subscribe. The name of the model must be provided. The endpoint returns a model_id used to manage the model. Once the model is created, the model_id can be assigned to an allocation, and portfolios can subscribe to the model. Note that the metadata and node map information are stored as nested objects within the model object.

HTTP REQUEST

POST /model

ARGUMENTS

Parameter Type Required Description
name string required Name of the model usually used to indicate what is included in the model
category string optional Category that the model falls under such as “Tech”
description string optional Description of what types of investments are represented in the model
client_id UUID optional If the model is to be used by a specific client such as an advisor, the id of the client
benchmark_id UUID optional The id of the benchmark to compare this model against
node_map list optional List of the node_ids for the nodes of a decision tree that map to this model
      node_id UUID required The id of the last node in the branch of a decision tree that maps to the model
currency_code string optional Alphabetic currency code for the base currency of the model, limited to 3 characters. See currency codes
is_active boolean optional Indicates for whether or not the model is active. Defaults to true which indicates that it is currently active
metadata map optional Custom information associated with the model in the format key:value. See Metadata
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

PROTON API

The following arguments may be used in conjunction with the Proton API.

Field Type Required Description
downside boolean optional Indicator if rebalancing type for the model set to Downside Protection. true indicates that it is set for Downside Protection
tax_efficiency_id integer optional If downside is true, this represents level of restriction on the frequency of trading. Value may be 0 no restriction, 1 low, 2 moderate, 3 high, or 4 very high
period_rebal boolean optional Indicates if rebalancing type for the model is set to Period Based. true indicates that there is period-based rebalancing
rebalance_period integer optional If period_rebal is true, frequency of rebalancing period. Value may be 0 never, 1 annually, 2 semi-annually, 3 quarterly, or 4 monthly
drift_rebal boolean optional Indicates if rebalancing type for the model is set to Drift Based. true indicates that there is drift-base rebalancing
default_drift_factor float optional If drift_rebal is true, default drift threshold for the model as a decimal percentage. For example, 0.10 would set the model to rebalance when the weights drift 10% from the target weight. This is used if no drift_factor is set at the /model_holding level

Retrieve a model

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/model/013380bf-7f17-44c1-93c5-892a7ed3498c"

Example Response

{
    "id": "013380bf-7f17-44c1-93c5-892a7ed3498c",
    "create_date": "2018-02-02T9:00:03.000+0000",
    "update_date": "2018-02-02T21:56:03.000+0000",
    "category": "Alpha Generating",
    "description": "Tactical Industrial Stock",
    "is_active": true,
    "currency_code": "USD",
    "secondary_id": "3546728",
    "node_map": [],
    "benchmark_id": null,
    "metadata": {}
}

Get the information for a model for your firm. The model_id must be provided. The endpoint returns a model_id and the details for the model specified.

HTTP REQUEST

GET /model/{model_id}

Update a model

Example Request

curl -X PUT -H "Authorization: Bearer <access_token>" \
   -H "Content-Type: application/json" \
   -d '{
          "category": "Alpha Generating",
          "description": "Tactical Industrial Stock",
          "name": "Industrial Stocks",
          "currency_code": "USD",
          "secondary_id": "3546728"
      }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/model/013380bf-7f17-44c1-93c5-892a7ed3498c"

Example Response

{
    "id": "013380bf-7f17-44c1-93c5-892a7ed3498c",
    "create_date": "2018-02-02T9:00:03.000+0000",
    "update_date": "2018-02-02T21:56:03.000+0000",
    "category": "Alpha Generating",
    "description": "Tactical Industrial Stock",
    "is_active": true,
    "name": "Industrial Stocks",
    "currency_code": "USD",
    "secondary_id": "3546728",
    "node_map": [],
    "benchmark_id": null,
    "metadata": {}
}

Update a model for your firm. The model_id must be provided. To obtain the appropriate model_id, use the GET /model endpoint to view all models defined for your firm and their current information. The details to be updated must also be provided. The endpoint returns the model_id and the details for the model. If you wish the model to no longer be used without permanently deleting it, you can use this endpoint to update the is_active field to false.

HTTP REQUEST

PUT /model/{model_id}

Change a model composition

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d '{
          "model_id": "a0d59204-82b7-430b-ab32-e94dee48e7ae",
          "holdings": [
              {
               "current_weight": 90,
               "strategic_weight": 90,
               "date": "2018-09-05",
               "is_safe_security": true,
               "is_initial_holding": true,
               "security_id": "f8265114-06e8-48c9-82d8-e0962c7b5a47"
              },
              {
               "current_weight": 10,
               "strategic_weight": 10,
               "date": "2018-09-05",
               "is_safe_security": true,
               "is_initial_holding": true,
               "security_id": "51e57240-a213-435e-aff6-652daf37f6f0"
              }
            ],
          "sell_transaction_code_id": "81745d99-6a23-4faa-9072-3e5d529af61f",
          "buy_transaction_code_id": "2e0a00db-035b-43fc-b30a-3ef8eeaac78f"
      }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/model/a0d59204-82b7-430b-ab32-e94dee48e7ae/model_change"

Example Response

[
    {
        "id": "befd2c52-307e-4e54-904d-a9fff0115f89",
        "create_date": "2018-09-05T18:54:11.473+0000",
        "update_date": "2018-09-05T18:54:11.473+0000",
        "shares": 0.9,
        "price": 10,
        "date": "2018-09-05",
        "model_id": "a0d59204-82b7-430b-ab32-e94dee48e7ae",
        "security_id": "f8265114-06e8-48c9-82d8-e0962c7b5a47",
        "transaction_code_id": "2e0a00db-035b-43fc-b30a-3ef8eeaac78f"
    },
    {
        "id": "befd2c52-307e-4e54-904d-a9fff0115f89",
        "create_date": "2018-09-05T18:54:11.473+0000",
        "update_date": "2018-09-05T18:54:11.473+0000",
        "shares": 10,
        "price": 1,
        "date": "2018-09-05",
        "model_id": "a0d59204-82b7-430b-ab32-e94dee48e7ae",
        "security_id": "51e57240-a213-435e-aff6-652daf37f6f0",
        "transaction_code_id": "2e0a00db-035b-43fc-b30a-3ef8eeaac78f"
    }
]

Model composition changes represent a change in a model’s holdings. When the model holdings are changed, model transactions are created that may be used to calculate the model holdings. This endpoint creates both the necessary model holdings and model transaction records to reflect the changes to the model composition. This endpoint combines the following three actions into one workflow:

1) Create new model holdings
2) Calculate each model transaction
3) Create each model transaction to track the changes in the model’s composition

The endpoint takes in the details for the new model holding records, including the model_id and a list of all the model’s securities and their corresponding weights. Information should be provided for the new securities to be added to the model, the securities whose weights within the model change, and security weights that remain consistent. The endpoint then creates the new model holding records and returns the ids for all of the model transactions created.

HTTP REQUEST

POST /model/{model_id}/model_change

DATA DEPENDENCIES

  1. Model - POST /model
  2. Model Holdings - POST /model_holding
  3. Model Asset Size - POST /model_asset_size
  4. Security - POST /security
  5. Security Price - POST /security_price
  6. Buy and Sell Transaction Codes - POST /transaction_code

ARGUMENTS

Parameter Type Required Description
model_id UUID required The id of the model whose holdings are to be updated
holdings array required The information for the new holding records to be created
      security_id UUID required The id of the security included in this holding record
      current_weight double required Current weight of the security as a percentage of the model’s total value; ex. 20 representing 20%. If the security is the only one, enter 100
      strategic_weight double required Strategic weight of the security as a percentage of the model’s total value; ex. 20 representing 20%. If the security is the only one, enter 100
      date date required Date of the security weight
sell_transaction_code_id UUID required The transaction_code_id to be populated in any model transaction to sell securities
buy_transaction_code_id UUID required The transaction_code_id to be populated in any model transaction to buy securities

PROTON API

The following fields may optionally be used in conjunction with the Proton API.

Field Type Required Description
drift_factor float optional Drift factor for the security as a decimal percentage. For example, 0.10 would set the security to rebalance when the weights drift 10% from the target weight in the model.
is_cash boolean optional Indicates if the security is cash. Used for Downside Protection rebalancing. Default is false meaning it is not a cash security
is_safe_security boolean optional Indicates if the security is “safe” such as fixed income or cash. Used for Downside Protection rebalancing. Default is false meaning it is not a safe security

RESPONSE

Field Type Description
id UUID The id of the model transaction record created
shares double Number of shares of the security purchased as part of the transaction
price double Security price at which the shares were purchased as part of the transaction
date date Date of the transaction
model_id UUID The id of the model that the transaction record falls under
security_id UUID The id of the security included in the transaction
transaction_code_id integer The id referring to the transaction codes defined by your firm
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

Delete a model

Example Request

curl -X DELETE -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/model/013380bf-7f17-44c1-93c5-892a7ed3498c"

Response (204 No Content)

Permanently delete a model for your firm. The model_id must be provided. To obtain the appropriate model_id, use the GET /model endpoint to view all models defined for your firm. This deletes the model_id and all the model information so that the model is no longer available. If you wish the model to no longer be used without permanently deleting it, you can use the PUT /model/{model_id} endpoint to update the is_active field to false.

HTTP REQUEST

DELETE /model/{model_id}

Model Asset Sizes

Asset sizes are used to track the progression of the model. Asset size records are created at a model level and aggregated at an allocation level. Model asset sizes represent the growth of the theoretical model assets rather than a monetary amount. For example, you may store model asset sizes as the growth of $1 or $10,000.

Field Type Description
id UUID The id of the model asset size record
date date Date for this asset size record
asset_size double “Growth of a dollar” within the model on the particular date
is_reconciled boolean Indicates the asset size record is reconciled. true means it is reconciled
model_id UUID The id of the model that the asset size record falls under
currency_code string Alphabetic currency code for the base currency of the model, limited to 3 characters. See currency codes
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

List all model asset sizes

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/model_asset_size"

Example Response

{
  "content": [
    {
      "id": "b4c033db-9d05-4a33-8e28-40650d454487",
      "create_date": "2018-02-02T9:00:03.000+0000",
      "update_date": "2018-02-02T21:56:03.000+0000",
      "asset_size": 1.1,
      "date": "2016-01-04",
      "is_reconciled": true,
      "model_id": "5736e6f7-5e12-448e-830c-c1f2b9317d48",
      "currency_code": "USD"
    },
    {
      "id": "b4c033db-9d05-4a33-8e28-40650d454488",
      "create_date": "2018-02-02T9:00:03.000+0000",
      "update_date": "2018-02-02T21:56:03.000+0000",
      "asset_size": 1.1,
      "date": "2016-01-04",
      "is_reconciled": true,
      "model_id": "4b61f78e-d80e-452d-8201-b1adb87f5bb4",
      "currency_code": "USD"
    }
  ],
  "last": false,
  "total_pages": 1,
  "total_elements": 2,
  "first": true,
  "sort": [
    {
      "direction": "DESC",
      "property": "id",
      "ignore_case": false,
      "null_handling": "NATIVE",
      "ascending": false,
      "descending": true
    }
  ],
  "number_of_elements": 2,
  "size": 25,
  "number": 0
}

Get a list of asset sizes per date for all models defined for your firm. Additional parameters available to narrow down what is returned include a date range, only obtaining the latest record, and sorting by different units of time (eg. annually, quarterly, monthly, daily), etc. The endpoint returns a date, amount, and the amount added to the asset size since the previous asset size for each date within the date range.

HTTP REQUEST

GET /model_asset_size

Create a model asset size

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d '{
            "asset_size" : 1.1,
            "date" : "2017-01-02",
            "is_reconciled" : true,
            "model_id" : "5736e6f7-5e12-448e-830c-c1f2b9317d48",
            "currency_code": "USD"
        }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/model_asset_size"

Example Response

{
  "id": "4b61f78e-d80e-452d-8201-b1adb87f5bb4",
  "create_date": "2018-02-02T9:00:03.000+0000",
  "update_date": "2018-02-02T21:56:03.000+0000",
  "asset_size": 1.1,
  "date": "2017-01-02",
  "is_reconciled": true,
  "model_id": "5736e6f7-5e12-448e-830c-c1f2b9317d48",
  "currency_code": "USD"
}

Create a new asset size record for a model. Asset sizes are used to track the progression of the model. The unique model_id must be provided. To obtain the appropriate model_id, use the GET /model endpoint to view all the models defined for your firm. The value of the asset size and date for the asset size record must also be provided. The endpoint returns a model_asset_size_id used to manage the asset size record.

HTTP REQUEST

POST /model_asset_size

ARGUMENTS

Parameter Type Required Description
date date required Date for this asset size record
asset_size double required “Growth of a dollar” within the model on the particular date
is_reconciled boolean required Indicates the asset size record is reconciled. true means it is reconciled
model_id UUID required The id of the model for the asset size record
currency_code string optional Alphabetic currency code for the base currency of the model, limited to 3 characters. See currency codes
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Retrieve a model asset size

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/model_asset_size/4b61f78e-d80e-452d-8201-b1adb87f5bb4"

Example Response

{
  "id": "4b61f78e-d80e-452d-8201-b1adb87f5bb4",
  "create_date": "2018-02-02T9:00:03.000+0000",
  "update_date": "2018-02-02T21:56:03.000+0000",
  "asset_size": 1.1,
  "date": "2016-01-02",
  "is_reconciled": true,
  "model_id": "5736e6f7-5e12-448e-830c-c1f2b9317d48",
  "currency_code": "USD"
}

Retrieve the information for a model asset size record for a model. The model_asset_size_id must be provided. The endpoint returns the model_asset_size_id and details for the model asset size record specified.

HTTP REQUEST

GET /model_asset_size/{model_asset_size_id}

Update a model asset size

Example Request

curl -X PUT -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d '{
            "asset_size" : 1.1,
            "date" : "2017-01-04",
            "is_reconciled" : true,
            "model_id" : "5736e6f7-5e12-448e-830c-c1f2b9317d48",
            "currency_code": "USD"
        }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/model_asset_size/4b61f78e-d80e-452d-8201-b1adb87f5bb4"

Example Response

{
  "id": "4b61f78e-d80e-452d-8201-b1adb87f5bb4",
  "create_date": "2018-02-02T9:00:03.000+0000",
  "update_date": "2018-02-02T21:56:03.000+0000",
  "asset_size": 1.1,
  "date": "2016-01-04",
  "is_reconciled": true,
  "model_id": "5736e6f7-5e12-448e-830c-c1f2b9317d48",
  "currency_code": "USD"
}

Update a model asset size record for a model. The model_asset_size_id must be provided. To obtain the appropriate model_asset_size_id, use the GET /model_asset_size endpoint to view all model asset size records and their current information. The details to be updated must also be provided. The endpoint returns the model_asset_size_id and details for the model asset size record specified.

HTTP REQUEST

PUT /model_asset_size/{model_asset_size_id}

Delete a model asset size

Example Request

curl -X DELETE -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/model_asset_size/4b61f78e-d80e-452d-8201-b1adb87f5bb4"

Response (204 No Content)

Permanently delete a model asset size record for a model. The model_asset_size_id must be provided.

HTTP REQUEST

DELETE /model_asset_size/{model_asset_size_id}

Model Holdings

Holding records represent the securities that are held under a model for a particular date. Holding records are created at the model level and aggregated at an allocation level.

Field Type Description
id UUID The id of the security holding record
model_id UUID The id of the model that the security holding record falls under
security_id UUID The id of the security included in this holding record
current_weight double Current weight of the security as a percentage of the model’s total value; ex. 20 representing 20%. If the security is the only one, enter 100
strategic_weight double Strategic weight of the security as a percentage of the model’s total value; ex. 20 representing 20%. If the security is the only one, enter 100
date date Date of the security weight
metadata map Custom information associated with the model holding in the format key:value. See Metadata
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

PROTON API

The following fields may optionally be used in conjunction with the Proton API.

Field Type Description
drift_factor float Drift factor for the security as a decimal percentage. For example, 0.10 would set the security to rebalance when the weights drift 10% from the target weight in the model.
is_cash boolean Indicates if the security is cash. Used for Downside Protection rebalancing. Default is false meaning it is not a cash security
is_safe_security boolean Indicates if the security is “safe” such as fixed income or cash. Used for Downside Protection rebalancing. Default is false meaning it is not a safe security

List all model holdings

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
      "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/model_holding"

Example Response

{
  "content": [
    {
      "id": "b4c033db-9d05-4a33-8e28-40650d454487",
      "create_date": "2018-02-02T19:29:37.000+0000",
      "update_date": "2018-02-02T09:00:00.000+0000",
      "current_weight": 20,
      "strategic_weight": 20,
      "date": "2018-02-02",
      "model_id": "efa289b2-3565-42e6-850b-8dad25727e99",
      "security_id": "cf9de92f-1c59-4188-93af-d7d5cefd0644",
      "metadata": {}
    },
    {
      "id": "7960419c-c098-4450-8cc5-866b7385230b",
      "create_date": "2018-02-02T19:29:37.000+0000",
      "update_date": "2018-02-02T09:00:00.000+0000",
      "current_weight": 20,
      "strategic_weight": 20,
      "date": "2018-02-02",
      "model_id": "cf9de92f-1c59-4188-93af-d7d5cefd0644",
      "security_id": "4b61f78e-d80e-452d-8201-b1adb87f5bb4",
      "metadata": {}
    }
  ],
  "last": true,
  "total_pages": 1,
  "total_elements": 2,
  "first": true,
  "sort": [
    {
      "direction": "ASC",
      "property": "id",
      "ignore_case": false,
      "null_handling": "NATIVE",
      "ascending": true,
      "descending": false
    }
  ],
  "number_of_elements": 2,
  "size": 25,
  "number": 0
}

Get all model holding records for all models defined for your firm. You can provide the model_id to filter results for a model. To obtain the appropriate model_id, us the GET /model endpoint to view all the model defined by your firm. You can provide a security_id to filter results for a security. To obtain the appropriate security_id use the GET /security endpoint to view all securities defined for your firm. You can also provide a specific date range to view the model holdings on the dates within that range. Note that the metadata and node_map information are stored as a nested object within the model holding object.

HTTP REQUEST

GET /model_holding

ARGUMENTS

Parameter Type Required Description
use_strategic boolean optional Return holdings based on the strategic weight. Defaults to false meaning the holdings are returned based on the current weight

Create a model holding

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d '{
            "current_weight": 20,
            "strategic_weight": 20,
            "date": "2018-02-02",
            "model_id": "cf9de92f-1c59-4188-93af-d7d5cefd0644",
            "security_id": "4b61f78e-d80e-452d-8201-b1adb87f5bb4"
      }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/model_holding"

Example Response

{
  "id": "7960419c-c098-4450-8cc5-866b7385230b",
  "create_date": "2018-02-02T19:29:37.000+0000",
  "current_weight": 20,
  "strategic_weight": 20,
  "date": "2018-02-02",
  "model_id": "cf9de92f-1c59-4188-93af-d7d5cefd0644",
  "security_id": "4b61f78e-d80e-452d-8201-b1adb87f5bb4",
  "metadata": {}
}

Create a new model holding record for a specific model and date. The unique model_id must be provided. To obtain the appropriate model_id, us the GET /model endpoint to view all the model defined by your firm. The security_id for the specific security must be provided. To obtain the appropriate security_id use the GET /security endpoint to view all securities defined for your firm. The endpoint returns a model_holding_id used to manage this model holding record.

HTTP REQUEST

POST /model_holding

ARGUMENTS

Parameter Type Required Description
model_id UUID required The id of the model that the security holding record falls under
security_id UUID required The id of the security included in this holding record
current_weight double required Current weight of the security as a percentage of the model’s total value; ex. 20 representing 20%. If the security is the only one, enter 100
strategic_weight double required Strategic weight of the security as a percentage of the model’s total value; ex. 20 representing 20%. If the security is the only one, enter 100
date date required Date of the security weight
metadata map optional Custom information associated with the model holding in the format key:value. See Metadata
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

PROTON API

The following fields may optionally be used in conjunction with the Proton API.

Field Type Required Description
drift_factor float optional Drift factor for the security as a decimal percentage. For example, 0.10 would set the security to rebalance when the weights drift 10% from the target weight in the model.
is_cash boolean optional Indicates if the security is cash. Used for Downside Protection rebalancing. Default is false meaning it is not a cash security
is_safe_security boolean optional Indicates if the security is “safe” such as fixed income or cash. Used for Downside Protection rebalancing. Default is false meaning it is not a safe security

Retrieve a model holding

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
      "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/model_holding/7960419c-c098-4450-8cc5-866b7385230b"

Example Response

{
  "id": "7960419c-c098-4450-8cc5-866b7385230b",
  "create_date": "2018-02-02T19:29:37.000+0000",
  "update_date": "2018-02-02T09:00:00.000+0000",
  "current_weight": 20,
  "strategic_weight": 20,
  "date": "2018-02-02",
  "model_id": "cf9de92f-1c59-4188-93af-d7d5cefd0644",
  "security_id": "4b61f78e-d80e-452d-8201-b1adb87f5bb4",
  "metadata": {}
}

Retrieve the information for a model holding record for a model. The model_holding_id must be provided. The endpoint returns the model_holding_id and details for the model holding record specified.

HTTP REQUEST

GET /model_holding/{model_holding_id}

Update a model holding

Example Request

curl -X PUT -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d '{
            "current_weight": 20,
            "strategic_weight": 20,
            "date": "2018-02-02",
            "model_id": "cf9de92f-1c59-4188-93af-d7d5cefd0644",
            "security_id": "4b61f78e-d80e-452d-8201-b1adb87f5bb4"
      }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/model_holding/7960419c-c098-4450-8cc5-866b7385230b"

Example Response

{
  "id": "7960419c-c098-4450-8cc5-866b7385230b",
  "create_date": "2018-02-02T19:29:37.000+0000",
  "update_date": "2018-02-02T09:00:00.000+0000",
  "current_weight": 20,
  "strategic_weight": 20,
  "date": "2018-02-02",
  "model_id": "cf9de92f-1c59-4188-93af-d7d5cefd0644",
  "security_id": "4b61f78e-d80e-452d-8201-b1adb87f5bb4",
  "metadata": {}
}

Update a model holding record for a model. The model_holding_id must be provided. To obtain the appropriate model_holding_id, use the GET /model_holding endpoint to view all model holdings and their current information. The details to be update and the details to be maintained must also be provided. The endpoint returns the model_holding_id and details for the model holding record.

HTTP REQUEST

PUT /model_holding/{model_holding_id}

Delete a model holding

Example Request

curl -X DELETE -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/model_holding/7960419c-c098-4450-8cc5-866b7385230b"

Response (204 No Content)

Permanently delete a model holding record for a model. The model_holding_id must be provided. To obtain the appropriate model_holding_id, use the GET /model_holding endpoint to view all model holdings. This deletes the model_holding_id and model holding record information from the model.

HTTP REQUEST

DELETE /model_holding/{model_holding_id}

Model Transactions

Transactions represent buy or sell orders for securities. Transactions are created at a model or portfolio level and aggregated at a goal, account, allocation, or client level.

Field Type Description
id UUID The id of the model transaction record
shares double Number of shares of the security purchased as part of the transaction
price double Security price at which the shares were purchased as part of the transaction
date date Date of the transaction
model_id UUID The id of the model that the transaction record falls under
security_id UUID The id of the security included in the transaction
transaction_code_id integer The id referring to the transaction codes defined by your firm
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

List all model transactions

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/model_transaction"

Example Response

{
  "content": [
    {
      "id": "e7cf805b-4307-41e9-8b58-90b6359fa900",
      "create_date": "2018-02-07T19:29:37.000+0000",
      "update_date": "2018-02-12T09:00:00.000+0000",
      "shares": 20,
      "price": 101.10,
      "date": "2018-02-07",
      "model_id": "5736e6f7-5e12-448e-830c-c1f2b9317d48",
      "security_id": "fad85772-ded2-4f12-90f7-28e68afcac6f",
      "transaction_code_id": "099961da-7f41-4309-950f-2b51689a0033"
    }
  ],
  "total_pages": 1,
  "total_elements": 1,
  "last": true,
  "sort": [
      {
        "direction": "DESC",
        "property": "id",
        "ignore_case": false,
        "null_handling": "NATIVE",
        "descending": true,
        "ascending": false
      }
  ],
  "first": true,
  "number_of_elements": 1,
  "size": 25,
  "number": 1
}

Get details for all transaction records for all models defined by your firm. Additional parameters available to limit what is returned include a date range.

HTTP REQUEST

GET /model_transaction

Create a model transaction

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d '{
            "shares" : 200,
            "price": 1.42,
            "date" : "2018-02-07",
            "model_id" : "5736e6f7-5e12-448e-830c-c1f2b9317d48",
            "security_id" : "fad85772-ded2-4f12-90f7-28e68afcac6f",
            "transaction_code_id" : "f5af397b-7d22-433f-b01e-8202184a6386"
        }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/model_transaction"

Example Response

{
  "id": "e7cf805b-4307-41e9-8b58-90b6359fa900",
  "create_date": "2018-02-07T19:29:37.000+0000",
  "shares": 200,
  "price": 1.42,
  "date": "2018-02-07",
  "model_id" : "5736e6f7-5e12-448e-830c-c1f2b9317d48",
  "security_id" : "fad85772-ded2-4f12-90f7-28e68afcac6f",
  "transaction_code_id" : "f5af397b-7d22-433f-b01e-8202184a6386"
}

Create a new transaction record for a security under a model for a specific date. Transactions represent buy or sell orders for securities. The unique model_id and the unique security_id must be provided. To obtain the appropriate model_id use the GET /model endpoint to view all available models defined for your firm. To obtain the appropriate security_id use the GET /security endpoint to view all securities defined for your firm. A transaction_code_id must also be provided. To obtain the appropriate transaction_code_id use the GET /transaction_code endpoint to view all available transaction codes for your firm. The create_date will default to the current date. The endpoint returns a transaction_id used to manage the transaction record.

HTTP REQUEST

POST /model_transaction

ARGUMENTS

Parameter Type Required Description
shares double required Number of shares of the security purchased as part of the transaction
price double required Security price at which the shares were purchased as part of the transaction
date date required Date of the transaction
model_id UUID required The id of the model that the transaction record falls under
security_id UUID required The id of the security included in the transaction
transaction_code_id integer required The id referring to the transaction codes defined by your firm
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Retrieve a model transaction

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/model_transaction/e7cf805b-4307-41e9-8b58-90b6359fa900"

Example Response

{
  "id": "e7cf805b-4307-41e9-8b58-90b6359fa900",
  "create_date": "2018-02-07T19:29:37.000+0000",
  "update_date": "2018-02-12T09:00:00.000+0000",
  "shares": 200,
  "price": 1.42,
  "date": "2018-02-07",
  "model_id" : "5736e6f7-5e12-448e-830c-c1f2b9317d48",
  "security_id" : "fad85772-ded2-4f12-90f7-28e68afcac6f",
  "transaction_code_id" : "72ebcdfa-70c7-427b-aebb-0df000b3a0a0"
}

Retrieve the information for a model transaction for a model. The model_transaction_id must be provided. The endpoint returns the model_transaction_id and details for the model transaction record specified.

HTTP REQUEST

GET /model_transaction/{model_transaction_id}

Update a model transaction

Example Request

curl -X PUT -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d '{
            "shares": 200,
            "price" : 1.42,
            "date" : "2018-02-07",
            "model_id" : "5736e6f7-5e12-448e-830c-c1f2b9317d48",
            "security_id" : "fad85772-ded2-4f12-90f7-28e68afcac6f",
            "transaction_code_id" : "f5af397b-7d22-433f-b01e-8202184a6386"
        }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/model_transaction/e7cf805b-4307-41e9-8b58-90b6359fa900"

Example Response

{
  "id": "e7cf805b-4307-41e9-8b58-90b6359fa900",
  "create_date": "2018-02-07T19:29:37.000+0000",
  "update_date": "2018-02-12T09:00:00.000+0000",
  "shares": 200,
  "price": 1.42,
  "date": "2018-02-07",
  "model_id": "5736e6f7-5e12-448e-830c-c1f2b9317d48",
  "security_id": "fad85772-ded2-4f12-90f7-28e68afcac6f",
  "transaction_code_id": "f5af397b-7d22-433f-b01e-8202184a6386"
}

Update a model transaction for a model. The model_transaction_id must be provided. To obtain the appropriate model_transaction_id, use the GET /model_transaction endpoint to view all model transactions and their current information. The details to be updated must also be provided. The endpoint returns the model_transaction_id and details for the model transaction record.

HTTP REQUEST

PUT /model_transaction/{model_transaction_id}

Delete a model transaction

Example Request

curl -X DELETE -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/model_transaction/e7cf805b-4307-41e9-8b58-90b6359fa90"

Response (204 No Content)

Permanently delete a model transaction for a model. The model_transaction_id must be provided. To obtain the appropriate model_transaction_id, use the GET /model_transaction endpoint to view all model transactions. This deletes the model_transaction_id and the model transaction record.

HTTP REQUEST

DELETE /model_transaction/{model_transaction_id}

Model Commentary

Model commentary is used to understand the logic behind each model. Commentary may consist of rationale behind various trades conducted by your investment team such as rebalancing or strategic asset allocation changes.

Field Type Description
id UUID The id of the model comment
model_id UUID The id of the model that the comment falls under
comment string Body of the comment
date date Date for when the comment applies
metadata map Custom information associated with the entity in the format key:value
See Metadata
secondary_id string Alternate id that can be used to identify the object such as an internal id
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

List all model commentary

Example Request

curl -X GET -H "Authorization: Bearer 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/model_comment"

Example Response

{
  "content": [
    {
      "id": "8d97c85c-8cbf-4ac1-a5df-f9d2bb6a77e0",
      "create_date": "2018-02-07T19:29:37.000+0000",
      "update_date": "2018-02-12T09:00:00.000+0000",
      "comment": "We reduced your holdings to risky assets due to heightened geo-political risks.",
      "date": "2018-02-07",
      "model_id": "fad85772-ded2-4f12-90f7-28e68afcac6f",
      "metadata": {}
    }
  ],
  "total_pages": 1,
  "last": true,
  "total_elements": 1,
  "first": true,
  "sort": [
    {
      "direction": "ASC",
      "property": "id",
      "ignore_case": false,
      "null_handling": "NATIVE",
      "ascending": true,
      "descending": false
    }
  ],
  "number_of_elements": 1,
  "size": 25,
  "number": 0
}

List all comments for all models defined by your firm. You can filter to view only the comments for a specific model by providing a model_id. To obtain the appropriate model_id, use the GET /model endpoint to view all models defined for your firm.

HTTP REQUEST

GET /model_comment

Create a model commentary

Example Request

curl -X POST -H "Authorization: Bearer 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
    -H "Content-Type: application/json" \
    -d '{
            "comment" : "We reduced your holdings to risky assets due to heightened geo-political risks.",
            "date" : "2018-01-31",
            "model_id" : "fad85772-ded2-4f12-90f7-28e68afcac6f"
        }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/model_comment"

Example Response

{
  "id": "e7cf805b-4307-41e9-8b58-90b6359fa900",
  "create_date": "2018-02-07T19:29:37.000+0000",
  "update_date": "2018-02-12T09:00:00.000+0000",
  "comment": "We reduced your holdings to risky assets due to heightened geo-political risks.",
  "date": "2018-02-07",
  "model_id": "fad85772-ded2-4f12-90f7-28e68afcac6f",
  "metadata": {}
}

Create a new comment for a model available for your firm. The unique model_id must be provided. To obtain the appropriate model_id, use the GET /model endpoint to view all models defined for your firm. The create_date will default to the current date. The endpoint returns a unique model_comment_id used to manage the model comment.

HTTP REQUEST

POST /model_comment

ARGUMENTS

Parameter Type Required Description
model_id UUID required The id of the model that the comment falls under
comment string required Body of the comment
date date required Date for when the comment applies
metadata map optional Custom information associated with the entity in the format key:value
See Metadata
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Retrieve a model commentary

Example Request

curl -X GET -H "Authorization: Bearer 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
      "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/model_comment/e7cf805b-4307-41e9-8b58-90b6359fa900"

Example Response

{
  "id": "e7cf805b-4307-41e9-8b58-90b6359fa900",
  "create_date": "2018-02-07T19:29:37.000+0000",
  "update_date": "2018-02-12T09:00:00.000+0000",
  "comment": "We reduced your holdings to risky assets due to heightened geo-political risks.",
  "date": "2018-02-07",
  "model_id": "fad85772-ded2-4f12-90f7-28e68afcac6f",
  "metadata": {}
}

Retrieve the information for a model comment for a model. The model_comment_id must be provided. The endpoint returns the model_comment_id and details for the model comment specified.

HTTP REQUEST

GET /model_comment/{model_comment_id}

Update a model commentary

Example Request

curl -X PUT -H "Authorization: Bearer 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
    -H "Content-Type: application/json" \
    -d '{
            "comment" : "We reduced your holdings to risky assets due to heightened geo-political risks.",
            "date" : "2018-01-31",
            "model_id" : "fad85772-ded2-4f12-90f7-28e68afcac6f2"
        }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/model_comment/e7cf805b-4307-41e9-8b58-90b6359fa900"

Example Response

{
  "id": "e7cf805b-4307-41e9-8b58-90b6359fa900",
  "create_date": "2018-02-07T19:29:37.000+0000",
  "update_date": "2018-02-12T09:00:00.000+0000",
  "comment": "We reduced your holdings to risky assets due to heightened geo-political risks.",
  "date": "2018-02-07",
  "model_id": "fad85772-ded2-4f12-90f7-28e68afcac6f",
  "metadata": {}
}

Update a model comment for a model. The model_comment_id must be provided. To obtain the appropriate model_comment_id, use the GET /model_comment endpoint to view all model comments and their current information. The details to be updated must also be provided. The endpoint returns the model_comment_id and details for the model comment.

HTTP REQUEST

PUT /model_comment/{model_comment_id}

Delete a model commentary

Example Request

curl -X DELETE -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/model_comment/e7cf805b-4307-41e9-8b58-90b6359fa900"

Response (204 No Content)

Permanently delete a model comment for a model. The model_comment_id must be provided. To obtain the appropriate model_comment_id, use the GET /model_comment endpoint to view all model comments. This deletes the model_comment_id and the model comment record from the model.

HTTP REQUEST

DELETE /model_comment/{model_comment_id}

Order

Order Management

Order records represent order tickets for securities that would be passed on to an agent or Securities Trading Organization (STO) for execution. Orders are usually generated as part of rebalancing of accounts or portfolios, but they can also be created one-off.

Field Type Description
id UUID The id of the order record
transaction_code_id UUID The id referring to the transaction codes defined by your firm
quantity double The number of shares of security being bought or sold
security_id UUID The id of the security being bought or sold
date date Date for when the order was generated
price double Price of the security at the time the order is created. Should be provided to use the rebalancing functionality
order_bulk_id UUID In the case that the order is part of a bulk order, the id of the bulk order
is_read boolean Indicates if the order record has been read. Defaults to false which indicates that it has not been read
order_type string Type of the order transaction
order_ticket_id UUID The id that reflects all orders generated during a rebalance
portfolio_id UUID The id of the portfolio that the order falls under
account_id UUID The id of the account that the order falls under
model_id UUID The id of the model with which the order is associated
metadata map Custom information associated with the order record in the format key:value.
See Metadata
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

List all order records

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/order"

Example Response

{
  "content": [
    {
      "id": "67190064-0731-4b29-b2a7-4a35eb8e7afe",
      "create_date": "2018-02-07T19:29:37.000+0000",
      "update_date": "2018-02-12T09:00:00.000+0000",
      "transaction_code_id": "f5af397b-7d22-433f-b01e-8202184a6386",
      "order_bulk_id": "114556fe-ee78-431d-be5e-60ae08ddf9a7",
      "date": "2018-02-12",
      "price": 51.25,
      "is_read": false,
      "order_ticket_id": "5da53a30-49e6-4162-8728-58d6348bfb24",
      "quantity": 4,
      "security_id": "65363b6d-fcca-41ea-bc88-419e927fff0d",
      "account_id": "c80c9729-3fd5-4a2f-be8e-915cdf21b49d",
      "model_id": "f43a535b-477d-447c-99ca-b47cb2037849",
      "metadata": {}
    },
    {
      "id": "fab27a8b-3d6d-4c74-a9a9-443feebe04e7",
      "create_date": "2018-02-07T19:29:37.000+0000",
      "update_date": "2018-02-12T09:00:00.000+0000",
      "transaction_code_id": "f5af397b-7d22-433f-b01e-8202184a6386",
      "order_bulk_id": "114556fe-ee78-431d-be5e-60ae08ddf9a7",
      "date": "2018-02-11",
      "price": 45,
      "is_read": true,
      "order_type": "bulk order",
      "order_ticket_id": "0de415ac-0265-43d7-add4-553232c5032b",
      "portfolio_id": "c34794e9-f927-468b-b47e-ea17c3d533c5",
      "quantity": 2,
      "security_id": "a7376937-da3e-423c-9764-767c22bf89e8",
      "account_id": "c80c9729-3fd5-4a2f-be8e-915cdf21b49d",
      "model_id": "f43a535b-477d-447c-99ca-b47cb2037849",
      "metadata": {
        "order_purpose": "tax loss harvested"
      }
    }
  ],
  "last": true,
  "total_elements": 2,
  "total_pages": 1,
  "sort": [
    {
      "direction": "DESC",
      "property": "id",
      "ignore_case": false,
      "null_handling": "NATIVE",
      "ascending": false,
      "descending": true
    }
  ],
  "first": true,
  "number_of_elements": 2,
  "size": 25,
  "number": 0
}

Get the information for all order records defined for your firm. You can provide an account_id, portfolio_id, or model_id to view the order records for a specific account, portfolio or model respectively. Note that the metadata information is stored as a nested object within the order record object.

HTTP REQUEST

GET /order

Create an order record

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -d '{
          "transaction_code_id": "f5af397b-7d22-433f-b01e-8202184a6386",
          "date": "2018-02-11",
          "price": 51.25,
          "order_type": "initial order",
          "order_ticket_id": "5da53a30-49e6-4162-8728-58d6348bfb24",
          "portfolio_id": "c34794e9-f927-468b-b47e-ea17c3d533c5",
          "quantity": 2,
          "security_id": "65363b6d-fcca-41ea-bc88-419e927fff0d",
          "account_id": "c80c9729-3fd5-4a2f-be8e-915cdf21b49d",
          "model_id": "f43a535b-477d-447c-99ca-b47cb2037849",
          "metadata": {
            "order_purpose": "tax loss harvested"
          }
      }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/order"

Example Response

{
    "id": "67190064-0731-4b29-b2a7-4a35eb8e7afe",
    "create_date": "2018-02-07T19:29:37.000+0000",
    "update_date": "2018-02-07T19:29:37.000+0000",
    "transaction_code_id": "f5af397b-7d22-433f-b01e-8202184a6386",
    "date": "2018-02-11",
    "price": 51.25,
    "order_type": "initial order",
    "order_ticket_id": "5da53a30-49e6-4162-8728-58d6348bfb24",
    "portfolio_id": "c34794e9-f927-468b-b47e-ea17c3d533c5",
    "quantity": 2,
    "security_id": "65363b6d-fcca-41ea-bc88-419e927fff0d",
    "account_id": "c80c9729-3fd5-4a2f-be8e-915cdf21b49d",
    "model_id": "f43a535b-477d-447c-99ca-b47cb2037849",
    "metadata": {
        "order_purpose": "tax loss harvested"
    }
}

Create an order record for your firm. The details for the order including the security_id for the securities being ordered and the transaction_code_id to indicate if the securities are being bought or sold must be provided. To obtain the appropriate security_id and transaction_code_id, use the GET /security and GET /transaction_code endpoints to view all securities and transaction codes defined by your firm. The create_date will default to the current date. the endpoint returns an order_id used to manage the order record.

HTTP REQUEST

POST /order

ARGUMENTS

Parameter Type Required Description
transaction_code_id UUID required The id referring to the transaction codes defined by your firm
quantity double required The number of shares of security being bought or sold
security_id UUID required The id of the security being bought or sold
date date required Date for when the order was generated
price double optional Price of the security at the time the order is created. Should be provided to use the rebalancing functionality
order_bulk_id UUID optional In the case that the order is part of a bulk order, the id of the bulk order
is_read boolean optional Indicator for whether or not the order record has been read. Defaults to false which indicates that it has not been read
order_type string optional Type of the order transaction
order_ticket_id UUID optional The id that reflects all orders generated during a rebalance
portfolio_id UUID optional The id of the portfolio that the order falls under. Used when aggregating order records into Bulk Order
account_id UUID optional The id of the account that the order falls under. Used when aggregating order records into Bulk Order
model_id UUID optional The id of the model with which the order is associated. Used when aggregating order records into Bulk Order
metadata map optional Custom information associated with the order record in the format key:value.
See Metadata

Retrieve an order record

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
     "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/order/67190064-0731-4b29-b2a7-4a35eb8e7afe"

Example Response

{
    "id": "67190064-0731-4b29-b2a7-4a35eb8e7afe",
    "create_date": "2018-02-07T19:29:37.000+0000",
    "update_date": "2018-02-12T09:00:00.000+0000",
    "transaction_code_id": "f5af397b-7d22-433f-b01e-8202184a6386",
    "date": "2018-02-11",
    "price": 51.25,
    "order_bulk_id": "114556fe-ee78-431d-be5e-60ae08ddf9a7",
    "order_type": "bulk order",
    "order_ticket_id": "5da53a30-49e6-4162-8728-58d6348bfb24",
    "portfolio_id": "c34794e9-f927-468b-b47e-ea17c3d533c5",
    "quantity": 2,
    "security_id": "65363b6d-fcca-41ea-bc88-419e927fff0d",
    "account_id": "c80c9729-3fd5-4a2f-be8e-915cdf21b49d",
    "model_id": "f43a535b-477d-447c-99ca-b47cb2037849",
    "metadata": {
      "order_purpose": "tax loss harvested"
    }
}

Retrieve the information for an order record. The unique order_id must be provided. The endpoint returns the order_id and the details for the order record specified.

HTTP REQUEST

GET /order/{order_id}

Update an order record

Example Request

curl -X PUT -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -d '{
            "transaction_code_id": "f5af397b-7d22-433f-b01e-8202184a6386",
            "order_bulk_id": "8df5a4ff-4ca3-4f6f-a0f7-89bc3d4dabc9",
            "date": "2018-02-11",
            "price": 51.25,
            "is_read": true,
            "order_type": "bulk order",
            "order_ticket_id": "5da53a30-49e6-4162-8728-58d6348bfb24",
            "portfolio_id": "066304b6-017d-4c2c-8b76-92d772f1f3d5",
            "quantity": 2,
            "security_id": "066304b6-017d-4c2c-8b76-92d772f1f3d56",
            "account_id": "066304b6-017d-4c2c-8b76-92d772f1f3d7",
            "model_id": "066304b6-017d-4c2c-8b76-92d772f1f3d8",
            "metadata": {
              "order_purpose": "tax loss harvested"
            }
       }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/order/cd10b1f0-a158-499c-b3d6-ce3277b779fe"

Example Response

{
    "id": "cd10b1f0-a158-499c-b3d6-ce3277b779fe",
    "create_date": "2018-02-07T19:29:37.000+0000",
    "update_date": "2018-02-12T09:00:00.000+0000",
    "transaction_code_id": "f5af397b-7d22-433f-b01e-8202184a6386",
    "order_bulk_id": "8df5a4ff-4ca3-4f6f-a0f7-89bc3d4dabc9",
    "date": "2018-02-11",
    "price": 51.25,
    "is_read": true,
    "order_type": "bulk order",
    "order_ticket_id": "5da53a30-49e6-4162-8728-58d6348bfb24",
    "portfolio_id": "066304b6-017d-4c2c-8b76-92d772f1f3d5",
    "quantity": 2,
    "security_id": "066304b6-017d-4c2c-8b76-92d772f1f3d56",
    "account_id": "066304b6-017d-4c2c-8b76-92d772f1f3d7",
    "model_id": "066304b6-017d-4c2c-8b76-92d772f1f3d8",
    "metadata": {
      "order_purpose": "tax loss harvested"
    }
}

Update the information for an order record. The unique order_id must be provided. To obtain the appropriate order_id, use the GET /order endpoint to view all order records defined for your firm and their current information. The details to be updated must also be provided. The endpoint returns the order_id and all of the details for the order record.

HTTP REQUEST

PUT /order/{order_id}

Delete an order record

Example Request

curl -X DELETE -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/order/cd10b1f0-a158-499c-b3d6-ce3277b779fe"

Response (204 No Content)

Permanently delete an order record. The unique order_id must be provided. To obtain the appropriate order_id, use the GET /order endpoint to view all order records defined for your firm and their current information. This deletes the order_id and the order record information.

HTTP REQUEST

DELETE /order/{order_id}

Bulk Orders

Order records for each security can be aggregated into bulk orders by date at a firm, client, account, or portfolio level in order to optimize the number of transactions needed.

Field Type Description
order_bulk_id UUID The id of the bulk order
order_id UUID The id of the order record that is part of the bulk order
account_id UUID The id of the account that the order falls under
model_id UUID The id of the model associated with the order
portfolio_id UUID The id of the portfolio that the order falls under
date date Date for when the order was generated
metadata map Custom information associated with the entity in the format key:value
See Metadata
create_date timestamp Timestamp for the date and time that the record was created
update_date timestamp Timestamp for the date and time that the record was last updated

List all bulk orders

Example Request

curl -X GET -H "Authorization: Bearer <access_token>" \
    "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/order_bulk"

Example Response

{
  "content": [
    {
      "id": "67190064-0731-4b29-b2a7-4a35eb8e7afe",
      "create_date": "2018-02-07T19:29:37.000+0000",
      "update_date": "2018-02-12T09:00:00.000+0000",
      "order_id": "72c0c834-03e1-49c3-bf13-eb5adcba6e9e",
      "portfolio_id": "066304b6-017d-4c2c-8b76-92d772f1f3d5",
      "account_id": "066304b6-017d-4c2c-8b76-92d772f1f3d7",
      "model_id": "066304b6-017d-4c2c-8b76-92d772f1f3d8",
      "date": "2018-02-11",
      "metadata": {}
    },
    {
      "id": "f43a535b-477d-447c-99ca-b47cb2037849",
      "create_date": "2018-02-07T19:29:37.000+0000",
      "update_date": "2018-02-12T09:00:00.000+0000",
      "order_id": "a7376937-da3e-423c-9764-767c22bf89e8",
      "portfolio_id": "066304b6-017d-4c2c-8b76-92d772f1f3d5",
      "account_id": "066304b6-017d-4c2c-8b76-92d772f1f3d7",
      "model_id": "066304b6-017d-4c2c-8b76-92d772f1f3d8",
      "date": "2018-02-11",
      "metadata": {}
    }
  ],
  "last": true,
  "total_elements": 2,
  "total_pages": 1,
  "sort": [
    {
      "direction": "ASC",
      "property": "id",
      "ignore_case": false,
      "null_handling": "NATIVE",
      "ascending": true,
      "descending": false
    }
  ],
  "first": true,
  "number_of_elements": 2,
  "size": 25,
  "number": 0
}

Get the information for all bulk order records. The endpoint returns the list of ids for the bulk order, the ids for the order records that are part of each bulk order, the date for each order record, and the ids for the account, portfolios, and models that each order record falls under.

HTTP REQUEST

GET /order_bulk

Bulk orders for your firm

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d '{
        "date":"2017-03-06",
        "buy_transaction_code_id": "f5af397b-7d22-433f-b01e-8202184a6386",
        "sell_transaction_code_id": "7d8d41d0-ed4b-4ae2-acb3-e0baed2ff1cc"
      }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/order_bulk"

Example Response

[
    {
        "id": "0bc55529-b998-42bc-9637-6a19b317760e",
        "create_date": "2017-03-06T18:09:27.031+0000",
        "update_date": "2017-03-06T18:09:27.031+0000",
        "transaction_code_id": "9e0b8266-5fe2-422a-bb2a-e0910225c39e",
        "order_bulk_id": "bc565812-d50e-49c5-9e4e-6bb6524dceb7",
        "date": "2017-03-06",
        "is_read": false,
        "order_ticket_id": "53eaa9da-9a5d-4e20-8e76-24aa8b1dd4d1",
        "quantity": 1,
        "security_id": "615e3777-98d6-48d6-a05b-9c000af5d4b6",
        "metadata": {},
        "price": 100
    },
    {
        "id": "8e658fe0-5309-42f2-805d-5cc76db1b3ca",
        "create_date": "2017-03-06T18:09:27.031+0000",
        "update_date": "2017-03-06T18:09:27.031+0000",
        "transaction_code_id": "9e0b8266-5fe2-422a-bb2a-e0910225c39e",
        "order_bulk_id": "bc565812-d50e-49c5-9e4e-6bb6524dceb7",
        "date": "2017-03-06",
        "is_read": false,
        "order_ticket_id": "f891c472-f534-40bb-b8bb-48fb6e62b1d2",
        "quantity": 4,
        "security_id": "a678d82d-2101-4966-89f3-cf57dcbed1c4",
        "metadata": {},
        "price": 65.44
    }
]

Aggregates all orders on a given date for your firm. The specific date must be provided. This endpoint will net all the orders for that date to reduce the number of required transactions. The endpoint returns a list of all orders included in the bulk order, including a bulk_order_id which can be used to manage the bulk order record for all of the orders.

HTTP REQUEST

POST /order_bulk

ARGUMENTS

Parameter Type Required Description
date date required Date for all the orders that should be aggregated together in the bulk order record
buy_transaction_code_id string required The id of the transaction code that will ultimately be used to denote the buy transactions
sell_transaction_code_id string required The id of the transaction code that will ultimately be used to denote the sell transactions
metadata map optional Custom information associated with the entity in the format key:value
See Metadata

Bulk orders for a client

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d '{
        "date":"2017-03-06",
        "buy_transaction_code_id": "f5af397b-7d22-433f-b01e-8202184a6386",
        "sell_transaction_code_id": "7d8d41d0-ed4b-4ae2-acb3-e0baed2ff1cc"
      }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/client/c34794e9-f927-468b-b47e-ea17c3d533c5/order_bulk"

Example Response

[
    {
        "id": "0bc55529-b998-42bc-9637-6a19b317760e",
        "create_date": "2017-03-06T18:09:27.031+0000",
        "update_date": "2017-03-06T18:09:27.031+0000",
        "transaction_code_id": "9e0b8266-5fe2-422a-bb2a-e0910225c39e",
        "order_bulk_id": "bc565812-d50e-49c5-9e4e-6bb6524dceb7",
        "date": "2017-03-06",
        "is_read": false,
        "order_ticket_id": "53eaa9da-9a5d-4e20-8e76-24aa8b1dd4d1",
        "quantity": 1,
        "security_id": "615e3777-98d6-48d6-a05b-9c000af5d4b6",
        "metadata": {},
        "price": 100
    },
    {
        "id": "8e658fe0-5309-42f2-805d-5cc76db1b3ca",
        "create_date": "2017-03-06T18:09:27.031+0000",
        "update_date": "2017-03-06T18:09:27.031+0000",
        "transaction_code_id": "9e0b8266-5fe2-422a-bb2a-e0910225c39e",
        "order_bulk_id": "bc565812-d50e-49c5-9e4e-6bb6524dceb7",
        "date": "2017-03-06",
        "is_read": false,
        "order_ticket_id": "f891c472-f534-40bb-b8bb-48fb6e62b1d2",
        "quantity": 4,
        "security_id": "a678d82d-2101-4966-89f3-cf57dcbed1c4",
        "metadata": {},
        "price": 65.44
    }
]

Aggregates all orders on a given date for a client. The unique client_id and the specific date must be provided. To obtain the appropriate client_id, use the GET /client endpoint to view all clients registered with your firm. This endpoint will net all the client’s orders for that date to reduce the number of required transactions. The endpoint returns a list of all orders included in the bulk order, including a bulk_order_id which can be used to manage the bulk order record for all of the orders.

HTTP REQUEST

POST /client/{client_id}/order_bulk

ARGUMENTS

Parameter Type Required Description
date date required Date for all the orders that should be aggregated together in the bulk order record
buy_transaction_code_id string required The id of the transaction code that will ultimately be used to denote the buy transactions
sell_transaction_code_id string required The id of the transaction code that will ultimately be used to denote the sell transactions

Bulk orders for an account

Example Request

curl -X POST -H "Authorization: Bearer <access_token>" \
    -H "Content-Type: application/json" \
    -d '{
        "date":"2017-03-06",
        "buy_transaction_code_id": "f5af397b-7d22-433f-b01e-8202184a6386",
        "sell_transaction_code_id": "7d8d41d0-ed4b-4ae2-acb3-e0baed2ff1cc"
      }' "https://[sandbox][api].hydrogenplatform.com/nucleus/v1/account/066304b6-017d-4c2c-8b76-92d772f1f3d7/order_bulk"

Example Response

[
    {
        "id": "0bc55529-b998-42bc-9637-6a19b317760e",
        "create_date": "2017-03-06T18:09:27.031+0000",
        "update_date": "2017-03-06T18:09:27.031+0000",
        "transaction_code_id": "9e0b8266-5fe2-422a-bb2a-e0910225c39e",
        "order_bulk_id": "bc565812-d50e-49c5-9e4e-6bb6524dceb7",
        "date": "2017-03-06"</