---
# System prepended metadata

title: Origin API Docs

---

# Origin API Docs

# Retirement API

## Linked Bank Account

### Create

Creates a linked bank account for a given user.

Requires a bearer token.

#### Endpoint

`POST retirement/v1/401k/linked_bank_accounts/<user_id>`

#### Example
```json
{
	"public_token": "public_token",
	"name": "name",
	"mask": "mask",
	"institution_name": "institution_name",
	"institution_id": "institution_id",
	"account_id": "12345",
	"type": "investment",
	"subtype": "401k"
}
```

##### Response

```json
{
        "name": "name",
        "mask": "mask",
        "institution_name": "institution_name",
        "institution_id": "institution_id",
        "account_id": "12345",
        "type": "investment",
        "subtype": "401k"
}
```

#### Error responses

##### 400

```json
{
    "detail": "Linked account is not a 401k.",
    "code": "linked-account-not-401k"
}
```

## Consolidated Balance

### Retrieve

Returns a consolidated balance for a given user.

Requires a bearer token.

#### Endpoint

`GET retirement/v1/401k/portfolio/consolidated_balance/<user_id>`

#### Example

##### Request

Body is empty.

##### Response

```json
{
    "total_amount": "total_amount",
    "asset_allocations": [
        {
            "asset_class": "cash",
            "proportion": "propertion",
            "holdings_fees": "holdings_fees",
            "total_amount": "total_amount"
        },
        {
            "asset_class": "bonds",
            "proportion": "proportion",
            "holdings_fees": "holdings_fees",
            "total_amount": "total_amount"
        },
        {
            "asset_class": "stocks",
            "proportion": "proportion",
            "holdings_fees": "holdings_fees",
            "total_amount": "total_amount"
        },
        {
            "asset_class": "other",
            "proportion": "proportion",
            "holdings_fees": "holdings_fees",
            "total_amount": "total_amount"
        }
    ]
}
```

## Transactions

### Retrieve


Returns a list of transactions ordered from the newest to the lowest.
Can be filtered with `year` and/or `max_items` as query strings.

Requires a bearer token.

#### Endpoint

`GET retirement/v1/401k/portfolios/transactions/<user_id>?year=2019&max_items=5`

##### Request

Body is empty.

##### Response

```json
[
    {
        "amount": -8.72,
        "date": "2019-05-05"
    },
    {
        "amount": -1289.01,
        "date": "2019-05-04"
    },
    {
        "amount": 7.7,
        "date": "2019-05-03"
    },
    {
        "amount": -0.22,
        "date": "2019-05-02"
    },
    {
        "amount": 1.1,
        "date": "2019-05-01"
    }
]
```

# Savings API

Postman collection: [https://www.getpostman.com/collections/629bb53b8c0d39fd28a9]

## Saving Goal

### Create

Creates a saving goal for a given user.

Requires a bearer token.

#### Endpoint

`POST financial_services/savings/v1/goals/<user_id>`

#### Example

##### Request

```json
{
    "tag": "take_a_vacation",
    "term": 12,
    "total_amount": 12000.0,
    "monthly_amount": 1000.00
}
```

##### Response

The status code is 201.

```json
{
  "tag": "go_to_college",
  "term": 12,
  "total_amount": 1200.0,
  "monthly_amount": 100.0
}
```

### Retrieve

Retrieves the saving goals of a given user.

Requires a bearer token.

#### Endpoint

`GET financial_services/savings/v1/goals/<user_id>`

#### Example

##### Request

The body is empty.

##### Response

The status code is 200.

```json
[
    {
        "tag": "take_a_vacation",
        "term": 12,
        "total_amount": 1200.0,
        "monthly_amount": 100.0
    },
    {
        "tag": "go_to_college",
        "term": 120,
        "total_amount": 18000.0,
        "monthly_amount": 150.0
    }
]
```

## Recommendation

### Retrieve

Returns the recommendation for a given saving goal tag for a given user.

Requires a bearer token.

#### Endpoint

`GET financial_services/savings/v1/recommendations/<user_id>/<saving_goal_tag>`

#### Example

##### Request

Body is empty.

##### Response

```json
{
    "tag": "take_a_vacation",
    "term": 12,
    "total_amount": 4000.0,
    "monthly_amount": 333.33,
    "resources": {
        "total_time_off_in_days": 20.0,
        "number_of_travel_companions": 1.0,
        "average_vacation_expenses_per_day": 100.0
    },
    "description": "Covers the average travel expenses for a 30 day trip with a family your size."
}
```

### List

Returns recommendations for all saving goal tags for a given user.

Requires a bearer token.

#### Endpoint

`GET financial_services/savings/v1/recommendations/<user_id>`

#### Example

##### Request

Body is empty.

##### Response

```json
[
    {
        "tag": "take_a_vacation",
        "term": 12,
        "total_amount": 4000.0,
        "monthly_amount": 333.33,
        "resources": {
            "total_time_off_in_days": 20.0,
            "number_of_travel_companions": 1.0,
            "average_vacation_expenses_per_day": 100.0
        },
        "description": "Covers the average travel expenses for a 30 day trip with a family your size."
    },
    {
        "tag": "throw_a_wedding_party",
        "term_in_months": 12,
        "total_amount": 35000.0,
        "monthly_amount": 2916.67,
        "resources": {
            "average_wedding_party_cost": 35000.0
        },
        "description": "Based on the average cost of a wedding party in the United States."
    }
]
```


## Simulation

### Create

Creates a simulation for a given user.

A simulation consists in a `monthly_amount` that is calculated based on either the `total_amount` or the `resources` (which are used to calculate the `total_amount`) that are passed. If a `total_amount` is passed, the `resources` are ignored.

Requires a bearer token.

#### Endpoint

`POST savings/v1/simulations/<user_id>`

#### Example

##### Request

```json
{
    "tag": "throw_a_wedding_party",
    "term_in_months": 37,
    "total_amount": null,
    "resources": {
        "average_wedding_party_cost": 37000.0
    },
    "description": "Based on the average cost of a wedding party in the United States."
}
```

##### Response

```json
{
    "tag": "throw_a_wedding_party",
    "term_in_months": 37,
    "total_amount": 37000.0,
    "monthly_amount": 1000.0,
    "resources": {
        "average_wedding_party_cost": 37000.0
    },
    "description": "Based on the average cost of a wedding party in the United States."
}
```


## Linked Bank Account

### Create

Creates a linked bank account for a given user.

Accepts multiple objects in the same request.

Requires a bearer token.

#### Endpoint

`POST savings/v1/linked_bank_accounts/<user_id>`

#### Example
```json
[
	{
		"public_token": "public_token",
		"name": "name",
		"mask": "mask",
		"institution_name": "institution_name",
		"institution_id": "institution_id",
		"account_id": "1111",
		"type": "investment",
		"subtype": "checkings"
	},
	{
        "public_token": "public_token2",
		"name": "name2",
		"mask": "mask2",
		"institution_name": "institution_name2",
		"institution_id": "institution_id2",
		"account_id": "2222",
		"type": "investment",
		"subtype": "checkings"
	}
]
```

##### Response

```json
[
    {
        "name": "name",
        "mask": "mask",
        "institution_name": "institution_name",
        "institution_id": "institution_id",
        "account_id": "1111",
        "type": "investment",
        "subtype": "checkings"
    },
    {
        "name": "name2",
        "mask": "mask2",
        "institution_name": "institution_name2",
        "institution_id": "institution_id2",
        "account_id": "2222",
        "type": "investment",
        "subtype": "checkings"
    }
]
```



## Transactions

### List

Returns the transactions for a given user id.
Can be filtered with `tag` and/or `max_items` as query strings.

Requires a bearer token.

#### Endpoint

`POST savings/v1/transactions/<user_id>?tag=have_a_baby&max_items=5`

#### Example
```json
[
	{
		"amount": "1000",
		"date": "2016-01-02",
		"processed": true,
		"manual": false
	}
]
```



## Deposit

### Create

Makes a deposit from a given user to the given savings plan tag.

Requires a bearer token.

#### Endpoint

`POST savings/v1/savings_plan/<user_id>/<tag>/deposit`

#### Example
```json
[
	{
		"amount": "1000",
	}
]
```

##### Response

The status code is 204.



## Withdraw

### Create

Makes a withdraw from savings plan tag to the given user.

Requires a bearer token.

#### Endpoint

`POST savings/v1/savings_plan/<user_id>/<tag>/withdraw`

#### Example
```json
[
	{
		"amount": "1000",
	}
]
```

##### Response

The status code is 204.



## Savings Plan List

### List

Returns the savings plans for a given user id.

Requires a bearer token.

#### Endpoint

`GET savings/v1/savings_plan/<user_id>`

#### Example
```json
[
    {
        "tag": "have_a_baby",
        "deposit_day": 10,
        "started_at": "2020-12-12",
        "chosen_total_amount": 10000.0,
        "current_balance": 0,
        "deposits_left": 11,
        "monthly_deposit_amount": "909.09"
    },
    {
        "tag": "buy_a_car",
        "deposit_day": 10,
        "started_at": null,
        "chosen_total_amount": 10000.0,
        "current_balance": 0,
        "deposits_left": 11,
        "monthly_deposit_amount": "909.09"
    }
]
```


## Savings Plan Retrieve

### Retrieve

Returns the savings plan for a given user id and tag.

Requires a bearer token.

#### Endpoint

`GET savings/v1/savings_plan/<user_id>/<tag>`

#### Example
```json
{
    "tag": "have_a_baby",
    "deposit_day": 10,
    "started_at": "2020-12-12",
    "chosen_total_amount": 10000.0,
    "current_balance": 0,
    "deposits_left": 11,
    "monthly_deposit_amount": "909.09"
}
```

# Insurance API

Postman collection: [https://www.getpostman.com/collections/278ab43d21ae33f0538a]

## Recommendation

### Retrieve

Returns the recommendation for a given insurance line for a given user.

Requires a bearer token.

#### Endpoint

`GET financial_services/insurance/v1/recommendations/<user_id>/<insurance_line>`

#### Example

##### Request

Body is empty.

##### Response

```json
{
    "line_name": "renters",
    "recommended_plan": null,
    "eligible": false,
    "outcome_description": "You don't rent."
}
```

### List

Returns recommendations for all insurance lines for a given user.

Requires a bearer token.

#### Endpoint

`GET financial_services/insurance/v1/recommendations/<user_id>`

#### Example

##### Request

Body is empty.

##### Response

```json
[
    {
        "line_name": "renters",
        "recommended_plan": null,
        "eligible": false,
        "outcome_description": "You don't rent."
    },
    {
        "line_name": "auto",
        "recommended_plan": "mid",
        "eligible": true,
        "outcome_description": "You are a homeowner with more assets to protect but you are on somewhat of a budget, so we made sure to take those items into account when building this plan."
    },
    {
        "line_name": "term_life",
        "recommended_plan": "mid",
        "eligible": true,
        "outcome_description": "You are a homeowner with more assets to protect but you are less risk-averse than most. This plan has takes into account that."
    },
    {
        "line_name": "condo",
        "recommended_plan": null,
        "eligible": false,
        "outcome_description": "You don't own a condo."
    },
    {
        "line_name": "home",
        "recommended_plan": "mid",
        "eligible": true,
        "outcome_description": "We created a plan specifically for you since you are comfortable with very little risk but you are on somewhat of a budget."
    }
]
```

## Offer

### Create

Creates an insurance offer for a given user.

It includes all insurances lines that the user hasn't created a `selection` for.

Requires a bearer token.

#### Endpoint

`POST financial_services/insurance/v1/offers/<user_id>`

#### Example

##### Request

Body is empty.

##### Response

```json
{
    "auto": {
        "plans": [
            "less",
            "mid",
            "more"
        ],
        "coverages": {
            "less": [
                {
                    "name": "Bodily Injury",
                    "type": "limit",
                    "occurrence_amount": 60000,
                    "individual_amount": 30000
                },
                {
                    "name": "Property Damage",
                    "type": "limit",
                    "occurrence_amount": 25000,
                    "individual_amount": null
                },
                {
                    "name": "Medical Payments",
                    "type": "limit",
                    "occurrence_amount": 1000,
                    "individual_amount": null
                },
                {
                    "name": "Personal Injury Protection",
                    "type": "limit",
                    "occurrence_amount": 2500,
                    "individual_amount": null
                },
                {
                    "name": "Uninsured Motorist",
                    "type": "limit",
                    "occurrence_amount": 60000,
                    "individual_amount": 30000
                },
                {
                    "name": "Comprehensive",
                    "type": "deductible",
                    "occurrence_amount": 500,
                    "individual_amount": null
                },
                {
                    "name": "Collision",
                    "type": "deductible",
                    "occurrence_amount": 500,
                    "individual_amount": null
                },
                {
                    "name": "Towing & Labor",
                    "type": "limit",
                    "occurrence_amount": 0,
                    "individual_amount": null
                }
            ],
            "mid": [
                {
                    "name": "Bodily Injury",
                    "type": "limit",
                    "occurrence_amount": 100000,
                    "individual_amount": 50000
                },
                {
                    "name": "Property Damage",
                    "type": "limit",
                    "occurrence_amount": 50000,
                    "individual_amount": null
                },
                {
                    "name": "Medical Payments",
                    "type": "limit",
                    "occurrence_amount": 5000,
                    "individual_amount": null
                },
                {
                    "name": "Personal Injury Protection",
                    "type": "limit",
                    "occurrence_amount": 10000,
                    "individual_amount": null
                },
                {
                    "name": "Uninsured Motorist",
                    "type": "limit",
                    "occurrence_amount": 100000,
                    "individual_amount": 50000
                },
                {
                    "name": "Comprehensive",
                    "type": "deductible",
                    "occurrence_amount": 500,
                    "individual_amount": null
                },
                {
                    "name": "Collision",
                    "type": "deductible",
                    "occurrence_amount": 500,
                    "individual_amount": null
                },
                {
                    "name": "Towing & Labor",
                    "type": "limit",
                    "occurrence_amount": 50,
                    "individual_amount": null
                }
            ],
            "more": [
                {
                    "name": "Bodily Injury",
                    "type": "limit",
                    "occurrence_amount": 300000,
                    "individual_amount": 100000
                },
                {
                    "name": "Property Damage",
                    "type": "limit",
                    "occurrence_amount": 100000,
                    "individual_amount": null
                },
                {
                    "name": "Medical Payments",
                    "type": "limit",
                    "occurrence_amount": 10000,
                    "individual_amount": null
                },
                {
                    "name": "Personal Injury Protection",
                    "type": "limit",
                    "occurrence_amount": 25000,
                    "individual_amount": null
                },
                {
                    "name": "Uninsured Motorist",
                    "type": "limit",
                    "occurrence_amount": 300000,
                    "individual_amount": 100000
                },
                {
                    "name": "Comprehensive",
                    "type": "deductible",
                    "occurrence_amount": 500,
                    "individual_amount": null
                },
                {
                    "name": "Collision",
                    "type": "deductible",
                    "occurrence_amount": 500,
                    "individual_amount": null
                },
                {
                    "name": "Towing & Labor",
                    "type": "limit",
                    "occurrence_amount": 80,
                    "individual_amount": null
                }
            ]
        },
        "eligible": true,
        "recommended_plan": "more",
        "outcome_description": "You are a homeowner with more assets to protect and you have high income and more assets, so we built a plan with more coverage to make sure you're protected."
    },
    "home": {
        "plans": [
            "less",
            "mid",
            "more"
        ],
        "coverages": {
            "less": [
                {
                    "name": "Dwelling",
                    "type": "limit",
                    "occurrence_amount": 0,
                    "individual_amount": null
                },
                {
                    "name": "Other Structures",
                    "type": "limit",
                    "occurrence_amount": 0,
                    "individual_amount": null
                },
                {
                    "name": "Personal Property",
                    "type": "limit",
                    "occurrence_amount": 0,
                    "individual_amount": null
                },
                {
                    "name": "Loss of Use",
                    "type": "limit",
                    "occurrence_amount": 2500,
                    "individual_amount": null
                },
                {
                    "name": "Personal Liability",
                    "type": "limit",
                    "occurrence_amount": 50000,
                    "individual_amount": null
                }
            ],
            "mid": [
                {
                    "name": "Dwelling",
                    "type": "limit",
                    "occurrence_amount": 0,
                    "individual_amount": null
                },
                {
                    "name": "Other Structures",
                    "type": "limit",
                    "occurrence_amount": 0,
                    "individual_amount": null
                },
                {
                    "name": "Personal Property",
                    "type": "limit",
                    "occurrence_amount": 0,
                    "individual_amount": null
                },
                {
                    "name": "Loss of Use",
                    "type": "limit",
                    "occurrence_amount": 2500,
                    "individual_amount": null
                },
                {
                    "name": "Personal Liability",
                    "type": "limit",
                    "occurrence_amount": 100000,
                    "individual_amount": null
                }
            ],
            "more": [
                {
                    "name": "Dwelling",
                    "type": "limit",
                    "occurrence_amount": 0,
                    "individual_amount": null
                },
                {
                    "name": "Other Structures",
                    "type": "limit",
                    "occurrence_amount": 0,
                    "individual_amount": null
                },
                {
                    "name": "Personal Property",
                    "type": "limit",
                    "occurrence_amount": 0,
                    "individual_amount": null
                },
                {
                    "name": "Loss of Use",
                    "type": "limit",
                    "occurrence_amount": 2500,
                    "individual_amount": null
                },
                {
                    "name": "Personal Liability",
                    "type": "limit",
                    "occurrence_amount": 200000,
                    "individual_amount": null
                }
            ]
        },
        "eligible": true,
        "recommended_plan": "more",
        "outcome_description": "We created a plan with full coverage since you have high income and more assets and you need more insurance to let you sleep easy at night."
    },
    "renters": {
        "plans": [],
        "coverages": [],
        "eligible": false,
        "recommended_plan": null,
        "outcome_description": "You don't rent."
    },
    "condo": {
        "plans": [],
        "coverages": [],
        "eligible": false,
        "recommended_plan": null,
        "outcome_description": "You don't own a condo."
    },
    "term_life": {
        "plans": [
            "less",
            "mid",
            "more"
        ],
        "coverages": {
            "less": [
                {
                    "name": "Death Benefit",
                    "type": "limit",
                    "occurrence_amount": 100000,
                    "individual_amount": null
                }
            ],
            "mid": [
                {
                    "name": "Death Benefit",
                    "type": "limit",
                    "occurrence_amount": 125000,
                    "individual_amount": null
                }
            ],
            "more": [
                {
                    "name": "Death Benefit",
                    "type": "limit",
                    "occurrence_amount": 150000,
                    "individual_amount": null
                }
            ]
        },
        "eligible": true,
        "recommended_plan": "more",
        "outcome_description": "You have a family that will need financial support and you are a homeowner with more assets to protect. This full coverage plan has everything you need."
    }
}
```

## Selection

### Get

Returns all insurance selections of a given user.

#### Endpoint

`GET financial_services/insurance/v1/selections/<user_id>`

#### Example

##### Request

The body is empty.

##### Response

```json
{
    "auto": {
        "selected_plan": "less",
        "selected_coverages": [
            {
                "name": "Dwelling",
                "type": "limit",
                "occurrence_amount": 0,
                "individual_amount": null
            },
            {
                "name": "Other Structures",
                "type": "limit",
                "occurrence_amount": 0,
                "individual_amount": null
            },
            {
                "name": "Personal Property",
                "type": "limit",
                "occurrence_amount": 0,
                "individual_amount": null
            },
            {
                "name": "Loss of Use",
                "type": "limit",
                "occurrence_amount": 2500,
                "individual_amount": null
            },
            {
                "name": "Personal Liability",
                "type": "limit",
                "occurrence_amount": 50000,
                "individual_amount": null
            }
        ]
    },
    "term_life": {
        "selected_plan": "mid",
        "selected_coverages": [
            {
                "name": "Death Benefit",
                "type": "limit",
                "occurrence_amount": 125000,
                "individual_amount": null
            }
        ]
    }
}
```

### Create

Creates insurance selections for a given user.

#### Endpoint

`POST financial_services/insurance/v1/selections/<user_id>`

#### Example

##### Request

```json
{
    "auto":{
        "selected_plan": "less",
        "selected_coverages":[
            {
                "name": "Bodily Injury",
                "type": "limit",
                "occurrence_amount": 60000,
                "individual_amount": 30000
            },
            {
                "name": "Property Damage",
                "type": "limit",
                "occurrence_amount": 25000,
                "individual_amount": null
            },
            {
                "name": "Medical Payments",
                "type": "limit",
                "occurrence_amount":1000,
                "individual_amount":null
            },
            {
                "name": "Personal Injury Protection",
                "type": "limit",
                "occurrence_amount": 2500,
                "individual_amount": null
            },
            {
                "name": "Uninsured Motorist",
                "type": "limit",
                "occurrence_amount": 60000,
                "individual_amount": 30000
            },
            {
                "name": "Comprehensive",
                "type": "deductible",
                "occurrence_amount": 500,
                "individual_amount": null
            },
            {
                "name": "Collision",
                "type": "deductible",
                "occurrence_amount": 500,
                "individual_amount": null
            },
            {
                "name": "Towing & Labor",
                "type": "limit",
                "occurrence_amount": 0,
                "individual_amount": null
            }
        ]
    },
    "term_life": {
        "selected_plan": "mid",
        "selected_coverages": [
            {
                "name": "Death Benefit",
                "type": "limit",
                "occurrence_amount": 125000,
                "individual_amount": null
            }
        ]
    }
}
```

##### Response

Returns an empty body with a 204 status code.
