Release: Nucleus Version 1.2

We are excited to announce the release of version 1.2 of the Nucleus API, as part of Hydrogen’s Atom offering. Check the details below to find out what’s new!

This release focuses on making schema changes in Nucleus and Electron and creating new entities in order to support a variety of upcoming third-party integrations and improvements to simplify front-end development.

The existing entities affected in Nucleus include:

• Client
• Bank Link
• Questionnaire
• Withdrawal

And in Electron the existing entities affected include:

• Document
• FAQ

The new entities created in Nucleus are:

• Aggregation Account
• Aggregation Account Balance
• Score
• Client-Hydro
• Goals Track

CLIENT ENTITY CHANGES

The following fields have been added to the Client entity to reduce reliance on metadata to store key client details as well as support future integrations with Know-Your-Customer (KYC) third-party vendors and the Hydrogen Hydro product:

• title — optional — The title of the client such as “Mr.”, “Ms.”, “Miss”, “Mx.”, etc.
• middle_name — optional — The middle name of the client (“first_name” and “last_name” are existing field options)
• date_of_birth — optional — The date of birth of the client in the ISO 8601 format YYYY-MM-DD
• identification_number — optional — National or local identification number for a client such as Social Security Number
• country_of_residence — optional — The country of residence of a client, often corresponding to the country issuing the identification number mentioned above. Should be the country’s ISO ALPHA-2 Code
• is_verified — Defaults to false — Indicator for whether or not the identifying details provided by the client have been verified by a KYC vendor
• hydro_id — optional — The Hydro ID associated with the client (if applicable). Corresponds to the new Client_Hydro table

BANK LINK ENTITY CHANGES

The following fields have been added to the Bank Link entity to support future integrations with Instant Account Verification third-party providers:

• currency_code — optional — Currency code for the base currency of the bank account linked, limited to 3 characters
• routing_wire — optional — The routing number used for wire transfers for the bank account linked
• available_balance — optional — Available balance in the account, usually taking into consideration pending transactions or available overdraft
• metadata — optional — Custom information associated with the bank link in the format key:value

QUESTIONNAIRE ENTITY CHANGES

New fields have been added to the Questionnaire entity, and the embedded Questions and Answers, to facilitate front-end development. Fields added include:

Fields added to Questions

• category — optional — A category for the question such as “Onboarding” or “Risk Profile”
• subcategory — optional — A subcategory for the question
• title — optional — A title for the question such as the body of the question or a header. Pairs with the “description” field currently available
• question_type — optional — The type of question structure such as “multiple_choice” or “free_form”
• order_index — optional — The order of the question within the questionnaire or category such as “1”, “2”, “3”
• document — optional — A reference link to a document related to the question
• image — optional — A reference link to an image associated with the question

Fields added to Answers

• order_index — optional — The order of the answer option within the question such as “1”, “2”, “3”
• image — optional — The reference link to an image associated with the question
• label — optional — A label to be assigned to the answer option for data labeling purposes

WITHDRAWAL ENTITY CHANGES

The following field has been added to the Withdrawal entity to align the structure with the Deposit entity:

• status_time_stamp — optional — Date and time that the “status” field of the record was last updated

DOCUMENT ENTITY CHANGES

The following field has been added to the Document entity to support future integrations with e-Signature third-party providers:

• metadata — optional — Custom information associated with the document in the format key:value

FAQ ENTITY CHANGES

The following field has been added to the FAQ entity to facilitate front-end development of a user interface where certain frequently asked questions are displayed prominently:

• is_featured — Defaults to false — Indicates whether or not this is a featured FAQ, `false` indicating it is not featured.

NEW ENTITY: AGGREGATION ACCOUNT

Two new entities, an Aggregation Account entity and an Aggregation Account Balance entity, have been created to store information and balances for held-away accounts. 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.

AGGREGATION ACCOUNT

This entity contains the details of an individual held-away account such as a checking account, a savings account, a credit card account, an external investment account, etc.

New Services

• GET /aggregation_account
• POST /aggregation_account
• GET /aggregation_account/{aggregation_account_id}
• PUT /aggregation_account/{aggregation_account_id}
• DELETE /aggregation_account/{aggregation_account_id}

New Entity Fields

• aggregation_account_id — required — The unique identifier of the aggregation account record
• client_id — required — The unique identifier of the client to whom the aggregation account record belongs
• account_name — required — The name of the held-away account for this aggregation account record
• institution_name — required — The name of the institution holding the held-away account for this aggregation account record
• category — required — Category for the held-away account such as “Bank Account”
• subcategory — optional — Subcategory for the held-away account such as “Checking Account”
• account_number — optional — The account number of the held-away account for this aggregation account record
• mask — optional — Masked version of the “account_number”
• currency_code — optional — Currency code for the base currency of the held-away account, limited to 3 characters.
• is_active — Defaults to true — Indicator for whether or not the aggregation account record is active; true indicates it is active
• metadata — optional — Custom information associated with the aggregation account in the format key:value

AGGREGATION ACCOUNT BALANCE

This entity is intended to store the balance of the held-away account, either once or to store the balance over time.

New Services

• GET /aggregation_account_balance
• POST/aggregation_account_balance
• GET /aggregation_account_balance/{aggregation_account_balance_id}
• PUT /aggregation_account_balance/{aggregation_account_balance_id}
• DELETE /aggregation_account_balance/{aggregation_account_balance_id}

New Entity Fields

• aggregation_account_balance_id — required — The unique identifier for the aggregation account balance record
• aggregation_account_id — required — The unique identifier for the aggregation account to which the record belongs
• currency_code — required — Currency code of the balance record, limited to 3 characters
• balance — required — Balance in the account, usually as of last night’s close and not taking into account intraday pending transactions
• available_balance — optional — Available balance in the account, usually taking into account pending transactions or available overdraft
• balance_time_stamp — required — Date & time for the balance record, Defaults to current date & time
• is_active — Defaults to true — Indicator for whether or not this balance record is a valid balance record (i.e. to facilitate business insights)

NEW ENTITY: SCORE

A new Score entity has been created to store scores referenced within the application, supporting storage of either scores calculated using the Proton API tool or obtained from an alternate source. Scores can be stored for key entities including client, account, goal, portfolio, model, allocation, benchmark and security. Score types supported include:

• Risk Score
• Dimensional Risk Score
• Diversification Score
• Portfolio Optimization Score
• Goal Achievement Score
• Credit Score

New Services

• GET /score
• POST /score
• GET /score/{score_id}
• PUT /score/{score_id}
• DELETE /score/{score_id}

New Entity Fields

• score_id — required — The unique identifier for the score record
• score_type — required — The type of score. Values may be “risk_score”, “dimensional_risk_score”, “diversification_score”, “portfolio_optimization_score”, “goal_achievement_score”, “credit_score”
• score_value — required — The value of the score, which may be a number, a label, etc.
• client_id — optional — The unique identifier for the client to which the score applies
• account_id — optional — The unique identifier for the account to which the score applies
• goal_id — optional — The unique identifier for the goal to which the score applies
• allocation_id — optional — The unique identifier for the allocation to which the score applies
• model_id — optional — The unique identifier for the model to which the score applies
• security_id — optional — The unique identifier for the security to which the score applies
• score_time_stamp — optional — The date for the score in the ISO 8601 format YYYY-MM-DDThh:mm:ssTZD
• metadata — optional — Custom information associated with the score in the format key:value

NEW ENTITY: GOAL TRACK

A new Goal Track entity has been created to store the current status of a goal at a point in time and track over time. The status information stored includes the set 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. These metrics can be obtained using the Proton API.

New Services

• GET /goal_track
• POST /goal_track
• GET /goal_track/{goal_track_id}
• PUT /goal_track/{goal_track_id}
• DELETE /goal_track/{goal_track_id}

New Entity Fields

• goal_track_id — required — The unique identifier for the goal track record
• goal_id — required — The unique identifier for the goal to whom the record applies
• client_id — optional — The unique identifier for the client to whom the record applies
• goal_amount — optional — Target amount for the goal at this point in time
• accumulation_horizon — optional — The time horizon of the goal during the accumulation phase, in years, at this point in time
• decumulation_horizon — optional — The time horizon of the goal during the decumulation phase, in years, at this point in time
• accounts.account_id — optional — The list of unique identifier of the account(s) linked to the goal
• current_investment — optional — The current amount invested toward the goal at this point in time
• on_track — optional — Indicator for whether or not the goal is on track at this point in time, true indicating it is on track
• progress — optional — The goal progress percentage, in decimal format
• goal_probability — optional — The probability of achieving the goal with the client’s given investments at this point in time
• goal_achievement_score — optional — Probability of achieving the goal in relation to the confidence target of a simulation at this point in time
• projection_balance — optional — The projected balance of the goal at this point in time
• projection_date — optional — The date of the projection balance
• status_time_stamp — optional — Date and time to which this record applies, defaults to the current date & time
• metadata — optional — Custom information associated with the goal track record entity in the format key:value

NEW ENTITY: CLIENT-HYDRO RELATIONSHIP

A new Client-Hydro entity has been created to link the id of a Client in the platform to their Hydro ID as well as attributes relating to integrations with Hydro capabilities.

New Services

• GET /client_hydro
• POST /client_hydro
• GET /client_hydro/{client_hydro_id}
• PUT /client_hydro/{client_hydro_id}
• DELETE /client_hydro/{client_hydro_id}

New Entity Fields

• client_hydro_id — required — The unique identifier for the client-hydro relationship record
• hydro_id — required — The hydro ID for the client. Also found under the Client entity
• client_id — required — The unique identifier for the client
• is_hydro_id_verified — Defaults to false — Indicator if the client has verified ownership of the Hydro ID provided
• is_client_raindrop_linked — Defaults to false — Indicator for whether or not the client has successfully linked their Hydro ID to your Client-side Raindrop application
• is_client_raindrop_enabled — Defaults to false — Indicator for whether or not the client has chosen to enable the Hydro Client-side Raindrop service on your application
• metadata — optional — Custom information associated with the client-hydro entity in the format key:value