NAV

Introduction

Welcome to the StratiFi API!

With our API you can manage your portfolios in StratiFi and get information on various risks and scores.

This page describe the available API endpoints. You will find some code examples in the dark area to the right. Also, if you are familiar with Postman, you can consult and import this collection and play with the API.

Before start using the API you need contact us at support@stratifi.com and request API access. We will provide you a CLIENT ID an a SECRET KEY required to complete the authorization process.

If you want to know more about how the information is organized in StratiFi or want to familiarize with the API structure go to the About section. If you are ready to start, go to the Authorization section.

Overview

Our API follows a REST pattern, where HTTP methods define the action to perform and the endpoint URL determines the object(s) scope.

HTTP method Usage
GET List objects or Retrieve a particular object if the ID is provided in the URL.
POST Create object.
PUT Update entire object.
PATCH Update only the provided attributes.
DELETE Delete object.

The result of the operations is well described by standard HTTP response codes.

HTTP response code Description
20x Success
30x Resource moved
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The resource requested is hidden for administrators only.
404 Not Found -- The specified resource could not be found.
405 Method Not Allowed -- You tried to access a uri with an invalid method.
429 Too Many Requests -- You're making too many requests. Please allow some time for our server to serve your previous requests.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

The StratiFi API uses the following error codes:

Domain

We offer a sandbox where you can test safely: https://sandbox.stratifi.com

Once you are ready, you will get access to the production domain https://backend.stratifi.com

About StratiFi

You can think about data in StratiFi as a hierarchical structure where a companies are at the higher level and accounts at the bottom level.

Company ⟶ Advisor ⟶ Household * ⟶ Investor ⟶ Account

Each object is linked to another in the upper level, for instance, an account has an investor_id attribute that contains the ID of the investor that owns that account.

(*) Households are optional. An investor can be linked directly to the advisor.

Search & Filtering

You can search and filter objects returned by an endpoint using URL parameters.

For searching, you need to include the search parameter in the URL. e.g. /api/v1/households/?search=Smith

For filtering, you need to include the desired attribute in the URL parameters. Each section describes the allowed Filtering Fields for that endpoint. For instance, if you want to list the accounts of the investor with ID 31 you can use /api/v1/accounts/?investor=31

Authorization

We use the OAuth 2.0 protocol with PKCE, an industry standard for authorization management.

Make sure you have the CLIENT ID an a SECRET KEY provided by our support team. If you don't have them contact us at support@stratifi.com.

Authorization Code Flow + PCKE

Following the steps below you will get an access token that can be used to access StratiFi on behalf of the advisor.

PCKE

import base64
import hashlib
import random
import string

# generate the code verifier
code_verifier = "".join(
    random.choice(string.ascii_uppercase + string.digits)
    for _ in range(random.randint(43, 128))
)
code_verifier = base64.urlsafe_b64encode(code_verifier.encode("utf-8"))

# generate the code challenge
code_challenge = hashlib.sha256(code_verifier).digest()
code_challenge = (
    base64.urlsafe_b64encode(code_challenge).decode("utf-8").replace("=", "")
)

  1. Generate an authentication code grant with PKCE (Proof Key for Code Exchange).

    • Generate a random strng between 43 and 128 characters, encode it in base64 and save it as code_verifier.
    • Hash the code_verifier with SHA-256, encode it in base64 and save it as code_challenge.

  2. Redirect the advisor to the StratiFi authorization page:

    https://{{ domain }}/o/authorize/?response_type=code&code_challenge={{ code_challenge }}&code_challenge_method=S256&client_id={{ client_id }}&scope={{ scope }}&state={{ state }}

    Parameter Description
    domain StratiFi sandbox or production domain.
    response_type "code"
    state Random string generated by your application. It will be returned along with the code in the response.
    code_challenge Random string between 43 and 128 characters encoded with SHA-256. We use it to validate the token request.
    code_challenge_method "S256"
    client_id Provided by StratiFi.
    scope Required scopes. You will want to use "read write".

  3. The advisor submits the StratiFi credentials.

    login

  4. The advisor allow your application access the resources in StratiFi.

    grant

  5. We redirect the browser to your return url with a single-usage access code.

    https://{{ callback-url }}code={{ code }}&state={{ state }}

    Parameter Description
    callback-url URL provided by you when during the application setup
    code Single-usage code that can be exchanged by an access token.
    state Random string generated by your application included in the authorization URL.

  6. Your application backend exchange the access code by an access token.


curl -X POST "https://backend.stratifi.com/o/token/" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'client_id={{ client_id }}' \
  --data-urlencode 'client_secret={{ secret_key }}' \
  --data-urlencode 'redirect_uri={{ redirect_url }}' \
  --data-urlencode 'code={{ code }}' \
  --data-urlencode 'code_verifier={{ code_verifier }}'

{
    "access_token": "{{ access_token }}",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "{{ refresh_token }}",
    "scope": "read write",
    "advisor_id": 1,
    "session_token": "{{ session_token }}
}

Request Parameters

Parameter Type
grant_type string Always "authorization_code"
code string The single-usage code received in the callback
code_verifier string The random string generated in the first step
redirect_uri string The callback URL
client_id string Your application client id
client_secret string Your application secret key

Response

Parameter Type
token_type string Always "Bearer"
access_token string An access token valid to consult other endpoints on behalf of the user
expires_in string Expiration time of the access token in seconds
refresh_token string An refresh token valid to renew the access token. It does not expires.
scope string The scopes with granted access for this token
advisor_id int The ID of the advisor associated to this user
session_token string A short-lived token used to start a session in stratifi.com (more details)

6. Include the Authorization header in your requests as follows:

Authorization: Bearer {{ access-token }}

Refresh Token Flow

If your access token expired you can renew it using a valid refresh token.

curl -X POST "https://backend.stratifi.com/o/token/" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode 'client_id={{ client_id }}' \
  --data-urlencode 'client_secret={{ secret_key }}' \
  --data-urlencode 'refresh_token={{ refresh_token }}'

{
    "access_token": "{{ access_token }}",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "{{ refresh_token }}",
    "scope": "read write",
    "advisor_id": 1,
    "session_token": "{{ session_token }}

}

Request Parameters

Parameter Type
grant_type string Always "refresh_token"
refresh_token string Your Refresh Token
client_id string Your application client id
client_secret string Your application secret key

Response

Parameter Type
token_type string Always "Bearer"
access_token string An access token valid to consult other endpoints on behalf of the user
expires_in string Expiration time of the access token in seconds
refresh_token string An refresh token valid to renew the access token
scope string The scopes with granted access for this token
advisor_id int The ID of the advisor associated to this user
session_token string A short-lived token used to start a session in stratifi.com (more details)

Starting a session in stratifi.com

The authorization responses described above contain a session_token property. This token automatically authenticates advisors in stratifi.com, meaning that the advisor won't be required to fill the credentials when visiting Stratifi.

To build an authenticated URL you need 3 parts:

Description URL
Clients list /advisor/investors/
Clients overview /advisor/investors/<id>/
Prospects list /advisor/prospects/
Prospects overview /advisor/prospects/<id>/
Households list /advisor/households/
Households overview /advisor/households/<id>/
Model Portfolios list /advisor/models/
Model Portfolios overview /advisor/models/<id>/

Having these 3 elements, the full URL is: https://{{ base_domain}}{{ path }}?session={{ sesison_token }}

For instance, https://advisors-sandbox.stratifi.com/advisor/investors/1/?session=abc123 will lead the user to the details page of the client with id 1 in the sandbox environment.

Note: The session token has a life of 5 minutes. After that, you will need to follow the refresh token flow to get a new one. If you use an expired token in an URL, the user will be redirected to the signin page in Stratifi.

Retrieving logged user information

You can get basic information about the user related to a token by consulting the /userinfo endpoint. The response includes the advisor ID and the session_token described above.

curl -X GET "https://backend.stratifi.com/api/v1/userinfo/"

{
    "first_name":"John",
    "last_name":"Wick",
    "email":"john.wick@example.com",
    "advisor_id": 1,
    "session_token": "{{ session_token }}
}

Response

Name Type Description
first_name string User first name
last_name string User last name
email string User email address
advisor_id int The ID of the advisor associated to this user
session_token string A short-lived token used to start a session in stratifi.com (more details)

Companies

Company Object Definition

Company Object

{
  "id": 1,
  "name": "Company A, LLC"
}
Name Type Description
id int ID of the company
external_id string Your company identifier
name string Name of the company

List Companies

List Companies

curl "https://backend.stratifi.com/api/v1/companies/" -H "Authorization: Bearer {{ access-token }}"

{
  "count": 10,
  "next": "https://backend.stratifi.com/api/v1/companies/?page=2",
  "previous": null,
  "results": [
    {
        "id": 1,
        "external_id": "co-1",
        "name": "Companny A, LLC"
    },
    …
  ]
}

-request-type: GET

-request-url: /companies/

Response Fields

Name Type Description
count int Total number of companies
next string Link to next page of companies
previous string Link to previous page of companies
results Object List of company objects

Filtering Fields

Name Type Description
external_id string Your company identifier

Get Company

Get Company

curl "https://backend.stratifi.com/api/v1/companies/1/" -H "Authorization: Bearer {{ access-token }}"

{
  "id": 1,
  "external_id": "co-1",
  "name": "Companny A, LLC"
}

-request-type: GET

-request-url: /companies/<id>/

Response: The requested company object.

Create Company

Create Company

curl -X POST "https://backend.stratifi.com/api/v1/companies/" -H "Authorization: Bearer {{ access-token }}" \
  -d '{"name": "Company Z, LLC", "external_id": "co-1",}'

{
  "id": 11,
  "external_id": "co-1",
  "name": "Companny Z, LLC"
}

-request-type: POST

-request-url: /companies/

Request Parameters

Parameter Type
name string Required
external_id string Optional

Response: The new company object.

Update Company

Update Company

curl -X PUT "https://backend.stratifi.com/api/v1/companies/11/"
  -H "Authorization: Bearer {{ access-token }}" \
  -d '{"name": "Company W, LLC", "external_id": "co-1"}'

{
  "id": 11,
  "external_id": "co-1",
  "name": "Companny W, LLC"
}

-request-type: PUT/PATCH

-request-url: /companies/<id>/

Request Parameters

Parameter Type
name string Required
external_id string Optional

Company Prism Aggregation

Company Prism Aggregation

curl "https://backend.stratifi.com/api/v1/companies/11/prism_aggregation/" -H "Authorization: Bearer {{ access-token }}"

{
  "scores": {…},
  "media": {…},
}

-request-type: GET

-request-url: /companies/<id>/prism_aggregation/

Response Fields

Name Type Description
scores Scores Factors Risk score factors
media Scores Images Risk score factors images

Users

User Object Definition

Name Type Description
first_name string User first name
last_name string User last name
email string User email address

User Object

{
 "first_name":"John",
 "last_name":"Wick",
 "email":"john.wick@example.com"
}

Advisors

Advisor Object Definition

Advisor Object

{
  "id": 1,
  "external_id": "adv-1",
  "company": 1,
  "default_investor": 101,
  "phone": "5555555555",
  "title": "Co-founder",
  "user": {
     "first_name":"John",
     "last_name":"Wick",
     "email":"john.wick@example.com"
  }
}
Name Type Description
id int Advisor ID
external_id string Your advisor identifier
company int Company ID
default_investor int ID of the default investor of this advisor *
phone string Advisor Phone
title string Advisor Job Title
user User Object User info

(*) Sometimes the advisor owns accounts that are not attached to an investor or the investor information is not available. In these cases, you can use the advisor default investor to create link accounts to the advisor without an investor.

List Advisors

List Advisors

curl "https://backend.stratifi.com/api/v1/advisors/" -H "Authorization: Bearer {{ access-token }}"

{
  "count": 10,
  "next": "https://backend.stratifi.com/api/v1/advisors/?page=2",
  "previous": null,
  "results": [
    {
      "id": 1,
      "external_id": "adv-1",
      "company": 1,
      "default_investor": 101,
      "phone": "5555555555",
      "title": "Co-founder",
      "user": {
         "first_name":"John",
         "last_name":"Wick",
         "email":"john.wick@example.com"
      }
    },
    …
  ]
}

-request-type: GET

-request-url: /advisors/

Response Fields

Name Type Description
count int Total number of advisors
next string Link to next page of advisors
previous string Link to previous page of advisors
results Object List of advisor objects

Filtering Fields

Name Type Description
company int Company ID
external_id string Your advisor identifier

Get Advisor

Get Advisor

curl "https://backend.stratifi.com/api/v1/advisors/1/" -H "Authorization: Bearer {{ access-token }}"

{
  "id": 1,
  "external_id": "adv-1",
  "company": 1,
  "default_investor": 101,
  "phone": "5555555555",
  "title": "Co-founder",
  "user": {
     "first_name":"John",
     "last_name":"Wick",
     "email":"john.wick@example.com"
  },
}

-request-type: GET

-request-url: /advisors/<id>/

Response: The requested advisor object.

Create Advisor

Create Advisor

curl -X POST "https://backend.stratifi.com/api/v1/advisors/" -H "Authorization: Bearer {{ access-token }}" \
  -d '{
    "external_id": "adv-1",
    "company": 1,
    "phone": "754-3010",
    "title": "CEO",
    "user": {
      "first_name": "Doug",
      "last_name": "Spencer",
      "email": "doug.spencer@example.com"
    }
  }'

{
  "id": 150,
  "external_id": "adv-1",
  "company": 1,
  "default_investor": 102,
  "phone": "754-3010",
  "title": "CEO",
  "user": {
    "first_name": "Doug",
    "last_name": "Spencer",
    "email": "doug.spencer@example.com"
  }
}

-request-type: POST

-request-url: /advisors/

Request Parameters

Parameter Type
user User Object Required
company int Required
phone string Optional
title string Optional
external_id string Optional

Response: The new advisor object.

Update Advisor

Update Advisor

curl -X PUT "https://backend.stratifi.com/api/v1/advisors/150/" -H "Authorization: Bearer {{ access-token }}" \
  -d '{
    "external_id": "adv-1",
    "title": "CEO/Founder",
    "company": 1,
    "phone": "754-3010",
    "user": {
      "first_name": "Doug",
      "last_name": "Spencer",
      "email": "dspencer@example.com"
    }
  }'

{
  "id": 150,
  "external_id": "adv-1",
  "company": 1
  "phone": "754-3010",
  "default_investor": 102,
  "title": "CEO/Founder",
  "user": {
    "first_name": "Doug",
    "last_name": "Spencer",
    "email": "dspencer@example.com"
  }
}

-request-type: PUT/PATCH

-request-url: /advisors/<id>/

Request Parameters

Parameter Type
user User Object Required
company int Required
phone string Optional
title string Optional
external_id string Optional

Advisor Stats

Individual Advisor Stats

curl "https://backend.stratifi.com/api/v1/advisors/11/stats/" -H "Authorization: Bearer {{ access-token }}"

{
    "risk": {
        "scores": {
            "overall": …
        },
        "media": {
            "overall": { … }
        }
    },
    "tolerance": {
        "scores": {
            "overall": …
        },
        "media": {
            "overall": { … }
        }
    },
    "drift": …
}

All Advisors Stats

curl "https://backend.stratifi.com/api/v1/advisors/stats/" -H "Authorization: Bearer {{ access-token }}"

{
  "10": {
      "risk": {
          "scores": {
              "overall": …
          },
          "media": {
              "overall": { … }
          }
      },
      "tolerance": {
          "scores": {
              "overall": …
          },
          "media": {
              "overall": { … }
          }
      },
      "drift": …
  },
  <advisor_id>: { … },
  …
}

-request-type: GET

-request-url: /advisors/stats/

-request-url: /advisors/<id>/stats/

Response Fields

Name Type Description
risk.scores.overall float Advisor risk score overall
risk.media.overall Scores Media Advisor risk score images
tolerance.scores.overall float Advisor tolerance score overall
tolerance.media.overall Scores Media Advisor tolerance score images
drift float Advisor drift score

Households

Household Object Definition

Household Object

{
  "id": 1,
  "external_id": "hou-1",
  "name": "Smith Family",
  "risk": {
    "scores": {
      "overall": 8.1,
      "concentrated": 3.0,
      "correlation": 3.0,
      "tail": 2.0,
      "volatility": 4.0
    }
  },
  "tolerance": {
    "scores": {
      "overall": 3.0,
      "concentrated": 3.0,
      "correlation": 3.0,
      "tail": 2.0,
      "volatility": 4.0
    }
  },
  "drift": 5.1
}
Name Type Description
id int Household ID
external_id string Your household identifier
name string Household Name
advisor int Advisor ID
risk.scores Scores Factors Household aggregated risk scores
risk.media Scores Media Household aggregated risk scores images
tolerance.scores Scores Factors Household aggregated tolerance scores
tolerance.media Scores Media Household aggregated tolerance scores images
drift float Household drift score

List Households

List Households

curl "https://backend.stratifi.com/api/v1/households/" -H "Authorization: Bearer {{ access-token }}"

{
  "count": 10,
  "next": "https://backend.stratifi.com/api/v1/households/?page=2",
  "previous": null,
  "results": [
    {
        "id": 1,
        "external_id": "hou-1",
        "name": "Smith Family"
        "advisor": 1,
        "risk": {…},
        "tolerance": {…},
        "drift": 5.1
    },
    …
  ]
}

-request-type: GET

-request-url: /households/

Response Fields

Name Type Description
count int Total number of households
next string Link to next page of households
previous string Link to previous page of households
results Object List of household objects

Filtering Fields

Name Type Description
advisor int Advisor ID
external_id string Your household identifier

Get Household

Get Household

curl "https://backend.stratifi.com/api/v1/households/1/" -H "Authorization: Bearer {{ access-token }}"

{
  "id": 1,
  "external_id": "hou-1",
  "name": "Smith Family"
  "advisor": 1,
  "risk": {…},
  "tolerance": {…},
  "drift": 5.1
}

-request-type: GET

-request-url: /households/<id>/

Response: The requested household object.

Create Household

Create Household

curl -X POST "https://backend.stratifi.com/api/v1/households/" -H "Authorization: Bearer {{ access-token }}" \
  -d '{
    "external_id": "hou-1",
    "name": "Smith-Pinkett Family",
    "advisor": 2
  }'

{
  "id": 11,
  "external_id": "hou-1",
  "name": "Smith-Pinkett Family",
  "advisor": 2,
  "risk": {…},
  "tolerance": {…},
  "drift": 5.1
}

-request-type: POST

-request-url: /households/

Request Parameters

Parameter Type
name string Required
external_id string Optional

Response: The new household object.

Update Household

Update Household

curl -X PUT "https://backend.stratifi.com/api/v1/households/2/"
  -H "Authorization: Bearer {{ access-token }}" \
  -d '{
    "external_id": "hou-1",
    "name": "Pinkett Family",
    "advisor": 2
  }'

{
  "id": 11,
  "external_id": "hou-1",
  "name": "Pinkett Family",
  "advisor": 2,
  "risk": {…},
  "tolerance": {…},
  "drift": 5.1
}

-request-type: PUT/PATCH

-request-url: /households/<id>/

Request Parameters

Parameter Type
name string Required
external_id string Optional

Household Prism Aggregation

Household Prism Aggregation

curl "https://backend.stratifi.com/api/v1/households/11/prism_aggregation/" -H "Authorization: Bearer {{ access-token }}"

{
  "scores": {…},
  "media": {…},
}

-request-type: GET

-request-url: /households/<id>/prism_aggregation/

Response Fields

Name Type Description
scores Scores Factors Risk score factors
media Scores Images Risk score factors images
status Scores Status Risk score status

Investors

Investor Object Definition

Investor Object

{
  "id": 1,
  "external_id": "inv-1",
  "advisor": 1,
  "household": 1,
  "phone": "5555555555",
  "user": {
     "first_name":"John",
     "last_name":"Wick",
     "email":"john.wick@example.com"
  },
  "risk": {
    "scores": {
      "overall": 8.1,
      "concentrated": 3.0,
      "correlation": 3.0,
      "tail": 2.0,
      "volatility": 4.0
    }
  },
  "tolerance": {
    "scores": {
      "overall": 3.0,
      "concentrated": 3.0,
      "correlation": 3.0,
      "tail": 2.0,
      "volatility": 4.0
    }
  },
  "drift": 5.1
}
Name Type Description
id int Investor ID
external_id string Your investor identifier
advisor int Advisor ID
household int Household ID
is_prospect bool Indicates if the investor is a client or a prospect
phone string Phone of the investor
user User Object User info
risk.scores Scores Factors Investor aggregated risk scores
risk.media Scores Media Investor aggregated risk scores images
tolerance.scores Scores Factors Investor aggregated tolerance scores
tolerance.media Scores Media Investor aggregated tolerance scores images
drift float Investor drift score

List Investors

List Investors

curl "https://backend.stratifi.com/api/v1/investors/" -H "Authorization: Bearer {{ access-token }}"

{
  "count": 10,
  "next": "https://backend.stratifi.com/api/v1/investors/?page=2",
  "previous": null,
  "results": [
    {
      "id": 1,
      "external_id": "inv-1",
      "advisor": 1,
      "household": 1,
      "phone": "5555555555",
      "user": {
         "first_name":"John",
         "last_name":"Wick",
         "email":"john.wick@example.com"
      },
      "risk": {…},
      "tolerance": {…},
      "drift": 5.1
    },
    …
  ]
}

-request-type: GET

-request-url: /investors/

Response Fields

Name Type Description
count int Total number of investors
next string Link to next page of investors
previous string Link to previous page of investors
results Object List of investor objects

Filtering Fields

Name Type Description
advisor int Advisor ID
household int Household ID
external_id string Your investor identifier

Get Investor

Get Investor

curl "https://backend.stratifi.com/api/v1/investors/1/" -H "Authorization: Bearer {{ access-token }}"

{
  "id": 1,
  "external_id": "inv-1",
  "advisor": 1,
  "household": 1,
  "phone": "5555555555",
  "user": {
     "first_name":"John",
     "last_name":"Wick",
     "email":"john.wick@example.com"
  },
  "risk": {…},
  "tolerance": {…},
  "drift": 5.1
}

-request-type: GET

-request-url: /investors/<id>/

Response: The requested investor object.

Create Investor

Create Investor

curl -X POST "https://backend.stratifi.com/api/v1/investors/" -H "Authorization: Bearer {{ access-token }}" \
  -d '{
    "external_id": "inv-1",
    "advisor": 1,
    "household": 1,
    "phone": "754-3010",
    "user": {
      "first_name": "Brian",
      "last_name": "May",
      "email": "brian.may@example.com"
    }
  }'

{
  "id": 150,
  "external_id": "inv-1",
  "advisor": 1,
  "household": 1,
  "phone": "754-3010",
  "user": {
    "first_name": "Brian",
    "last_name": "May",
    "email": "brian.may@example.com"
  },
  "risk": {…},
  "tolerance": {…},
  "drift": 5.1
}

-request-type: POST

-request-url: /investors/

Request Parameters

Parameter Type
user User Object Required
advisor int Required
household int Optional
phone string Optional
external_id string Optional

Response: The new investor object.

Update Investor

Update Investor

curl -X PUT "https://backend.stratifi.com/api/v1/investors/150/" -H "Authorization: Bearer {{ access-token }}" \
  -d '{
    "external_id": "inv-1",
    "advisor": 1,
    "household": 1,
    "phone": "754-3010",
    "user": {
      "first_name": "Brian",
      "last_name": "May",
      "email": "b.may@example.com"
    }
  }'

{
  "id": 150,
  "external_id": "inv-1",
  "advisor": 1
  "phone": "754-3010",
  "user": {
    "first_name": "Brian",
    "last_name": "May",
    "email": "b.may@example.com"
  },
  "risk": {…},
  "tolerance": {…},
  "drift": 5.1
}

-request-type: PUT/PATCH

-request-url: /investors/<id>/

Request Parameters

Parameter Type
user User Object Required
advisor int Required
household int Optional
phone string Optional
external_id string Optional

Investor Prism Aggregation

Investor Prism Aggregation

curl "https://backend.stratifi.com/api/v1/investors/11/prism_aggregation/" -H "Authorization: Bearer {{ access-token }}"

{
  "scores": {…},
  "media": {…},
}

-request-type: GET

-request-url: /investors/<id>/prism_aggregation/

Response Fields

Name Type Description
scores Scores Factors Risk score factors
media Scores Images Risk score factors images
status Scores Status Risk score status

Risk and Tolerance

Risk statuses

Calculating scores for a portfolio might take some time (from a few seconds to a few minutes). In order to make our system more responsive, we calculate the scores in asynchronously. That means that when an account is created or updated, we will be able to provide an immediate answer to the request and, at the same time, queue the score calculation. In the response, we provide a readable status that indicates what is happening in background. The available statuses are:

Name Type Description
pending (Default) string The risk score calculation has not started
processing string The risk score calculation is in progress or the existing score is outdated
error string The last risk score calculation failed
ready string The risk score calculation is completed and is up to date

Scores Factors

Scores Factors

{
    "overall": 8.1,
    "concentrated": 1.0,
    "correlation": 8.0,
    "tail": 9.0,
    "volatility": 8.0
}
Name Type Description
overall float Overall score
concentrated float Concentrated score
correlation float Correlation score
tail float Tail score
volatility float Volatility score

Scores Media

Scores Images

{
    "overall": {
        "large": "https://scores-media.stratifi.com/10/large/81.png",
        "medium": "https://scores-media.stratifi.com/10/medium/81.png",
        "compact": "https://scores-media.stratifi.com/10/compact/81.png"
    },
    "concentrated": {
        "large": "https://scores-media.stratifi.com/10/large/10.png",
        "medium": "https://scores-media.stratifi.com/10/medium/10.png",
        "compact": "https://scores-media.stratifi.com/10/compact/10.png"
    },
    "correlation": {
        "large": "https://scores-media.stratifi.com/10/large/80.png",
        "medium": "https://scores-media.stratifi.com/10/medium/80.png",
        "compact": "https://scores-media.stratifi.com/10/compact/80.png"
    },
    "tail": {
        "large": "https://scores-media.stratifi.com/10/large/90.png",
        "medium": "https://scores-media.stratifi.com/10/medium/90.png",
        "compact": "https://scores-media.stratifi.com/10/compact/90.png"
    },
    "volatility": {
        "large": "https://scores-media.stratifi.com/10/large/80.png",
        "medium": "https://scores-media.stratifi.com/10/medium/80.png",
        "compact": "https://scores-media.stratifi.com/10/compact/80.png"
    }
}
Name Type Description
overall string Overall score image URLs
concentrated string Concentrated score image URLs
correlation string Correlation score image URLs
tail string Tail score image URLs
volatility string Volatility score image URLs

Notice that we provide 3 image versions for each one of the score factors. You can use the version that better adjust to your site layout.

large image

medium image

compact image

Risk Object Definition

Risk Object

{
  "scores": {
      "overall": 8.1,
      "concentrated": 1.0,
      "tail": 9.0,
      "correlation": 8.0,
      "volatility": 8.0
  },
  "media": {
    "overall": {
        "large": "https://scores-media.stratifi.com/10/large/81.png",
        "medium": "https://scores-media.stratifi.com/10/medium/81.png",
        "compact": "https://scores-media.stratifi.com/10/compact/81.png"
    },
    "concentrated": {
        "large": "https://scores-media.stratifi.com/10/large/10.png",
        "medium": "https://scores-media.stratifi.com/10/medium/10.png",
        "compact": "https://scores-media.stratifi.com/10/compact/10.png"
    },
    "correlation": {
        "large": "https://scores-media.stratifi.com/10/large/80.png",
        "medium": "https://scores-media.stratifi.com/10/medium/80.png",
        "compact": "https://scores-media.stratifi.com/10/compact/80.png"
    },
    "tail": {
        "large": "https://scores-media.stratifi.com/10/large/90.png",
        "medium": "https://scores-media.stratifi.com/10/medium/90.png",
        "compact": "https://scores-media.stratifi.com/10/compact/90.png"
    },
    "volatility": {
        "large": "https://scores-media.stratifi.com/10/large/80.png",
        "medium": "https://scores-media.stratifi.com/10/medium/80.png",
        "compact": "https://scores-media.stratifi.com/10/compact/80.png"
    }
  },
  "status": "processing",
  "created": "2021-04-21T15:11:37.564188",
  "top_risk_attributions": [
      {
          "ticker_name": "VANGUARD TARGET 2045",
          "ticker": "OPPI",
          "risk": 0.9997862976486193,
          "weight": 99.763225
      },
      {
          "ticker_name": "Fha Non Int Bearing",
          "ticker": "UNTB",
          "risk": 0.00021370235138087705,
          "weight": 0.236775
      }
  ],
  "scenarios": [
      {
          "risk": 8.8,
          "name": "Global Financial Crisis",
          "end_date": "2009-2-1",
          "start_date": "2007-2-1"
      },
      {
          "risk": 8.8,
          "name": "2011 Euro Credit Crisis",
          "end_date": "2012-1-1",
          "start_date": "2010-1-1"
      },
      {
          "risk": 8.1,
          "name": "2013 Taper Tantrum",
          "end_date": "2014-6-1",
          "start_date": "2012-6-1"
      },
      {
          "risk": 7.7,
          "name": "2015-16 Market Selloff",
          "end_date": "2017-1-1",
          "start_date": "2015-1-1"
      }
  ]
}
Name Type Description
scores Scores Factors Risk score factors
media Scores Images Risk score factors images
status Risk Status Risk score status
created date Score timestamp
top_risk_attributions[].ticker string Risk attribution ticker
top_risk_attributions[].ticker_name string Risk attribution ticker description
top_risk_attributions[].risk float Risk attribution overall score
top_risk_attributions[].weight float Risk attribution weight
scenarios[].name string Scenario name
scenarios[].start_date string Scenario start date
scenarios[].end_date string Scenario end date
scenarios[].risk float Scenario overall risk

Tolerance Object Definition

Tolerance Object

{
  "scores": {
      "overall": 6.4,
      "concentrated": 5.0,
      "correlation": 5.0,
      "tail": 5.0,
      "volatility": 8.0
  },
  "media": {
    "overall": {
        "large": "https://scores-media.stratifi.com/10/large/64.png",
        "medium": "https://scores-media.stratifi.com/10/medium/64.png",
        "compact": "https://scores-media.stratifi.com/10/compact/64.png"
    },
    "concentrated": {
        "large": "https://scores-media.stratifi.com/10/large/50.png",
        "medium": "https://scores-media.stratifi.com/10/medium/50.png",
        "compact": "https://scores-media.stratifi.com/10/compact/50.png"
    },
    "correlation": {
        "large": "https://scores-media.stratifi.com/10/large/50.png",
        "medium": "https://scores-media.stratifi.com/10/medium/50.png",
        "compact": "https://scores-media.stratifi.com/10/compact/50.png"
    },
    "tail": {
        "large": "https://scores-media.stratifi.com/10/large/50.png",
        "medium": "https://scores-media.stratifi.com/10/medium/50.png",
        "compact": "https://scores-media.stratifi.com/10/compact/50.png"
    },
    "volatility": {
        "large": "https://scores-media.stratifi.com/10/large/80.png",
        "medium": "https://scores-media.stratifi.com/10/medium/80.png",
        "compact": "https://scores-media.stratifi.com/10/compact/80.png"
    }
}
}
Name Type Description
scores Scores Factors Tolerance score factors
media Scores Images Tolerance score factors images

Positions

Position Object Description:

{
    "ticker": "GOOGL",
    "ticker_name": "ALPHABET INC CLASS A",
    "cusip": "02079K305",
    "isin": "US38259P5089",
    "type": "Equity",
    "subtype": "US",
    "sector": "Large Cap",
    "value": 36275.50
    "quantity": 780,
    "price": 46.5070,
    "unit": "shares",
    "cost_basis": 57.0179,
}
Name Type Description -
ticker string Asset symbol Required
ticker_name string Asset description Optional
cusip string Asset cusip Optional
isin string ISIN identifier Optional
type string Position type Read-only
subtype string Position subtype Read-only
sector string Position sector Read-only
value number Value Required
quantity number Number of units of the security held Optional
price number Price per unit of the security Read-only
unit string Denomination of each unit of the security Optional
cost_basis number The total cost of the position Optional

Accounts

Account Object Definition

Account Object

{
  "id": 1,
  "external_id": "act-1",
  "name": "John Doe Trust",
  "value": "1234567.89",
  "type": "100",
  "tax_status": "taxable",
  "number": "987654321",
  "investor": 1,
  "advisor": 1,
  "strategy": 1,
  "positions": […],
  "risk": {…},
  "tolerance": {…},
  "drift": 1.7
}
Name Type Description
id int Account ID
external_id string Your account identifier
name string Account name
value string Account value
type string Account type .
tax_status string Account tax status. One of these values.
number string Account number
strategy int Account strategy represented as Model Portfolio Id. You can find the desired model portfolio using the list or get endpoint.
investor int Investor ID
advisor int Advisor ID. Ideally, you would provide the investor ID. However, if you don't have that information but you know who is the advisor that owns this account then you can pass the advisor ID. We will assign the account to the default_investor of the selected advisor.
positions[] List of Positions Objects Account holdings
risk Risk Object Account risk
tolerance Tolerance Object Account tolerance
drift float Drift between the risk and the tolerance overall scores

Account Tax Statuses

Value Description
taxable Taxable accounts
exempt Tax Exempt accounts
deferred Tax Deferred accounts

List Accounts

-request-type: GET

-request-url: /accounts/

List Accounts

curl "https://backend.stratifi.com/api/v1/accounts/" -H "Authorization: Bearer {{ access-token }}"

{
  "count": 10,
  "next": "https://backend.stratifi.com/api/v1/accounts/?page=2",
  "previous": null,
  "results": [
    {
      "id": 1,
      "external_id": "act-1",
      "name": "John Doe Trust",
      "value": "1234567.89",
      "type": "100",
      "tax_status": "taxable",
      "number": "987654321",
      "investor": 1,
      "advisor": 1,
      "strategy": 1,
      "positions": [ … ],
      "risk": { … },
      "tolerance": { … },
      "drift": 1.0,
    },
    …
  ]
}

Response Fields

Name Type Description
count int Total number of accounts
next string Link to next page of accounts
previous string Link to previous page of accounts
results Object List of account objects

Filtering Fields

Name Type Description
external_id string Your account identifier
investor int Investor ID
household int Household ID

Get Account

Get Account

curl "https://backend.stratifi.com/api/v1/accounts/1/" -H "Authorization: Bearer {{ access-token }}"

{
  "id": 1,
  "external_id": "act-1",
  "name": "John Doe Trust",
  "value": "1234567.89",
  "type": "100",
  "tax_status": "tax-exempt",
  "number": "987654321",
  "investor": 1,
  "advisor": 1,
  "positions": [ … ],
  "risk": { … },
  "tolerance": { … },
  "drift": 1.0,
}

-request-type: GET

-request-url: /accounts/<id>/

Response: The requested account object.

Create Account

Create Account

curl -X POST "https://backend.stratifi.com/api/v1/accounts/" -H "Authorization: Bearer {{ access-token }}" \
  -d '{
    "external_id": "act-1",
    "name": "John Doe Trust",
    "value": "1234567.89",
    "type": "100",
    "tax_status": "tax-exempt",
    "number": "987654321",
    "investor": 1,
    "positions": [
      {
        "ticker": "SPY",
        "ticker_name": "SPDR S&P 500",
        "value": "823045.26"
      },
      {
        "ticker": "IBM",
        "ticker_name": "IBM",
        "value": "411522.63"
      },
      …
    ]
  }'

{
  "id": 1,
  "external_id": "act-1",
  "name": "John Doe Trust",
  "value": "1234567.89",
  "type": "100",
  "tax_status": "tax-exempt",
  "number": "987654321",
  "investor": 1,
  "advisor": 1,
  "strategy": 1,
  "positions": [ … ],
  "risk": { … },
  "tolerance": { … },
  "drift": 1.0,
}

-request-type: POST

-request-url: /accounts/

Request Parameters

Parameter Type
name string Required
positions[] List of Positions Objects Required
value string Optional
type string Optional
tax_status string Optional
number string Optional
investor int Optional
advisor int Optional
strategy int Optional
external_id string Optional

Response: The new account object.

Update Account

Update Account

curl -X PUT "https://backend.stratifi.com/api/v1/accounts/1/" -H "Authorization: Bearer {{ access-token }}" \
  -d '{
    "external_id": "act-1",
    "name": "John Doe 401k",
    "value": "1234567.89",
    "type": "401",
    "tax_status": "tax-deferred",
    "number": "987654321",
    "investor": 1,
    "strategy": 1,
    "positions": [
      {
        "ticker": "SPY",
        "ticker_name": "SPDR S&P 500",
        "value": "823045.26"
      },
      {
        "ticker": "IBM",
        "ticker_name": "IBM",
        "value": "411522.63"
      },
      …
    ]
  }'

{
  "id": 1,
  "external_id": "act-1",
  "name": "John Doe Trust",
  "value": "1234567.89",
  "type": "100",
  "tax_status": "tax-deferred",
  "number": "987654321",
  "investor": 1,
  "advisor": 1,
  "strategy": 1,
  "positions": [ … ],
  "risk": { … },
  "tolerance": { … },
  "drift": 1.0,
}

-request-type: PUT/PATCH

-request-url: /accounts/<id>/

Request Parameters

Parameter Type
name string Required
positions[] List of Positions Objects Required
value string Optional
type [1] string Optional
tax_status [2] string Optional
number string Optional
investor int Optional
advisor [3] int Optional
strategy [4] int Optional
external_id string Optional

Account Prism Score

Account Prism Score

curl "https://backend.stratifi.com/api/v1/accounts/11/prism_score/" -H "Authorization: Bearer {{ access-token }}"

{
  "scores": {…},
  "media": {…},
}

-request-type: GET

-request-url: /accounts/<id>/prism_score/

Response Fields

Name Type Description
scores Scores Factors Risk score factors
media Scores Images Risk score factors images

Model Portfolios

Model Portfolio Object Definition

Model Portfolio Object

{
  "id": 1,
  "external_id": "mp-1",
  "name": "80% Equities / 20% Fixed Income",
  "value": 100.0,
  "type": "Aggressive",
  "company": 1,
  "positions": [
    {
        "ticker": "AGG",
        "ticker_name": "iShares Core US Aggregate Bond",
        "value": 20.0
    },
    {
        "ticker": "SPY",
        "ticker_name": "SPDR S&P500 ETF Trust",
        "value": 80.0
    }
  ],
  "risk": {…}
}
Name Type Description
id int Model Portfolio ID
external_id string Your model identifier
name string Model Portfolio name
value string Model Portfolio value
type string Model Portfolio type
is_strategy bool Is this model a strategy?
company int Company ID
positions[] List of Positions Objects Model Portfolio holdings
risk Risk Object Model Portfolio risk

List Model Portfolios

List Model Portfolios

curl "https://backend.stratifi.com/api/v1/models/" -H "Authorization: Bearer {{ access-token }}"

{
  "count": 10,
  "next": "https://backend.stratifi.com/api/v1/models/?page=2",
  "previous": null,
  "results": [
    {
      "id": 1,
      "external_id": "mp-1",
      "name": "80% Equities / 20% Fixed Income",
      "value": 100.0,
      "type": "Aggressive",
      "is_strategy": false,
      "company": 1,
      "positions": [ … ],
      "risk": { … }
    },
    …
  ]
}

-request-type: GET

-request-url: /models/

Response Fields

Name Type Description
count int Total number of models
next string Link to next page of models
previous string Link to previous page of models
results Object List of model objects

Filtering Fields

Name Type Description
external_id string Your model identifier

Get Model Portfolio

Get Model Portfolio

curl "https://backend.stratifi.com/api/v1/models/1/" -H "Authorization: Bearer {{ access-token }}"

{
  "id": 1,
  "external_id": "mp-1",
  "name": "80% Equities / 20% Fixed Income",
  "value": 100.0,
  "type": "Aggressive",
  "is_strategy": false,
  "company": 1,
  "positions": [ … ],
  "risk": { … }
}

-request-type: GET

-request-url: /models/<id>/

Response: The requested model object.

Create Model Portfolio

Create Model Portfolio

curl -X POST "https://backend.stratifi.com/api/v1/models/" -H "Authorization: Bearer {{ access-token }}" \
  -d '{
    "external_id": "mp-1",
    "name": "80% Equities / 20% Fixed Income",
    "value": 100.0,
    "type": "Aggressive",
    "is_strategy": false,
    "company": 1,
    "positions": [
      {
          "ticker": "AGG",
          "ticker_name": "iShares Core US Aggregate Bond",
          "value": 20.0
      },
      {
          "ticker": "SPY",
          "ticker_name": "SPDR S&P500 ETF Trust",
          "value": 80.0
      }
    ]
  }'

{
  "id": 1,
  "external_id": "mp-1",
  "name": "80% Equities / 20% Fixed Income",
  "value": 100.0,
  "type": "Aggressive",
  "is_strategy": false,
  "company": 1,
  "positions": [ … ],
  "risk": { … }
}

-request-type: POST

-request-url: /models/

Request Parameters

Parameter Type
name string Required
positions[] List of Positions Objects Required
value string Optional
type string Optional
is_strategy bool Optional
company int Optional
external_id int Optional

Response: The new model object.

Update Model Portfolio

Update Model Portfolio

curl -X PUT "https://backend.stratifi.com/api/v1/models/1/" -H "Authorization: Bearer {{ access-token }}" \
  -d '{
    "external_id": "mp-1",
    "name": "70% Equities / 30% Fixed Income",
    "value": 100.0,
    "type": "Moderate",
    "is_strategy": true,
    "company": 1,
    "positions": [
      {
          "ticker": "AGG",
          "ticker_name": "iShares Core US Aggregate Bond",
          "value": 30.0
      },
      {
          "ticker": "SPY",
          "ticker_name": "SPDR S&P500 ETF Trust",
          "value": 70.0
      }
    ]
  }'

{
  "id": 1,
  "external_id": "mp-1",
  "name": "80% Equities / 20% Fixed Income",
  "value": 100.0,
  "type": "Moderate",
  "is_strategy": true,
  "company": 1,
  "positions": [ … ],
  "risk": { … }
}

-request-type: PUT/PATCH

-request-url: /models/<id>/

Request Parameters

Parameter Type
name string Required
positions[] List of Positions Objects Required
value string Optional
type * string Optional
is_strategy bool Optional
company int Optional
external_id int Optional

Model Portfolio Prism Score

Model Portfolio Prism Score

curl "https://backend.stratifi.com/api/v1/models/11/prism_score/" -H "Authorization: Bearer {{ access-token }}"

{
  "scores": {…},
  "media": {…},
}

-request-type: GET

-request-url: /models/<id>/prism_score/

Response Fields

Name Type Description
scores Scores Factors Risk score factors
media Scores Images Risk score factors images
status Scores Status Risk score status

Securities

Security Object

{
    "ticker": "GOOGL",
    "cusip": "02079K305",
    "isin": "US02079K3059",
    "ticker_name": "Alphabet Inc",
    "type": "Equity",
    "subtype": "US",
    "sector": "Large Cap",
    "prism_score": {
        "concentrated": 10,
        "overall": 9.3,
        "tail": 9,
        "correlation": 6,
        "volatility": 10,
        "upside_capture_ratio": 1.33886097996,
        "downside_capture_ratio": 0.863528362089

    }
}
Name Type Description
ticker string Asset symbol
cusip string Asset cusip
isin string ISIN identifier
ticker_name string Asset description
type string Asset type
subtype string Asset subtype
sector string Asset sector
prism_score.overall float Overall risk score
prism_score.concentrated float Concentrated risk score
prism_score.tail float Tail risk score
prism_score.volatility float Volatility risk score
prism_score.correlation float Correlation risk score
prism_score.downside_capture_ratio float Asset downside capture vs the market
prism_score.upside_capture_ratio float Asset upside capture vs the market

Get security by ticker

Get security by ticker

curl "https://backend.stratifi.com/api/v1/securities/ticker/GOOGL" -H "Authorization: Bearer {{ access-token }}"

-request-type: GET

-request-url: /securties/ticker/<ticker>

Get security by cusip

Get security by cusip

curl "https://backend.stratifi.com/api/v1/securities/cusip/02079K305" -H "Authorization: Bearer {{ access-token }}"

-request-type: GET

-request-url: /securties/cusip/<cusip>

Changelog