API Documentation
Session API

56min
Session API enables investment firms to access data of investment advice sessions and order execution sessions. Data collected by the advisor through DeepAlpha and suggested saving plan/order, can be integrated into existing systems. Such integration streamlines dataflow securely, increase efficiency and reduces friction for advisors. 

Key use cases enabled by Session API
Extract information about suggested saving plan and automatically update your portfolio system to prepare orders for execution 

Extract advice information and store it in your data warehouse for further data analysis

Session object returned by session get call
This JSON file represents a record of an information collected throughout a session in Deep Alpha. It might include information about the investor, advice information, purpose and risk, knowledge and experience, financial situation, sustainability preferences, and details about the suggest investment plan. 
Data Structure
The JSON file consists of several objects with various properties:
adviceInformation
An array of objects that contains information about questions from the advice information page in Deep Alpha. This will be empty if the page is not in use.
fieldName
The name of the field related to the advice information.
value
The value associated with the field.
advisorNote 
The advisors note in regard to collecting advice information. PLACEHOLDER
advisor
An object that contains information about advisor that has given this advice
email
a string that contains advisors email address
id
a string that defines a unique identifier for an advisor
name
a string that defines an advisors name
advisorNotes
A string that contains any notes or comments made by the advisor during the meeting. This field defines what was the reasoning for advice.
channel
A string that contains the channel through which the advisory meeting was conducted.
Possible values:
Tenants office
Phone
Online
Other
completedAt
A string that contains the date and time when the advisory meeting was completed, or null if it has not yet been completed.
createdAt
A string that contains the date and time when the advisory meeting was created.
customKnowledgeAndExperienceFields
An array of objects that contain information about custom fields that were set up by the tenant for Knowledge and Experience page
fieldName
a name of the custom field
value
a value submitted to custom field during a session
executed
A boolean value that indicates whether or not the investment advice has been executed. This field is patched by tenants to indicate that this advice session has been finished and resulted in purchase of instrument shares. 
More about patching﻿﻿
financialSituation

An object that contains information about client's financial situation. It is highly configurable and defines   asset  / sub asset classes and/or debt and its classes.
Below there are examples of asset class - cash and debt class - mortgage
Moreover this section might include custom fields. Those fields should be in this indentation of a payload and be a key / value pair.
cash
An object that contains information about the client's cash assets.
defaultValue
The default value for the client's cash assets.
details
An array of objects that contain details about the client's cash assets, including their ID, title, value, and whether they are to be advised on.
id
A unique identifier for the cash details item
title
A string that defines what is that cash position name
toAdvisory
A number that defines how much of the cash will be used for advisory
value
A number that defines how much cash is in a given position
toAdvisory
The total value of the client's cash assets to be advised on.
mortgage
An object that contains information about the client's mortgage.
defaultValue
The default value for the client's mortgage.
toAdvisory
The total value of the client's mortgage to be advised on.
advisorNote
A string that contains any notes or comments made by the advisor during the meeting. This field defines financial situation page note. PLACEHOLDER
goals
An array of objects that contain information about the client's investment goals, including the amount they want to invest and the time horizon for their investment.
advisedPortfolio
An array that contains information about the advised portfolio related to the goal.
mainAssetClass
A string that represents the main asset class of the advised portfolio.
subAssetClass
A string that represents the sub-asset class of the advised portfolio.
weight
A string that represents the weight of the advised portfolio.
instruments
An array that contains information about the instruments in the advised portfolio.
id
A string that represents a unique identifier for the instrument.
title
A string that represents the title of the instrument.
weight
A string that represents the weight of the instrument.
suitabilityAssessment
An object that contains information about the suitability assessment for the instrument.
productIsSuitable
A boolean value that indicates whether the product is suitable.
details
An array that contains details of the suitability assessment.
checkId
A number that represents the identifier for the suitability check.
checkKey
A string that represents the key for the suitability check.
score
A number that represents the score for the suitability check.
threshold
A number that represents the threshold for the suitability check.
assetClassAllocationAdvisorNote
A string that defines what was the advisor note for asset class allocation added by an advisor
capitalNeed
The client's capital need for their investment goals. Only available when tenant is using cashflow.
customPortfolio
A boolean value that indicates whether or not the client has a custom investment portfolio.
description
A string that contains a description of the client's investment goals.
firstDeposit
The amount of the client's first deposit towards their investment goals.
fundAllocationAdvisorNote
A string that defines what was the advisor note for fund allocation added by an advisor
id
A unique identifier for the client's investment goals.
isPortfolioCustom
A boolean value that indicates whether or not the client's investment portfolio is custom.
monthlyDeposit
The amount of the client's monthly deposit towards their investment goals.
name
A string that contains the name of the client's investment goals.
portfolio
A string that contains the ID of the client's investment portfolio.
productPlatform
An object that contains information about the client's investment product platform.
namespaceId
The namespace ID for the client's investment product platform.
productPlatformReasoning
A string that contains the reasoning behind the client's investment product platform.
questions
An object that contains questions related to the client's investment product platform.
riskScore
a string that defines risk level assigned to an investor
themes
A string that contains the themes associated with the client's investment goals.
timeHorizon
The time horizon for the client's investment goals.
type
A string that defines type of a goal
withdrawalPlan
An integer that defines how this goal should be withdrawn
id
A string that contains a unique identifier for the investment advisory meeting.
investorData
An object that contains information about the investor, including their name, contact details, and KYC (know your customer) information.
address
The investor's address.
advisorId
A string that contains a unique identifier for the advisor providing the investment advice.
advisorName
The name of the advisor providing the investment advice.
city
The investor's city.
country
The investor's country.
customFields
Custom fields related to the investor.
email
The investor's email address.
externalId
A unique identifier for the investor.
id
A string that contains a unique identifier for the investor.
kyc
An object that contains KYC (know your customer) information for the investor.
advisoryTypeExperience
An array of strings that contains the investor's advisory type experience.
clientClassification
A string that contains the client classification for the investor.
moneyOrigin
An array of strings that contains the investor's source of money.
pep
A boolean value that indicates whether or not the investor is a politically exposed person.
sanctions
A boolean value that indicates whether or not the investor is subject to sanctions.
name
The name of the investor.
organizationNumber
company unique identifier
phone
The investor's phone number.
ssn
The investor's social security number.
type
A string that contains the type of investor.
zipCode
The investor's zip code.
knowledgeAndExperienceAdvisorNotes
a string that contains notes written by an advisor within knowledge and experience page
proposalAdvisorNotes
a string that contains notes written by an advisor within proposal page
purposeAndRisk
An object that contains information about the client's investment purpose and risk, including their expectation of risk, experience, and risk strategy.
advisorNotes
Notes added by advisor when filling purpose and risk section
dropInPercent
The client's expectation of the drop in percent of their investment.
dropInStd
The client's expectation of the drop in standard deviation of their investment.
educationWork
The client's education and work experience related to investing.
expectationOfRisk
The client's expectation of the level of risk for their investment.
experience
The client's investing experience.
riskStrategy
The client's risk strategy for their investment.
suitability
This object contains information about investors choices regarding suitability. Inside there can be up to five objects, each object will have same keys - names of the categories that tenant checks suitability for. Values for those keys are answers of the investor - how comfortable he is with a given topic within that category.
Example:
JSON
"suitability": {
      "custom1": {
        "Aif": 4,
        "Equity": 3,
        "Fixedincome": 3,
        "Fundandetfs": 1,
        "Realestate": 4,
        "Unitlink": 2
      },
}
"suitability": {
      "custom1": {
        "Aif": 4,
        "Equity": 3,
        "Fixedincome": 3,
        "Fundandetfs": 1,
        "Realestate": 4,
        "Unitlink": 2
      },
}
﻿
signed
A boolean value that indicates whether or not the investment advice has been signed by the client. This field is patched by tenants to indicate that this advice session has been finished and order has been signed by him. 
More about patching﻿﻿
status
A string that contains the current status of the investment advisory meeting.
sustainability
An object that contains information about the client's sustainability preferences.
alignmentCriteria
An object that contains the client's alignment criteria preferences.
alignmentCriteria1
The client's preference for alignment criteria 1.
alignmentCriteria2
The client's preference for alignment criteria 2.
preferenceCriteria
An array of strings that contain the client's preference criteria.
advisorNote
﻿A string that contains any notes or comments made by the advisor during the meeting. This field defines sustainability section note. PLACEHOLDER
type
A string that contains the type of investment advice provided.
updatedAt
A string that contains the date and time when the investment advisory meeting was last updated.
Sessions GET
This endpoint is used to retrieve sessions generated within a tenant.  When calling this endpoint it is possible to filter sessions. Detailed payload field definitions are listed above 
Success
Returns session object supplied with number of sessions returned, number of the page, page numbers, how many items per page and whether there are previous or next available pages. More about object here Session API﻿﻿
Errors
Here are the reasons why call results in error.
401 code:
JSON
{
  "message": "Something went wrong: Signature expired. Please log in again. Signature has expired."
}
{
  "message": "Something went wrong: Signature expired. Please log in again. Signature has expired."
}
﻿
 Authorization token is incorrect. Generate new token
Session GET
This endpoint is used to retrieve one session based on advice id. Additionally it allows to enable / disable  investor data and investor goals. Detailed payload field definitions are listed above.
Success
Returns session object. More about object here Session API﻿﻿
Errors
Here are the reasons why call results in error.
401 code:
JSON
{
  "message": "Something went wrong: Signature expired. Please log in again. Signature has expired."
}
{
  "message": "Something went wrong: Signature expired. Please log in again. Signature has expired."
}
﻿
 Authorization token is incorrect. Generate new token
404 code:
JSON
{
  "detail": {},
  "message": "Advice was not found"
}
{
  "detail": {},
  "message": "Advice was not found"
}
﻿
It means that advice_id is incorrect.
Session PATCH
﻿This endpoint is used to patch one session based on advice id. It allows to patch session values executed and signed. Detailed payload field definitions are listed above.﻿
Patch payload example
JSON
{
  "executed": true,
  "signed": "waiting"//"waiting";"signed";"declined"
}
{
  "executed": true,
  "signed": "waiting"//"waiting";"signed";"declined"
}
﻿
Success
Returns session object. More about object here Session API﻿﻿
Errors
Here are the reasons why call results in error.
401 code:
JSON
{
  "message": "Something went wrong: Signature expired. Please log in again. Signature has expired."
}
{
  "message": "Something went wrong: Signature expired. Please log in again. Signature has expired."
}
﻿
 Authorization token is incorrect. Generate new token
Disclaimers
Session API do not return deleted sessions.
Updated 24 May 2023
Did this page help you?
Webhooks
Method Documentation