NAV

Nucleus  Proton  Electron

curl

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 savings, investing, wealth, insurance, and financial wellness. 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

Example Request

curl -X POST https://api.hydrogenplatform.com/authorization/v1/oauth/token?grant_type=client_credentials \
  -H "Authorization: Basic aHlkcm9nZW5faWQ6aHlkcm9nZW5fc2VjcmV0"

Example Response

{
  "access_token": "ac6b8213-2a77-4ecc-89fd-68c9f2aff256",
  "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:

curl -X GET https://api.hydrogenplatform.com/nucleus/v1/account \
-H "Authorization: Bearer ac6b8213-2a77-4ecc-89fd-68c9f2aff256"

Hydrogen uses OAuth 2.0 to facilitate authorization on the API, an industry standard framework for authorization. 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.


REQUEST 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 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, hydro, ion

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.

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:

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 Version Description
2018-09-07 v1.1.1 Added new optional fields to the goal entity. Added two new orchestration endpoints to subscribe an account to an allocation and to change the composition of a model
2018-11-30 v1.2.0 Added new optional fields to the client, bank link, withdrawal, and questionnaire entities. Created new entities including aggregation account, aggregation account balance, score, client-hydro, and goal track

Pagination

Example Request

curl -X GET -H "Authorization: Bearer ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://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 the 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 and max is 1000
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

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 follow:

/<endpoint>?filter=<query>

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

/<endpoint>?filter=<field>

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

/<endpoint>?filter=<embedded object>.<field>

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.

Endpoints

The following is an explanation of the major entities in the Nucleus API endpoints:

Name Description
Client A client is identified based on a unique identifier, usually a government issued id (e.g. social security number). A client can have multiple accounts, models, allocations and goals.
Account A client can have one or more accounts and each account may hold n-number of portfolios.
Portfolio Portfolios fall under accounts. Portfolios can only belong to one account. These portfolios may or may not be subscribed to a model, and can be a component of an allocation. Portfolios are unique to a given account, while models have holdings with theoretical strategic weights; portfolios reflect actual account holdings, which depend on changes in the model, account additions & withdrawals, dividends, cancelled trades, and other account-specific activity.
Model An abstract collection of one or more securities grouped together and strategically weighted. An account can be subscribed to n-number of models. Each model holds n-number of securities and may be a component of n-number of allocations.
Allocation An abstract collection of one or more models grouped together and strategically weighted. Each account is assigned to one or more allocations, which can contain multiple models.
Goal A desired financial outcome in the future, defined by time and monetary value.
Security Any financial instrument or product that an investor may own. Securities have certain attributes, like prices and unique identifiers. Securities are held within models and portfolios.
Asset Size The aggregate monetary value of an investment account based on underlying positions. The asset size changes as securities fluctuate or monies/securities are deposited/withdrawn.

Account

Account Management

Accounts are created below clients to represent an account on your firm’s platform, such as an investment account. One or more portfolios can be created below an account and map to models. Accounts will subscribe to an allocation. 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
managed boolean Indicates if the account is managed or self directed. Defaults to true, or that it’s managed
clients array 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. Only the owner will be able to execute transactions and trades on the account
      signature_data string Stored signature for the client on the account such as a Base30 or Base64 string
goals array List of goals mapped to the account with information such as goal amount and horizon
      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. Option to also store under the goal entity
      accumulation_horizon double 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 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
metadata map Custom information associated with the account 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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://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,
            "name": "Joint IRA 23",
            "account_type_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
            "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
                }
            ],
            "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",
            "managed": true,
            "name": "Investment Account 87 - Admin Owned",
            "account_type_id": "39770e8d-890d-485b-822e-5a1578f26d47",
            "clients": [
                {
                    "client_id": "107516c3-9035-4811-af7c-501be5a1fe26",
                    "client_account_association_type": "admin"
                }
            ],
            "goals": [
                {
                    "goal_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
                    "goal_amount": 40000,
                    "accumulation_horizon": 10,
                }
            ],
            "metadata": {}
        },
        {
            "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,
            "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
                }
            ],
            "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 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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
-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://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,
    "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
        }
    ],
    "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
managed boolean optional Indicates if the account is managed or self directed. Defaults to true, or that it’s managed
clients array 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. Only the owner will be able to execute transactions and trades on the account
      signature_data string optional Stored signature for the client on the account such as a Base30 or Base64 string
goals array optional List of goals mapped to the account with information such as goal amount and horizon
      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
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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    -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"
         },
         {
            "current_weight" : "50",
            "strategic_weight": "50",
            "date": "2018-06-28",
            "allocation_id": "f29d942a-7509-41be-8016-46743be0bcc8",  
            "goal_id": "a65929b6-b0a9-46e5-858a-121f0b10f4fb"
         }' "https://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 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 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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://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,
    "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
        }
    ],
    "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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
-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://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,
    "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
        }
    ],
    "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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://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 allocation can also optionally map to a goal. 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 below an account must add up to 100. 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 below an account must add up to 100. If the allocation is the only one, enter 100
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

List all account allocations

Example Request

curl -X GET -H "Authorization: Bearer ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
-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://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. 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
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

Retrieve an account allocation

Example Request

curl -X GET -H "Authorization: Bearer ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
-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://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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://api.hydrogenplatform.com/nucleus/v1/account/50b4d384-986d-4892-a30a-bc4c146d25a9/asset_size"

Example Response

[
    {
        "date": "2018-02-03",
        "value": 20000,
        "additions": 0
    },
    {
        "date": "2018-02-10",
        "value": 20543,
        "additions": 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

RESPONSE

Field Type Description
date date Date for this asset size record
value double Monetary value of the account on the particular date
additions double Amount added to the account value since the last asset size date, usually via deposit

List all account holdings

Example Request

curl -X GET -H "Authorization: Bearer ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://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,
        "amount": 2000,
        "shares": 20
    },
    {
        "date": "2018-02-03",
        "security_id": "24c3f327-20ac-4302-8330-6cf19de9a353",
        "weight": 2,
        "amount": 400,
        "shares": 40
    },
    {
        "date": "2018-02-03",
        "security_id": "cc5a6c52-32a5-4cd8-98db-4541c9b29add",
        "weight": 30,
        "amount": 6000,
        "shares": 6
    },
    {
        "date": "2018-02-03",
        "security_id": "3c416c11-1e43-4031-bc0a-e9dc3677f15a",
        "weight": 30,
        "amount": 6000,
        "shares": 60
    },
    {
        "date": "2018-02-03",
        "security_id": "59add370-01cf-42a0-bee8-ad75065df603",
        "weight": 28,
        "amount": 5600,
        "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
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

List all account transactions

Example Request

curl -X GET -H "Authorization: Bearer ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://api.hydrogenplatform.com/nucleus/v1/account/50b4d384-986d-4892-a30a-bc4c146d25a9/transaction"

Example Response

{
  "content": [
    {
        "id": "50b4d384-986d-4892-a30a-bc4c146d25a9",
        "date": "2018-01-31",
        "is_read": true,
        "portfolio_id": "c193de6e-564d-4b2d-893d-0307e92279b7",
        "model_id": "19ef73a9-8dd9-4df0-970e-c3f57c6f8d38",
        "price": 432.2,
        "quantity": 0.5,
        "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-31",
        "is_read": true,
        "portfolio_id": "c193de6e-564d-4b2d-893d-0307e92279b7",
        "model_id": "19ef73a9-8dd9-4df0-970e-c3f57c6f8d38",
        "price": 132.2,
        "quantity": 4,
        "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 date Date for when the transaction occurred
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
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

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
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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://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"
        },
        {
            "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"
        },
        {
            "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"
        }
    ],
    "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" \
-d '{
        "category": "Taxable",
        "code": "103",
        "is_taxable": true,
        "name": "Taxable",
        "short_name": "TXB"
    }' "https://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"
}

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
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://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"
}

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" \
-d '{
        "category": "Taxable",
        "code": "103",
        "is_active": true,
        "is_taxable": true,
        "short_name": "TXB",
        "name": "Taxable"
    }' "https://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"
}

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://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. 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 Stage

Account stages indicate what point an account is in along a user journey. The account 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 account stage such as Pending Funding or Signed Up
description string Description of what the step along the registration process that the account stage represents
order_index integer Indicator for where along the process the account stage falls. Generally, the higher the order index, the further along the process
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 stages

Example Request

curl -X GET -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
    "https://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",
            "order_index": 3
        },
        {
            "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",
            "order_index": 2
        },
        {
            "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",
            "order_index": 6
        },
        {
            "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",
            "order_index": 1
        },
        {
            "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",
            "order_index": 5
        },
        {
            "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",
            "order_index": 7
        },
        {
            "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",
            "order_index": 8
        },
        {
            "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",
            "order_index": 4
        },
        {
            "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",
            "order_index": 9
        },
        {
            "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",
            "order_index": 10
        }
    ],
    "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 an account 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
        }' "https://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",
    "order_index": 1
}

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”
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
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Retrieve an account stage

Example Request

curl -X GET -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
    "https://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",
    "order_index": 1
}

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 an account 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://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",
    "description": "Initial information provided and client created",
    "order_index": 1
}

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 an account stage

Example Request

curl -X DELETE -H "Authorization: Bearer 921c2e12-c3c3-4fe5-b8cc-2035d39ad44e" \
    "https://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}

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 account stage section for stage_ids.

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
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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://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"
        },
        {
            "id": "013380bf-7f17-44c1-93c5-892a7ed3498c",
            "create_date": "2017-04-07T00:00:00.000+0000",
            "update_date": "2018-02-08T16:59:27.000+0000",
            "status": "",
            "stage_id": "1d7e1aad-3c79-49fe-bbb9-bd5e239ae1e7",
            "account_id": "21098ed9-6439-46ba-abd9-eb6cf28866fb"
        },
        {
            "id": "01b252d3-1412-477f-8d29-6e2ff6e54c81",
            "create_date": "2017-10-05T00:00:00.000+0000",
            "update_date": "2018-02-08T16:59:27.000+0000",
            "status": "",
            "stage_id": "2a7a6cb7-ef71-4fe8-9169-2678f3799657",
            "account_id": "4ff21db3-97ab-4bbd-9885-be6aec522c44"
        }
    ],
    "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://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"
}

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
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://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"
}

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://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"
}

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://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}

Aggregation Account

Aggregation Account Management

Aggregation accounts are created below clients to store the details of individual, held-away accounts. Held-away accounts are usually checking accounts, savings accounts, credit card accounts, or external investment accounts that sit with and are managed by external institutions and financial companies independent of your firm. Held-away account information can be captured by integrating with a third-party service which supports Account Aggregation. This information can be used to provide customers with a better picture of their current financial health and gain business insights on holdings outside of the application.

Field Type Description
id UUID The id for the aggregation account
client_id UUID The id of a client to which the aggregation account belongs
account_name string The name of the held-away account for this aggregation account record
institution_name string The name of the institution holding the held-away account for this aggregation account record
category string Category for the held-away account such as “Bank Account”
subcategory string Subcategory for the held-away account such as “Checking Account”
account_number string The account number of the held-away account for this aggregation account record
mask string The masked version of the account number of the held-away account for this aggregation account record
currency_code string Alphabetic currency code for the base currency of the account linked, limited to 3 characters. See currency codes
is_active string Indicates if the aggregation account record is active. Defaults to true which indicates it is active
metadata map Custom information associated with the aggregation account 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 aggregation accounts

Example Request

curl -X GET -H "Authorization: Bearer ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://api.hydrogenplatform.com/nucleus/v1/aggregation_account"

Example Response

{
    "content": [
        {
            "id": "f96fad3e-a8cf-4915-bc0c-da4d9693ab83",
            "create_date": "2017-01-03T00:00:00.000+0000",
            "update_date": "2017-01-05T00:00:00.000+0000",
            "client_id": "b1d2b9dc-fb9d-4ce2-b2df-eb8801127b23",
            "account_name": "Bank Gold Checking",
            "institution_name": "Citywide Bank",
            "category": "Bank Account",
            "subcategory": "Checking Account",
            "account_number": "566788991",
            "mask": "XXXXX8991",
            "currency_code": "USD",
            "is_active": true,
            "metadata": {
                "source": "vendor"
            }
        },
        {
            "id": "e04683e9-d1d2-4382-86f0-88092971435e",
            "create_date": "2017-01-03T00:00:00.000+0000",
            "update_date": "2017-01-05T00:00:00.000+0000",
            "client_id": "63c4690b-88c3-47f4-b3d7-d4957eea9c3c",
            "account_name": "Priority Savings - 4455",
            "institution_name": "Citywide Bank",
            "category": "Bank Account",
            "subcategory": "Savings Account",
            "account_number": "677859916",
            "mask": "XXXXX9916",
            "currency_code": "USD",
            "is_active": true,
            "metadata": {
                "source": "vendor"
            }
        }
    ],
    "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 aggregation 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 metadata information is stored as a nested object within the aggregation account object.

HTTP REQUEST

GET /aggregation_account

Create an aggregation account

Example Request

curl -X POST -H "Authorization: Bearer ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
-H "Content-Type: application/json" \
-d '{
        "client_id": "b1d2b9dc-fb9d-4ce2-b2df-eb8801127b23",
        "account_name": "Bank Gold Checking",
        "institution_name": "Citywide Bank",
        "category": "Bank Account",
        "subcategory": "Checking Account",
        "account_number": "566788991",
        "mask": "XXXXX8991",
        "currency_code": "USD"
    }' "https://api.hydrogenplatform.com/nucleus/v1/aggregation_account"

Example Response

{
    "id": "f96fad3e-a8cf-4915-bc0c-da4d9693ab83",
    "create_date": "2017-01-03T00:00:00.000+0000",
    "client_id": "b1d2b9dc-fb9d-4ce2-b2df-eb8801127b23",
    "account_name": "Bank Gold Checking",
    "institution_name": "Citywide Bank",
    "category": "Bank Account",
    "subcategory": "Checking Account",
    "account_number": "566788991",
    "mask": "XXXXX8991",
    "currency_code": "USD",
    "is_active": true,
    "metadata": {}
}

Create an aggregation 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 endpoint returns an aggregation_account_id that can then be used to manage the aggregation account record and mapped to balance records for the aggregation account.

HTTP REQUEST

POST /aggregation_account

ARGUMENTS

Parameter Type Required Description
client_id UUID required The id of a client to which the aggregation account belongs
account_name string required The name of the held-away account for this aggregation account record
institution_name string required The name of the institution holding the held-away account for this aggregation account record
category string optional Category for the held-away account such as “Bank Account”
subcategory string optional Subcategory for the held-away account such as “Checking Account”
account_number string optional The account number of the held-away account for this aggregation account record
mask string optional The masked version of the account number of the held-away account for this aggregation account record
currency_code string optional Alphabetic currency code for the base currency of the account linked, limited to 3 characters. See currency codes
is_active string optional Indicates if the aggregation account record is active. Defaults to true which indicates it is active
metadata map optional Custom information associated with the aggregation 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

Retrieve an aggregation account

Example Request

curl -X GET -H "Authorization: Bearer ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://api.hydrogenplatform.com/nucleus/v1/aggregation_account/f96fad3e-a8cf-4915-bc0c-da4d9693ab83"

Example Response

{
    "id": "f96fad3e-a8cf-4915-bc0c-da4d9693ab83",
    "create_date": "2017-01-03T00:00:00.000+0000",
    "update_date": "2017-01-05T00:00:00.000+0000",
    "client_id": "b1d2b9dc-fb9d-4ce2-b2df-eb8801127b23",
    "account_name": "Bank Gold Checking",
    "institution_name": "Citywide Bank",
    "category": "Bank Account",
    "subcategory": "Checking Account",
    "account_number": "566788991",
    "mask": "XXXXX8991",
    "currency_code": "USD",
    "is_active": true,
    "metadata": {}
}

Retrieve the information for a specific aggregation account associated with a client. The unique aggregation_account_id must be provided. The endpoint returns the aggregation_account_id and details for the account specified. Note that the metadata information is stored as a nested object within the aggregation account object.

HTTP REQUEST

GET /aggregation_account/{aggregation_account_id}

Update an aggregation account

Example Request

curl -X PUT -H "Authorization: Bearer ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
-H "Content-Type: application/json" \
-d '{
        "client_id": "b1d2b9dc-fb9d-4ce2-b2df-eb8801127b23",
        "account_name": "Bank Gold Checking",
        "institution_name": "Citywide Bank",
        "category": "Bank Account",
        "subcategory": "Checking Account",
        "account_number": "566788991",
        "mask": "XXXXX8991",
        "currency_code": "USD",
        "is_active": true,
        "metadata": {
            "source": "vendor"
        }
    }' "https://api.hydrogenplatform.com/nucleus/v1/aggregation_account/f96fad3e-a8cf-4915-bc0c-da4d9693ab83"

Example Response

{
    "id": "f96fad3e-a8cf-4915-bc0c-da4d9693ab83",
    "create_date": "2017-01-03T00:00:00.000+0000",
    "update_date": "2017-01-06T00:00:00.000+0000",
    "client_id": "b1d2b9dc-fb9d-4ce2-b2df-eb8801127b23",
    "account_name": "Bank Gold Checking",
    "institution_name": "Citywide Bank",
    "category": "Bank Account",
    "subcategory": "Checking Account",
    "account_number": "566788991",
    "mask": "XXXXX8991",
    "currency_code": "USD",
    "is_active": true,
    "metadata": {
        "source": "vendor"
    }
}

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

HTTP REQUEST

PUT /aggregation_account/{aggregation_account_id}

Delete an aggregation account

Example Request

curl -X DELETE -H "Authorization: Bearer ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://api.hydrogenplatform.com/nucleus/v1/aggregation_account/f96fad3e-a8cf-4915-bc0c-da4d9693ab83"

Response (204 No Content)

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

HTTP REQUEST

DELETE /aggregation_account/{aggregation_account_id}

Aggregation Account Balance

Aggregation account balances are created under aggregation accounts. This entity is intended to store the monetary balance of the held-away account represented in the aggregation account record. Balance information can be stored either once or stored over time by creating new aggregation account balance records every time the balances are updated. Held-away account balance information can be captured by integrating with a third-party service which supports Account Aggregation. This information can be used to provide customers with a better picture of their current financial health and gain business insights on holdings outside of the application.

Field Type Description
id UUID The id for the aggregation account balance record
aggregation_account_id UUID The id of the aggregation account to which the balance record belongs
currency_code string Alphabetic currency code for the currency of the balance, limited to 3 characters. See currency codes
balance string Current balance of the aggregation account
available_balance string Available balance in the aggregation account, usually taking into consideration pending transactions or available overdraft
balance_time_stamp datetime Date and time for when the balance above applies, defaults to current timestamp
is_active string Indicates if the aggregation account balance record 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

List all aggregation account balances

Example Request

curl -X GET -H "Authorization: Bearer ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://api.hydrogenplatform.com/nucleus/v1/aggregation_account_balance"

Example Response

{
    "content": [
        {
            "id": "951d0ad2-cb3b-46b6-bd96-ba712b41b02f",
            "create_date": "2018-11-30T00:00:00.000+0000",
            "aggregation_account_id": "c6f59c0b-3407-4f6e-bcea-2dc71424847d",
            "currency_code": "USD",
            "balance": "36760.43",
            "available_balance": "35760.43",
            "balance_time_stamp": "2018-11-30T00:00:00.000+0000",
            "is_active": true
        },
        {
            "id": "951d0ad2-cb3b-46b6-bd96-ba712b41b02f",
            "create_date": "2018-12-01T00:00:00.000+0000",
            "aggregation_account_id": "c6f59c0b-3407-4f6e-bcea-2dc71424847d",
            "currency_code": "USD",
            "balance": "35760.43",
            "available_balance": "35760.43",
            "balance_time_stamp": "2018-12-01T00:00:00.000+0000",
            "is_active": true
        },
        {
            "id": "951d0ad2-cb3b-46b6-bd96-ba712b41b02f",
            "create_date": "2018-12-02T00:00:00.000+0000",
            "aggregation_account_id": "c6f59c0b-3407-4f6e-bcea-2dc71424847d",
            "currency_code": "USD",
            "balance": "35760.43",
            "available_balance": "40000.00",
            "balance_time_stamp": "2018-12-02T00:00:00.000+0000",
            "is_active": true
        }
    ],
    "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 all of the balance records for all aggregation accounts defined for your firm. You can filter using a unique aggregation_account_id to view the balance records for a specific aggregation account. To identify the appropriate aggregation_account_id, use the GET /aggregation_account endpoint to see all aggregation accounts defined for your firm. You can also filter based on the value provided for the balance_time_stamp to see the balance records for a specifc date or date range.

HTTP REQUEST

GET /aggregation_account_balance

Create an aggregation account balance

Example Request

curl -X POST -H "Authorization: Bearer ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
-H "Content-Type: application/json" \
-d '{
        "aggregation_account_id": "c6f59c0b-3407-4f6e-bcea-2dc71424847d",
        "currency_code": "USD",
        "balance": "36760.43",
        "available_balance": "35760.43",
        "balance_time_stamp": "2018-11-30T00:00:00.000+0000"
    }' "https://api.hydrogenplatform.com/nucleus/v1/aggregation_account_balance"

Example Response

{
    "id": "951d0ad2-cb3b-46b6-bd96-ba712b41b02f",
    "create_date": "2018-12-01T00:00:00.000+0000",
    "aggregation_account_id": "c6f59c0b-3407-4f6e-bcea-2dc71424847d",
    "currency_code": "USD",
    "balance": "36760.43",
    "available_balance": "35760.43",
    "balance_time_stamp": "2018-11-30T00:00:00.000+0000",
    "is_active": true
}

Create a balance record under an aggregation account. The aggregation_account_id must be provided. To obtain the appropriate aggregation_account_id use the GET /aggregation_account endpoint to view all aggregation accounts for your firm. If the values provided for balance and/or available_balane are not current, ensure the specify the timestamp for when the values apply. The endpoint returns an aggregation_account_balance_id used to manage the aggregation account record.

HTTP REQUEST

POST /aggregation_account_balance

ARGUMENTS

Parameter Type Required Description
aggregation_account_id UUID required The id of the aggregation account to which the balance record belongs
currency_code string required Alphabetic currency code for the currency of the balance, limited to 3 characters. See currency codes
balance string optional Balance of the aggregation account
available_balance string optional Available balance in the aggregation account, usually taking into consideration pending transactions or available overdraft
balance_time_stamp datetime optional Date and time for when the balance above applies, defaults to current timestamp
is_active string optional Indicates if the aggregation account balance record is 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 an aggregation account balance

Example Request

curl -X GET -H "Authorization: Bearer ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://api.hydrogenplatform.com/nucleus/v1/aggregation_account_balance/951d0ad2-cb3b-46b6-bd96-ba712b41b02f"

Example Response

{
    "id": "951d0ad2-cb3b-46b6-bd96-ba712b41b02f",
    "create_date": "2018-11-30T00:00:00.000+0000",
    "aggregation_account_id": "c6f59c0b-3407-4f6e-bcea-2dc71424847d",
    "currency_code": "USD",
    "balance": "36760.43",
    "available_balance": "35760.43",
    "balance_time_stamp": "2018-11-30T00:00:00.000+0000",
    "is_active": true
}

Retrieve the information for a specific balance record for an aggregation account. The unique aggregation_account_balance_id must be provided. The endpoint returns the aggregation_account_balance_id and details for the aggregation account balance record.

HTTP REQUEST

GET /aggregation_account_balance/{aggregation_account_balance_id}

Update an aggregation account balance

Example Request

curl -X PUT -H "Authorization: Bearer ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
-H "Content-Type: application/json" \
-d '{
        "aggregation_account_id": "c6f59c0b-3407-4f6e-bcea-2dc71424847d",
        "currency_code": "USD",
        "balance": "35760.43",
        "available_balance": "35760.43",
        "balance_time_stamp": "2018-12-01T00:00:00.000+0000",
        "is_active": true
    }' "https://api.hydrogenplatform.com/nucleus/v1/aggregation_account_balance/951d0ad2-cb3b-46b6-bd96-ba712b41b02f"

Example Response

{
    "id": "951d0ad2-cb3b-46b6-bd96-ba712b41b02f",
    "create_date": "2018-11-30T00:00:00.000+0000",
    "update_date": "2018-12-01T00:00:00.000+0000",
    "aggregation_account_id": "c6f59c0b-3407-4f6e-bcea-2dc71424847d",
    "currency_code": "USD",
    "balance": "35760.43",
    "available_balance": "35760.43",
    "balance_time_stamp": "2018-12-01T00:00:00.000+0000",
    "is_active": true
}

Update a balance record for an aggregation account. The unique aggregation_account_balance_id must be provided. To obtain the appropriate aggregation_account_balance_id, use the GET /aggregation_account_balance endpoint to view all aggregation account balance records and their current information. The details to be updated must also be provided. The endpoint returns the aggregation_account_balance_id and the details for the aggregation account balance record. If you wish to mark the aggregation account balance record as no longer relevant without permanently deleting it, use this endpoint to update the is_active field to false.

HTTP REQUEST

PUT /aggregation_account_balance/{aggregation_account_balance_id}

Delete an aggregation account balance

Example Request

curl -X DELETE -H "Authorization: Bearer ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://api.hydrogenplatform.com/nucleus/v1/aggregation_account_balance/951d0ad2-cb3b-46b6-bd96-ba712b41b02f"

Response (204 No Content)

Permanently delete a balance record for an aggregation account. The unique aggregation_account_balance_id must be provided. To obtain the appropriate aggregation_account_balance_id, use the GET /aggregation_account_balance endpoint to view all aggregation account balance records. This deletes the aggregation_account_balance_id and the details for the aggregation account balance record. If you wish to mark the aggregation account balance record as no longer relevant without permanently deleting it, use the PUT /aggregation_account_balance endpoint to update the is_active field to false.

HTTP REQUEST

DELETE /aggregation_account_balance/{aggregation_account_balance_id}

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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
  "https://api.hydrogenplatform.com/nucleus/v1/allocation"

Example Response

{
"content": [
    {
        "id": "04907eaa-3f33-49be-a35b-378cdf639fba",
        "category": "Alternative",
        "description": "Hedgeable Venture Fund I, L.P. gives accredited Hedgeable 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 by Hedgeable.",
        "is_active": true,
        "name": "Hedgeable Venture Fund I, L.P.",
        "volatility": 0.05999999865889549,
        "performance": 0.05999999865889549,
        "node_map": [],
        "metadata": {}
    },
    {
        "id": "073def0e-6fa0-4e52-badb-6ff2aecbc2b2",
        "category": "Asset Allocation",
        "description": "",
        "is_active": true,
        "name": "Retirement Core 5",
        "volatility": 0.05999999865889549,
        "performance": 0.05999999865889549,
        "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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    -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://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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    -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://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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://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

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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://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"
        },
        {
            "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"
        },
        {
            "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"
        }
    ],
    "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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    -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://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"
}

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

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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://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"
}

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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    -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://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"
}

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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
     "https://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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://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

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
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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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"
                }
            ]
        },
        {
            "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"
                }
            ]
        }
    ],
    "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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
     -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://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"
        }
    ]
}

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
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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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"
        }
    ]
}

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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
     -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://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"
        }
    ]
}

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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://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

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]
title string The title of the client such as “Mr.”, “Ms.”, “Miss”, “Mx.”, 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
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 or local identification number for a client such as Social Security Number, frequently used for Know-Your-Customer (KYC) purposes
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
is_verified boolean Indicator for whether or not 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 array 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
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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/nucleus/v1/client"

Example Response

{
    "content": [
        {
            "id": "099961da-7f41-4309-950f-2b51689a0033",
            "create_date": "2017-01-03T00:00:00.000+0000",
            "update_date": "2018-02-23T18:29:09.000+0000",
            "email": "[email protected]",
            "username": "[email protected]",
            "client_type": "individual",
            "title": "Mrs.",
            "first_name": "Jane",
            "middle_name": "Mary",
            "last_name": "Doe",
            "phone_number": "987-765-1244",
            "date_of_birth": "1971-12-27",
            "identification_number": "123-44-5566",
            "country_of_residence": "US",
            "is_verified": true,
            "hydro_id": "10lm4nz",
            "is_active": true,
            "metadata": {
                "median_household_income": "10000",
                "net_worth": "100000",
                "occupation": "Business Owner",
                "zillow_home_value": "450000",
                "annual_income": "70000"
            },
            "address": [
                {
                    "address_line1": "3 Downtown Street",
                    "address_line2": "",
                    "city": "New York",
                    "type": "Home",
                    "postalcode": "01191",
                    "country": "US",
                    "state": "NY"
                }
            ]
        },
        {
            "id": "fbc03484-08e8-446d-83aa-6d6cc236355e",
            "secondary_id": "234892384",
            "create_date": "2017-01-09T00:00:00.000+0000",
            "update_date": "2018-02-23T18:29:09.000+0000",
            "email": "[email protected]",
            "username": "advisor1",
            "client_type": "advisor",
            "title": "Mrs.",
            "first_name": "Marie",
            "last_name": "Baker",
            "date_of_birth": "1987-12-23",
            "is_active": true,
            "metadata": {
                "median_household_income": "10000",
                "net_worth": "550000",
                "occupation": "Service",
                "zillow_home_value": "450000",
                "annual_income": "80000"
            },
            "address": [
                {
                    "address_line1": "9 Main Street",
                    "address_line2": "",
                    "city": "New York9",
                    "type": "Home",
                    "postalcode": "99999",
                    "country": "US",
                    "state": "WY"
                }
            ]
        },
        {
            "id": "04907eaa-3f33-49be-a35b-378cdf639fba",
            "create_date": "2017-04-03T00:00:00.000+0000",
            "update_date": "2018-02-23T18:29:09.000+0000",
            "email": "[email protected]",
            "username": "andrewl",
            "title": "Mr.",           
            "first_name": "Andrew",
            "last_name": "Lewelz",
            "phone_number": "234-566-7788",
            "date_of_birth": "1993-12-21",
            "client_type": "individual",
            "is_active": true,
            "metadata": {
                "median_household_income": "70000",
                "net_worth": "400000",
                "occupation": "Information Systems",
                "zillow_home_value": "425000",
                "annual_income": "180000"
            },
            "address": [
                {
                    "address_line1": "93 Main Street",
                    "address_line2": "",
                    "city": "New York",
                    "type": "Home",
                    "postalcode": "100001",
                    "country": "US",
                    "state": "NY"
                }
            ]
        }
    ],
    "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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    -H "Content-Type: application/json" \
    -d '{
            "email": "[email protected]",
            "username": "[email protected]",
            "client_type": "individual",
            "title": "Mrs.",
            "first_name": "Jane",
            "middle_name": "Mary",
            "last_name": "Doe",
            "phone_number": "987-765-1244",
            "date_of_birth": "1971-12-27",
            "identification_number": "123-44-5566",
            "country_of_residence": "US",
            "is_verified": true,
            "hydro_id": "10lm4nz",
            "is_active": true,
            "metadata": {
                "median_household_income": "10000",
                "net_worth": "100000",
                "occupation": "Business Owner",
                "zillow_home_value": "450000",
                "annual_income": "70000"
            },
            "address": [
                {
                    "address_line1": "3 Downtown Street",
                    "address_line2": "",
                    "city": "New York",
                    "type": "Home",
                    "postalcode": "01191",
                    "country": "US",
                    "state": "NY"
                }
            ]
        }' "https://api.hydrogenplatform.com/nucleus/v1/client"

Example Response

{
    "id": "099961da-7f41-4309-950f-2b51689a0033",
    "create_date": "2017-01-03T00:00:00.000+0000",
    "email": "[email protected]",
    "username": "[email protected]",
    "client_type": "individual",
    "title": "Mrs.",
    "first_name": "Jane",
    "middle_name": "Mary",
    "last_name": "Doe",
    "phone_number": "987-765-1244",
    "date_of_birth": "1971-12-27",
    "identification_number": "123-44-5566",
    "country_of_residence": "US",
    "is_verified": true,
    "hydro_id": "10lm4nz",
    "is_active": true,
    "metadata": {
        "median_household_income": "10000",
        "net_worth": "100000",
        "occupation": "Business Owner",
        "zillow_home_value": "450000",
        "annual_income": "70000"
    },
    "address": [
        {
            "address_line1": "3 Downtown Street",
            "address_line2": "",
            "city": "New York",
            "type": "Home",
            "postalcode": "01191",
            "country": "US",
            "state": "NY"
        }
    ]
}

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]
title string optional The title of the client such as “Mr.”, “Ms.”, “Miss”, “Mx.”, 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
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 or local identification number for a client such as Social Security Number, frequently used for Know-Your-Customer (KYC) purposes
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
is_verified boolean optional Indicator 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 array 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
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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/nucleus/v1/client/099961da-7f41-4309-950f-2b51689a0033"

Example Response

{
    "id": "099961da-7f41-4309-950f-2b51689a0033",
    "create_date": "2017-01-03T00:00:00.000+0000",
    "update_date": "2018-02-23T18:29:09.000+0000",
    "email": "[email protected]",
    "username": "[email protected]",
    "client_type": "individual",
    "title": "Mrs.",
    "first_name": "Jane",
    "middle_name": "Mary",
    "last_name": "Doe",
    "phone_number": "987-765-1244",
    "date_of_birth": "1971-12-27",
    "identification_number": "123-44-5566",
    "country_of_residence": "US",
    "is_verified": true,
    "hydro_id": "10lm4nz",
    "is_active": true,
    "metadata": {
        "median_household_income": "10000",
        "net_worth": "100000",
        "occupation": "Business Owner",
        "zillow_home_value": "450000",
        "annual_income": "70000"
    },
    "address": [
        {
            "address_line1": "3 Downtown Street",
            "address_line2": "",
            "city": "New York",
            "type": "Home",
            "postalcode": "01191",
            "country": "US",
            "state": "NY"
        }
    ]
}

HTTP REQUEST

GET /client/{client_id}

Update a client

Example Request

curl -X PUT -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    -H "Content-Type: application/json" \
    -d '{
            "email": "[email protected]",
            "username": "[email protected]",
            "client_type": "individual",
            "title": "Mrs.",
            "first_name": "Jane",
            "middle_name": "Mary",
            "last_name": "Doe",
            "phone_number": "987-765-1244",
            "date_of_birth": "1971-12-27",
            "identification_number": "123-44-5566",
            "country_of_residence": "US",
            "is_verified": true,
            "hydro_id": "10lm4nz",
            "is_active": false,
            "metadata": {
                "median_household_income": "10000",
                "net_worth": "100000",
                "occupation": "Business Owner",
                "zillow_home_value": "450000",
                "annual_income": "70000"
            },
            "address": [
                {
                    "address_line1": "3 Downtown Street",
                    "address_line2": "",
                    "city": "New York",
                    "type": "Home",
                    "postalcode": "01191",
                    "country": "US",
                    "state": "NY"
            }
        ]
}' "https://api.hydrogenplatform.com/nucleus/v1/client/099961da-7f41-4309-950f-2b51689a0033"

Example Response

{
    "id": "099961da-7f41-4309-950f-2b51689a0033",
    "create_date": "2017-01-03T00:00:00.000+0000",
    "update_date": "2018-02-23T18:29:09.000+0000",
    "email": "[email protected]",
    "username": "[email protected]",
    "client_type": "individual",
    "title": "Mrs.",
    "first_name": "Jane",
    "middle_name": "Mary",
    "last_name": "Doe",
    "phone_number": "987-765-1244",
    "date_of_birth": "1971-12-27",
    "identification_number": "123-44-5566",
    "country_of_residence": "US",
    "is_verified": true,
    "hydro_id": "10lm4nz",
    "is_active": false,
    "metadata": {
        "median_household_income": "10000",
        "net_worth": "100000",
        "occupation": "Business Owner",
        "zillow_home_value": "450000",
        "annual_income": "70000"
    },
    "address": [
        {
            "address_line1": "3 Downtown Street",
            "address_line2": "",
            "city": "New York",
            "type": "Home",
            "postalcode": "01191",
            "country": "US",
            "state": "NY"
        }
    ]
}

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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/nucleus/v1/client/099961da-7f41-4309-950f-2b51689a0033"

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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://api.hydrogenplatform.com/nucleus/v1/client/099961da-7f41-4309-950f-2b51689a0033/asset_size"

Example Response

[
    {
        "date": "2018-02-03",
        "value": 20000,
        "additions": 0
    },
    {
        "date": "2018-02-04",
        "value": 24500,
        "additions": 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

RESPONSE

Field Type Description
date date Date for this asset size record
value double Monetary value of all the client’s accounts on the particular date
additions double Amount added to all of the client’s accounts on the particular date, usually via deposits

List all client holdings

Example Request

curl -X GET -H "Authorization: Bearer ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://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,
        "amount": 2000,
        "shares": 20
    },
    {
        "date": "2018-02-03",
        "security_id": "691c2255-a1a6-451f-b772-cb262725d7e2",
        "weight": 2,
        "amount": 400,
        "shares": 4
    },
    {
        "date": "2018-02-03",
        "security_id": "0283c814-db55-4470-8cd8-8b9ae945182f",
        "weight": 30,
        "amount": 6000,
        "shares": 60
    },
    {
        "date": "2018-02-03",
        "security_id": "0d652520-7e6a-461d-abe8-56b956c08d2e",
        "weight": 30,
        "amount": 6000,
        "shares": 70
    },
    {
        "date": "2018-02-03",
        "security_id": "c090f392-409d-459a-8054-333fe96fb877",
        "weight": 28,
        "amount": 5600,
        "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
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%
amount double Monetary value of the shares in the holding record
shares double Number of shares in the holding record

List all client transactions

Example Request

curl -X GET -H "Authorization: Bearer ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://api.hydrogenplatform.com/nucleus/v1/client/099961da-7f41-4309-950f-2b51689a0033/transaction"

Example Response

{
  "content": [
        {
            "id": "efa289b2-3565-42e6-850b-8dad25727e99",
            "date": "2018-01-31",
            "is_read": true,
            "portfolio_id": "8ec467e6-6faa-4916-b380-6af0b21a34cc",
            "model_id": "6dbadddc-41ff-4634-a145-16678b422557",
            "price": 200,
            "quantity": 2,
            "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-31",
            "is_read": true,
            "portfolio_id": "8ec467e6-6faa-4916-b380-6af0b21a34cc",
            "model_id": "6dbadddc-41ff-4634-a145-16678b422557",
            "price": 1000,
            "quantity": 6,
            "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 date Date of the transaction record
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
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

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
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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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"
        }
     ],
    "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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    -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://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"
}

Create a new client response for a question as part of a questionnaires. Must provide the answer_id and the answer value. 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 optional The id of the client to whom the response belongs
account_id UUID optional 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
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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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"
}

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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    -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://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"
}

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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
-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://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 an 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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
-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://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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://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}

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
description string Description for the decision tree such as “Tree to allocate clients to taxable portfolios”
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://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",
            "description": "Decision tree which allocates people looking to open a retirement account"
        },
        {
            "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",
            "description": "Decision tree which allocates people looking to open a retirement account"
        },
        {
            "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",
            "description": "Decision tree which allocates people looking to open a retirement account"
        }
    ],
    "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",
              "description": "Decision tree which allocates people looking to open a retirement account"
          }' "https://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",
    "description": "Decision tree which allocates people looking to open a retirement account"
}

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
description string optional Description for the decision tree such as “Tree to allocate clients to taxable portfolios”
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://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",
    "description": "Decision tree which allocates people looking to open a retirement account"
}

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",
              "description": "Decision tree which allocates people looking to open a retirement account"
          }' "https://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",
    "description": "Decision tree which allocates people looking to open a retirement account"
}

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://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
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://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
        },
        {
            "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
        },
        {
            "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
        }
    ],
    "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://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
}

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
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://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
}

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://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
}

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://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
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://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"
      },
      {
          "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"
      },
      {
          "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"
      }
  ],
  "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://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"
}

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
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://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"
}

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://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"
}

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://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}

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
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
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
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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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",
        "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",
        "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",
        "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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    -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://api.hydrogenplatform.com/nucleus/v1/funding"

Example Response

{
    "id": "9f5d3254-95c5-4c9d-8fad-f47c801bb888",
    "create_date": "2018-02-28T21:58:26.000+0000",
    "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
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”
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
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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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",
    "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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
     -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://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",
    "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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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
account_id UUID The id for the account to which the bank link belongs
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
bank_account_name string Name of the bank account, e.g. Mike’s HSBC Checking
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_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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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",
            "name": "HSBC",
            "routing": "111111",
            "routing_wire": "111111-22",
            "currency_code": "USD",
            "balance": "1500",
            "available_balance": "1600",
            "type": "Checking",
            "is_active": true,
            "is_link_verified": true,
            "link_verified_date": "2018-01-01",
            "type": "Checking",
            "metadata": {}
        },
        {
            "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",
            "bank_account_name": "Bank 2 - Checking Account",
            "name": "Bank XYZ2",
            "routing": "5289786002",
            "currency_code": "USD",
            "balance": "36754.04",
            "available_balance": "35754.04",
            "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",
            "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_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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
     -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",
            "name": "HSBC",
            "routing": "111111",
            "routing_wire": "111111-22",
            "currency_code": "USD",
            "balance": "1500",
            "available_balance": "1600",
            "type": "Checking",
            "is_active": true,
            "is_link_verified": true,
            "link_verified_date": "2018-01-01",
            "type": "Checking"
        }' "https://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",
    "name": "HSBC",
    "routing": "111111",
    "routing_wire": "111111-22",
    "currency_code": "USD",
    "balance": "1500",
    "available_balance": "1600",
    "type": "Checking",
    "is_active": true,
    "is_link_verified": true,
    "link_verified_date": "2018-01-01",
    "type": "Checking",
    "metadata": {}
}

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
account_id UUID required The id for the account to which the bank link belongs
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
bank_account_name string optional Name of the bank account, e.g. Mike’s HSBC Checking
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_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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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",
    "name": "HSBC",
    "routing": "111111",
    "routing_wire": "111111-22",
    "currency_code": "USD",
    "balance": "1500",
    "available_balance": "1600",
    "type": "Checking",
    "is_active": true,
    "is_link_verified": true,
    "link_verified_date": "2018-01-01",
    "type": "Checking",
    "metadata": {}
}

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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
     -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",
            "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",
            "type": "Checking",
            "metadata": {}
        }' "https://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",
    "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",
    "type": "Checking",
    "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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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
invested_date date 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 date In the case of recurring deposits, the last date and time that the deposit was last requested
received_date date 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 date Date and time that the status of the record was last updated
type string Indicates the payment type such as “check, “wire”, etc.
funding_id UUID The id of the funding record that maps to this deposit
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 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
    "https://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",
            "amount": 2000,
            "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",
            "funding_id": "43a983e7-c930-443b-a499-53767814b07d"
        },
        {
            "id": "c1df397e-17c0-4fab-a61f-367f7ff90f57",
            "create_date": "2018-03-19T15:16:50.000+0000",
            "update_date": "2018-03-19T16:08:59.000+0000",
            "amount": 2000,
            "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",
            "funding_id": "43a983e7-c930-443b-a499-53767814b07d"
        },
        {
            "id": "08e5f077-0c8c-4831-a4cc-3a7a59e067d2",
            "create_date": "2018-03-19T15:16:47.000+0000",
            "update_date": "2018-03-19T15:16:47.000+0000",
            "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",
            "funding_id": "9f5d3254-95c5-4c9d-8fad-f47c801bb888"
        }
    ],
    "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 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
    -H "Content-Type: application/json" \
    -d '{
            "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",
            "funding_id": "9f5d3254-95c5-4c9d-8fad-f47c801bb888"
        }' "https://api.hydrogenplatform.com/nucleus/v1/deposit"

Example Response

{
    "id": "08e5f077-0c8c-4831-a4cc-3a7a59e067d2",
    "create_date": "2018-03-19T15:16:47.000+0000",
    "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",
    "funding_id": "9f5d3254-95c5-4c9d-8fad-f47c801bb888"
}

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
invested_date date required Date and time that the funds should be pulled from the funding request to be invested
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 date optional In the case of recurring deposits, the last date and time that the deposit was last requested
received_date date 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 datetime optional Date and time that the record was last updated
type string optional Indicates the payment type such as “check, “wire”, etc.
funding_id UUID optional The id of the funding record that maps to this deposit
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 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
    "https://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",
    "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",
    "funding_id": "9f5d3254-95c5-4c9d-8fad-f47c801bb888"
}

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 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
    -H "Content-Type: application/json" \
    -d '{
            "account_number": "569345",
            "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",
            "funding_id": "9f5d3254-95c5-4c9d-8fad-f47c801bb888"
    }' "https://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",
    "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",
    "funding_id": "9f5d3254-95c5-4c9d-8fad-f47c801bb888"
}

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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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
withdrawal_date date 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 date In the case of recurring withdrawals, the date and time that the withdrawal was last requested
received_date date Date and time that the withdrawal was received
status string Status of the transaction such as “Processing”
status_time_stamp datetime Date and time that the status of the record was last updated
type string Indicates the payment type such as “check, “wire”, etc.
funding_id UUID The id of the funding record that maps to this withdrawal
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 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
    "https://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",
        "account_number": "bKU8LQ6gI",
        "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",
        "funding_id": "4cc15366-def0-4b39-b9b7-840a67ff9a88"
    }
  ],
  "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 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
    -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://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",
    "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"
}

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
withdrawal_date date required Date and time that the withdrawal was made
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 date optional In the case of recurring withdrawals, the date and time that the withdrawal was last requested
received_date date optional Date and time that the withdrawal was received
status string optional Status of the transaction such as “Processing”
status_time_stamp datetime 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.
funding_id UUID optional The id of the funding record that maps to this withdrawal
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 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
    "https://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",
    "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"
}

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 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
    -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://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",
    "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"
}

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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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
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”
transfer_type string Type of transaction being made such as “wire” or “check”
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 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
    "https://api.hydrogenplatform.com/nucleus/v1/transfer"

Example Response

{
    "content": [
        {
            "id": "111d714c-1d1c-47cf-9cb7-760428e86c24",
            "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",
            "amount": 13000,
            "comment": "Closed down previous 401k",
            "firm_name": "Vanguard",
            "status": "Pending",
            "transfer_all_cash": true,
            "transfer_type": "WIRE",
            "account_id": "099961da-7f41-4309-950f-2b51689a0033",
            "account_type_id": "647c54c3-b649-477e-8cc7-eee56a120dd3"
        },
        {
            "id": "1b19a750-f3c6-46e7-9131-fe11f06314ea",
            "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",
            "amount": 13000,
            "comment": "Closed down previous 401k",
            "firm_name": "Vanguard",
            "status": "Pending",
            "transfer_all_cash": true,
            "transfer_type": "WIRE",
            "account_id": "04907eaa-3f33-49be-a35b-378cdf639fba",
            "account_type_id": "eb3d7f60-a133-4ca9-815f-3677bcdc23a3"
        },
        {
            "id": "93197309-ff29-458a-ac9d-ad24ac2d95c9",
            "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",
            "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"
        }
    ],
    "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 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
    -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",
            "transfer_all_cash": true,
            "transfer_type": "WIRE",
            "account_id": "099961da-7f41-4309-950f-2b51689a0033",
            "account_type_id": "647c54c3-b649-477e-8cc7-eee56a120dd3"
        }' "https://api.hydrogenplatform.com/nucleus/v1/transfer"

Example Response

{
    "id": "111d714c-1d1c-47cf-9cb7-760428e86c24",
    "create_date": "2018-04-09T21:02:11.000+0000",
    "account_holder": "JB Smith",
    "account_number": "5889632503",
    "amount": 13000,
    "comment": "Closed down previous 401k",
    "firm_name": "Vanguard",
    "dtc_number" : "345928204",
    "status": "Pending",
    "transfer_all_cash": true,
    "transfer_type": "WIRE",
    "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
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 transaction being made such as “wire” or “check”
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 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
    "https://api.hydrogenplatform.com/nucleus/v1/transfer/111d714c-1d1c-47cf-9cb7-760428e86c24"

Example Response

{
    "id": "111d714c-1d1c-47cf-9cb7-760428e86c24",
    "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",
    "amount": 13000,
    "comment": "Closed down previous 401k",
    "firm_name": "Vanguard",
    "dtc_number" : "345928204",
    "status": "Pending",
    "transfer_all_cash": true,
    "transfer_type": "WIRE",
    "account_id": "099961da-7f41-4309-950f-2b51689a0033",
    "account_type_id": "647c54c3-b649-477e-8cc7-eee56a120dd3"
}

Retrieve the information for a 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 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
    -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",
            "transfer_all_cash": true,
            "transfer_type": "WIRE",
            "account_id": "099961da-7f41-4309-950f-2b51689a0033",
            "account_type_id": "647c54c3-b649-477e-8cc7-eee56a120dd3"
        }' "https://api.hydrogenplatform.com/nucleus/v1/transfer/111d714c-1d1c-47cf-9cb7-760428e86c24"

Example Response

{
    "id": "111d714c-1d1c-47cf-9cb7-760428e86c24",
    "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",
    "amount": 13000,
    "comment": "Closed down previous 401k",
    "firm_name": "Vanguard",
    "dtc_number" : "345928204",
    "status": "Pending",
    "transfer_all_cash": true,
    "transfer_type": "WIRE",
    "account_id": "099961da-7f41-4309-950f-2b51689a0033",
    "account_type_id": "647c54c3-b649-477e-8cc7-eee56a120dd3"
}

Update the information for a 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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/nucleus/v1/transfer/111d714c-1d1c-47cf-9cb7-760428e86c24"

Response (204 No Content)

Permanently delete a 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 type 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.
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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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,
          "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,
          "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,
          "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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
     -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://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,
    "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 type 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.
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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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,
    "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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
     -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://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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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 goal asset sizes

Example Request

curl -X GET -H "Authorization: Bearer ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://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",
      "value": 20000,
      "additions": 0
    },
    {
      "date": "2018-02-04",
      "value": 24500,
      "additions": 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 this asset size record
value double Monetary value of the goal on the particular date
additions double Amount added to the goal in all of the client’s accounts on the particular date

List goal holdings

Example Request

curl -X GET -H "Authorization: Bearer ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://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,
    "amount": 2000,
    "shares": 20
  },
  {
    "date": "2018-02-03",
    "security_id": "89da9660-3efe-4694-b1a7-0958a4f72f0e",
    "weight": 2,
    "amount": 400,
    "shares": 40
  },
  {
    "date": "2018-02-03",
    "security_id": "8f7de7e6-3b32-42ff-97a4-d1260811b099",
    "weight": 30,
    "amount": 6000,
    "shares": 6
  },
  {
    "date": "2018-02-03",
    "security_id": "b2870d61-d6e0-4a94-9c1e-7a064af13eca",
    "weight": 30,
    "amount": 6000,
    "shares": 60
  },
  {
    "date": "2018-02-03",
    "security_id": "dd3e251e-90e2-4e2d-9f3a-4675be5b172f",
    "weight": 28,
    "amount": 5600,
    "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
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%
amount double Monetary value of the shares in the holding record
shares double Number of shares in the holding record

List goal transactions

Example Request

curl -X GET -H "Authorization: Bearer ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://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-31",
        "is_read": true,
        "portfolio_id": "b4c033db-9d05-4a33-8e28-40650d454487",
        "model_id": "4b61f78e-d80e-452d-8201-b1adb87f5bb4",
        "price": 432.2,
        "quantity": 0.5,
        "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-31",
        "is_read": true,
        "portfolio_id": "fad85772-ded2-4f12-90f7-28e68afcac6f",
        "model_id": "72ebcdfa-70c7-427b-aebb-0df000b3a0a0",
        "price": 132.2,
        "quantity": 4,
        "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
date date Date of the transaction record
is_read boolean Indicator to show whether or not the transaction has been read. Defaults to true which indicates it has been read.
portfolio_id UUID The id of the portfolio that the transaction falls under
model_id UUID The id of the model to which the portfolio that the transaction falls under subscribes
price double Price for the security included in the transaction at which is was sold or purchased
quantity double Quantity of shares of the security purchased
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

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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
  "https://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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
-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://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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
  "https://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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
-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://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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
  "https://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
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
metadata map Custom information associated with the model in the format key:value. See Metadata
is_active boolean Indicates if the model is active. Defaults to true which indicates that it is currently 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 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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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",
            "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,
            "node_map": [],
        },
        {
            "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,
            "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",
            "secondary_id": "3546730",
            "category": "Risk Managed",
            "description": "Dynamic Nasdaq Stock (Tax-Efficient)",
            "is_active": true,
            "name": "Concentrated Aggressive Core [Tax-Efficient]",
            "node_map": [],
            "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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
       -H "Content-Type: application/json" \
       -d '{
              "category": "Alpha Generating",
              "description": "Tactical Industrial Stock",
              "name": "Industrial Stocks",
              "secondary_id": "3546728"
          }' "https://api.hydrogenplatform.com/nucleus/v1/model"

Example Response

{
    "id": "013380bf-7f17-44c1-93c5-892a7ed3498c",
    "create_date": "2018-02-02T9:00:03.000+0000",
    "category": "Alpha Generating",
    "description": "Tactical Industrial Stock",
    "is_active": true,
    "name": "Industrial Stocks",
    "secondary_id": "3546728",
    "node_map": [],
    "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
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
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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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,
    "secondary_id": "3546728",
    "node_map": [],
    "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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
       -H "Content-Type: application/json" \
       -d '{
              "category": "Alpha Generating",
              "description": "Tactical Industrial Stock",
              "name": "Industrial Stocks",
              "secondary_id": "3546728"
          }' "https://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",
    "secondary_id": "3546728",
    "node_map": [],
    "metadata": {}
}

Update a model for your firm. The model_id must be provided. To obtain the 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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    -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://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
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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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 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
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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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"
    },
    {
      "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"
    }
  ],
  "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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    -H "Content-Type: application/json" \
    -d '{
            "asset_size" : 1.1,
            "date" : "2017-01-02",
            "is_reconciled" : true,
            "model_id" : "5736e6f7-5e12-448e-830c-c1f2b9317d48"
        }' "https://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"
}

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
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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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"
}

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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    -H "Content-Type: application/json" \
    -d '{
            "asset_size" : 1.1,
            "date" : "2017-01-04",
            "is_reconciled" : true,
            "model_id" : "5736e6f7-5e12-448e-830c-c1f2b9317d48"
        }' "https://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"
}

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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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
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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
      "https://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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    -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://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
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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
      "https://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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    -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://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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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 an 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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    -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://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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    -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://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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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
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://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"
    }
  ],
  "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://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"
}

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
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://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"
}

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://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"
}

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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
     -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://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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
     "https://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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
     -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://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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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
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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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"
    },
    {
      "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"
    }
  ],
  "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 a 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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    -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://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

Bulk orders for a client

Example Request

curl -X POST -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    -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://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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    -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://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",
        "price": 100,
        "is_read": false,
        "order_ticket_id": "53eaa9da-9a5d-4e20-8e76-24aa8b1dd4d1",
        "quantity": 1,
        "security_id": "615e3777-98d6-48d6-a05b-9c000af5d4b6",
        "metadata": {}
    },
    {
        "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",
        "price": 65.44,
        "is_read": false,
        "order_ticket_id": "f891c472-f534-40bb-b8bb-48fb6e62b1d2",
        "quantity": 4,
        "security_id": "a678d82d-2101-4966-89f3-cf57dcbed1c4",
        "metadata": {}
    }
]

Aggregates all orders on a given date for an account . The unique account_id and the specific date must be provided. To obtain the appropriate account_id, use the GET /account endpoint to view all accounts defined for your firm. This endpoint will net all the orders on that date for the account 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 /account/{account_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

Sell all account order

Example Request

curl -X POST -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    -H "Content-Type: application/json" \
    -d '{
        "sell_transaction_code_id": "7d8d41d0-ed4b-4ae2-acb3-e0baed2ff1cc"
      }' "https://api.hydrogenplatform.com/nucleus/v1/account/52654829-e80b-4f16-9f8b-c9fde8a1aa63/order_sell_all"

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",
        "order_bulk_id": "114556fe-ee78-431d-be5e-60ae08ddf9a7",
        "date": "2017-03-06",
        "price": 51.25,
        "is_read": false,
        "order_ticket_id": "5da53a30-49e6-4162-8728-58d6348bfb24",
        "quantity": 4,
        "security_id": "000cb131-0b59-4b14-a0ef-e7832d5ecf51",
        "account_id": "c80c9729-3fd5-4a2f-be8e-915cdf21b49d",
        "portfolio_id": "665969c4-7b2d-44f8-91de-4607416c75cf",
        "model_id": "f43a535b-477d-447c-99ca-b47cb2037849",
        "metadata": {}
    },
    {
        "id": "35895811-9b52-4497-ac47-7ceba25dc4e5",
        "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": "2017-03-06",
        "price": 40.5,
        "is_read": false,
        "order_ticket_id": "5da53a30-49e6-4162-8728-58d6348bfb24",
        "quantity": 4,
        "security_id": "351c6084-1ed2-4b48-ba8e-fa8fe9709756",
        "account_id": "c80c9729-3fd5-4a2f-be8e-915cdf21b49d",
        "portfolio_id": "665969c4-7b2d-44f8-91de-4607416c75cf",
        "model_id": "8ac591a5-fa28-4880-b066-3db3d61c6bf9",
        "metadata": {}
    },
  ]

Create order records necessary to entirely sell all the holdings within an account. Securities will only be sold; no securities will be bought. The unique account_id must be provided. To obtain the appropriate account_id, use the GET /account endpoint to view all of the accounts defined for your firm. The endpoint returns a series of order records with order_ids and their underlying information, similar to the GET /order endpoint.

HTTP REQUEST

POST /account/{account_id}/order_sell_all

ARGUMENTS

Parameter Type Required Description
sell_transaction_code_id UUID required The id of the transaction code to denote a buy transaction
buy_transaction_code_id UUID optional The id of the transaction code to denote a buy transaction
buy_threshold double optional Buying threshold for the account as a monetary amount. Defaults to 0
cash_portfolio_id UUID optional The id of the cash portfolio for the account
commit_orders boolean optional Indicates if the orders should be committed for execution. Defaults to true which indicates they should be committed
non_fractional boolean optional Indicates if purchasing/selling fractional shares of securities is allowed. Defaults to false which indicates it is allowed
port_threshold double optional Threshold for the portfolio as a monetary amount. Defaults to 0
restrictions_on boolean optional Indicates if there are restrictions on the account that should be followed. Defaults to false which indicates there are not
sell_threshold double optional Selling threshold for the account as a monetary amount. Defaults to 0

Sell all portfolio order

curl -X POST -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    -H "Content-Type: application/json" \
    -d '{
          "sell_transaction_code_id": "7d8d41d0-ed4b-4ae2-acb3-e0baed2ff1cc"
      }' "https://api.hydrogenplatform.com/nucleus/v1/portfolio/ef93ce1c-b50e-4856-803a-db5332be93b0/order_sell_all"

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",
        "order_bulk_id": "114556fe-ee78-431d-be5e-60ae08ddf9a7",
        "date": "2017-03-06",
        "price": 51.25,
        "is_read": false,
        "order_ticket_id": "5da53a30-49e6-4162-8728-58d6348bfb24",
        "quantity": 4,
        "portfolio_id": "8bf331f7-c7c6-46b5-b57b-36fcffdd5cbb",
        "security_id": "000cb131-0b59-4b14-a0ef-e7832d5ecf51",
        "account_id": "c80c9729-3fd5-4a2f-be8e-915cdf21b49d",
        "model_id": "f43a535b-477d-447c-99ca-b47cb2037849",
        "metadata": {}
    },
    {
        "id": "35895811-9b52-4497-ac47-7ceba25dc4e5",
        "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": "2017-03-062",
        "price": 40.5,
        "is_read": false,
        "order_ticket_id": "5da53a30-49e6-4162-8728-58d6348bfb24",
        "quantity": 4,
        "portfolio_id": "8bf331f7-c7c6-46b5-b57b-36fcffdd5cbb",
        "security_id": "351c6084-1ed2-4b48-ba8e-fa8fe9709756",
        "account_id": "c80c9729-3fd5-4a2f-be8e-915cdf21b49d",
        "model_id": "f43a535b-477d-447c-99ca-b47cb2037849",
        "metadata": {}
    }
]

Create order records necessary to entirely sell all the holdings within a portfolio. Securities will only be sold; no securities will be bought. The unique portfolio_id must be provided. To obtain the appropriate portfolio_id, use the GET /portfolio endpoint to view all of the portfolios defined for your firm. The endpoint returns a series of order records with order_ids and their underlying information, similar to the GET /order endpoint.

HTTP REQUEST

POST /portfolio/{portfolio_id}/order_sell_all

ARGUMENTS

Parameter Type Required Description
sell_transaction_code_id UUID required The id of the transaction code to denote a buy transaction
buy_transaction_code_id UUID optional The id of the transaction code to denote a buy transaction
buy_threshold double optional Buying threshold for the account as a monetary amount. Defaults to 0
cash_sec_id UUID optional The id of the cash security for the portfolio
commit_orders boolean optional Indicates if the orders should be committed for execution. Defaults to true which indicates they should be committed
non_fractional boolean optional Indicates if purchasing/selling fractional shares of securities is allowed. Defaults to false which indicates it is allowed
port_threshold double optional Threshold for the portfolio as a monetary amount. Defaults to 0
restrictions_on boolean optional Indicates if there are restrictions on the account that should be followed. Defaults to false which indicates there are not
sell_threshold double optional Selling threshold for the account as a monetary amount. Defaults to 0

Order Status

Order statuses are assigned to order track records to track the progress of the order record. For example, an order status can be used to track that an order ticket was passed to an agent for execution, or that an agent has returned an “advice of execution”.

Field Type Description
id UUID The id of the order status
status string Value of the order status such as “Passed to Agent”
description string Additional description of the order status
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 statuses

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/nucleus/v1/order_status"

Example Response

{
  "content": [
    {
      "id": "9b515c67-3791-400f-9da4-9dc69eb992ac",
      "create_date": "2018-02-07T19:29:37.000+0000",
      "update_date": "2018-02-12T09:00:00.000+0000",
      "description": "orders have been executed",
      "status": "complete"
    }
  ],
  "last": true,
  "total_elements": 1,
  "total_pages": 1,
  "sort": [
    {
      "direction": "DESC",
      "property": "id",
      "ignore_case": false,
      "null_handling": "NATIVE",
      "ascending": false,
      "descending": true
    }
  ],
  "first": true,
  "number_of_elements": 1,
  "size": 25,
  "number": 0
}

Get the information for all order statuses defined for your firm. The endpoint returns a list of ids with details for each order status.

HTTP REQUEST

GET /order_status

Create an order status

Example Request

curl -X POST -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    -H "Content-Type: application/json" \
    -d '{
          "description": "orders have been executed",
          "status": "complete"
      }' "https://api.hydrogenplatform.com/nucleus/v1/order_status"

Example Response

{
  "id": "9b515c67-3791-400f-9da4-9dc69eb992ac",
  "create_date": "2018-02-07T19:29:37.000+0000",
  "description": "orders have been executed",
  "status": "complete"
}

Create an order status for your firm. An order status represents a step in the order track process and the it can later be assigned to order records. Must provide the status value (ex. “Passed to Agent”) and the status description. The create_date will default to the current date. The endpoint returns a order_status_id used to manage the order status and to assign it to order records later on.

HTTP REQUEST

POST /order_status

ARGUMENTS

Parameter Type Required Description
status string required Value of the order status such as “Passed to Agent”
description string required Additional description of the order status

Retrieve an order status

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/nucleus/v1/order_status/9b515c67-3791-400f-9da4-9dc69eb992ac"

Example Response

{
  "id": "9b515c67-3791-400f-9da4-9dc69eb992ac",
  "create_date": "2018-02-07T19:29:37.000+0000",
  "update_date": "2018-02-12T09:00:00.000+0000",
  "description": "orders have been executed",
  "status": "complete"
}

Retrieve the information for an order status defined for your firm. The unique order_status_id must be provided. The endpoint returns the details for the order status specified.

HTTP REQUEST

GET /order_status/{order_status_id}

Update an order status

Example Request

curl -X PUT -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    -H "Content-Type: application/json" \
    -d '{
        "description": "orders have not been executed",
        "status": "not complete"
    }' "https://api.hydrogenplatform.com/nucleus/v1/order_status/9b515c67-3791-400f-9da4-9dc69eb992ac"

Example Response

{
    "id": "9b515c67-3791-400f-9da4-9dc69eb992ac",
    "create_date": "2018-02-07T19:29:37.000+0000",
    "update_date": "2018-02-12T09:00:00.000+0000",
    "description": "orders have not been executed",
    "status": "not complete"
}

Update the information for an order status defined for your firm. The unique order_status_id must be provided. To obtain the appropriate order_status_ud, use the GET /order_status endpoint to view all order statuses defined for your firm and their current information. The details to be updated must also be provided. The endpoint returns the order_status_id and all of the details for the order status.

HTTP REQUEST

PUT /order_status/{order_status_id}

Delete an order status

Example Request

curl -X DELETE -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/nucleus/v1/order_status/9b515c67-3791-400f-9da4-9dc69eb992ac"

Response (204 No Content)

Permanently delete an order status defined for your firm. The unique order_status_id must be provided. To obtain the appropriate order_status_ud, use the GET /order_status endpoint to view all order statuses defined for your firm. Deletes the order_status_id and the order status so that it can no longer be assigned to order track records.

HTTP REQUEST

DELETE /order_status/{order_status_id}

Order Tracking

Order tracking records are created to store the order status history of an order record and information on the order ticket that was carried out by the agent (ex. commission or fees).

Field Type Description
id UUID The id of the order track record
order_id UUID The id of the order that the to which order track record belongs
order_status_id UUID The id of the order status currently assigned to the order track record
date date Date of the order track record
commission double Commission earned by the agent on the order
external_track_id UUID The external id used by the agent or other party executing the order to track the order ticket (if provided)
fee double Total fees associated with the order
price double Execution price at which the securities in the order were bought or sold
quantity double Quantity of securities that were bought or sold
metadata map Custom information associated with the order tracking 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 tracking records

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/nucleus/v1/order_track"

Example Response

{
  "content": [
    {
      "id": "ef93ce1c-b50e-4856-803a-db5332be93b0",
      "create_date": "2018-02-07T19:29:37.000+0000",
      "update_date": "2018-02-12T09:00:00.000+0000",
      "commission": 10,
      "date": "2018-02-11",
      "fee": 5,
      "price": 55,
      "quantity": 5,
      "order_id": "a20c0b29-836f-419d-9000-b47e4392d5f1",
      "order_status_id": "9b515c67-3791-400f-9da4-9dc69eb992ac",
      "metadata": {
        "order_management_system": "IBM",
        "order_settlement": "T+3"
      }
    }
  ],
  "last": true,
  "total_elements": 1,
  "total_pages": 1,
  "sort": [
    {
      "direction": "DESC",
      "property": "id",
      "ignore_case": false,
      "null_handling": "NATIVE",
      "ascending": false,
      "descending": true
    }
  ],
  "first": true,
  "number_of_elements": 1,
  "size": 25,
  "number": 0
}

Get the information for all order tracking record for all order records. You can filter using order_id to view all order tracking records for a specific order. Note that the metadata is stored as a nested object within the order tracking object.

HTTP REQUEST

GET /order_track

Create an order tracking record

Example Request

curl -X POST -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    -H "Content-Type: application/json" \
    -d '{
          "commission": 10,
          "date": "2018-02-11",
          "fee": 5,
          "price": 55,
          "quantity": 5,
          "order_id": "a20c0b29-836f-419d-9000-b47e4392d5f1",
          "order_status_id": "9b515c67-3791-400f-9da4-9dc69eb992ac"
      }' "https://api.hydrogenplatform.com/nucleus/v1/order_track"

Example Response

{
    "id": "ef93ce1c-b50e-4856-803a-db5332be93b0",
    "create_date": "2018-02-07T19:29:37.000+0000",
    "commission": 10,
    "date": "2018-02-11",
    "fee": 5,
    "price": 55,
    "quantity": 5,
    "order_id": "a20c0b29-836f-419d-9000-b47e4392d5f1",
    "order_status_id": "9b515c67-3791-400f-9da4-9dc69eb992ac",
    "metadata": {}
}

Create a new order tracking record for an order. The unique order_id and the unique order_status_id and the date for the tracking record must be provided. To obtain the appropriate order_id, use the GET /order endpoint to view all order records defined for your firm. To obtain the appropriate order_status_id, use the GET /order_status endpoint to view all order statuses defined for your firm. The create_date will default to the current date. The endpoint returns an order_tracking_id used to manage the order tracking record.

HTTP REQUEST

POST /order_track

ARGUMENTS

Parameter Type Required Description
order_id UUID required The id of the order that the to which order track record belongs
order_status_id UUID required The id of the order status currently assigned to the order track record
date date required Date of the order track record
commission double optional Commission earned by the agent on the order
external_track_id UUID optional The external id used by the agent or other party executing the order to track the order ticket (if provided)
fee double optional Total fees associated with the order
price double optional Execution price at which the securities in the order were bought or sold
quantity double optional Quantity of securities that were bought or sold
metadata map optional Custom information associated with the order tracking record in the format key:value. See Metadata

Retrieve an order tracking record

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/nucleus/v1/order_track/ef93ce1c-b50e-4856-803a-db5332be93b0"

Example Response

{
    "id": "ef93ce1c-b50e-4856-803a-db5332be93b0",
    "create_date": "2018-02-07T19:29:37.000+0000",
    "update_date": "2018-02-12T09:00:00.000+0000",
    "commission": 10,
    "date": "2018-02-11",
    "fee": 5,
    "price": 55,
    "quantity": 5,
    "order_id": "a20c0b29-836f-419d-9000-b47e4392d5f1",
    "order_status_id": "9b515c67-3791-400f-9da4-9dc69eb992ac",
    "metadata": {}
}

Retrieve the information for an order tracking record for an order. The unique order_track_id must be provided. The endpoint returns the details for the order tracking record specified.

HTTP REQUEST

GET /order_track/{order_track_id}

Update an order tracking record

Example Request

curl -X PUT -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    -H "Content-Type: application/json" \
    -d '{
        "id": "ef93ce1c-b50e-4856-803a-db5332be93b0",
        "commission": 10,
        "date": "2018-02-11",
        "fee": 5,
        "price": 50,
        "quantity": 5,
        "order_id": "a20c0b29-836f-419d-9000-b47e4392d5f1",
        "order_status_id": "9b515c67-3791-400f-9da4-9dc69eb992ac"
      }' "https://api.hydrogenplatform.com/nucleus/v1/order_track/ef93ce1c-b50e-4856-803a-db5332be93b0"

Example Response

{
    "id": "ef93ce1c-b50e-4856-803a-db5332be93b0",
    "create_date": "2018-02-07T19:29:37.000+0000",
    "update_date": "2018-02-13T09:00:00.000+0000",
    "commission": 10,
    "date": "2018-02-11",
    "fee": 5,
    "price": 50,
    "quantity": 5,
    "order_id": "a20c0b29-836f-419d-9000-b47e4392d5f1",
    "order_status_id": "9b515c67-3791-400f-9da4-9dc69eb992ac",
    "metadata": {}
}

Update the information for an order tracking record for an order. The unique order_track_id must be provided. To obtain the appropriate order_track_id, use the GET /order_track endpoint to view all order tracking records for your firm and their current information. The details to be updated must also be provided. The endpoint returns the order_track_id and all of the details for the order tracking record.

HTTP REQUEST

PUT /order_track/{order_track_id}

Delete an order tracking record

Example Request

curl -X DELETE -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/nucleus/v1/order_track/ef93ce1c-b50e-4856-803a-db5332be93b0"

Response (204 No Content)

Permanently delete an order tracking record for an order. The unique order_track_id must be provided. To obtain the appropriate order_track_id, use the GET /order_track endpoint to view all order tracking records for your firm. Deletes the order_track and the order tracking record.

HTTP REQUEST

DELETE /order_track/{order_track_id}

Rebalancing

Create account rebalance orders

Example Request

curl -X POST -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    -H "Content-Type: application/json" \
    -d '{
        "restrictions_on": false,
        "non_fractional": true,
        "sell_threshold": 100,
        "port_threshold": 100,
        "commit_orders": false,
        "buy_threshold": 100,
        "use_strategic": false,
        "cash_portfolio_id": "15c78020-3be9-472e-9349-f2d895cc4f23",
        "buy_transaction_code_id": "f5af397b-7d22-433f-b01e-8202184a6386",
        "sell_transaction_code_id": "7d8d41d0-ed4b-4ae2-acb3-e0baed2ff1cc"
    }' "https://api.hydrogenplatform.com/nucleus/v1/account/f053d394-e10f-46d8-8eeb-ce39e980c758/order_rebalance"

Example Response

[
    {
      "id": "a20c0b29-836f-419d-9000-b47e4392d5f1",
      "create_date": "2018-02-07T19:29:37.000+0000",
      "transaction_code_id": "f5af397b-7d22-433f-b01e-8202184a6386",
      "date": "2018-02-07",
      "price": 51.25,
      "is_read": false,
      "quantity": 0.55,
      "security_id": "681a3155-e82a-476b-8f83-cf36b6d81952",
      "account_id": "f053d394-e10f-46d8-8eeb-ce39e980c758",
      "portfolio_id": "ef93ce1c-b50e-4856-803a-db5332be93b0",
      "model_id": "ca74f042-eb32-4965-84c6-b0754d2115c5",
      "metadata": {}
    },
    {
      "id": "2fae86f5-a2ab-4d11-be1d-4ce08f903135",
      "create_date": "2018-02-07T19:29:37.000+0000",
      "transaction_code_id": "7d8d41d0-ed4b-4ae2-acb3-e0baed2ff1cc",
      "date": "2018-02-07",
      "price": 40.5,
      "is_read": true,
      "quantity": 2.0,
      "security_id": "762d058e-defa-4b8c-9cba-d0fc248df527",
      "account_id": "f053d394-e10f-46d8-8eeb-ce39e980c758",
      "portfolio_id": "ef93ce1c-b50e-4856-803a-db5332be93b0",
      "model_id": "ca74f042-eb32-4965-84c6-b0754d2115c5",
      "metadata": {}
    }
]

Create order records necessary to rebalance an account and all its portfolios according to the allocation(s) to which the account subscribes and models to which the portfolios subscribe. These will be both buy and sell transactions. The unique account_id must be provided. To obtain the appropriate account_id, use the GET /account endpoint to view all of the accounts defined for your firm. The endpoint returns a series of order_id records and their underlying information, similar to the GET /order endpoint. All of the order_ids will be part of a bulk order and will have a bulk_order_id assigned to them.

HTTP REQUEST

POST /account/{account_id}/order_rebalance

ARGUMENTS

Parameter Type Required Description
sell_transaction_code_id UUID required The id of the transaction code to denote a sell transaction
buy_transaction_code_id UUID required The id of the transaction code to denote a buy transaction
buy_threshold double optional Buying threshold for the account as the number of shares. Defaults to 0
cash_portfolio_id UUID optional The id of the cash portfolio for the account
commit_orders boolean optional Indicates if the orders should be committed for execution. Defaults to true which indicates they should be committed
non_fractional boolean optional Indicates if purchasing/selling fractional shares of securities is allowed. Defaults to false which indicates it is allowed
port_threshold double optional Threshold for the minimum asset size the portfolio as a monetary amount for rebalancing to take place. Defaults to 0
restrictions_on boolean optional Indicates if there are restrictions on the account that should be followed. Defaults to false which indicates there are not
sell_threshold double optional Selling threshold for the account as the number of shares. Defaults to 0
use_cash_available boolean optional Indicates if only the cash in the cash portfolio should be used. Defaults to false which indicates it should not
use_strategic boolean optional Indicates if the account should be synced to strategic weights as opposed to current weights. Defaults to false which indicates it should not

Create buy-only account rebalance orders

Example Request

curl -X POST -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    -H "Content-Type: application/json" \
    -d '{
        "restrictions_on": false,
        "non_fractional": true,
        "port_threshold": 0,
        "commit_orders": false,
        "buy_threshold": 100,
        "use_strategic": false,
        "cash_portfolio_id": "57db7cea-325e-495f-b3c9-029d38053e77",
        "buy_transaction_code_id": "f5af397b-7d22-433f-b01e-8202184a6386",
        "sell_transaction_code_id": "7d8d41d0-ed4b-4ae2-acb3-e0baed2ff1cc"
    }' "https://api.hydrogenplatform.com/nucleus/v1/account/f053d394-e10f-46d8-8eeb-ce39e980c758/order_buy_only"

Example Response

[
    {
      "id": "8116098b-e5be-4039-a6d0-38de204b7d36",
      "create_date": "2018-02-07T19:29:37.000+0000",
      "transaction_code_id": "f5af397b-7d22-433f-b01e-8202184a6386",
      "date": "2018-02-07",
      "price": 51.25,
      "is_read": false,
      "quantity": 2.0,
      "security_id": "762d058e-defa-4b8c-9cba-d0fc248df527",
      "account_id": "f053d394-e10f-46d8-8eeb-ce39e980c758",
      "portfolio_id": "ef93ce1c-b50e-4856-803a-db5332be93b0",
      "model_id": "ca74f042-eb32-4965-84c6-b0754d2115c5",
      "metadata": {}
    }
]

Create order records necessary to rebalance an account and all its portfolios according to the allocation(s) to which the account subscribes and models to which the portfolios subscribe. However, these will only be buy transactions, and no securities will be sold. The unique account_id must be provided. To obtain the appropriate account_id, use the GET /account endpoint to view all of the accounts defined for your firm. The endpoint returns a series of order_id records and their underlying information, similar to the GET /order endpoint. All of the order_ids will be part of a bulk order and will have a bulk_order_id assigned to them.

HTTP REQUEST

POST /account/{account_id}/order_buy_only

ARGUMENTS

Parameter Type Required Description
buy_transaction_code_id UUID required The id of the transaction code to denote a buy transaction
sell_transaction_code_id UUID optional The id of the transaction code to denote a sell transaction
buy_threshold double optional Buying threshold for the account as the number of shares. Defaults to 0
cash_portfolio_id UUID optional The id of the cash portfolio for the account
commit_orders boolean optional Indicates if the orders should be committed for execution. Defaults to true which indicates they should be committed
non_fractional boolean optional Indicates if purchasing/selling fractional shares of securities is allowed. Defaults to false which indicates it is allowed
port_threshold double optional Threshold for the minimum asset size the portfolio as a monetary amount for rebalancing to take place. Defaults to 0
restrictions_on boolean optional Indicates if there are restrictions on the account that should be followed. Defaults to false which indicates there are not
sell_threshold double optional Selling threshold for the account as the number of shares. Defaults to 0
use_strategic boolean optional Indicates if the account should be synced to strategic weights as opposed to current weights. Defaults to false which indicates it should not

Create sell-only account rebalance orders

Example Request

curl -X POST -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    -H "Content-Type: application/json" \
    -d '{
        "restrictions_on": false,
        "non_fractional": true,
        "sell_threshold": 100,
        "port_threshold": 100,
        "commit_orders": false,
        "use_strategic": false,
        "cash_portfolio_id": "57db7cea-325e-495f-b3c9-029d38053e77",
        "sell_transaction_code_id": "7d8d41d0-ed4b-4ae2-acb3-e0baed2ff1cc"
    }' "https://api.hydrogenplatform.com/nucleus/v1/account/f053d394-e10f-46d8-8eeb-ce39e980c758/order_sell_only"

Example Response

[
    {
      "id": "66b53074-57e3-4031-a0b0-1620f64146f3",
      "create_date": "2018-02-07T19:29:37.000+0000",
      "transaction_code_id": "7d8d41d0-ed4b-4ae2-acb3-e0baed2ff1cc",
      "date": "2018-02-07",
      "price": 51.25,
      "is_read": true,
      "quantity": 15,
      "security_id": "cce4cb18-9a0a-499e-be38-cfb089ba1781",
      "account_id": "f053d394-e10f-46d8-8eeb-ce39e980c758",
      "portfolio_id": "ef93ce1c-b50e-4856-803a-db5332be93b0",
      "model_id": "ca74f042-eb32-4965-84c6-b0754d2115c5",
      "metadata": {}
    }
  ]

Create order records necessary to rebalance an account and all its portfolios according to the allocation(s) to which the account subscribes and models to which the portfolios subscribe. However, these will only be sell transactions, and no securities will be bought. The unique account_id must be provided. To obtain the appropriate account_id, use the GET /account endpoint to view all of the accounts defined for your firm. The endpoint returns a series of order_id records and their underlying information, similar to the GET /order endpoint. All of the order_ids will be part of a bulk order and will have a bulk_order_id assigned to them.

HTTP REQUEST

POST /account/{account_id}/order_sell_only

ARGUMENTS

Parameter Type Required Description
sell_transaction_code_id UUID required The id of the transaction code to denote a sell transaction
buy_transaction_code_id UUID optional The id of the transaction code to denote a buy transaction
cash_portfolio_id UUID optional The id of the cash portfolio for the account
commit_orders boolean optional Indicates if the orders should be committed for execution. Defaults to true which indicates they should be committed
non_fractional boolean optional Indicates if purchasing/selling fractional shares of securities is allowed. Defaults to false which indicates it is allowed
port_threshold double optional Threshold for the minimum asset size the portfolio as a monetary amount for rebalancing to take place. Defaults to 0
restrictions_on boolean optional Indicates if there are restrictions on the account that should be followed. Defaults to false which indicates there are not
buy_threshold double optional Buying threshold for the account as the number of shares. Defaults to 0
sell_threshold double optional Selling threshold for the account as the number of shares. Defaults to 0
use_strategic boolean optional Indicates if the account should be synced to strategic weights as opposed to current weights. Defaults to false which indicates it should not

Create portfolio rebalance orders

Example Request

curl -X POST -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    -H "Content-Type: application/json" \
    -d '{
        "restrictions_on": false,
        "non_fractional": true,
        "sell_threshold": 100,
        "port_threshold": 100,
        "commit_orders": false,
        "buy_threshold": 100,
        "cash_sec_id": "5276c9a5-5263-4aea-8027-327003738cef",
        "use_strategic": false,
        "buy_transaction_code_id": "f5af397b-7d22-433f-b01e-8202184a6386",
        "sell_transaction_code_id": "7d8d41d0-ed4b-4ae2-acb3-e0baed2ff1cc"
    }' "https://api.hydrogenplatform.com/nucleus/v1/portfolio/ef93ce1c-b50e-4856-803a-db5332be93b0/order_rebalance"

Example Response

[
    {
      "id": "d6f9b056-77a5-4c5d-8bea-8358b8ceb4f5",
      "create_date": "2018-02-07T19:29:37.000+0000",
      "transaction_code_id": "f5af397b-7d22-433f-b01e-8202184a6386",
      "date": "2018-02-07",
      "price": 51.25,
      "is_read": false,
      "quantity": 36,
      "security_id": "cce4cb18-9a0a-499e-be38-cfb089ba1781",
      "account_id": "cce4cb18-9a0a-499e-be38-cfb089ba1781",
      "portfolio_id": "ef93ce1c-b50e-4856-803a-db5332be93b0",
      "model_id": "ca74f042-eb32-4965-84c6-b0754d2115c5",
      "metadata": {}
    },
    {
      "id": "7b8def71-cbb9-4603-8791-4399aef5b395",
      "create_date": "2018-02-07T19:29:37.000+0000",
      "transaction_code_id": "7d8d41d0-ed4b-4ae2-acb3-e0baed2ff1cc",
      "date": "2018-02-07",
      "price": 40.5,
      "is_read": true,
      "quantity": 12,
      "security_id": "4762d058e-defa-4b8c-9cba-d0fc248df527",
      "portfolio_id": "ef93ce1c-b50e-4856-803a-db5332be93b0",
      "account_id": "cce4cb18-9a0a-499e-be38-cfb089ba1781",
      "model_id": "ca74f042-eb32-4965-84c6-b0754d2115c5",
      "metadata": {}
    }
  ]

Create order records necessary to rebalance a portfolio to the model to which it subscribes. These will be both buy and sell transactions. The unique portfolio_id must be provided. To obtain the appropriate portfolio_id, use the GET /portfolio endpoint to view all of the portfolios defined for your firm. The endpoint returns a series of order_id records and their underlying information, similar to the GET /order endpoint. All of the order_ids will be part of a bulk order and will have a bulk_order_id assigned to them.

HTTP REQUEST

POST /portfolio/{portfolio_id}/order_rebalance

ARGUMENTS

Parameter Type Required Description
sell_transaction_code_id UUID required The id of the transaction code to denote a sell transaction
buy_transaction_code_id UUID required The id of the transaction code to denote a buy transaction
buy_threshold double optional Buying threshold for the account as the number of shares. Defaults to 0
cash_sec_id UUID optional The id of the cash security for the portfolio
commit_orders boolean optional Indicates if the orders should be committed for execution. Defaults to true which indicates they should be committed
non_fractional boolean optional Indicates if purchasing/selling fractional shares of securities is allowed. Defaults to false which indicates it is allowed
port_threshold double optional Threshold for the minimum asset size the portfolio as a monetary amount for rebalancing to take place. Defaults to 0
restrictions_on boolean optional Indicates if there are restrictions on the account that should be followed. Defaults to false which indicates there are not
sell_threshold double optional Selling threshold for the account as the number of shares. Defaults to 0
use_cash_available boolean optional Indicates if only the cash in the cash portfolio should be used. Defaults to false which indicates it should not
use_strategic boolean optional Indicates if the account should be synced to strategic weights as opposed to current weights. Defaults to false which indicates it should not

Create buy-only portfolio rebalance orders

Example Request

curl -X POST -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    -H "Content-Type: application/json" \
    -d '{
        "restrictions_on": false,
        "non_fractional": true,
        "port_threshold": 100,
        "commit_orders": false,
        "buy_threshold": 100,
        "cash_sec_id": "5276c9a5-5263-4aea-8027-327003738cef",
        "use_strategic": false,
        "buy_transaction_code_id": "f5af397b-7d22-433f-b01e-8202184a6386",
        "sell_transaction_code_id": "7d8d41d0-ed4b-4ae2-acb3-e0baed2ff1cc"
    }' "https://api.hydrogenplatform.com/nucleus/v1/portfolio/ef93ce1c-b50e-4856-803a-db5332be93b0/order_buy_only"

Example Response

[
    {
      "id": "0ecf8650-0581-403c-a777-2e722d9a65b5",
      "create_date": "2018-02-07T19:29:37.000+0000",
      "transaction_code_id": "f5af397b-7d22-433f-b01e-8202184a6386",
      "date": "2018-02-07",
      "price": 51.25,
      "is_read": false,
      "quantity": 15,
      "security_id": "a6cfc335-c9b0-47bf-8ee6-db895ea1b668",
      "account_id": "cce4cb18-9a0a-499e-be38-cfb089ba1781",
      "portfolio_id": "ef93ce1c-b50e-4856-803a-db5332be93b0",
      "model_id": "ca74f042-eb32-4965-84c6-b0754d2115c5",
      "metadata": {}
    }
]

Create order records necessary to rebalance a portfolio to the model to which it subscribes. However, these will only be buy transactions, and no securities will be sold. The unique portfolio_id must be provided. To obtain the appropriate portfolio_id, use the GET /portfolio endpoint to view all of the portfolios defined for your firm. The endpoint returns a series of order_id records and their underlying information, similar to the GET /order endpoint. All of the order_ids will be part of a bulk order and will have a bulk_order_id assigned to them. Note that this endpoint requires that the portfolio and its corresponding model have asset sizes and holdings.

HTTP REQUEST

POST /portfolio/{portfolio_id}/order_buy_only

ARGUMENTS

Parameter Type Required Description
buy_transaction_code_id UUID required The id of the transaction code to denote a buy transaction
sell_transaction_code_id UUID optional The id of the transaction code to denote a sell transaction
buy_threshold double optional Buying threshold for the account as the number of shares. Defaults to 0
cash_sec_id UUID optional The id of the cash security for the portfolio
commit_orders boolean optional Indicates if the orders should be committed for execution. Defaults to true which indicates they should be committed
non_fractional boolean optional Indicates if purchasing/selling fractional shares of securities is allowed. Defaults to false which indicates it is allowed
port_threshold double optional Threshold for the minimum asset size the portfolio as a monetary amount for rebalancing to take place. Defaults to 0
restrictions_on boolean optional Indicates if there are restrictions on the account that should be followed. Defaults to false which indicates there are not
sell_threshold double optional Selling threshold for the account as the number of shares. Defaults to 0
use_strategic boolean optional Indicates if the account should be synced to strategic weights as opposed to current weights. Defaults to false which indicates it should not

Create sell-only portfolio rebalance orders

Example Request

curl -X POST -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    -H "Content-Type: application/json" \
    -d '{
        "restrictions_on": false,
        "non_fractional": true,
        "sell_threshold": 100,
        "port_threshold": 100,
        "commit_orders": false,
        "cash_sec_id": "5276c9a5-5263-4aea-8027-327003738cef",
        "use_strategic": false,
        "sell_transaction_code_id": "7d8d41d0-ed4b-4ae2-acb3-e0baed2ff1cc"
    }' "https://api.hydrogenplatform.com/nucleus/v1/portfolio/ef93ce1c-b50e-4856-803a-db5332be93b0/order_sell_only"

Example Response

[
    {
      "id": "2fae86f5-a2ab-4d11-be1d-4ce08f903135",
      "create_date": "2018-02-07T19:29:37.000+0000",
      "transaction_code_id": "7d8d41d0-ed4b-4ae2-acb3-e0baed2ff1cc",
      "date": "2018-02-07",
      "price": 51.25,
      "is_read": true,
      "quantity": 26,
      "security_id": "52654829-e80b-4f16-9f8b-c9fde8a1aa63",
      "portfolio_id": "ef93ce1c-b50e-4856-803a-db5332be93b0",
      "account_id": "cce4cb18-9a0a-499e-be38-cfb089ba1781",
      "model_id": "ca74f042-eb32-4965-84c6-b0754d2115c5",
      "metadata": {}
    }
]

Create order records necessary to rebalance a portfolio to the model to which it subscribes. However, these will only be sell transactions, and no securities will be bought. The unique portfolio_id must be provided. To obtain the appropriate portfolio_id, use the GET /portfolio endpoint to view all of the portfolios defined for your firm. The endpoint returns a series of order_id records and their underlying information, similar to the GET /order endpoint. All of the order_ids will be part of a bulk order and will have a bulk_order_id assigned to them. Note that this endpoint requires that the portfolio and its corresponding model have asset sizes and holdings.

HTTP REQUEST

POST /portfolio/{portfolio_id}/order_sell_only

ARGUMENTS

Parameter Type Required Description
sell_transaction_code_id UUID required The id of the transaction code to denote a sell transaction
buy_transaction_code_id UUID optional The id of the transaction code to denote a buy transaction
cash_portfolio_id UUID optional The id of the cash portfolio for the account
commit_orders boolean optional Indicates if the orders should be committed for execution. Defaults to true which indicates they should be committed
non_fractional boolean optional Indicates if purchasing/selling fractional shares of securities is allowed. Defaults to false which indicates it is allowed
port_threshold double optional Threshold for the minimum asset size the portfolio as a monetary amount for rebalancing to take place. Defaults to 0
restrictions_on boolean optional Indicates if there are restrictions on the account that should be followed. Defaults to false which indicates there are not
buy_threshold double optional Buying threshold for the account as the number of shares. Defaults to 0
sell_threshold double optional Selling threshold for the account as the number of shares. Defaults to 0
use_strategic boolean optional Indicates if the account should be synced to strategic weights as opposed to current weights. Defaults to false which indicates it should not

Transaction Code

Transaction codes are defined by your firm to identify the type of transaction for an order record. Examples of generic transactions codes include “Customer Payment” or “Cash Dividend”. Transaction codes also indicate whether an order record is a buy transaction or a sell transaction.

Field Type Description
id UUID The id of the transaction code
transaction_code string Usually a standard short combination of letters and numbers used to identify the transaction code within your firm
transaction_code_description string Short description to clarify the type of transaction
transaction_type string Name of the transaction code such as “Customer Payment”
is_buy boolean Indicates if the transaction is to buy securities. Defaults to false which means it is a sell transaction
category string Grouping of similar transaction codes
subcategory string Sub-grouping of similar transaction codes
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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/nucleus/v1/transaction_code"

Example Response

{
    "content": [
      {
        "id": "099961da-7f41-4309-950f-2b51689a0033",
        "category": "Deposits",
        "is_buy": true,
        "subcategory": "Cash",
        "transaction_code": "CDEP",
        "transaction_code_description": "Client Deposits",
        "transaction_type": "Check Returned"
      },
      {
        "id": "1d7e1aad-3c79-49fe-bbb9-bd5e239ae1e7",
        "category": "Deposits",
        "is_buy": true,
        "subcategory": "Cash",
        "transaction_code": "CDEP",
        "transaction_code_description": "Client Deposits",
        "transaction_type": "Bill Pay"
      },
      {
        "id": "2a7a6cb7-ef71-4fe8-9169-2678f3799657",
        "category": "Deposits",
        "is_buy": true,
        "subcategory": "Cash",
        "transaction_code": "CDEP",
        "transaction_code_description": "Client Deposits",
        "transaction_type": "Wire Returned"
      }
    ],
    "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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
     -H "Content-Type: application/json" \
     -d '{
            "category": "Deposits",
            "is_buy": true,
            "subcategory": "Cash",
            "transaction_code": "CDEP",
            "transaction_code_description": "Client Deposits"
        }' "https://api.hydrogenplatform.com/nucleus/v1/transaction_code"

Example Response

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

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 Usually a standard short combination of letters and numbers used to identify the transaction code within your firm
transaction_code_description string optional Short description to clarify the type of transaction
transaction_type string optional Name of the transaction code such as “Customer Payment”
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.

Retrieve a transaction code

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/nucleus/v1/transaction_code/099961da-7f41-4309-950f-2b51689a0033"

Example Response

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

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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
     -H "Content-Type: application/json" \
     -d '{
            "id": "099961da-7f41-4309-950f-2b51689a0033",
            "category": "Deposits",
            "is_buy": true,
            "subcategory": "Cash",
            "transaction_code": "CDEP-1",
            "transaction_code_description": "Client Deposits",
            "transaction_type": "Check Returned"
        }' "https://api.hydrogenplatform.com/nucleus/v1/transaction_code/099961da-7f41-4309-950f-2b51689a0033"

Example Response

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

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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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}

Performance

Performance is tracked via a series of statistics and can be tracked at the client, account, portfolio, allocation, model, goal, security, or benchmark level. Statistics are pre-defined and can be obtained in the statistics resource table.

Hydrogen uses two methods to calculate performance. On each endpoint, it will be noted which method is being used. These two methods include:

IRR (Internal Rate of Return)

IRR, also known as dollar-weighted return, calculates the performance of a portfolio while incorporating inflows and outflows. Therefore, the timing of deposits and withdrawals substantially affects the return rate, with larger cash movements having a greater impact on performance compared to smaller changes in cash. IRR is a useful tool to calculate the absolute return of a portfolio and for determining whether a portfolio is growing at a return necessary to meet an investment goal. Therefore, IRR is used mostly by Hydrogen for account and client-related performance measures.

TWR (Time Weighted Return)

TWR captures the true performance of a portfolio by removing the impact of cash inflows and outflows on the portfolio’s return. It reflects the effects of portfolio composition on return, without considering the effects of the client’s deposits or withdrawals. TWR captures the return of the very first investment into a portfolio. At Hydrogen, we use TWR for all performance calculations which do not have cash flows. This includes allocation, benchmark, model, and security performance, which do not change based on total assets invested in them. TWR is also required by the Global Investment Performance Standards (GIPS) published by the CFA Institute. Calculating returns using TWR is the better method of calculating a manager’s performance and analyzing the performance of a portfolio’s underlying assets.

Account Performance

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/nucleus/v1/account/08b1ec98-8f86-416b-a1bf-a6fc29da00be/performance?stat=ann_return"

Example Response

{
    "ann_return": 0.06132398215253243
}

Get information on the performance of an account using IRR (Internal Rate of Return). You must provide the unique account_id. To obtain the appropriate account_id, use the GET /account endpoint to view all accounts defined for your firm and their current information. You must also specify the statistic to be returned using the stat parameter. For more information and to obtain the stat use the statistics resource table.

HTTP REQUEST

GET /account/{account_id}/performance?stat={stat name}

DATA DEPENDENCIES

To calculate performance for an account, you must first have the following data:

  1. Account - POST /account
  2. Portfolio - POST /portfolio and assign account_id from step #1
  3. Portfolio Asset Sizes - POST /portfolio_asset_size for portfolio_id from step #2 for all applicable dates

To calculate any applicable statistic against a benchmark_id, you must first have the following data:

  1. Benchmark - POST /benchmark with composition of all security_ids that make up this benchmark
  2. Security Prices - POST /security_price for all security_ids that make up this benchmark for all applicable dates

ARGUMENTS

Parameter Type Required Description
stat string required The statistic you want to run on the account. See all available statistics here
start_date date optional Start date for the period for which to calculate the statistic
end_date date optional End date for the period for which to calculate the statistic
period_type string optional Period to carry out statistic. Options are Y for annually, Q for quarterly, M for monthly, D for daily (must use capital letters)
benchmark_id UUID optional If stat = beta, treynor_ratio, alpha, correlation, covariance, r_squared, information_ratio, tracking_error, active_premium, up_pct_ratio, down_pct_ratio, pct_gain_ratio, tstat, down_capture, or up_capture, the benchmark you want to use in the calculation
n_rolling_volatility integer optional If stat = rolling_n_day_vol, number of days. Default is 7
n_day_returns integer optional If stat = rolling_n_day_return, number of days. Default is 7
moving_average integer optional If stat = moving_avg_n_day, number of days. Default is 7
annualized_return_period string optional If stat = ann_return, period to calculate return. Default is D
active_premium_period string optional If stat = active_premium, period to calculate return. Default is D
hist_factor double optional If stat = histogram, number of data bins. Default is 5
var_conf_interval double optional If stat = var, confidence interval for the var
n_rolling_max_drawdown integer optional If stat = rolling_n_day_max_drawdown, number of days. Default is 7
risk_free_sharpe double optional If stat = sharpe_ratio, risk free rate of return. Default is 0
risk_free_treynor double optional If stat = treynor_ratio, risk free rate of return. Default is 0
risk_free_alpha double optional If stat = alpha, risk free rate of return. Default is 0
risk_free_sortino double optional If stat = sortino_ratio, risk free rate of return. Default is 0
mar_down_side_deviation double optional If stat = downside_deviation, minimum acceptable return. Default is 0
num_sim_monte_carlo integer optional If stat = monte_carlo, number of Monte Carlo simulations. Default is 1000
n_path_monte_carlo integer optional If stat = monte_carlo, number of Monte Carlo paths. Default is 100
max_percentile_monte_carlo double optional If stat = monte_carlo, maximum probability for a Monte Carlo simulation. Default is 95
min_percentile_monte_carlo double optional If stat = monte_carlo, minimum probability for a Monte Carlo simulation. Default is 5
mean_percentile_monte_carlo double optional If stat = monte_carlo, mean probability for a Monte Carlo simulation. Default is 50

Allocation Performance

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/nucleus/v1/allocation/f053d394-e10f-46d8-8eeb-ce39e980c758/performance?stat=ann_return"

Example Response

{
    "ann_return": 0.06132398215253243
}

Get information on the performance of an allocation using TWR (Time Weighted Return). You 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 and their current information. You must also specify the statistic to be returned using the stat parameter. To obtain the stat use the statistics resource table.

HTTP REQUEST

GET /allocation/{allocation_id}/performance?stat={stat name}

DATA DEPENDENCIES

To calculate performance for an allocation, you must first have the following data:

  1. Allocation - POST /allocation
  2. Model - POST /model
  3. Model Asset Sizes - POST /model_asset_size for model_id from step #2 for all applicable dates
  4. Allocation Composition - POST /allocation_composition for allocation_id from step #1 and model_id from step #2 for all applicable dates. Please make sure the dates match the dates of the model asset sizes in step #3

To calculate any applicable statistic against a benchmark_id, you must first have the following data:

  1. Benchmark - POST /benchmark with composition of all security_ids that make up this benchmark
  2. Security Prices - POST /security_price for all security_ids that make up this benchmark for all applicable dates

ARGUMENTS

Parameter Type Required Description
stat string required The statistic you want to run on the account. See all available statistics here
start_date date optional Start date for the period for which to calculate the statistic
end_date date optional End date for the period for which to calculate the statistic
period_type string optional Period to carry out statistic. Options are Y for annually, Q for quarterly, M for monthly, D for daily (must use capital letters)
benchmark_id UUID optional If stat = beta, treynor_ratio, alpha, correlation, covariance, r_squared, information_ratio, tracking_error, active_premium, up_pct_ratio, down_pct_ratio, pct_gain_ratio, tstat, down_capture, or up_capture, the benchmark you want to use in the calculation
n_rolling_volatility integer optional If stat = rolling_n_day_vol, number of days. Default is 7
n_day_returns integer optional If stat = rolling_n_day_return, number of days. Default is 7
moving_average integer optional If stat = moving_avg_n_day, number of days. Default is 7
annualized_return_period string optional If stat = ann_return, period to calculate return. Default is D
active_premium_period string optional If stat = active_premium, period to calculate return. Default is D
hist_factor double optional If stat = histogram, number of data bins. Default is 5
var_conf_interval double optional If stat = var, confidence interval for the var
n_rolling_max_drawdown integer optional If stat = rolling_n_day_max_drawdown, number of days. Default is 7
risk_free_sharpe double optional If stat = sharpe_ratio, risk free rate of return. Default is 0
risk_free_treynor double optional If stat = treynor_ratio, risk free rate of return. Default is 0
risk_free_alpha double optional If stat = alpha, risk free rate of return. Default is 0
risk_free_sortino double optional If stat = sortino_ratio, risk free rate of return. Default is 0
mar_down_side_deviation double optional If stat = downside_deviation, minimum acceptable return. Default is 0
num_sim_monte_carlo integer optional If stat = monte_carlo, number of Monte Carlo simulations. Default is 1000
n_path_monte_carlo integer optional If stat = monte_carlo, number of Monte Carlo paths. Default is 100
max_percentile_monte_carlo double optional If stat = monte_carlo, maximum probability for a Monte Carlo simulation. Default is 95
min_percentile_monte_carlo double optional If stat = monte_carlo, minimum probability for a Monte Carlo simulation. Default is 5
mean_percentile_monte_carlo double optional If stat = monte_carlo, mean probability for a Monte Carlo simulation. Default is 50

Benchmark Performance

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/nucleus/v1/account/762d058e-defa-4b8c-9cba-d0fc248df527/performance?stat=ann_return"

Example Response

{
    "ann_return": 0.06132398215253243
}

Get information on the performance of a benchmark using TWR (Time Weighted Return). You must provide the unique benchmark_id. To obtain the appropriate benchmark_id, use the GET /benchmark endpoint to view all benchmarks defined for your firm and their current information. You must also specify the statistic to be returned using the stat parameter. To obtain the stat use the statistics resource table.

HTTP REQUEST

GET /benchmark/{benchmark_id}/performance?stat={stat name}

DATA DEPENDENCIES

To calculate performance for a benchmark, you must first have the following data:

  1. Benchmark - POST /benchmark with composition of all security_ids that make up this benchmark
  2. Security Prices - POST /security_price for all security_ids that make up this benchmark for all applicable dates

To calculate any applicable statistic against a comparison_benchmark_id, please follow the same instructions above.

ARGUMENTS

Parameter Type Required Description
stat string required The statistic you want to run on the account. See all available statistics here
start_date date optional Start date for the period for which to calculate the statistic
end_date date optional End date for the period for which to calculate the statistic
period_type string optional Period to carry out statistic. Options are Y for annually, Q for quarterly, M for monthly, D for daily (must use capital letters)
benchmark_id UUID optional If stat = beta, treynor_ratio, alpha, correlation, covariance, r_squared, information_ratio, tracking_error, active_premium, up_pct_ratio, down_pct_ratio, pct_gain_ratio, tstat, down_capture, or up_capture, the benchmark you want to use in the calculation
n_rolling_volatility integer optional If stat = rolling_n_day_vol, number of days. Default is 7
n_day_returns integer optional If stat = rolling_n_day_return, number of days. Default is 7
moving_average integer optional If stat = moving_avg_n_day, number of days. Default is 7
annualized_return_period string optional If stat = ann_return, period to calculate return. Default is D
active_premium_period string optional If stat = active_premium, period to calculate return. Default is D
hist_factor double optional If stat = histogram, number of data bins. Default is 5
var_conf_interval double optional If stat = var, confidence interval for the var
n_rolling_max_drawdown integer optional If stat = rolling_n_day_max_drawdown, number of days. Default is 7
risk_free_sharpe double optional If stat = sharpe_ratio, risk free rate of return. Default is 0
risk_free_treynor double optional If stat = treynor_ratio, risk free rate of return. Default is 0
risk_free_alpha double optional If stat = alpha, risk free rate of return. Default is 0
risk_free_sortino double optional If stat = sortino_ratio, risk free rate of return. Default is 0
mar_down_side_deviation double optional If stat = downside_deviation, minimum acceptable return. Default is 0
num_sim_monte_carlo integer optional If stat = monte_carlo, number of Monte Carlo simulations. Default is 1000
n_path_monte_carlo integer optional If stat = monte_carlo, number of Monte Carlo paths. Default is 100
max_percentile_monte_carlo double optional If stat = monte_carlo, maximum probability for a Monte Carlo simulation. Default is 95
min_percentile_monte_carlo double optional If stat = monte_carlo, minimum probability for a Monte Carlo simulation. Default is 5
mean_percentile_monte_carlo double optional If stat = monte_carlo, mean probability for a Monte Carlo simulation. Default is 50

Client Performance

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/nucleus/v1/client/5276c9a5-5263-4aea-8027-327003738cef/performance?stat=ann_return"

Example Response

{
    "ann_return": 0.06132398215253243
}

Get information on the performance of a client using IRR (Internal Rate of Return). You must provide the unique client_id. To obtain the appropriate client_id, use the GET /client endpoint to view all clients defined for your firm and their current information. You must also specify the statistic to be returned using the stat parameter. To obtain the stat use the statistics resource table.

HTTP REQUEST

GET /client/{client_id}/performance?stat={stat name}

DATA DEPENDENCIES

To calculate performance for a client, you must first have the following data:

  1. Client - POST /client
  2. Account - POST /account and assign to client_id from step #1 for each account
  3. Portfolio - POST /portfolio and assign account_id from step #2
  4. Portfolio Asset Sizes - POST /portfolio_asset_size for portfolio_id from step #3 for all applicable dates

To calculate any applicable statistic against a benchmark_id, you must first have the following data:

  1. Benchmark - POST /benchmark with composition of all security_ids that make up this benchmark
  2. Security Prices - POST /security_price for all security_ids that make up this benchmark for all applicable dates

ARGUMENTS

Parameter Type Required Description
stat string required The statistic you want to run on the account. See all available statistics here
start_date date optional Start date for the period for which to calculate the statistic
end_date date optional End date for the period for which to calculate the statistic
period_type string optional Period to carry out statistic. Options are Y for annually, Q for quarterly, M for monthly, D for daily (must use capital letters)
benchmark_id UUID optional If stat = beta, treynor_ratio, alpha, correlation, covariance, r_squared, information_ratio, tracking_error, active_premium, up_pct_ratio, down_pct_ratio, pct_gain_ratio, tstat, down_capture, or up_capture, the benchmark you want to use in the calculation
n_rolling_volatility integer optional If stat = rolling_n_day_vol, number of days. Default is 7
n_day_returns integer optional If stat = rolling_n_day_return, number of days. Default is 7
moving_average integer optional If stat = moving_avg_n_day, number of days. Default is 7
annualized_return_period string optional If stat = ann_return, period to calculate return. Default is D
active_premium_period string optional If stat = active_premium, period to calculate return. Default is D
hist_factor double optional If stat = histogram, number of data bins. Default is 5
var_conf_interval double optional If stat = var, confidence interval for the var
n_rolling_max_drawdown integer optional If stat = rolling_n_day_max_drawdown, number of days. Default is 7
risk_free_sharpe double optional If stat = sharpe_ratio, risk free rate of return. Default is 0
risk_free_treynor double optional If stat = treynor_ratio, risk free rate of return. Default is 0
risk_free_alpha double optional If stat = alpha, risk free rate of return. Default is 0
risk_free_sortino double optional If stat = sortino_ratio, risk free rate of return. Default is 0
mar_down_side_deviation double optional If stat = downside_deviation, minimum acceptable return. Default is 0
num_sim_monte_carlo integer optional If stat = monte_carlo, number of Monte Carlo simulations. Default is 1000
n_path_monte_carlo integer optional If stat = monte_carlo, number of Monte Carlo paths. Default is 100
max_percentile_monte_carlo double optional If stat = monte_carlo, maximum probability for a Monte Carlo simulation. Default is 95
min_percentile_monte_carlo double optional If stat = monte_carlo, minimum probability for a Monte Carlo simulation. Default is 5
mean_percentile_monte_carlo double optional If stat = monte_carlo, mean probability for a Monte Carlo simulation. Default is 50

Goal Performance

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/nucleus/v1/goal/149c5490-b7d2-4813-a6d9-02bbd08a4ab1/performance?client_id=099961da-7f41-4309-950f-2b51689a0033&stat=ann_return"

Example Response

{
    "ann_return": 0.06132398215253243
}

Get information on the performance of a goal using IRR (Internal Rate of Return). You 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. You must also specify the statistic to be returned using the stat parameter. To obtain the stat use the statistics resource table.

HTTP REQUEST

GET /goal/{goal_id}/performance?client_id={client_id}&stat={stat name}

DATA DEPENDENCIES

To calculate performance for a goal, you must first have the following data:

  1. Allocation - POST /allocation
  2. Allocation Composition - POST /allocation_composition using the allocation_id from step #1
  3. Goal - POST /goal
  4. Client - POST /client
  5. Account - POST /account and assign to client_id from step #4 and goal_id from step #3 for each account
  6. Account Allocation - POST /account_allocation and assign allocation_id from step #1 to account_id from step #5
  7. Portfolio - POST /portfolio and assign account_id from step #5
  8. Portfolio Asset Sizes - POST /portfolio_asset_size for portfolio_id from step #7 for all applicable dates

To calculate any applicable statistic against a benchmark_id, you must first have the following data:

  1. Benchmark - POST /benchmark with composition of all security_ids that make up this benchmark
  2. Security Prices - POST /security_price for all security_ids that make up this benchmark for all applicable dates

ARGUMENTS

Parameter Type Required Description
client_id string required The id of the client to whom the goal belongs. For example, the client_id obtained in step 4 of the Data Dependencies workflow above
stat string required The statistic you want to run on the account. See all available statistics here
start_date date optional Start date for the period for which to calculate the statistic
end_date date optional End date for the period for which to calculate the statistic
period_type string optional Period to carry out statistic. Options are Y for annually, Q for quarterly, M for monthly, D for daily (must use capital letters)
benchmark_id UUID optional If stat = beta, treynor_ratio, alpha, correlation, covariance, r_squared, information_ratio, tracking_error, active_premium, up_pct_ratio, down_pct_ratio, pct_gain_ratio, tstat, down_capture, or up_capture, the benchmark you want to use in the calculation
n_rolling_volatility integer optional If stat = rolling_n_day_vol, number of days. Default is 7
n_day_returns integer optional If stat = rolling_n_day_return, number of days. Default is 7
moving_average integer optional If stat = moving_avg_n_day, number of days. Default is 7
annualized_return_period string optional If stat = ann_return, period to calculate return. Default is D
active_premium_period string optional If stat = active_premium, period to calculate return. Default is D
hist_factor double optional If stat = histogram, number of data bins. Default is 5
var_conf_interval double optional If stat = var, confidence interval for the var
n_rolling_max_drawdown integer optional If stat = rolling_n_day_max_drawdown, number of days. Default is 7
risk_free_sharpe double optional If stat = sharpe_ratio, risk free rate of return. Default is 0
risk_free_treynor double optional If stat = treynor_ratio, risk free rate of return. Default is 0
risk_free_alpha double optional If stat = alpha, risk free rate of return. Default is 0
risk_free_sortino double optional If stat = sortino_ratio, risk free rate of return. Default is 0
mar_down_side_deviation double optional If stat = downside_deviation, minimum acceptable return. Default is 0
num_sim_monte_carlo integer optional If stat = monte_carlo, number of Monte Carlo simulations. Default is 1000
n_path_monte_carlo integer optional If stat = monte_carlo, number of Monte Carlo paths. Default is 100
max_percentile_monte_carlo double optional If stat = monte_carlo, maximum probability for a Monte Carlo simulation. Default is 95
min_percentile_monte_carlo double optional If stat = monte_carlo, minimum probability for a Monte Carlo simulation. Default is 5
mean_percentile_monte_carlo double optional If stat = monte_carlo, mean probability for a Monte Carlo simulation. Default is 50

Model Performance

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/nucleus/v1/model/cce4cb18-9a0a-499e-be38-cfb089ba1781/performance?stat=ann_return"

Example Response

{
    "ann_return": 0.06132398215253243
}

Get information on the performance of a model using TWR (Time Weighted Return). You must provide the unique model_id. To obtain the appropriate model_id, use the GET /model endpoint to view all models defined for your firm and their current information. You must also specify the statistic to be returned using the stat parameter. To obtain the stat use the statistics resource table.

HTTP REQUEST

GET /model/{model_id}/performance?stat={stat name}

DATA DEPENDENCIES

To calculate performance for a model, you must first have the following data:

  1. Model - POST /model
  2. Model Asset Sizes - POST /model_asset_size for model_id from step #1 for all applicable dates

To calculate any applicable statistic against a benchmark_id, you must first have the following data:

  1. Benchmark - POST /benchmark with composition of all security_ids that make up this benchmark
  2. Security Prices - POST /security_price for all security_ids that make up this benchmark for all applicable dates

ARGUMENTS

Parameter Type Required Description
stat string required The statistic you want to run on the account. See all available statistics here
start_date date optional Start date for the period for which to calculate the statistic
end_date date optional End date for the period for which to calculate the statistic
period_type string optional Period to carry out statistic. Options are Y for annually, Q for quarterly, M for monthly, D for daily (must use capital letters)
benchmark_id UUID optional If stat = beta, treynor_ratio, alpha, correlation, covariance, r_squared, information_ratio, tracking_error, active_premium, up_pct_ratio, down_pct_ratio, pct_gain_ratio, tstat, down_capture, or up_capture, the benchmark you want to use in the calculation
n_rolling_volatility integer optional If stat = rolling_n_day_vol, number of days. Default is 7
n_day_returns integer optional If stat = rolling_n_day_return, number of days. Default is 7
moving_average integer optional If stat = moving_avg_n_day, number of days. Default is 7
annualized_return_period string optional If stat = ann_return, period to calculate return. Default is D
active_premium_period string optional If stat = active_premium, period to calculate return. Default is D
hist_factor double optional If stat = histogram, number of data bins. Default is 5
var_conf_interval double optional If stat = var, confidence interval for the var
n_rolling_max_drawdown integer optional If stat = rolling_n_day_max_drawdown, number of days. Default is 7
risk_free_sharpe double optional If stat = sharpe_ratio, risk free rate of return. Default is 0
risk_free_treynor double optional If stat = treynor_ratio, risk free rate of return. Default is 0
risk_free_alpha double optional If stat = alpha, risk free rate of return. Default is 0
risk_free_sortino double optional If stat = sortino_ratio, risk free rate of return. Default is 0
mar_down_side_deviation double optional If stat = downside_deviation, minimum acceptable return. Default is 0
num_sim_monte_carlo integer optional If stat = monte_carlo, number of Monte Carlo simulations. Default is 1000
n_path_monte_carlo integer optional If stat = monte_carlo, number of Monte Carlo paths. Default is 100
max_percentile_monte_carlo double optional If stat = monte_carlo, maximum probability for a Monte Carlo simulation. Default is 95
min_percentile_monte_carlo double optional If stat = monte_carlo, minimum probability for a Monte Carlo simulation. Default is 5
mean_percentile_monte_carlo double optional If stat = monte_carlo, mean probability for a Monte Carlo simulation. Default is 50

Portfolio Performance

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/nucleus/v1/portfolio/ef93ce1c-b50e-4856-803a-db5332be93b0/performance?stat=ann_return"

Example Response

{
    "ann_return": 0.06132398215253243
}

Get information on the performance of a portfolio using IRR (Internal Rate of Return). You must provide the unique portfolio_id. To obtain the appropriate portfolio_id, use the GET /portfolio endpoint to view all portfolios defined for your firm and their current information. You must also specify the statistic to be returned using the stat parameter. To obtain the stat use the statistics resource table.

HTTP REQUEST

GET /portfolio/{portfolio_id}/performance?stat={stat name}

DATA DEPENDENCIES

To calculate performance for a portfolio, you must first have the following data:

  1. Account - POST /account
  2. Portfolio - POST /portfolio and assign account_id from step #1
  3. Portfolio Asset Sizes - POST /portfolio_asset_size for portfolio_id from step #2 for all applicable dates

To calculate any applicable statistic against a benchmark_id, you must first have the following data:

  1. Benchmark - POST /benchmark with composition of all security_ids that make up this benchmark
  2. Security Prices - POST /security_price for all security_ids that make up this benchmark for all applicable dates

ARGUMENTS

Parameter Type Required Description
stat string required The statistic you want to run on the account. See all available statistics here
start_date date optional Start date for the period for which to calculate the statistic
end_date date optional End date for the period for which to calculate the statistic
period_type string optional Period to carry out statistic. Options are Y for annually, Q for quarterly, M for monthly, D for daily (must use capital letters)
benchmark_id UUID optional If stat = beta, treynor_ratio, alpha, correlation, covariance, r_squared, information_ratio, tracking_error, active_premium, up_pct_ratio, down_pct_ratio, pct_gain_ratio, tstat, down_capture, or up_capture, the benchmark you want to use in the calculation
n_rolling_volatility integer optional If stat = rolling_n_day_vol, number of days. Default is 7
n_day_returns integer optional If stat = rolling_n_day_return, number of days. Default is 7
moving_average integer optional If stat = moving_avg_n_day, number of days. Default is 7
annualized_return_period string optional If stat = ann_return, period to calculate return. Default is D
active_premium_period string optional If stat = active_premium, period to calculate return. Default is D
hist_factor double optional If stat = histogram, number of data bins. Default is 5
var_conf_interval double optional If stat = var, confidence interval for the var
n_rolling_max_drawdown integer optional If stat = rolling_n_day_max_drawdown, number of days. Default is 7
risk_free_sharpe double optional If stat = sharpe_ratio, risk free rate of return. Default is 0
risk_free_treynor double optional If stat = treynor_ratio, risk free rate of return. Default is 0
risk_free_alpha double optional If stat = alpha, risk free rate of return. Default is 0
risk_free_sortino double optional If stat = sortino_ratio, risk free rate of return. Default is 0
mar_down_side_deviation double optional If stat = downside_deviation, minimum acceptable return. Default is 0
num_sim_monte_carlo integer optional If stat = monte_carlo, number of Monte Carlo simulations. Default is 1000
n_path_monte_carlo integer optional If stat = monte_carlo, number of Monte Carlo paths. Default is 100
max_percentile_monte_carlo double optional If stat = monte_carlo, maximum probability for a Monte Carlo simulation. Default is 95
min_percentile_monte_carlo double optional If stat = monte_carlo, minimum probability for a Monte Carlo simulation. Default is 5
mean_percentile_monte_carlo double optional If stat = monte_carlo, mean probability for a Monte Carlo simulation. Default is 50

Security Performance

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/nucleus/v1/benchmark/681a3155-e82a-476b-8f83-cf36b6d81952/performance?stat=ann_return"

Example Response

{
    "ann_return": 0.06132398215253243
}

Get performance statistics for a security using TWR (Time Weighted Return). You must provide the unique security_id. To obtain the appropriate security_id, use the GET /security endpoint to view all securities defined for your firm and their current information. You must also specify the statistic to be returned using the stat parameter. To obtain the stat use the statistics resource table.

HTTP REQUEST

GET /security/{security_id}/performance?stat={stat name}

DATA DEPENDENCIES

To calculate any statistic for a security, you must first have the following data:

  1. Security - POST /security
  2. Security Prices - POST /security_price for security_id from step #1 all applicable dates

To calculate any applicable statistic against a benchmark_id, you must first have the following data:

  1. Benchmark - POST /benchmark with composition of all security_ids that make up this benchmark
  2. Security Prices - POST /security_price for all security_ids that make up this benchmark for all applicable dates

ARGUMENTS

Parameter Type Required Description
stat string required The statistic you want to run on the account. See all available statistics here
start_date date optional Start date for the period for which to calculate the statistic
end_date date optional End date for the period for which to calculate the statistic
period_type string optional Period to carry out statistic. Options are Y for annually, Q for quarterly, M for monthly, D for daily (must use capital letters)
benchmark_id UUID optional If stat = beta, treynor_ratio, alpha, correlation, covariance, r_squared, information_ratio, tracking_error, active_premium, up_pct_ratio, down_pct_ratio, pct_gain_ratio, tstat, down_capture, or up_capture, the benchmark you want to use in the calculation
n_rolling_volatility integer optional If stat = rolling_n_day_vol, number of days. Default is 7
n_day_returns integer optional If stat = rolling_n_day_return, number of days. Default is 7
moving_average integer optional If stat = moving_avg_n_day, number of days. Default is 7
annualized_return_period string optional If stat = ann_return, period to calculate return. Default is D
active_premium_period string optional If stat = active_premium, period to calculate return. Default is D
hist_factor double optional If stat = histogram, number of data bins. Default is 5
var_conf_interval double optional If stat = var, confidence interval for the var
n_rolling_max_drawdown integer optional If stat = rolling_n_day_max_drawdown, number of days. Default is 7
risk_free_sharpe double optional If stat = sharpe_ratio, risk free rate of return. Default is 0
risk_free_treynor double optional If stat = treynor_ratio, risk free rate of return. Default is 0
risk_free_alpha double optional If stat = alpha, risk free rate of return. Default is 0
risk_free_sortino double optional If stat = sortino_ratio, risk free rate of return. Default is 0
mar_down_side_deviation double optional If stat = downside_deviation, minimum acceptable return. Default is 0
num_sim_monte_carlo integer optional If stat = monte_carlo, number of Monte Carlo simulations. Default is 1000
n_path_monte_carlo integer optional If stat = monte_carlo, number of Monte Carlo paths. Default is 100
max_percentile_monte_carlo double optional If stat = monte_carlo, maximum probability for a Monte Carlo simulation. Default is 95
min_percentile_monte_carlo double optional If stat = monte_carlo, minimum probability for a Monte Carlo simulation. Default is 5
mean_percentile_monte_carlo double optional If stat = monte_carlo, mean probability for a Monte Carlo simulation. Default is 50

Portfolio

Portfolio Management

Portfolios are created under accounts and hold securities. A portfolio subscribes to a model to determine the security composition of the portfolio. An account may have one of more portfolios, but the weights of all the portfolios must add up to 100%.

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

List all portfolios

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/nucleus/v1/portfolio"

Example Response

{
    "content": [
        {
            "id": "04907eaa-3f33-49be-a35b-378cdf639fba",
            "create_date": "2018-01-01T21:56:03.000+0000",
            "update_date": "2018-01-15T21:56:03.000+0000",
            "description": "Portfolio 93 - Retirement Goal 1",
            "name": "Portfolio 93",
            "percentage": 100,
            "account_id": "04907eaa-3f33-49be-a35b-378cdf639fba",
            "model_id": "d5e3daf8-1ebf-4654-ac7a-2685502ec387",
            "metadata": {}
        },
        {
            "id": "099961da-7f41-4309-950f-2b51689a0033",
            "create_date": "2018-01-01T21:56:03.000+0000",
            "update_date": "2018-01-15T21:56:03.000+0000",
            "description": "Portfolio 10 - Major Purchase Goal 1",
            "name": "Portfolio 10",
            "percentage": 100,
            "account_id": "099961da-7f41-4309-950f-2b51689a0033",
            "model_id": "f68508c6-e23b-482e-b4f3-b449964eb08a",
            "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 information for all portfolios assigned to all of your firm’s accounts. Note that the metadata is stored as a nested object within the portfolio object.

HTTP REQUEST

GET /portfolio

Create a portfolio

Example Request

curl -X POST -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    -H "Content-Type: application/json" \
    -d '{
            "description": "Portfolio 93 - Retirement Goal 1",
            "name": "Portfolio 93",
            "percentage": 100,
            "account_id": "04907eaa-3f33-49be-a35b-378cdf639fba",
            "model_id": "d5e3daf8-1ebf-4654-ac7a-2685502ec387"
        }' "https://api.hydrogenplatform.com/nucleus/v1/portfolio"

Example Response

{
    "id": "04907eaa-3f33-49be-a35b-378cdf639fba",
    "create_date": "2018-01-01T21:56:03.000+0000",
    "description": "Portfolio 93 - Retirement Goal 1",
    "name": "Portfolio 93",
    "percentage": 100,
    "account_id": "04907eaa-3f33-49be-a35b-378cdf639fba",
    "model_id": "d5e3daf8-1ebf-4654-ac7a-2685502ec387",
    "metadata": {}
}

Create a new portfolio for an account. The account_id that the portfolio belongs to and the model_id to which the portfolio subscribes 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 model_id, use the GET /model endpoint to view all the models defined for your firm. The create_date will default to the current date. The endpoint returns a portfolio_id used to manage the portfolio.

HTTP REQUEST

POST /portfolio

ARGUMENTS

Parameter Type Required Description
name string required Name of the portfolio such as “Stock”
account_id UUID required The id of the account to which the portfolio belongs
model_id UUID required The id of the model to which the portfolio subscribes
percentage double required 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 optional Description for the portfolio such as “Stock Portfolio”
metadata map optional Custom information associated with the portfolio 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 portfolio

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/nucleus/v1/portfolio/04907eaa-3f33-49be-a35b-378cdf639fba"

Example Response

{
    "id": "04907eaa-3f33-49be-a35b-378cdf639fba",
    "create_date": "2018-01-01T21:56:03.000+0000",
    "update_date": "2018-01-15T21:56:03.000+0000",
    "description": "Portfolio 93 - Retirement Goal 1",
    "name": "Portfolio 93",
    "percentage": 100,
    "account_id": "04907eaa-3f33-49be-a35b-378cdf639fba",
    "model_id": "d5e3daf8-1ebf-4654-ac7a-2685502ec387",
    "metadata": {}
}

Retrieve a portfolio for an account. The portfolio_id must be provided. The endpoint returns the portfolio_id and the details for the portfolio specified.

HTTP REQUEST

GET /portfolio/{portfolio_id}

Update a portfolio

Example Request

curl -X PUT -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    -H "Content-Type: application/json" \
    -d '{
            "description": "Test Portfolio 1 Retirement",
            "name": "Test Portfolio 1",
            "percentage": 100,
            "account_id": "e281137e-748d-4f45-aaf1-ec91b90d7fe4",
            "model_id": "17b0323c-5a69-4d1e-a7b7-98c6d423148f",
            "metadata": {}
        }' "https://api.hydrogenplatform.com/nucleus/v1/portfolio/04907eaa-3f33-49be-a35b-378cdf639fba"

Example Response

{
    "id": "04907eaa-3f33-49be-a35b-378cdf639fba",
    "create_date": "2018-01-01T21:56:03.000+0000",
    "update_date": "2018-01-15T21:56:03.000+0000",
    "description": "Portfolio 93 - Retirement Goal 1",
    "name": "Portfolio 93",
    "percentage": 100,
    "account_id": "04907eaa-3f33-49be-a35b-378cdf639fba",
    "model_id": "d5e3daf8-1ebf-4654-ac7a-2685502ec387",
    "metadata": {}
}

Update a portfolio for an account. The portfolio_id must be provided. To obtain the appropriate portfolio_id, use the GET /portfolio endpoint to view all portfolios firm-wide and their current information. The details to be updated must also be provided. The endpoint returns the portfolio_id and the details for the portfolio.

HTTP REQUEST

PUT /portfolio/{portfolio_id}

Delete a portfolio

Example Request

curl -X DELETE -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/nucleus/v1/portfolio/04907eaa-3f33-49be-a35b-378cdf639fba"

Response (204 No Content)

Permanently delete a portfolio for an account. The portfolio_id must be provided. To obtain the appropriate portfolio_id, use the GET /portfolio endpoint to view all portfolios firm-wide. This deletes the portfolio_id and removes the portfolio record from the account entirely.

HTTP REQUEST

DELETE /portfolio/{portfolio_id}

Portfolio Asset Sizes

Portfolio asset sizes represent the total monetary value of the portfolio, including negative values. Asset sizes are used to track the progression of the portfolio. Asset size records are created at a portfolio level and aggregated at a goal, account, or client level.

Field Type Description
id UUID The id of the portfolio asset size record
date date Date for this asset size record
asset_size double Monetary value of the portfolio on the particular date. Can be less than, greater than or equal to 0
cash_flow double Net monetary value that has flowed in or out of the portfolio since the last asset size date, usually via deposits or withdrawals. Can be less than, greater than or equal to 0
portfolio_id UUID The id of the portfolio that the asset size record falls under
model_id UUID The id of the model to which the portfolio subscribes. Derived from the portfolio
account_id UUID The id of the account that the portfolio falls under. Derived from the portfolio
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 portfolio asset sizes

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/nucleus/v1/portfolio_asset_size"

Example Response

{
    "content": [
        {
            "id": "01b252d3-1412-477f-8d29-6e2ff6e54c81",
            "create_date": "2018-02-02T9:00:03.000+0000",
            "update_date": "2018-02-02T21:56:03.000+0000",
            "cash_flow": -50,
            "asset_size": 89160,
            "date": "2018-02-02",
            "account_id": "fbc03484-08e8-446d-83aa-6d6cc236355e",
            "portfolio_id": "fbc03484-08e8-446d-83aa-6d6cc236355e",
            "model_id": "9875ce25-82fe-4db5-90b2-2e0fa1f8791d"
        },
        {
            "id": "63ffef5e-1962-477a-9803-bc6a334d142c",
            "create_date": "2018-01-26T9:00:03.000+0000",
            "update_date": "2018-01-26T21:56:03.000+0000",
            "cash_flow": 100,
            "asset_size": 88250,
            "date": "2018-01-26",
            "account_id": "fbc03484-08e8-446d-83aa-6d6cc236355e",
            "portfolio_id": "fbc03484-08e8-446d-83aa-6d6cc236355e",
            "model_id": "9875ce25-82fe-4db5-90b2-2e0fa1f8791d"
        },
        {
            "id": "013380bf-7f17-44c1-93c5-892a7ed3498c",
            "create_date": "2018-01-22T9:00:03.000+0000",
            "update_date": "2018-01-22T21:56:03.000+0000",
            "cash_flow": 0,
            "asset_size": 39050,
            "date": "2018-01-22",
            "account_id": "eb3d7f60-a133-4ca9-815f-3677bcdc23a3",
            "portfolio_id": "eb3d7f60-a133-4ca9-815f-3677bcdc23a3",
            "model_id": "4ff21db3-97ab-4bbd-9885-be6aec522c44"
        }
    ],
    "last": false,
    "total_pages": 3,
    "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 a list of asset sizes per date for all portfolios defined for your firm. The endpoint returns a list of portfolio_asset_size_ids and the details for each asset size. You can filter using a portfolio_id to view the asset size records for a specific portfolio. To obtain the appropriate portfolio_id use the GET /portfolio endpoint to view portfolios firm-wide.

HTTP REQUEST

Create a portfolio asset size

Example Request

curl -X POST -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
     -H "Content-Type: application/json" \
     -d '{
            "cash_flow": -50,
            "asset_size": 89160,
            "date": "2018-02-02",
            "portfolio_id": "fbc03484-08e8-446d-83aa-6d6cc236355e"
        }' "https://api.hydrogenplatform.com/nucleus/v1/portfolio_asset_size"

Example Response

{
    "id": "01b252d3-1412-477f-8d29-6e2ff6e54c81",
    "create_date": "2018-02-02T9:00:03.000+0000",
    "cash_flow": -50,
    "asset_size": 89160,
    "date": "2018-02-02",
    "account_id": "fbc03484-08e8-446d-83aa-6d6cc236355e",
    "portfolio_id": "fbc03484-08e8-446d-83aa-6d6cc236355e",
    "model_id": "9875ce25-82fe-4db5-90b2-2e0fa1f8791d"
}

Create a new asset size record for a portfolio. The unique portfolio_id, model_id, and account_id must be provided. To obtain the appropriate portfolio_id , use the GET /portfolio endpoint to view all the portfolios defined for your firm. This will automatically also pass in the model_id and account_id. The endpoint returns a portfolio_asset_size_id id used to manage the asset size record.

HTTP REQUEST

POST /portfolio_asset_size

ARGUMENTS

Parameter Type Required Description
date date required Date for this asset size record
asset_size double required Monetary value of the portfolio on the particular date. Can be less than, greater than or equal to 0
cash_flow double required Net monetary value that has flowed in or out of the portfolio since the last asset size date, usually via deposits or withdrawals. Can be less than, greater than or equal to 0
portfolio_id UUID required The id of the portfolio that the asset size record falls under
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Retrieve a portfolio asset size

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/nucleus/v1/portfolio_asset_size/01b252d3-1412-477f-8d29-6e2ff6e54c81"

Example Response

{
    "id": "01b252d3-1412-477f-8d29-6e2ff6e54c81",
    "create_date": "2018-02-02T9:00:03.000+0000",
    "update_date": "2018-02-02T21:56:03.000+0000",
    "cash_flow": -50,
    "asset_size": 89160,
    "date": "2018-02-02",
    "account_id": "fbc03484-08e8-446d-83aa-6d6cc236355e",
    "portfolio_id": "fbc03484-08e8-446d-83aa-6d6cc236355e",
    "model_id": "9875ce25-82fe-4db5-90b2-2e0fa1f8791d"
}

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

HTTP REQUEST

GET /portfolio_asset_size/{portfolio_asset_size_id}

Update a portfolio asset size

Example Request

curl -X PUT -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
     -H "Content-Type: application/json" \
     -d '{
            "cash_flow": -50,
            "asset_size": 89160,
            "date": "2018-02-02",
            "portfolio_id": "fbc03484-08e8-446d-83aa-6d6cc236355e"
        }' "https://api.hydrogenplatform.com/nucleus/v1/portfolio_asset_size/01b252d3-1412-477f-8d29-6e2ff6e54c81"

Example Response

{
    "id": "01b252d3-1412-477f-8d29-6e2ff6e54c81",
    "create_date": "2018-02-02T9:00:03.000+0000",
    "update_date": "2018-02-02T21:56:03.000+0000",
    "cash_flow": -50,
    "asset_size": 89160,
    "date": "2018-02-02",
    "account_id": "fbc03484-08e8-446d-83aa-6d6cc236355e",
    "portfolio_id": "fbc03484-08e8-446d-83aa-6d6cc236355e",
    "model_id": "9875ce25-82fe-4db5-90b2-2e0fa1f8791d"
}

Update the information for a portfolio asset size record for a portfolio. The portfolio_asset_size_id must be provided. To obtain the appropriate portfolio_asset_size_id use the GET /portfolio_asset_size endpoint to view all portfolio asset size records and their current information. The details to be updated must also be provided. The endpoint returns the portfolio_asset_size_id and the details for the portfolio asset size record.

HTTP REQUEST

PUT /portfolio_asset_size/{portfolio_asset_size_id}

Delete a portfolio asset size

Example Request

curl -X DELETE -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/nucleus/v1/portfolio_asset_size/01b252d3-1412-477f-8d29-6e2ff6e54c81"

Response (204 No Content)

Permanently delete a portfolio asset size record for a portfolio. The portfolio_asset_size_id must be provided. To obtain the appropriate portfolio_asset_size_id use the GET /portfolio_asset_size endpoint to view all portfolio asset size records. This deletes the portfolio_asset_size_id and the details of the portfolio asset size record from the portfolio.

HTTP REQUEST

DELETE /portfolio_asset_size/{portfolio_asset_size_id}

Portfolio Holdings

Holding records represent the securities that are held in a portfolio for a particular date. Holding records are created at the model and portfolio level and aggregated to show the holdings at a goal, account, allocation, or client level.

Field Type Description
id UUID The id of the security holding record
date date Date for this security holding record
portfolio_id UUID The id of the portfolio to which the holding record belongs
security_id UUID The id of the security included in the holding record
shares double The quantity of shares of the security being held
amount double Total monetary value of the security being held. Used to calculate weights
weight double Weight of the holding as a percentage of a portfolio’s total monetary value; ex. 20 representing 20%. If the security is the only one, enter 100
model_id UUID The id of the model to which the portfolio subscribes. Derived from the portfolio
account_id UUID The id of the account that the portfolio falls under. Derived from the portfolio
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 holding record was created
update_date timestamp Timestamp for the date and time that the holding record was last updated

List all portfolio holdings

Example Request

curl -X GET -H "Authorization: Bearer 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
    "https://api.hydrogenplatform.com/nucleus/v1/portfolio_holding"

Example Response

{
    "content": [
        {
            "id": "099961da-7f41-4309-950f-2b51689a0033",
            "create_date": "2018-02-03T9:00:03.000+0000",
            "update_date": "2018-02-03T21:56:03.000+0000",
            "amount": 1000,
            "shares": 12,
            "date": "2018-02-03",
            "weight": 10,
            "security_id": "bd409fc9-10ba-4a01-ac32-955d835a1954",
            "portfolio_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
            "account_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
            "model_id": "feb846da-a06d-402e-a3bb-abc7260f7138"
        },
        {
            "id": "107516c3-9035-4811-af7c-501be5a1fe26",
            "create_date": "2018-02-03T9:00:03.000+0000",
            "update_date": "2018-02-03T21:56:03.000+0000",
            "amount": 32400,
            "shares": 45,
            "date": "2018-02-03",
            "weight": 54,
            "security_id": "1cec111a-4d06-45dc-a7e5-b7673461adcf",
            "portfolio_id": "2a7a6cb7-ef71-4fe8-9169-2678f3799657",
            "account_id": "2a7a6cb7-ef71-4fe8-9169-2678f3799657",
            "model_id": "ed3399b4-4a57-4b5d-9083-790b2a47d3d1"
        },
        {
            "id": "199a8c08-cdd5-4c8c-8abf-535447cea11b",
            "create_date": "2018-02-03T9:00:03.000+0000",
            "update_date": "2018-02-03T21:56:03.000+0000",
            "amount": 15200,
            "shares": 123,
            "date": "2018-02-03",
            "weight": 19,
            "security_id": "cd9128c8-8a79-4b7f-9ba7-b58fc0e629e4",
            "portfolio_id": "e995d4c1-f989-4733-9867-713966ac9856",
            "account_id": "e995d4c1-f989-4733-9867-713966ac9856",
            "model_id": "eb3d7f60-a133-4ca9-815f-3677bcdc23a3"
        }
    ],
    "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 information for all holding records for all portfolios defined for your firm. The endpoint returns a list of portfolio_holding_ids and the details for each holding record. You can filter using a portfolio_id to view the holding records for a specific portfolio. You can also provide a date range to view the holding records on dates within the range. To obtain the appropriate portfolio_id use the GET /portfolio endpoint to view portfolios firm-wide.

HTTP REQUEST

GET /portfolio_holding

Create a portfolio holding

Example Request

curl -X POST -H "Authorization: Bearer 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
    -H "Content-Type: application/json" \
    -d '{
            "amount": 1000,
            "shares": 12,
            "date": "2018-02-03",
            "weight": 10,
            "security_id": "bd409fc9-10ba-4a01-ac32-955d835a1954",
            "portfolio_id": "647c54c3-b649-477e-8cc7-eee56a120dd3"
        }' "https://api.hydrogenplatform.com/nucleus/v1/portfolio_holding"

Example Response

{
    "id": "099961da-7f41-4309-950f-2b51689a0033",
    "create_date": "2018-02-03T9:00:03.000+0000",
    "amount": 1000,
    "shares": 12,
    "date": "2018-02-03",
    "weight": 10,
    "security_id": "bd409fc9-10ba-4a01-ac32-955d835a1954",
    "portfolio_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
    "account_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
    "model_id": "feb846da-a06d-402e-a3bb-abc7260f7138"
}

Create a new holding record for a portfolio. The unique portfolio_id, model_id, and account_id must be provided. To obtain the appropriate portfolio_id , use the GET /portfolio endpoint to view all the portfolios defined for your firm. This will automatically also pass in the model_id and account_id. In addition, even though amount is optional, it is recommended to provide a value for amount based on the shares and security price to calculate accurate weights when aggregating at a client, account, or goal level. The endpoint returns a portfolio_holding_id id used to manage the holding record.

HTTP REQUEST

POST /portfolio_holding

ARGUMENTS

Parameter Type Required Description
date date required Date for this security holding record
portfolio_id UUID required The id of the portfolio to which the holding record belongs
security_id UUID required The id of the security included in the holding record
shares double required The quantity of shares of the security being held
amount double optional Total monetary value of the security being held. Used to calculate weights
weight integer optional Weight of the holding as a percentage of a portfolio’s total monetary value; ex. 20 representing 20%. If the security is the only one, enter 100
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Retrieve a portfolio holding

Example Request

curl -X GET -H "Authorization: Bearer 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
    "https://api.hydrogenplatform.com/nucleus/v1/portfolio_holding/099961da-7f41-4309-950f-2b51689a0033"

Example Response

{
    "id": "099961da-7f41-4309-950f-2b51689a0033",
    "create_date": "2018-02-03T9:00:03.000+0000",
    "update_date": "2018-02-03T21:56:03.000+0000",
    "amount": 1000,
    "shares": 12,
    "date": "2018-02-03",
    "weight": 10,
    "security_id": "bd409fc9-10ba-4a01-ac32-955d835a1954",
    "portfolio_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
    "account_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
    "model_id": "feb846da-a06d-402e-a3bb-abc7260f7138"
}

Retrieve the information for a portfolio holding record for a portfolio. The portfolio_holding_id must be provided. The endpoint returns the portfolio_holding_id and the details for the portfolio holding record specified.

HTTP REQUEST

GET /portfolio_holding/{portfolio_holding_id}

Update a portfolio holding

Example Request

curl -X PUT -H "Authorization: Bearer 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
    -H "Content-Type: application/json" \
    -d '{
            "amount": 1000,
            "shares": 12,
            "date": "2018-02-03",
            "weight": 10,
            "security_id": "bd409fc9-10ba-4a01-ac32-955d835a1954",
            "portfolio_id": "647c54c3-b649-477e-8cc7-eee56a120dd3"
        }' "https://api.hydrogenplatform.com/nucleus/v1/portfolio_holding/099961da-7f41-4309-950f-2b51689a0033"

Example Response

{
    "id": "099961da-7f41-4309-950f-2b51689a0033",
    "create_date": "2018-02-03T9:00:03.000+0000",
    "update_date": "2018-02-03T21:56:03.000+0000",
    "amount": 1000,
    "shares": 12,
    "date": "2018-02-03",
    "weight": 10,
    "security_id": "bd409fc9-10ba-4a01-ac32-955d835a1954",
    "portfolio_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
    "account_id": "647c54c3-b649-477e-8cc7-eee56a120dd3",
    "model_id": "feb846da-a06d-402e-a3bb-abc7260f7138"
}

Update the information for a portfolio holding record for a portfolio. The portfolio_holding_id must be provided. To obtain the appropriate portfolio_holding_id use the GET /portfolio_holding endpoint to view all portfolio holding records and their current information. The details to be updated must also be provided. The endpoint returns the portfolio_holding_id and the details for the portfolio holding record.

HTTP REQUEST

PUT /portfolio_holding/{portfolio_holding_id}

Delete a portfolio holding

Example Request

curl -X DELETE -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/nucleus/v1/portfolio_holding/099961da-7f41-4309-950f-2b51689a0033"

Response (204 No Content)

Permanently delete a portfolio holding record for a portfolio. The portfolio_holding_id must be provided. To obtain the appropriate portfolio_holding_id use the GET /portfolio_holding endpoint to view all portfolio holding records. This deletes the portfolio_holding_id and the details of the portfolio holding record from the portfolio.

HTTP REQUEST

DELETE /portfolio_holding/{portfolio_holding_id}

Portfolio 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 portfolio transaction record
portfolio_id UUID The id of the portfolio that the transaction record falls under
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 date Date for this transaction record
is_read boolean Indicates if the transaction has been read. Defaults to false which indicates that it has not been read
price double Price at which the security was bought or sold
quantity double Quantity of units of a security that were bought or sold
model_id UUID The id of the model to which the portfolio subscribes. Derived from the portfolio
account_id UUID The id of the account that the portfolio falls under. Derived from the portfolio
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 portfolio transactions

Example Request

curl -X GET -H "Authorization: Bearer 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
    "https://api.hydrogenplatform.com/nucleus/v1/portfolio_transaction"

Example Response

{
    "content": [
        {
            "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-01",
            "is_read": false,
            "price": 1,
            "quantity": 9000,
            "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"
        },
        {
            "id": "107516c3-9035-4811-af7c-501be5a1fe26",
            "create_date": "2018-01-02T9:00:03.000+0000",
            "update_date": "2018-01-08T21:56:03.000+0000",
            "date": "2018-01-02",
            "is_read": false,
            "price": 60,
            "quantity": 133.33,
            "security_id": "36a4b748-8a63-49a2-950f-deaa240c63d1",
            "transaction_code_id": "62fd0a9f-4bac-4b1d-94d2-2c5ea2adca3d",
            "portfolio_id": "a65929b6-b0a9-46e5-858a-121f0b10f4fb",
            "account_id": "a65929b6-b0a9-46e5-858a-121f0b10f4fb",
            "model_id": "21098ed9-6439-46ba-abd9-eb6cf28866fb"
        },
        {
            "id": "199a8c08-cdd5-4c8c-8abf-535447cea11b",
            "create_date": "2018-01-02T9:00:03.000+0000",
            "update_date": "2018-01-08T21:56:03.000+0000",
            "date": "2018-01-02",
            "is_read": false,
            "price": 30,
            "quantity": 280,
            "security_id": "7853af80-8d42-4bbb-bc06-00eda88a668e",
            "transaction_code_id": "62fd0a9f-4bac-4b1d-94d2-2c5ea2adca3d",
            "portfolio_id": "bab849d6-de96-4dc7-a5ea-19be45c52a4e",
            "account_id": "bab849d6-de96-4dc7-a5ea-19be45c52a4e",
            "model_id": "40a4bd78-d798-49f7-b1e8-35144c82e35e"
        }
    ],
    "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 information for all transaction records for all portfolios defined for your firm. The endpoint returns a list of portfolio_transaction_ids and the details for each transaction record. You can filter using a portfolio_id to view the transaction records for a specific portfolio. You can also provide a date range to view the transactions on the dates within that range. To obtain the appropriate portfolio_id use the GET /portfolio endpoint to view portfolios firm-wide.

HTTP REQUEST

GET /portfolio_transaction

Create a portfolio transaction

Example Request

curl -X POST -H "Authorization: Bearer 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
    -H "Content-Type: application/json" \
    -d '{
            "date": "2018-01-01",
            "is_read": false,
            "price": 1,
            "quantity": 9000,
            "security_id": "9679fd84-f6d5-44f9-bba9-a5fcb1b8b028",
            "transaction_code_id": "a65929b6-b0a9-46e5-858a-121f0b10f4fb",
            "portfolio_id": "647c54c3-b649-477e-8cc7-eee56a120dd3"
        }' "https://api.hydrogenplatform.com/nucleus/v1/portfolio_transaction"

Example Response

{
    "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-01",
    "is_read": false,
    "price": 1,
    "quantity": 9000,
    "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"
}

Create a new transaction record for a portfolio. The unique portfolio_id, model_id, and account_id must be provided. To obtain the appropriate portfolio_id , use the GET /portfolio endpoint to view all the portfolios defined for your firm. This will automatically also pass in the model_id and account_id. The endpoint returns a portfolio_transaction_id id used to manage the transaction record.

HTTP REQUEST

POST /portfolio_transaction

ARGUMENTS

Parameter Type Required Description
portfolio_id UUID required The id of the portfolio that the transaction record falls under
security_id UUID required The id of the security that was bought or sold in the transaction
transaction_code_id UUID required The id of the transaction code for the type of transaction
date date required Date for this transaction record
is_read boolean optional Indicates if the transaction has been read. Defaults to false which indicates that it has not been read
price double optional Price at which the security was bought or sold
quantity double optional Quantity of units of a security that were bought or sold
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Retrieve a portfolio transaction

Example Request

curl -X GET -H "Authorization: Bearer 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
    "https://api.hydrogenplatform.com/nucleus/v1/portfolio_transaction/099961da-7f41-4309-950f-2b51689a0033"

Example Response

{
    "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-01",
    "is_read": false,
    "price": 1,
    "quantity": 9000,
    "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"
}

Retrieve the information for a portfolio transaction record for a portfolio. The portfolio_transaction_id must be provided. The endpoint returns the portfolio_transaction_id and the details for the portfolio transaction record specified.

HTTP REQUEST

GET /portfolio_transaction/{portfolio_transaction_id}

Update a portfolio transaction

Example Request

curl -X PUT -H "Authorization: Bearer 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
    -H "Content-Type: application/json" \
    -d '{
            "date": "2018-01-01",
            "is_read": false,
            "price": 1,
            "quantity": 9000,
            "security_id": "9679fd84-f6d5-44f9-bba9-a5fcb1b8b028",
            "transaction_code_id": "a65929b6-b0a9-46e5-858a-121f0b10f4fb",
            "portfolio_id": "647c54c3-b649-477e-8cc7-eee56a120dd3"
       }' "https://api.hydrogenplatform.com/nucleus/v1/portfolio_transaction/099961da-7f41-4309-950f-2b51689a0033"

Example Response

{
    "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-01",
    "is_read": false,
    "price": 1,
    "quantity": 9000,
    "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"
}

Update the information for a portfolio transaction record for a portfolio. The portfolio_transaction_id must be provided. To obtain the appropriate portfolio_transaction_id use the GET /portfolio_transaction endpoint to view all portfolio transaction records and their current information. The details to be updated must also be provided. The endpoint returns the portfolio_transaction_id and the details for the portfolio transaction record.

HTTP REQUEST

PUT /portfolio_transaction/{portfolio_transaction_id}

Delete a portfolio transaction

Example Request

curl -X DELETE -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/nucleus/v1/portfolio_transaction/099961da-7f41-4309-950f-2b51689a0033"

Response (204 No Content)

Permanently delete a portfolio transaction record for a portfolio. The portfolio_transaction_id must be provided. To obtain the appropriate portfolio_transaction_id use the GET /portfolio_transaction endpoint to view all portfolio transaction records. This deletes the portfolio_transaction_id and the details of the portfolio transaction record from the portfolio.

HTTP REQUEST

DELETE /portfolio_transaction/{portfolio_transaction_id}

Portfolio Commentary

Portfolio commentary is used to understand the logic behind each portfolio. 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 portfolio comment record
portfolio_id UUID The id of the portfolio that the comment falls under
model_comment_id UUID The id of the corresponding model comment
model_id UUID The id of the model to which the portfolio subscribes. Derived from the portfolio
account_id UUID The id of the account to which the portfolio belongs. Derived from the portfolio
is_read boolean Indicates if the comment has been read. Defaults to false which indicates 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

List all portfolio commentary

Example Request

curl -X GET -H "Authorization: Bearer 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
    "https://api.hydrogenplatform.com/nucleus/v1/portfolio_comment"

Example Response

{
    "content": [
        {
            "id": "0d6d469e-22a9-4587-8249-bce8763d6efd",
            "create_date": "2018-01-01T19:29:37.000+0000",
            "update_date": "2018-01-15T09:00:00.000+0000",
            "is_read": false,
            "portfolio_id": "46841d3c-ac30-4011-b0a6-a0fcb313ebe3",
            "model_comment_id": "7f06b7b9-17f7-4390-afb2-1143b3ab7b",
            "model_id": "17b0323c-5a69-4d1e-a7b7-98c6d423148f",
            "account_id": "e281137e-748d-4f45-aaf1-ec91b90d7fe4"
        }
    ],
    "total_pages": 1,
    "total_elements": 1,
    "last": true,
    "sort": [
        {
            "direction": "DESC",
            "property": "id",
            "ignore_case": false,
            "null_handling": "NATIVE",
            "ascending": false,
            "descending": true
        }
    ],
    "first": true,
    "number_of_elements": 1,
    "size": 25,
    "number": 0
}

List all comments for all portfolios defined for your firm. You can filter using a portfolio_id to view the comments for a specific portfolio. To obtain the appropriate portfolio_id. To obtain the appropriate portfolio_id, use the GET /portfolio endpoint to view all portfolios form-wide. The endpoint returns a list of ids and the details for each portfolio comment.

HTTP REQUEST

GET /portfolio_comment

Create a portfolio commentary

Example Request

curl -X POST -H "Authorization: Bearer 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
    -H "Content-Type: application/json" \
    -d '{
            "is_read": false,
            "portfolio_id": "46841d3c-ac30-4011-b0a6-a0fcb313ebe3",
            "model_comment_id": "7f06b7b9-17f7-4390-afb2-1143b3ab7b"
        }' "https://api.hydrogenplatform.com/nucleus/v1/portfolio_comment"

Example Response

{
    "id": "0d6d469e-22a9-4587-8249-bce8763d6efd",
    "create_date": "2018-01-01T19:29:37.000+0000",
    "is_read": false,
    "portfolio_id": "46841d3c-ac30-4011-b0a6-a0fcb313ebe3",
    "model_comment_id": "7f06b7b9-17f7-4390-afb2-1143b3ab7b",
    "model_id": "17b0323c-5a69-4d1e-a7b7-98c6d423148f",
    "account_id": "e281137e-748d-4f45-aaf1-ec91b90d7fe4"
}

Create a new comment for a portfolio defined for your firm. The unique portfolio_id must be provided. To obtain the appropriate portfolio_id, use the GET /portfolio endpoint to view all portfolios firm-wide. This will also pass in the account_id and model_id associated with the portfolio. The corresponding model_comment_id must also be provided. To obtain the appropriate model_comment_id, use the GET /model_comment endpoint to view all model comment records defined for your firm. The create_date will default to the current date. The endpoint returns a portfolio_comment_id used to manage the portfolio comment.

HTTP REQUEST

POST /portfolio_comment

ARGUMENTS

Parameter Type Required Description
portfolio_id string required The id of the portfolio that the comment falls under
model_comment_id UUID required The id of the corresponding model comment
model_id UUID required The id of the model to which the portfolio subscribes. Derived from the portfolio
account_id UUID required The id of the account to which the portfolio belongs. Derived from the portfolio
is_read boolean optional Indicates if the comment has been read. Defaults to false which indicates it has not been read
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Retrieve a portfolio commentary

Example Request

curl -X GET -H "Authorization: Bearer 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
    "https://api.hydrogenplatform.com/nucleus/v1/portfolio_comment/0d6d469e-22a9-4587-8249-bce8763d6efd"

Example Response

{
    "id": "0d6d469e-22a9-4587-8249-bce8763d6efd",
    "create_date": "2018-01-01T19:29:37.000+0000",
    "update_date": "2018-01-15T09:00:00.000+0000",
    "is_read": false,
    "portfolio_id": "46841d3c-ac30-4011-b0a6-a0fcb313ebe3",
    "model_comment_id": "7f06b7b9-17f7-4390-afb2-1143b3ab7b",
    "model_id": "17b0323c-5a69-4d1e-a7b7-98c6d423148f",
    "account_id": "e281137e-748d-4f45-aaf1-ec91b90d7fe4"
}

Retrieve the information for a portfolio comment for a portfolio. The portfolio_comment_id must be provided. The endpoint returns the portfolio_comment_id and the details for the portfolio comment specified.

HTTP REQUEST

GET /portfolio_comment/{portfolio_comment_id}

Update a portfolio commentary

Example Request

curl -X PUT -H "Authorization: Bearer 7f137375-c63b-49fb-84eb-5abbd3b780a3" \
    -H "Content-Type: application/json" \
    -d '{
            "is_read": false,
            "portfolio_id": "46841d3c-ac30-4011-b0a6-a0fcb313ebe3",
            "model_comment_id": "7f06b7b9-17f7-4390-afb2-1143b3ab7b"
        }' "https://api.hydrogenplatform.com/nucleus/v1/portfolio_comment/0d6d469e-22a9-4587-8249-bce8763d6efd"

Example Response

{
    "id": "0d6d469e-22a9-4587-8249-bce8763d6efd",
    "create_date": "2018-01-01T19:29:37.000+0000",
    "update_date": "2018-01-15T09:00:00.000+0000",
    "is_read": false,
    "portfolio_id": "46841d3c-ac30-4011-b0a6-a0fcb313ebe3",
    "model_comment_id": "7f06b7b9-17f7-4390-afb2-1143b3ab7b",
    "model_id": "17b0323c-5a69-4d1e-a7b7-98c6d423148f",
    "account_id": "e281137e-748d-4f45-aaf1-ec91b90d7fe4"
}

Update the information for a portfolio comment for a portfolio. The portfolio_comment_id must be provided. To obtain the appropriate portfolio_comment_id, use the GET /portfolio_comment endpoint to view all the portfolio comments and their current information. The details to be updated must also be provided. The endpoint returns the portfolio_comment_id and the details for the portfolio comment.

HTTP REQUEST

PUT /portfolio_comment/{portfolio_comment_id}

Delete a portfolio commentary

Example Request

curl -X DELETE -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/nucleus/v1/portfolio_comment/0d6d469e-22a9-4587-8249-bce8763d6efd"

Response (204 No Content)

Permanently delete a portfolio comment for a portfolio. The portfolio_comment_id must be provided. To obtain the appropriate portfolio_comment_id, use the GET /portfolio_comment endpoint to view all the portfolio comments. This deletes the portfolio_comment_id and the portfolio comment record from the portfolio.

HTTP REQUEST

DELETE /portfolio_comment/{portfolio_comment_id}

Questionnaire

Questionnaires represent a series of questions that a customer or 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.

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”
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 additioonal 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%. Weights of all the questions must add up to 100
      is_account boolean Indicates if the question is answered at an account-level
      metadata hash 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 of the total questionnaire score if each answer does not contribute equally when calculating the final “score”; ex. 20 representing 20%. Weights of all the answers for a question must add up to 100
            metadata hash 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 e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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",
            "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",
                    "weight": 0,
                    "is_account": false,
                    "answers": [
                        {
                            "id": "d31c694f-bcb5-427f-b081-91e64e90229a",
                            "value": ">40",
                            "image": "http://domain.com/age_graphic1.pdf",
                            "weight": 0,
                            "metadata": {}
                        },
                        {
                            "id": "1e52401f-bfec-410b-bca1-afa5f0be37b5",
                            "value": "0-40",
                            "image": "http://domain.com/age_graphic2.pdf",
                            "weight": 0,
                            "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,
                    "is_account": false,
                    "answers": [
                        {
                            "id": "7d8de5fa-6174-4a30-9e70-8e638a3d5304",
                            "value": ">100,000",
                            "image": "http://domain.com/income_graphic1.pdf",
                            "label": "high_net_worth",
                            "weight": 0,
                            "metadata": {}
                        },
                        {
                            "id": "0ffe04ba-5db0-4a72-9fd1-2ba9479e685a",
                            "value": "0-100,000",
                            "image": "http://domain.com/income_graphic2.pdf",
                            "weight": 0,
                            "metadata": {}
                        }
                    ],
                    "metadata": {}
                }
            ]
      }
     ],
    "last": false,
    "total_pages": 1,
    "total_elements": 1,
    "sort": [
        {
            "direction": "ASC",
            "property": "updateDate",
            "ignore_case": false,
            "null_handling": "NATIVE",
            "descending": false,
            "ascending": true
        }
    ],
    "first": true,
    "number_of_elements": 1,
    "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 questionnaire metadata information and the questions are stored as nested objects within the questionnaire object. The question metadata and the answers are a nested objects within the question object, and the answer metadata is a nested object within the answer object.

HTTP REQUEST

GET /questionnaire

Create a questionnaire

Example Request

curl -X POST -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900"
     -H "Content-Type: application/json"
     -d '{
            "name": "Onboarding Questionnaire",
            "description": "Basic goals onboarding for accounts",
            "type": "Goals",
            "questions": [
                {
                    "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",
                    "weight": 0,
                    "is_account": false,
                    "answers": [
                        {
                            "value": ">40",
                            "image": "http://domain.com/age_graphic1.pdf",
                            "weight": 0
                        },
                        {
                            "value": "0-40",
                            "image": "http://domain.com/age_graphic2.pdf",
                            "weight": 0
                        }
                    ]
                },
                {
                    "category": "Onboarding",
                    "subcategory": "Basic",
                    "title": "What is your annual income in dollars?",
                    "question_type": "monetary_input",
                    "order_index": "2",
                    "weight": 0,
                    "is_account": false,
                    "answers": [
                        {
                            "value": ">100,000",
                            "image": "http://domain.com/income_graphic1.pdf",
                            "label": "high_net_worth",
                            "weight": 0
                        },
                        {
                            "id": "0ffe04ba-5db0-4a72-9fd1-2ba9479e685a",
                            "value": "0-100,000",
                            "image": "http://domain.com/income_graphic2.pdf",
                            "weight": 0
                        }
                    ]
                }
            ]
      }' "https://api.hydrogenplatform.com/nucleus/v1/questionnaire"

Example Response

{
    "id": "29fa5156-cd89-4056-9125-ce2428b05f11",
    "create_date": "2018-01-01T21:56:03.000+0000",
    "name": "Onboarding Questionnaire",
    "description": "Basic goals onboarding for accounts",
    "type": "Goals",
    "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",
            "weight": 0,
            "is_account": false,
            "answers": [
                {
                    "id": "d31c694f-bcb5-427f-b081-91e64e90229a",
                    "value": ">40",
                    "image": "http://domain.com/age_graphic1.pdf",
                    "weight": 0,
                    "metadata": {}
                },
                {
                    "id": "1e52401f-bfec-410b-bca1-afa5f0be37b5",
                    "value": "0-40",
                    "image": "http://domain.com/age_graphic2.pdf",
                    "weight": 0,
                    "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,
            "is_account": false,
            "answers": [
                {
                    "id": "7d8de5fa-6174-4a30-9e70-8e638a3d5304",
                    "value": ">100,000",
                    "image": "http://domain.com/income_graphic1.pdf",
                    "label": "high_net_worth",
                    "weight": 0,
                    "metadata": {}
                },
                {
                    "id": "0ffe04ba-5db0-4a72-9fd1-2ba9479e685a",
                    "value": "0-100,000",
                    "image": "http://domain.com/income_graphic2.pdf",
                    "weight": 0,
                    "metadata": {}
                }
            ],
            "metadata": {}
        }
    ]
}

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”
questions array optional List of questions to be answered as well as their respective answers and weights within the questionnaire
      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”
      title string optional 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 additioonal question content. Pairs with the title field
      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%. Weights of all the questions must add up to 100
      is_account boolean optional Indicates if the question is answered at an account-level
      metadata hash optional Custom information associated with the question in the format key:value. See Metadata
      answers array optional Possible answers to the question such as multiple choice options
            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 of the total questionnaire score if each answer does not contribute equally when calculating the final “score”; ex. 20 representing 20%. Weights of all the answers for a question must add up to 100
            metadata hash optional Custom information associated with the answer option 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 questionnaire

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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",
    "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",
            "weight": 0,
            "is_account": false,
            "answers": [
                {
                    "id": "d31c694f-bcb5-427f-b081-91e64e90229a",
                    "value": ">40",
                    "image": "http://domain.com/age_graphic1.pdf",
                    "weight": 0,
                    "metadata": {}
                },
                {
                    "id": "1e52401f-bfec-410b-bca1-afa5f0be37b5",
                    "value": "0-40",
                    "image": "http://domain.com/age_graphic2.pdf",
                    "weight": 0,
                    "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,
            "is_account": false,
            "answers": [
                {
                    "id": "7d8de5fa-6174-4a30-9e70-8e638a3d5304",
                    "value": ">100,000",
                    "image": "http://domain.com/income_graphic1.pdf",
                    "label": "high_net_worth",
                    "weight": 0,
                    "metadata": {}
                },
                {
                    "id": "0ffe04ba-5db0-4a72-9fd1-2ba9479e685a",
                    "value": "0-100,000",
                    "image": "http://domain.com/income_graphic2.pdf",
                    "weight": 0,
                    "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 e7cf805b-4307-41e9-8b58-90b6359fa900"
    -H "Content-Type: application/json"
    -d '{
            "name": "Onboarding Questionnaire",
            "description": "Basic goals onboarding for accounts",
            "type": "Goals",
            "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",
                    "weight": 0,
                    "is_account": false,
                    "answers": [
                        {
                            "id": "d31c694f-bcb5-427f-b081-91e64e90229a",
                            "value": ">40",
                            "image": "http://domain.com/age_graphic1.pdf",
                            "weight": 0
                        },
                        {
                            "id": "1e52401f-bfec-410b-bca1-afa5f0be37b5",
                            "value": "0-40",
                            "image": "http://domain.com/age_graphic2.pdf",
                            "weight": 0
                        }
                    ]
                },
                {
                    "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,
                    "is_account": false,
                    "answers": [
                        {
                            "id": "7d8de5fa-6174-4a30-9e70-8e638a3d5304",
                            "value": ">100,000",
                            "image": "http://domain.com/income_graphic1.pdf",
                            "label": "high_net_worth",
                            "weight": 0
                        },
                        {
                            "id": "0ffe04ba-5db0-4a72-9fd1-2ba9479e685a",
                            "value": "0-100,000",
                            "image": "http://domain.com/income_graphic2.pdf",
                            "weight": 0
                        }
                    ]
                }
            ]
      }' "https://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",
    "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",
            "weight": 0,
            "is_account": false,
            "answers": [
                {
                    "id": "d31c694f-bcb5-427f-b081-91e64e90229a",
                    "value": ">40",
                    "image": "http://domain.com/age_graphic1.pdf",
                    "weight": 0,
                    "metadata": {}
                },
                {
                    "id": "1e52401f-bfec-410b-bca1-afa5f0be37b5",
                    "value": "0-40",
                    "image": "http://domain.com/age_graphic2.pdf",
                    "weight": 0,
                    "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,
            "is_account": false,
            "answers": [
                {
                    "id": "7d8de5fa-6174-4a30-9e70-8e638a3d5304",
                    "value": ">100,000",
                    "image": "http://domain.com/income_graphic1.pdf",
                    "label": "high_net_worth",
                    "weight": 0,
                    "metadata": {}
                },
                {
                    "id": "0ffe04ba-5db0-4a72-9fd1-2ba9479e685a",
                    "value": "0-100,000",
                    "image": "http://domain.com/income_graphic2.pdf",
                    "weight": 0,
                    "metadata": {}
                }
            ],
            "metadata": {}
        }
    ]
}

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. Due to the embedded questions and answers structure, to make specific updates or changes there are particular combinations of information that must be provided in addition to the questionnaire_id:

  1. Update the details of a question and/or answer:
   a. Provide the questionnaire_id in the URL and the details about the questionnaire to be updated (if any) such as name
   b. Provide the question_id and existing details for all questions to remain the same
   c. Provide the answer_id and existing details for all answers to remain the same
   d. Provide the question_id and new details for all questions to be updated
   e. Provide the answer_id and new details for all answers to be updated
  2. Remove a question and/or answer:
   a. Provide the questionnaire_id in the URL and the details about the questionnaire to be updated (if any) such as name
   b. Provide the question_id and existing details for all questions to remain the same
   c. Provide the answer_id and existing details for all answers to remain the same
   d. Provide the question_id for the questions to be removed with no additional details
   e. Provide the answer_id for the answers to be removed with no additional details
  3. Replace all questions and answers and generate new question_ids and answer_ids:
   a. Provide the questionnaire_id in the URL and the details about the questionnaire to be updated (if any) such as name
   b. Provide the details for all of the new questions and answers with no question_ids and answer_ids
  4. Delete all questions and answers:
   a. Provide the questionnaire_id in the URL and the details about the questionnaire to be updated (if any) such as name
   b. Provide the question_ids and answer_ids for all the questions and answers with no additional details

HTTP REQUEST

PUT /questionnaire/{questionnaire_id}

Delete a questionnaire

Example Request

curl -X DELETE -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://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}

Score

Score Management

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

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, and credit_score
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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://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_score",
            "score_value": "35",
            "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 entitiy. 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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
-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://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, and credit_score
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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
-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://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 ac6b8213-2a77-4ecc-89fd-68c9f2aff256" \
    "https://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}

Securities

Security Management

Securities represent financial assets that correspond to a client’s holdings. Orders represent transactions to buy or sell securities. Securities belong to portfolios and are aggregated at a client or account level. A client, account, and portfolio will usually hold more than one security. Securities may also belong to one or more models.

Field Type Description
id UUID The id of the security
name string Name for the security
ticker string Security’s ticker on the exchange where it is traded
asset_class string The asset class for the security such as “equities”, “fixed income”, “commodities”, etc.
sector string Sector for the security such as “Technology” or “Pharmaceuticals”
industry string The industry of the security such as “Consumer Tech” or “Enterprise Systems”
exchange string The exchange on which the security is traded
security_class string The security class of the security such as “stock”, “mutual fund”, “exchange-traded fund (ETF)”, etc.
is_active boolean Indicates if the security is active. Defaults to true which indicates that it is active
security_composition array Details on the components of a security, their relative weight within the security, and their start and end dates
      component_id UUID The id of the underlying security that is part of the broader security
      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
      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
security_country array Each country where the security is traded and its relative weight within the security
      country string Country where the security is traded represented using their ISO ALPHA-2 Code. See Country Code reference table
      weight double The weight of the country as a percentage of the security; ex. 20 representing 20%. The weights of all the countries must add up to 100
metadata map Custom information associated with the security 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 securities

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/nucleus/v1/security"

Example Response

{
    "content": [
        {
            "id": "000094b3-aedb-4626-9bce-7d00140a614c",
            "create_date": "2018-01-01T21:56:03.000+0000",
            "update_date": "2018-01-15T21:56:03.000+0000",
            "category": "",
            "industry": "Heavy Construction",
            "is_active": true,
            "name": "Wowjoint Holdings Limited - Common Shares",
            "sector": "Industrial Goods",
            "security_class": "",
            "ticker": "BWOW",
            "security_country": [
                {
                    "weight": 100,
                    "country": "CN"
                }
            ],
            "security_composition": [],
            "asset_class": "EM Equities"
        },
        {
            "id": "0000c009-e76f-40cd-a0ad-d4f73bbc700f",
            "create_date": "2018-01-01T21:56:03.000+0000",
            "update_date": "2018-01-15T21:56:03.000+0000",
            "category": "World Stock",
            "industry": "",
            "is_active": true,
            "name": "JPMorgan Global Research Enh Idx Select",
            "sector": "",
            "security_class": "Mutual Fund",
            "ticker": "JEITX",
            "security_country": [],
            "security_composition": [],
            "asset_class": "Intl Equities"
        },
        {
            "id": "000183ac-2288-4564-a76b-119f4694be98",
            "create_date": "2018-01-01T21:56:03.000+0000",
            "update_date": "2018-01-15T21:56:03.000+0000",
            "category": "Large Blend",
            "industry": "",
            "is_active": true,
            "name": "Pioneer Research Y",
            "sector": "",
            "security_class": "Mutual Fund",
            "ticker": "PRFYX",
            "security_country": [],
            "security_composition": [],
            "asset_class": "US Equities"
        },
        {
            "id": "000228d4-6089-4b9f-8849-d0a5503411b1",
            "create_date": "2018-01-01T21:56:03.000+0000",
            "update_date": "2018-01-15T21:56:03.000+0000",
            "category": "Target Date 2051+",
            "industry": "",
            "is_active": true,
            "name": "BlackRock LifePath Active 2055 R",
            "sector": "",
            "security_class": "Mutual Fund",
            "ticker": "BRPLX",
            "security_country": [],
            "security_composition": [],
            "asset_class": "Diversified Allocation"
        },
        {
            "id": "00036fb7-c47e-44a2-9b55-0fd40e779887",
            "create_date": "2018-01-01T21:56:03.000+0000",
            "update_date": "2018-01-15T21:56:03.000+0000",
            "category": "",
            "industry": "Semiconductor Equipment &amp; Materials",
            "is_active": true,
            "name": "Cymer, Inc.",
            "sector": "Technology",
            "security_class": "",
            "ticker": "CYMI",
            "security_country": [
                {
                    "weight": 100,
                    "country": "US"
                }
            ],
            "security_composition": [],
            "asset_class": "US Equities"
        },
    ],
    "total_pages": 1,
    "total_elements": 5,
    "last": false,
    "number_of_elements": 5,
    "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 securities defined for your firm. Note that the metadata information, the country information, and the security composition information are stored as nested objects within the security object.

HTTP REQUEST

GET /security

Create a security

Example Request

curl -X POST -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    -H "Content-Type: application/json" \
    -d '{
            "industry": "",
            "is_active": true,
            "name": "Vanguard FTSE All-World ex-US ETF",
            "sector": "",
            "security_class": "ETF",
            "ticker": "VEU",
            "metadata": {},
            "security_country": [
                {
                  "weight": 50,
                  "country": "DE"
                },
                {
                  "weight": 15,
                  "country": "JP"
                },
                {
                  "weight": 21,
                  "country": "AX"
                },
                {
                  "weight": 5,
                  "country": "CN"
                },
                {
                  "weight": 5,
                  "country": "TU"
                },
                {
                  "weight": 4,
                  "country": "EU"
                }
          ],
          "security_composition": [
              {
                "component_id": "ac2ead7b-d3c2-401c-9c7e-5b769de9262e",
                "start_date": "2015-01-01",
                "end_date": "2020-01-01",
                "weight": 50
              },
              {
                "component_id": "bfa4621e-233f-4075-b7cc-d7946f38e484",
                "start_date": "2015-01-01",
                "end_date": "2020-01-01",
                "weight": 50
              }
          ],
          "asset_class": "Intl Equities"
      }' "https://api.hydrogenplatform.com/nucleus/v1/security"

Example Response

{
    "id": "b690fc43-9cdd-4547-b8cd-afadf6b58b2a",
    "create_date": "2018-01-01T21:56:03.000+0000",
    "industry": "",
    "is_active": true,
    "name": "Vanguard FTSE All-World ex-US ETF",
    "sector": "",
    "security_class": "ETF",
    "ticker": "VEU",
    "metadata": {},
    "security_country": [
      {
        "weight": 50,
        "country": "DE"
      },
      {
        "weight": 15,
        "country": "JP"
      },
      {
        "weight": 21,
        "country": "AX"
      },
      {
        "weight": 5,
        "country": "CN"
      },
      {
        "weight": 5,
        "country": "TU"
      },
      {
        "weight": 4,
        "country": "EU"
      }
    ],
    "security_composition": [
      {
        "component_id": "ac2ead7b-d3c2-401c-9c7e-5b769de9262e",
        "start_date": "2015-01-01",
        "end_date": "2020-01-01",
        "weight": 50
      },
      {
        "component_id": "bfa4621e-233f-4075-b7cc-d7946f38e484",
        "start_date": "2015-01-01",
        "end_date": "2020-01-01",
        "weight": 50
      }
    ],
    "asset_class": "Intl Equities"
}

Create a new security for your firm. The create_date will default to the current date. The endpoint returns the security_id used to manage the security and referenced in orders, portfolios, transactions etc. Note that the metadata information, the country information, and the security composition information are stored as nested objects within the security object.

HTTP REQUEST

POST /security

ARGUMENTS

Parameter Type Required Description
name string required Name for the security
ticker string required Security’s ticker on the exchange where it is traded
asset_class string optional The asset class for the security such as “equity”, “fixed-income”, “cash”, etc.
sector string optional Sector for the security such as “Technology” or “Pharmaceuticals”
industry string optional The industry of the security such as “Consumer Tech” or “Enterprise Systems”
security_class string optional The security class of the security such as “stock”, “mutual fund”, “ETF” (exchange-traded fund), etc.
exchange string optional The exchange on which the security is traded
is_active boolean optional Indicates if the security is active. Defaults to true which indicates that the it is active
security_composition array optional Details on the components of a security, their relative weight within the security, and their start and end dates
      component_id UUID required The id of the underlying security that is part of the broader security
      start_date date required Date for when the underlying security started being a part of the broader security
      end_date date required Date for when the underlying security no longer was a part of the broader security
      weight double required 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
security_country array optional Each country where the security is traded and its relative weight within the security
      country string required Country where the security is traded represented using their ISO ALPHA-2 Code. See Country Code reference table
      weight double required The weight of the country as a percentage of the security; ex. 20 representing 20%. The weights of all the countries must add up to 100
metadata map optional Custom information associated with the security 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 security

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/nucleus/v1/security/b690fc43-9cdd-4547-b8cd-afadf6b58b2a"

Example Response

{
    "id": "b690fc43-9cdd-4547-b8cd-afadf6b58b2a",
    "create_date": "2018-01-01T21:56:03.000+0000",
    "update_date": "2018-01-15T21:56:03.000+0000",
    "industry": "",
    "is_active": true,
    "name": "Vanguard FTSE All-World ex-US ETF",
    "sector": "",
    "security_class": "ETF",
    "ticker": "VEU",
    "metadata": {},
    "security_country": [
        {
          "weight": 50,
          "country": "DE"
        },
        {
          "weight": 15,
          "country": "JP"
        },
        {
          "weight": 21,
          "country": "AX"
        },
        {
          "weight": 5,
          "country": "CN"
        },
        {
          "weight": 5,
          "country": "TU"
        },
        {
          "weight": 4,
          "country": "EU"
        }
    ],
    "security_composition": [
        {
          "component_id": "ac2ead7b-d3c2-401c-9c7e-5b769de9262e",
          "start_date": "2015-01-01",
          "end_date": "2020-01-01",
          "weight": 50
        },{
          "component_id": "bfa4621e-233f-4075-b7cc-d7946f38e484",
          "start_date": "2015-01-01",
          "end_date": "2020-01-01",
          "weight": 50
        }
    ],
    "asset_class": "Intl Equities"
}

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

HTTP REQUEST

GET /security/{security_id}

Update a security

Example Request

curl -X PUT -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    -H "Content-Type: application/json" \
    -d '{
            "industry": "",
            "is_active": true,
            "name": "Vanguard FTSE All-World ex-US ETF",
            "sector": "",
            "security_class": "ETF",
            "ticker": "VEU",
            "metadata": {},
            "security_country": [
                {
                  "weight": 50,
                  "country": "DE"
                },
                {
                  "weight": 15,
                  "country": "JP"
                },
                {
                  "weight": 21,
                  "country": "AX"
                },
                {
                  "weight": 5,
                  "country": "CN"
                },
                {
                  "weight": 5,
                  "country": "TU"
                },
                {
                  "weight": 4,
                  "country": "EU"
                }
            ],
            "security_composition": [
                {
                  "component_id": "ac2ead7b-d3c2-401c-9c7e-5b769de9262e",
                  "start_date": "2015-01-01",
                  "end_date": "2020-01-01",
                  "weight": 50
                },
                {
                  "component_id": "bfa4621e-233f-4075-b7cc-d7946f38e484",
                  "start_date": "2015-01-01",
                  "end_date": "2020-01-01",
                  "weight": 50
                }
            ],
            "asset_class": "Intl Equities"
          }' "https://api.hydrogenplatform.com/nucleus/v1/security/b690fc43-9cdd-4547-b8cd-afadf6b58b2a"

Example Response

{
    "id": "b690fc43-9cdd-4547-b8cd-afadf6b58b2a",
    "create_date": "2018-01-01T21:56:03.000+0000",
    "update_date": "2018-01-15T21:56:03.000+0000",
    "industry": "",
    "is_active": true,
    "name": "Vanguard FTSE All-World ex-US ETF",
    "sector": "",
    "security_class": "ETF",
    "ticker": "VEU",
    "metadata": {},
    "security_country": [
        {
          "weight": 50,
          "country": "DE"
        },
        {
          "weight": 15,
          "country": "JP"
        },
        {
          "weight": 21,
          "country": "AX"
        },
        {
          "weight": 5,
          "country": "CN"
        },
        {
          "weight": 5,
          "country": "TU"
        },
        {
          "weight": 4,
          "country": "EU"
        }
    ],
    "security_composition": [
        {
            "component_id": "ac2ead7b-d3c2-401c-9c7e-5b769de9262e",
            "start_date": "2015-01-01",
            "end_date": "2020-01-01",
            "weight": 50
        },
        {
            "component_id": "bfa4621e-233f-4075-b7cc-d7946f38e484",
            "start_date": "2015-01-01",
            "end_date": "2020-01-01",
            "weight": 50
        }
    ],
    "asset_class": "Intl Equities"
}

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

HTTP REQUEST

PUT /security/{security_id}

Delete a security

Example Request

curl -X DELETE -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/nucleus/v1/security/b690fc43-9cdd-4547-b8cd-afadf6b58b2a"

Response (204 No Content)

Permanently delete a security for your firm. The security_id must be provided. To obtain the appropriate security_id, use the GET /security endpoint to view all securities defined for your firm. Deletes the security_id and the details for the security record. If you wish to have the security no longer be available without permanently deleting it entirely, then use the PUT /security endpoint to update the is_active field to false.

HTTP REQUEST

DELETE /security/{security_id}

Security Prices

Security prices represent stored market prices for specific securities. These can be used to provide a historical view of a security’s pricing and understand its performance. Security prices are required to use the Performance endpoints.

Parameter Type Description
id UUID The id of the security price
security_id UUID The id of the security
price double Value for the price of the security
adjusted_price double Value for the adjusted price of the security
date datetime Date and for when the particular price was applicable for this security
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 security prices

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/nucleus/v1/security_price"

Example Response

{
    "content": [
        {
            "id": "00036fb7-c47e-44a2-9b55-0fd40e779887",
            "create_date": "2018-01-01T21:56:03.000+0000",
            "update_date": "2018-01-15T21:56:03.000+0000",
            "adjusted_price": 0,
            "date": "2017-10-26T00:00:00.000+0000",
            "price": 60.55,
            "security_id": "7da36f64-928a-40c7-b663-7fcee7738979"
        },
        {
            "id": "0004b2c6-6909-4630-80fa-df45ccb2d3a1",
            "create_date": "2018-01-01T21:56:03.000+0000",
            "update_date": "2018-01-15T21:56:03.000+0000",
            "adjusted_price": 0,
            "date": "2017-10-09T00:00:00.000+0000",
            "price": 77.55,
            "security_id": "c925fdff-aafe-4e14-809f-c03a7717f265"
        },
        {
            "id": "000bca42-8461-4248-a5ff-a5d1f5716e27",
            "create_date": "2018-01-01T21:56:03.000+0000",
            "update_date": "2018-01-15T21:56:03.000+0000",
            "adjusted_price": 0,
            "date": "2017-10-04T00:00:00.000+0000",
            "price": 48.54,
            "security_id": "1f87f39b-e6c0-473f-ade0-dc6ba659920a"
        }
    ],
    "last": false,
    "total_pages": 1,
    "total_elements": 3,
    "sort": [
        {
            "direction": "ASC",
            "property": "updateDate",
            "ignore_case": false,
            "null_handling": "NATIVE",
            "descending": false,
            "ascending": true
        }
    ],
    "first": true,
    "number_of_elements": 3,
    "size": 25,
    "number": 0
}

Get prices for all securities defined for your firm. You can filter using a security_id to obtain the prices for a specific security. You can also choose to get the latest prices for a security or each security.

HTTP REQUEST

GET /security_price

Create a security price

Example Request

curl -X POST -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    -H "Content-Type: application/json" \
    -d '{
            "adjusted_price": 0,
            "date": "2017-10-26T00:00:00.000+0000",
            "price": 60.55,
            "security_id": "7da36f64-928a-40c7-b663-7fcee7738979"
        }' "https://api.hydrogenplatform.com/nucleus/v1/security_price"

Example Response

{
  "id": "00036fb7-c47e-44a2-9b55-0fd40e779887",
  "create_date": "2018-01-01T21:56:03.000+0000",
  "adjusted_price": 0,
  "date": "2017-10-26T00:00:00.000+0000",
  "price": 60.55,
  "security_id": "7da36f64-928a-40c7-b663-7fcee7738979"
}

Create a new price for a security defined for your firm. The unique security_id must be provided. To obtain the appropriate security_id, use the GET /security endpoint to view all securities defined for your firm. The create_date will default to the current date. The endpoint returns the security_price_id used to manage the security price and to map the price to the unique security_id provided.

HTTP REQUEST

POST /security_price

ARGUMENTS

Parameter Type Required Description
security_id UUID required The id of the security
price double required Value for the price of the security
date datetime required Date and for when the particular price was applicable for this security
adjusted_price double optional Value for the adjusted price of the security
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Retrieve a security price

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/nucleus/v1/security_price/00036fb7-c47e-44a2-9b55-0fd40e779887"

Example Response

{
  "id": "00036fb7-c47e-44a2-9b55-0fd40e779887",
  "create_date": "2018-01-01T21:56:03.000+0000",
  "update_date": "2018-01-15T21:56:03.000+0000",
  "adjusted_price": 0,
  "date": "2017-10-26T00:00:00.000+0000",
  "price": 60.55,
  "security_id": "7da36f64-928a-40c7-b663-7fcee7738979"
}

Retrieve the information for a security price for a security. The security_price_id must be provided. To obtain the appropriate security_price_id, use the GET /security_price to view all security prices defined for your firm. The endpoint returns the security_price_id and the details for the security price specified.

HTTP REQUEST

GET /security_price/{security_price_id}

Update a security price

Example Request

curl -X PUT -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    -H "Content-Type: application/json" \
    -d '{
            "adjusted_price": 0,
            "date": "2017-10-26T00:00:00.000+0000",
            "price": 60.55,
            "security_id": "7da36f64-928a-40c7-b663-7fcee7738979"
        }' "https://api.hydrogenplatform.com/nucleus/v1/security_price/00036fb7-c47e-44a2-9b55-0fd40e779887"

Example Response

{
    "id": "00036fb7-c47e-44a2-9b55-0fd40e779887",
    "create_date": "2018-01-01T21:56:03.000+0000",
    "update_date": "2018-01-15T21:56:03.000+0000",
    "adjusted_price": 0,
    "date": "2017-10-26T00:00:00.000+0000",
    "price": 60.55,
    "security_id": "7da36f64-928a-40c7-b663-7fcee7738979"
}

Update a security price for a security. The security_price_id must be provided. To obtain the appropriate security_price_id, use the GET /security_price to view all security prices defined for your firm and their current information. The details to be updated must also be provided. The endpoint returns the security_price_id and all the details for the security price.

HTTP REQUEST

PUT /security_price/{security_price_id}

Delete a security price

Example Request

curl -X DELETE -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/nucleus/v1/security_price/00036fb7-c47e-44a2-9b55-0fd40e779887"

Response (204 No Content)

Permanently delete a security price from a security. The security_price_id must be provided. To obtain the appropriate security_price_id, use the GET /security_price to view all security prices defined for your firm. Permanently deletes the security_price_id and the price information from the security.

HTTP REQUEST

DELETE /security_price/{security_price_id}

Security Exclusions

Security exclusions represent account or portfolio level preferences to not trade a certain security. For example, when rebalancing an account or portfolio, the security orders generated are checked against the security exclusions before the new order record is created to ensure the order does not include any security exclusions. If it does, then the order record is not generated.

Field Type Description
id UUID The id of the security exclusion
client_id UUID The id of the client to which the security exclusion applies
security_id UUID The id of the security that is subject to the exclusion
is_restrict_buy boolean Indicates if the exclusion applies to buy transactions
is_restrict_sell boolean Indicates if the exclusion applies to sell transactions
account_id UUID The id of the account to which the security exclusion applies (if account-specific)
portfolio_id UUID The id of the portfolio to which the security exclusion applies (if portfolio-specific)
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

List all security exclusions

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
      "https://api.hydrogenplatform.com/nucleus/v1/security_exclusion"

Example Response

{
    "content": [
        {
            "id": "9f8d05ec-e42c-4112-be35-af6dc5054bd4",
            "create_date": "2018-01-01T21:56:03.000+0000",
            "update_date": "2018-01-15T21:56:03.000+0000",
            "client_id": "199a8c08-cdd5-4c8c-8abf-535447cea11b",
            "security_id": "00036fb7-c47e-44a2-9b55-0fd40e779887",
            "account_id": "199a8c08-cdd5-4c8c-8abf-535447cea11b",
            "is_restrict_buy": true,
            "is_restrict_sell": false
        },
        {
            "id": "03722da4-9d79-4cd5-8411-6a15ced457c2",
            "create_date": "2018-01-01T21:56:03.000+0000",
            "update_date": "2018-01-15T21:56:03.000+0000",
            "is_restrict_buy": true,
            "is_restrict_sell": false,
            "client_id": "199a8c08-cdd5-4c8c-8abf-535447cea11b",
            "security_id": "00036fb7-c47e-44a2-9b55-0fd40e779887"
        }
    ],
    "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 security exclusions defined for your firm. There’s the option to filter using a security_id to view the exclusions on a specific security. There’s also the option to filter using a client_id, account_id, or portfolio_id to view the exclusions for a specific account or portfolio.

HTTP REQUEST

GET /security_exclusion

Create a security exclusion

Example Request

curl -X POST -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    -H "Content-Type: application/json" \
    -d '{
            "client_id": "199a8c08-cdd5-4c8c-8abf-535447cea11b",
            "security_id": "00036fb7-c47e-44a2-9b55-0fd40e779887",
            "account_id": "199a8c08-cdd5-4c8c-8abf-535447cea11b",
            "is_restrict_buy": true,
            "is_restrict_sell": false
        }' "https://api.hydrogenplatform.com/nucleus/v1/security_exclusion"

Example Response

{
    "id": "9f8d05ec-e42c-4112-be35-af6dc5054bd4",
    "create_date": "2018-01-01T21:56:03.000+0000",
    "client_id": "199a8c08-cdd5-4c8c-8abf-535447cea11b",
    "security_id": "00036fb7-c47e-44a2-9b55-0fd40e779887",
    "account_id": "199a8c08-cdd5-4c8c-8abf-535447cea11b",
    "is_restrict_buy": true,
    "is_restrict_sell": false
}

Create a new security exclusion for a specific account or portfolio. The security_id of the security to be excluded and a client_id and account_id to which the security exclusion applies must be provided. To obtain the appropriate security_id use the GET /security endpoint to view all securities defined for your firm. 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 the accounts defined for your firm. If the exclusion applies to a specific portfolio, then provide a unique portfolio_id for the client portfolio in question. To obtain the appropriate portfolio_id use the GET /portfolio endpoint to view all the portfolios defined for your firm. The create_date will default to the current date. The endpoint returns a security_exclusion_id that can be used to manage the security exclusion.

HTTP REQUEST

POST /security_exclusion

ARGUMENTS

Parameter Type Required Description
client_id UUID required The id of the client to which the security exclusion applies
security_id UUID required The id of the security that is subject to the exclusion
is_restrict_buy boolean required Indicates if the exclusion applies to buy transactions
is_restrict_sell boolean required Indicates if the exclusion applies to sell transactions
account_id UUID optional The id of the account to which the security exclusion applies (if account-specific)
portfolio_id UUID optional The id of the portfolio to which the security exclusion applies (if portfolio-specific)
secondary_id string optional Alternate id that can be used to identify the object such as an internal id

Retrieve a security exclusion

Example Request

curl -X GET -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
      "https://api.hydrogenplatform.com/nucleus/v1/security_exclusion/9f8d05ec-e42c-4112-be35-af6dc5054bd4"

Example Response

{
    "id": "9f8d05ec-e42c-4112-be35-af6dc5054bd4",
    "create_date": "2018-01-01T21:56:03.000+0000",
    "update_date": "2018-01-15T21:56:03.000+0000",
    "client_id": "199a8c08-cdd5-4c8c-8abf-535447cea11b",
    "security_id": "00036fb7-c47e-44a2-9b55-0fd40e779887",
    "account_id": "199a8c08-cdd5-4c8c-8abf-535447cea11b",
    "is_restrict_buy": true,
    "is_restrict_sell": false
}

Retrieve the information for a security exclusion. The security_exclusion_id must be provided. The endpoint returns the details for the security exclusion specified.

HTTP REQUEST

GET /security_exclusion/{security_exclusion_id}

Update a security exclusion

Example Request

curl -X PUT -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    -H "Content-Type: application/json" \
    -d '{
            "client_id": "199a8c08-cdd5-4c8c-8abf-535447cea11b",
            "security_id": "00036fb7-c47e-44a2-9b55-0fd40e779887",
            "account_id": "199a8c08-cdd5-4c8c-8abf-535447cea11b",
            "is_restrict_buy": true,
            "is_restrict_sell": false
        }' "https://api.hydrogenplatform.com/nucleus/v1/security_exclusion/9f8d05ec-e42c-4112-be35-af6dc5054bd4"

Example Response

{
    "id": "9f8d05ec-e42c-4112-be35-af6dc5054bd4",
    "create_date": "2018-01-01T21:56:03.000+0000",
    "update_date": "2018-01-15T21:56:03.000+0000",
    "client_id": "199a8c08-cdd5-4c8c-8abf-535447cea11b",
    "security_id": "00036fb7-c47e-44a2-9b55-0fd40e779887",
    "account_id": "199a8c08-cdd5-4c8c-8abf-535447cea11b",
    "is_restrict_buy": true,
    "is_restrict_sell": false
}

Update the information for a security exclusion. The security_exclusion_id must be provided. To obtain the appropriate security_exclusion_id, use the GET /security_exclusion endpoint to view all security exclusions defined firm-wide and their current information. The details to be updated must also be provided. The endpoint returns the security_exclusion_id and all of the details for the security exclusion.

HTTP REQUEST

PUT /security_exclusion/{security_exclusion_id}

Delete a security exclusion

Example Request

curl -X DELETE -H "Authorization: Bearer e7cf805b-4307-41e9-8b58-90b6359fa900" \
    "https://api.hydrogenplatform.com/nucleus/v1/security_exclusion/9f8d05ec-e42c-4112-be35-af6dc5054bd4"

Response (204 No Content)

Permanently delete a security exclusion. The security_exclusion_id must be provided. To obtain the appropriate security_exclusion_id, use the GET /security_exclusion endpoint to view all security exclusions defined firm-wide. The endpoint deletes the security_exclusion_id and the security exclusion record.

HTTP REQUEST

DELETE /security_exclusion/{security_exclusion_id}

Workflows

Workflows are a set of API operations that when combined allow you to accomplish a specific business case. We have included many of the most common workflows below for your reference.

Onboarding

Create a Client & Account

  1. Create all Account Types for your firm using POST /account_type. Returns an account_type_id for each.
  2. Create a Client using POST /client. Returns a client_id.
  3. Create an Account using POST /account. Returns an account_id
      3a. Assign the Client to the Account by providing the client_id from step 2 in the clients field.
      3b. Assign a role for the Client on the Account using client_account_association_type in the clients field.
      3c. Specify the Account Type of the Account using an account_type_id from step 1.

Create an Investment Model

  1. Create Securities using POST /security. Returns a security_id for each Security.
  2. Create one or more Model(s) using POST /model for each. Returns a model_id for each Model.
  3. Assign Securities to each Model using POST /model_holding. Returns a model_holding_id for each Security assigned.

Create an Investment Allocation

  1. Follow the “Create an Investment Model” workflow above.
  2. Create one or more Allocation(s) using POST /allocation. Returns an allocation_id for each Allocation.
  3. Assign one more more Model(s) to each Allocation using POST /allocation_composition. Specify the allocation_id and model_id from steps 1 and 2 as well as the date. Returns an allocation_composition_id for each Allocation-Model relationship.

Create a Questionnaire & Decision Tree

  1. Create a Questionnaire with embedded Questions and Answers using POST /questionnaire. Returns a questionnaire_id, a question_id for each Question and an answer_id for each Answer.
      1a. Option to define weights for each Question and Answer in the case that the Questionnaire is used to calculate a score.
  2. Create a Decision Tree using POST /decision_tree. Returns a decision_tree_id.
  3. Update the Questionnaire from step 1 with the decision_tree_id from step 2 using PUT /questionnaire/{questionnaire_id}.
  4. Create Nodes for each Question and Answer combination from the Questionnaire using POST /node. Returns a node_id for each Node.
      4a. Link a Node to a Question by providing the question_id from step 1.
      4b. Indicate if a Node is the first Node in a Decision Tree branch by marking is_first as true.
  5. Create Node Relationships to link the Nodes from step 4 using POST /node_relationship. Returns a node_relationship_id for each Node Relationship.
      5a. Link a Node Relationship to the Decision Tree by providing the decision_tree_id from step 2.
      5b. Specify one node_id from step 4 as the parent_node_id and one node_id from step 4 as the child_node_id.
      5c. Link a Node Relationship to an Answer by providing the answer_id from step 1.
      5d. Indicate if this Node Relationship points to the end of a Decision Tree branch by marking is_leaf as true.

Determining a Client’s Risk Profile

  1. Follow the “Create a Client & Account” workflow above.
  2. Follow the “Create a Questionnaire & Decision Tree” workflow above.
  3. Store each of the client’s responses using POST /client_response. Returns a client_response_id for each client response.
      3a. Provide the client_id from step 1. Also provide the account_id if the client’s response only applies to one Account.
      3b. Provide the answer_id from step 2.
      3c. Provide the value of the client’s response.
  4. Multiply the weights of the Question and Answers stored in the Questionnaire from step 2 based on the client’s responses from step 3 to calculate their risk score.

Create a Goal

  1. Follow the “Create a Questionnaire & Decision Tree” workflow above.
  2. Create a Goal using POST /goal. Returns a goal_id.
  3. Link the Goal to a Questionnaire by providing the questionnaire_id from step 1.

Create an Investment Portfolio

  1. Follow the “Create a Client & Account” workflow above.
  2. Follow the “Create an Investment Allocation” workflow above.
  3. Determine the appropriate Allocation for the Account using a Decision Tree from the “Create a Questionnaire & Decision Tree” workflow above.
  4. Use the “Subscribe an Account” service to create an investment portfolio

Account Funding

  1. Follow the “Create a Client & Account” workflow above.
  2. Create a Bank Link using POST /bank_link. Provide the account_id from step 1. Returns a bank_link_id.
  3. Option to verify the Bank Link externally. Once verified, mark the is_link_verified field a true and provide a link_verified_date using the PUT /bank_link/{bank_link_id} endpoint.

Fund an Account from a Bank Account

  1. Follow the “Create a Bank Link” workflow above.
  2. Create a Funding request using POST /funding. Returns a funding_id.
      2a. Provide the account_id and the bank_link_id from step 1.
      2b. Specify the amount.
      2c. If the Funding request is recurring, specify the frequency and the frequency_unit as well as the start_date.
      2d. Indicate that the Funding request is a deposit by marking the is_deposit field as true.
  3. Create a Deposit using POST /deposit. Returns a deposit_id
      3a. Provide the funding_id from step 2.
      3b. Provide the amount from the funding_id.
      3c. Provide the invested_date, or the date that the funds should start being pulled from the funding request to be invested.
  4. Update the funding_status using PUT /funding/{funding_id} as the request is processed.
       4a. If a Funding request is recurring, update the status of the individual deposit using PUT /deposit/{deposit_id}. Provide values for the status and status_time_stamp fields.
  5. Mark the funding request as complete using PUT /funding/{funding_id}. Specify the funding_status as request_complete.
      5a. In the case of a one-time funding request, this occurs when the funds are received.
      5b. In the case of a recurring funding request, this occurs when the end_date is reached.
  6. Follow the “Handling Cash & Legacy Holdings” workflow below.

Transfer an External Account

  1. Follow the “Create a Client & Account” workflow above.
  2. Create a Transfer request using POST /transfer. Returns a transfer_id. Provide the account_id from step 1.
  3. Create a one-time Funding request using POST /funding. Provide the transfer_id and account_id from step 1. Returns a funding_id.
  4. Update the funding_status using PUT /funding/{funding_id} as the request is processes. Option to also update the transfer’s status using PUT /transfer/{transfer_id}.
  5. Mark the funding request as complete using PUT /funding/{funding_id}. Specify the funding_status as request_complete.
  6. Follow the “Handling Cash & Legacy Holdings” workflow below.

Investing

Invest a Client Account

  1. Follow the “Create an Investment Portfolio” workflow above.
  2. Sync the Account to its Allocation using the POST /account/{account_id}/order_rebalance. Provide the account_id from step 1.
  3. Follow the “Generating Orders” workflow below.

Create a Security Exclusion

  1. Follow the “Create a Client & Account” workflow above.
  2. Follow the “Create a Portfolio” workflow above.
  3. Create Securities using POST /security. Returns a security_id for each Security.
  4. Create a Security Exclusion using POST /security_exclusion. Returns a security_exclusion_id.
      3a. Provide the client_id from step 1.
      3b. If the Security Exclusion applies to a Client’s specific Account, also provide the account_id from step 1.
      3c. If the Security Exclusion applies to a Client’s specific Portfolio below an Account, also provide the portfolio_id from step 2.
      3d. Provide the security_id from step 3.

Handling Cash & Legacy Holdings

  1. Follow the “Create an Investment Portfolio” workflow above to create a Cash Portfolio and a Legacy Portfolio for an Account.
      1a. The Allocation for the Account from step 1 should contain a Cash Model and a Legacy Model (See the “Create an Investment Allocation” workflow).
  2. Follow the “Fund an Account from a Bank Account” workflow or the “Transfer an External Account” workflow.
  3. Populate the Cash in the Cash Portfolio and/or Legacy Securities in the Legacy Portfolio using POST /portfolio_holding. Provide the appropriate portfolio_id from step 1. Returns a portfolio_holding_id.
  4. Update the Portfolio Asset Sizes for the Cash Portfolio and/or Legacy Portfolio using POST /portfolio_asset_size. Provide the appropriate portfolio_id from step 1. Returns a portfolio_asset_size_id.

Generating Orders

  1. Follow the “Create a Security Exclusion” workflow above.
  2. Follow the “Create an Investment Portfolio” workflow above.
  3. Create Order Statuses using POST /order_status for each step along the Order Management process. Returns an order_status_id for each step.
  4. Confirm that a Client or that the Client’s Account does not have any Security Exclusions for a Security using GET /security_exclusion.
      4a. Filter for the appropriate client_id or account_id.
  5. Create an Order using POST /order. Returns an order_id. Provide the portfolio_id from step 2
  6. Create an Order Track record using POST /order_track. Returns an order_track_id. Provide the order_status_id from step 3.
  7. Update the Order Track record using PUT /order_track/{order_track_id}. Provide the order_status_id from step 3.
  8. Once the Order has been completed, create a Portfolio Transaction using POST /portfolio_transaction. Provide the portfolio_id from step 2. Returns a portfolio_transaction_id.

Tracking

Track an Investment Portfolio & Model Holdings & Asset Sizes

  1. Follow the “Create an Investment Model” workflow above.
  2. Follow the “Create an Investment Portfolio” workflow above.
  3. Create a Security Price for each Security from step 1 using POST /security_price. Returns a security_price_id for each Security Price.
  4. Create Model Holdings and Portfolio Holdings using POST /model_holding and POST /portfolio_holding. Returns a model_holding_id and a portfolio_holding_id.
      4a. Provide the model_id and portfolio_id from steps 1 and 2.
      4b. Provide the security_id from step 1.
      4c. Calculate the Portfolio Holdings by netting out the Portfolio Transactions.
      4d. Update the Model Holdings and Portfolio Holdings nightly using POST /model_holding and POST /portfolio_holding to maintain a historical, date-based record of Holdings.
  5. Create Model Asset Sizes and Portfolio Asset Sizes using POST /model_asset_size and POST /portfolio_asset_size. Returns a model_asset_size_id and a portfolio_asset_size_id.
      5a. Provide the model_id and portfolio_id from steps 1 and 2.
      5b. Calculate the Model Asset Size using the Security Prices from step 3 and the weights of the Securities in the Model Holdings from step 4.
      5c. Calculate the Portfolio Asset Size using the Security Prices from step 3 and the shares of the Securities in the Portfolio Holdings from step 4.
      5d. Update the Model Asset Size and Portfolio Asset Size nightly using POST /model_asset_size and POST /portfolio_asset_size to maintain a historical, date-based record of Asset Sizes.

Resources

Countries

The following table includes the ISO Alpha-2 country codes that can be passed into endpoints that require a country

Country Code Country Name Latitude Longitude
AD Andorra 42.546245 1.601554
AE United Arab Emirates 23.424076 53.847818
AF Afghanistan 33.93911 67.709953
AG Antigua and Barbuda 17.060816 -61.796428
AI Anguilla 18.220554 -63.068615
AL Albania 41.153332 20.168331
AM Armenia 40.069099 45.038189
AN Netherlands Antilles 12.226079 -69.060087
AO Angola -11.202692 17.873887
AQ Antarctica -75.250973 -0.071389
AR Argentina -38.416097 -63.616672
AS American Samoa -14.270972 -170.132217
AT Austria 47.516231 14.550072
AU Australia -25.274398 133.775136
AW Aruba 12.52111 -69.968338
AZ Azerbaijan 40.143105 47.576927
BA Bosnia and Herzegovina 43.915886 17.679076
BB Barbados 13.193887 -59.543198
BD Bangladesh 23.684994 90.356331
BE Belgium 50.503887 4.469936
BF Burkina Faso 12.238333 -1.561593
BG Bulgaria 42.733883 25.48583
BH Bahrain 25.930414 50.637772
BI Burundi -3.373056 29.918886
BJ Benin 9.30769 2.315834
BM Bermuda 32.321384 -64.75737
BN Brunei 4.535277 114.727669
BO Bolivia -16.290154 -63.588653
BR Brazil -14.235004 -51.92528
BS Bahamas 25.03428 -77.39628
BT Bhutan 27.514162 90.433601
BV Bouvet Island -54.423199 3.413194
BW Botswana -22.328474 24.684866
BY Belarus 53.709807 27.953389
BZ Belize 17.189877 -88.49765
CA Canada 56.130366 -106.346771
CC Cocos Islands -12.164165 96.870956
CD Democratic Republic of the Congo -4.038333 21.758664
CF Central African Republic 6.611111 20.939444
CG The Republic of the Congo -0.228021 15.827659
CH Switzerland 46.818188 8.227512
CI Ivory Coast 7.539989 -5.54708
CK Cook Islands -21.236736 -159.777671
CL Chile -35.675147 -71.542969
CM Cameroon 7.369722 12.354722
CN China 35.86166 104.195397
CO Colombia 4.570868 -74.297333
CR Costa Rica 9.748917 -83.753428
CU Cuba 21.521757 -77.781167
CV Cape Verde 16.002082 -24.013197
CX Christmas Island -10.447525 105.690449
CY Cyprus 35.126413 33.429859
CZ Czech Republic 49.817492 15.472962
DE Germany 51.165691 10.451526
DJ Djibouti 11.825138 42.590275
DK Denmark 56.26392 9.501785
DM Dominica 15.414999 -61.370976
DO Dominican Republic 18.735693 -70.162651
DZ Algeria 28.033886 1.659626
EC Ecuador -1.831239 -78.183406
EE Estonia 58.595272 25.013607
EG Egypt 26.820553 30.802498
EH Western Sahara 24.215527 -12.885834
ER Eritrea 15.179384 39.782334
ES Spain 40.463667 -3.74922
ET Ethiopia 9.145 40.489673
FI Finland 61.92411 25.748151
FJ Fiji -16.578193 179.414413
FK Falkland Islands -51.796253 -59.523613
FM Micronesia 7.425554 150.550812
FO Faroe Islands 61.892635 -6.911806
FR France 46.227638 2.213749
GA Gabon -0.803689 11.609444
GB United Kingdom 55.378051 -3.435973
GD Grenada 12.262776 -61.604171
GE Georgia 42.315407 43.356892
GF French Guiana 3.933889 -53.125782
GG Guernsey 49.465691 -2.585278
GH Ghana 7.946527 -1.023194
GI Gibraltar 36.137741 -5.345374
GL Greenland 71.706936 -42.604303
GM Gambia 13.443182 -15.310139
GN Guinea 9.945587 -9.696645
GP Guadeloupe 16.995971 -62.067641
GQ Equatorial Guinea 1.650801 10.267895
GR Greece 39.074208 21.824312
GS South Georgia and the South Sandwich Islands -54.429579 -36.587909
GT Guatemala 15.783471 -90.230759
GU Guam 13.444304 144.793731
GW Guinea-Bissau 11.803749 -15.180413
GY Guyana 4.860416 -58.93018
GZ Gaza Strip 31.354676 34.308825
HK Hong Kong 22.396428 114.109497
HM Heard Island and McDonald Islands -53.08181 73.504158
HN Honduras 15.199999 -86.241905
HR Croatia 45.1 15.2
HT Haiti 18.971187 -72.285215
HU Hungary 47.162494 19.503304
ID Indonesia -0.789275 113.921327
IE Ireland 53.41291 -8.24389
IL Israel 31.046051 34.851612
IM Isle of Man 54.236107 -4.548056
IN India 20.593684 78.96288
IO British Indian Ocean Territory -6.343194 71.876519
IQ Iraq 33.223191 43.679291
IR Iran 32.427908 53.688046
IS Iceland 64.963051 -19.020835
IT Italy 41.87194 12.56738
JE Jersey 49.214439 -2.13125
JM Jamaica 18.109581 -77.297508
JO Jordan 30.585164 36.238414
JP Japan 36.204824 138.252924
KE Kenya -0.023559 37.906193
KG Kyrgyzstan 41.20438 74.766098
KH Cambodia 12.565679 104.990963
KI Kiribati -3.370417 -168.734039
KM Comoros -11.875001 43.872219
KN Saint Kitts and Nevis 17.357822 -62.782998
KP North Korea 40.339852 127.510093
KR South Korea 35.907757 127.766922
KW Kuwait 29.31166 47.481766
KY Cayman Islands 19.513469 -80.566956
KZ Kazakhstan 48.019573 66.923684
LA Laos 19.85627 102.495496
LB Lebanon 33.854721 35.862285
LC Saint Lucia 13.909444 -60.978893
LI Liechtenstein 47.166 9.555373
LK Sri Lanka 7.873054 80.771797
LR Liberia 6.428055 -9.429499
LS Lesotho -29.609988 28.233608
LT Lithuania 55.169438 23.881275
LU Luxembourg 49.815273 6.129583
LV Latvia 56.879635 24.603189
LY Libya 26.3351 17.228331
MA Morocco 31.791702 -7.09262
MC Monaco 43.750298 7.412841
MD Moldova 47.411631 28.369885
ME Montenegro 42.708678 19.37439
MG Madagascar -18.766947 46.869107
MH Marshall Islands 7.131474 171.184478
MK Macedonia 41.608635 21.745275
ML Mali 17.570692 -3.996166
MM Myanmar 21.913965 95.956223
MN Mongolia 46.862496 103.846656
MO Macau 22.198745 113.543873
MP Northern Mariana Islands 17.33083 145.38469
MQ Martinique 14.641528 -61.024174
MR Mauritania 21.00789 -10.940835
MS Montserrat 16.742498 -62.187366
MT Malta 35.937496 14.375416
MU Mauritius -20.348404 57.552152
MV Maldives 3.202778 73.22068
MW Malawi -13.254308 34.301525
MX Mexico 23.634501 -102.552784
MY Malaysia 4.210484 101.975766
MZ Mozambique -18.665695 35.529562
NA Namibia -22.95764 18.49041
NC New Caledonia -20.904305 165.618042
NE Niger 17.607789 8.081666
NF Norfolk Island -29.040835 167.954712
NG Nigeria 9.081999 8.675277
NI Nicaragua 12.865416 -85.207229
NL Netherlands 52.132633 5.291266
NO Norway 60.472024 8.468946
NP Nepal 28.394857 84.124008
NR Nauru -0.522778 166.931503
NU Niue -19.054445 -169.867233
NZ New Zealand -40.900557 174.885971
OM Oman 21.512583 55.923255
PA Panama 8.537981 -80.782127
PE Peru -9.189967 -75.015152
PF French Polynesia -17.679742 -149.406843
PG Papua New Guinea -6.314993 143.95555
PH Philippines 12.879721 121.774017
PK Pakistan 30.375321 69.345116
PL Poland 51.919438 19.145136
PM Saint Pierre and Miquelon 46.941936 -56.27111
PN Pitcairn Islands -24.703615 -127.439308
PR Puerto Rico 18.220833 -66.590149
PS Palestinian Territories 31.952162 35.233154
PT Portugal 39.399872 -8.224454
PW Palau 7.51498 134.58252
PY Paraguay -23.442503 -58.443832
QA Qatar 25.354826 51.183884
RE Réunion -21.115141 55.536384
RO Romania 45.943161 24.96676
RS Serbia 44.016521 21.005859
RU Russia 61.52401 105.318756
RW Rwanda -1.940278 29.873888
SA Saudi Arabia 23.885942 45.079162
SB Solomon Islands -9.64571 160.156194
SC Seychelles -4.679574 55.491977
SD Sudan 12.862807 30.217636
SE Sweden 60.128161 18.643501
SG Singapore 1.352083 103.819836
SH Saint Helena -24.143474 -10.030696
SI Slovenia 46.151241 14.995463
SJ Svalbard and Jan Mayen 77.553604 23.670272
SK Slovakia 48.669026 19.699024
SL Sierra Leone 8.460555 -11.779889
SM San Marino 43.94236 12.457777
SN Senegal 14.497401 -14.452362
SO Somalia 5.152149 46.199616
SR Suriname 3.919305 -56.027783
ST São Tomé and Príncipe 0.18636 6.613081
SV El Salvador 13.794185 -88.89653
SY Syria 34.802075 38.996815
SZ Swaziland -26.522503 31.465866
TC Turks and Caicos Islands 21.694025 -71.797928
TD Chad 15.454166 18.732207
TF French Southern Territories -49.280366 69.348557
TG Togo 8.619543 0.824782
TH Thailand 15.870032 100.992541
TJ Tajikistan 38.861034 71.276093
TK Tokelau -8.967363 -171.855881
TL Timor-Leste -8.874217 125.727539
TM Turkmenistan 38.969719 59.556278
TN Tunisia 33.886917 9.537499
TO Tonga -21.178986 -175.198242
TR Turkey 38.963745 35.243322
TT Trinidad and Tobago 10.691803 -61.222503
TV Tuvalu -7.109535 177.64933
TW Taiwan 23.69781 120.960515
TZ Tanzania -6.369028 34.888822
UA Ukraine 48.379433 31.16558
UG Uganda 1.373333 32.290275
UM U.S. Minor Outlying Islands
US United States 37.09024 -95.712891
UY Uruguay -32.522779 -55.765835
UZ Uzbekistan 41.377491 64.585262
VA Vatican City 41.902916 12.453389
VC Saint Vincent and the Grenadines 12.984305 -61.287228
VE Venezuela 6.42375 -66.58973
VG British Virgin Islands 18.420695 -64.639968
VI U.S. Virgin Islands 18.335765 -64.896335
VN Vietnam 14.058324 108.277199
VU Vanuatu -15.376706 166.959158
WF Wallis and Futuna -13.768752 -177.156097
WS Samoa -13.759029 -172.104629
XK Kosovo 42.602636 20.902977
YE Yemen 15.552727 48.516388
YT Mayotte -12.8275 45.166244
ZA South Africa -30.559482 22.937506
ZM Zambia -13.133897 27.849332
ZW Zimbabwe -19.015438 29.154857

Currencies

The following table includes the ISO 4217 currency codes that can be passed into endpoints that require a currency_code

Alphabetic Code Currency Name Numeric Code
AED UAE Dirham 784
AFN Afghani 971
ALL Albanian Lek 008
AMD Armenian Dram 051
ANG Netherlands Antillean Guilder 532
AOA Angolan Kwanza 973
ARS Argentine Peso 032
AUD Australian Dollar 036
AWG Aruban Florin 533
AZN Azerbaijan Manat 944
BAM Convertible Mark 977
BBD Barbados Dollar 052
BDT Bangladeshi Taka 050
BGN Bulgarian Lev 975
BHD Bahraini Dinar 048
BIF Burundi Franc 108
BMD Bermudian Dollar 060
BND Brunei Dollar 096
BOB Bolivian Boliviano 068
BOV Bolivian Mvdol 984
BRL Brazilian Real 986
BSD Bahamian Dollar 044
BTN Bhutanese Ngultrum 064
BWP Botswanan Pula 072
BYN Belarusian Ruble 933
BZD Belize Dollar 084
CAD Canadian Dollar 124
CDF Congolese Franc 976
CHE WIR Eur 947
CHF Swiss Franc 756
CHW WIR Franc 948
CLF Chilean Unidad de Fomento 990
CLP Chilean Peso 152
CNY Yuan Renminbi 156
COP Colombian Peso 170
COU Colombian Unidad de Valor Real 970
CRC Costa Rican Colon 188
CUC Cuban Peso Convertible 931
CUP Cuban Peso 192
CVE Cabo Verde Escudo 132
CZK Czech Koruna 203
DJF Djibouti Franc 262
DKK Danish Krone 208
DOP Dominican Peso 214
DZD Algerian Dinar 012
EGP Egyptian Pound 818
ERN Eritrean Nakfa 232
ETB Ethiopian Birr 230
EUR Euro 978
FJD Fiji Dollar 242
FKP Falkland Islands Pound 238
GBP Pound Sterling 826
GEL Georgian Lari 981
GHS Ghana Cedi 936
GIP Gibraltar Pound 292
GMD Gambian Dalasi 270
GNF Guinean Franc 324
GTQ Guatemalan Quetzal 320
GYD Guyana Dollar 328
HKD Hong Kong Dollar 344
HNL Honduran Lempir 340
HRK Croatian Kuna 191
HTG Haitian Gourde 332
HUF Hungarian Forint 348
IDR Indonesian Rupiah 360
ILS New Israeli Sheqel 376
INR Indian Rupee 356
IQD Iraqi Dinar 368
IRR Iranian Rial 364
ISK Iceland Krona 352
JMD Jamaican Dollar 388
JOD Jordanian Dinar 400
JPY Japanese Yen 392
KES Kenyan Shilling 404
KGS Kyrgyzstani Som 417
KHR Cambodian Riel 116
KMF Comorian Franc 174
KPW North Korean Won 408
KRW Korean Won 410
KWD Kuwaiti Dinar 414
KYD Cayman Islands Dollar 136
KZT Kazakhstani Tenge 398
LAK Lao Kip 418
LBP Lebanese Pound 422
LKR Sri Lanka Rupee 144
LRD Liberian Dollar 430
LSL Lesotho Loti 426
LYD Libyan Dinar 434
MAD Moroccan Dirham 504
MDL Moldovan Leu 498
MGA Malagasy Ariary 969
MKD Macedonian Denar 807
MMK Myanmar Kyat 104
MNT Mongolian Tugrik 496
MOP Macanese Pataca 446
MRU Mauritanian Ouguiya 929
MUR Mauritius Rupee 480
MVR Maldivian Rufiyaa 462
MWK Malawi Kwacha 454
MXN Mexican Peso 484
MXV Mexican Unidad de Inversion (UDI) 979
MYR Malaysian Ringgit 458
MZN Mozambique Metical 943
NAD Namibia Dollar 516
NGN Nigerian Naira 566
NIO Nicaraguan Cordoba Oro 558
NOK Norwegian Krone 578
NPR Nepalese Rupee 524
NZD New Zealand Dollar 554
OMR Omani Rial 512
PAB Panamanian Balboa 590
PEN Peruvian Sol 604
PGK Papua New Guinean Kina 598
PHP Philippine Peso 608
PKR Pakistan Rupee 586
PLN Polish Zloty 985
PYG Paraguayan Guarani 600
QAR Qatari Rial 634
RON Romanian Leu 946
RSD Serbian Dinar 941
RUB Russian Ruble 643
RWF Rwanda Franc 646
SAR Saudi Riyal 682
SBD Solomon Islands Dollar 090
SCR Seychelles Rupee 690
SDG Sudanese Pound 938
SEK Swedish Krona 752
SGD Singapore Dollar 702
SHP Saint Helena Pound 654
SLL Sierra Leonean Leone 694
SOS Somali Shilling 706
SRD Surinam Dollar 968
SSP South Sudanese Pound 728
STN Sao Tomean Dobra 930
SVC El Salvador Colon 222
SYP Syrian Pound 760
SZL Lilangeni 748
THB Thai Baht 764
TJS Tajikistani Somoni 972
TMT Turkmenistan New Manat 934
TND Tunisian Dinar 788
TOP Tongan Pa’anga 776
TRY Turkish Lira 949
TTD Trinidad and Tobago Dollar 780
TWD New Taiwan Dollar 901
TZS Tanzanian Shilling 834
UAH Ukrainian Hryvnia 980
UGX Uganda Shilling 800
USD US Dollar 840
UYI Uruguay Peso en Unidades Indexadas (UI) 940
UYU Uruguay Peso Uruguayo 858
UYW Uruguay Unidad Previsional 927
UZS Uzbekistan Sum 860
VES Venezuelan Bolívar Soberano 928
VND Vietnamese Dong 704
VUV Vanuatu Vatu 548
WST Samoan Tala 882
XAF CFA Franc BEAC 950
XAG Silver 961
XAU Gold 959
XCD East Caribbean Dollar 951
XOF CFA Franc BCEAO 952
XPD Palladium 964
XPF CFP Franc 953
XPT Platinum 962
XSU Sucre 994
XUA ADB Unit of Account 965
YER Yemeni Rial 886
ZAR South African Rand 710
ZMW Zambian Kwacha 967
ZWL Zimbabwe Dollar 932

Statistics

The following tables include all of the parameters that can be passed into the performance endpoints as a stat

PERFORMANCE

Parameter Name Type Description
cum_return Cumulative Return point-in-time Total percentage growth since inception
ann_return Annualized Return point-in-time Compounded percentage growth over a 1-year period
daily_return Daily Return time-series Price at time ‘t’ compared with the price at EOD ‘t-1’
mtd_return Month-to-Date Return time-series Price at time ‘t’ compared with the price at EOD on the last day of the previous month
ytd_return Year-to-Date Return time-series Price at time ‘t’ compared with the price at EOD on the last day of the previous year
rolling_n_day_return Rolling n-Day Return time-series Price at time ‘t’ compared with the price at EOD ‘t-n’
calendar_monthly_return Calendar Monthly Return time-series Price at EOD on the last day of the month compared against the price at end-of-day EOD on the last day of the previous month
calendar_quarterly_return Calendar Quarterly Return time-series Price at EOD on the last day of the quarter compared against the price at EOD on the last day of the previous quarter
calendar_yearly_return Calendar Yearly Return time-series Price at EOD December 31 of this year compared against the price at EOD December 31 the previous year
one_yr_return One Year Return time-series Price at time ‘t’ compared with the price at EOD same day, 1 year ago
three_yr_return Three Year Return time-series Price at time ‘t’ compared with the price at EOD same day, 3 years ago
five_yr_return Five Year Return time-series Price at time ‘t’ compared with the price at EOD same day, 5 years ago
seven_yr_return Seven Year Return time-series Price at time ‘t’ compared with the price at EOD same day, 7 years ago
ten_yr_return Ten Year Return time-series Price at time ‘t’ compared with the price at EOD same day, 10 years ago
best_month Best Month Return point-in-time Highest 1-month return
worst_month Worst Month Return point-in-time Lowest 1-month return
best_yr Best Year Return point-in-time Highest 1-year return
worst_yr Worst year Return point-in-time Lowest 1-year return
best_qtr Best Quarter Return point-in-time Highest 3-month return
worst_qtr Worst Quarter Return point-in-time Lowest 3-month return
avg_return Average Return point-in-time Average performance during a specified time period
avg_gain Average Gain point-in-time Average positive return during a specified time period
avg_loss Average Loss point-in-time Average negative return during a specified time period
alpha Alpha point-in-time Excess return relative to benchmark
active_premium Active Premium point-in-time Annualized return excess of benchmark annualized return
tracking_error Tracking Error point-in-time Difference between the price of a position and the price of the benchmark it was meant to track
moving_avg_n_day Moving Average n-Day time-series Average price over n-days
dollar_growth Growth of $1 time-series Growth in value of $1 invested in security or portfolio

RISK

Parameter Name Type Description
ann_vol Annualized Volatility/Standard Deviation point-in-time Variance of returns from the mean for a year
daily_vol Daily Volatility/Standard Deviation time-series Variance of returns from the mean every day
rolling_n_day_vol Rolling n-Day Volatility/Standard Deviation time-series Variance of returns from the mean for n-days
downside_deviation Downside Deviation point-in-time Downside risk exceeding a minimum threshold
semi_deviation Semi Deviation point-in-time Standard deviation of returns lower than mean return
beta Beta point-in-time Volatility of returns relative to market as a whole
correlation Correlation point-in-time Strength of relationship between two securities
covariance Covariance point-in-time Direction of relationship between two securities
r_squared R-squared point-in-time Percentage of returns attributable to a benchmark
drawdown Drawdown time-series Percentage peak-to-trough decline during specified time period
max_drawdown Maximum Drawdown point-in-time Maximum percentage peak-to-trough decline during specified time period
rolling_n_day_max_drawdown Rolling n-Day Maximum Drawdown time-series Percentage peak-to-trough decline for n-days during specified time period
upside_risk Upside Risk point-in-time Volatility of returns during winning periods
downside_risk Downside Risk point-in-time Volatility of returns during losing periods
current_drawdown Current Drawdown point-in-time Current peak-to-trough decline since inception
var VAR (Value at Risk) point-in-time Maximum possible loss during a specific time frame based on a confidence interval

RATIOS

Parameter Name Type Description
sharpe_ratio Sharpe Ratio point-in-time Risk-adjusted return (using standard deviation)
treynor_ratio Treynor Ratio point-in-time Risk-adjusted return (using beta)
sortino_ratio Sortino Ratio point-in-time Downside risk-adjusted return
up_capture Up Capture point-in-time Percentage of positive market returns captured
down_capture Down Capture point-in-time Percentage of negative market returns captured
information_ratio Information Ratio point-in-time Risk-adjusted return (using tracking error)
calmar_ratio Calmar Ratio point-in-time Risk-adjusted return for the previous 3 years (using drawdowns)
pct_gain_ratio Percentage Gain Ratio point-in-time Periods in which security return exceeded positive benchmark returns
pct_loss_ratio Percentage Loss Ratio point-in-time Periods in which security return exceeded negative benchmark returns
gain_loss_ratio Gain Loss Ratio point-in-time Number of instances positive returns exceeded negative returns
profit_loss_ratio Profit Loss Ratio point-in-time Average gains compared to average losses
up_pct_ratio Up Percentage Ratio point-in-time Ratio of periods return exceeded positive benchmark returns to periods of positive benchmark return
down_pct_ratio Down Percentage Ratio point-in-time Ratio of periods return exceeded negative benchmark returns to periods of negative benchmark return
up_capture Up Capture point-in-time Percentage of positive market returns captured
down_capture Down Capture point-in-time Percentage of negative market returns captured
sterling_ratio Sterling Ratio point-in-time Risk-adjusted return for the previous 3 years (assuming max drawdowns will be exceeded)

DISTRIBUTIONS

Parameter Name Type Description
skewness Skewness time-series Asymmetry of return distribution
kurtosis Kurtosis time-series Distribution of returns around the mean
monte_carlo Monte Carlo time-series Probability of a portfolio achieving a certain outcome
histogram Histogram time-series Distribution of data over a continuous interval or certain time period
tstat T-Statistic time-series Departure of estimated value from its hypothesized value