Docs

Positions

Suggest Edits

The Positions API can be used to view, create, update, and delete positions in Addepar. Positions are a connection between two entities in our ownership graph.

Base Route/v1/positions
EndpointsGET
/v1/positions/:id
/v1/positions
/v1/positions/:id/owner
/v1/positions/:id/owned
/v1/positions/:id/relationships/owner
/v1/positions/:id/relationships/owned

POST
/v1/positions

PATCH
/v1/positions/:id
/v1/positions

DELETE
/v1/positions/:id
/v1/positions
ProducesJSON
PaginationYes
Application Permissions Required"API Access: Create, edit, and delete"

"Portfolio Access" is required to retrieve, update, and delete positions.

“Transactions: Full permission (view, create, and edit)” is required to create, update and delete positions.

"Manage Attributes: Only edit certain attribute values or Manage all values and settings” is required to apply, edit, or delete attributes.
OAuth ScopesPOSITIONS or POSITIONS_WRITE

Resource Overview

Positions are described by the below resource object attributes. Attributes required for creating, updating or deleting Positions are noted. You can assign additional standard and custom attributes to Positions.

All attributes will be returned in successful GET, POST & PATCH responses.

AttributeDescriptionExample
namePosition name. String.

Required for cash positions.

Names must be different for cash positions that have the same owner and owned entities.		"GOOG"
incepting_open_position_dateDate that ownership was first linked. String. “YYYY-MM-DD”

Required for Percent Based Assets.

Not applicable for Share Based Assets or Value Based Assets.

When linking an entity that directly owns share-based assets, like an account, use a date one day earlier than the first transaction or snapshot. Otherwise, use a historical date like 1900/01/01.		“2015-12-31”
incepting_open_position_ownership_percentagePercentage ownership. Number. (Percent, represented as a decimal)

Required for Percent Based Assets.

Not applicable for Share Based Assets or Value Based Assets.		.5
created_atNot editable and cannot be passed in. String."2023-07-28T02:24:30Z"
modified_atNot editable and cannot be passed in. String."2023-07-30T10:43:21Z"
Optional AttributesAdditional attributes can be applied to positions.See Addepar Attributes

Relationships

RelationshipDescription
ownerThe entity that holds the position.
ownedThe entity that is being held in the position.
"relationships":{
        "owner":{
          "links":{
            "self":"/v1/positions/1017641/relationships/owner",
            "related":"/v1/positions/1017641/owner"
          },
          "data":{
            "type":"entities",
            "id":"259825"
          }
        },
        "owned":{
          "links":{
            "self":"/v1/positions/1017641/relationships/owned",
            "related":"/v1/positions/1017641/owned"
          },
          "data":{
            "type":"entities",
            "id":"259837"
          }
        }
      },
      "links":{
        "self":"/v1/positions/1017641"
      }
    }

📘

Note

There can be more than one open position between the same owner entity and owned entity. However, the positions route only reads or writes to the incepting open position. All GET responses include the incepting open position, and all PATCH requests modify the incepting open position.

Get a Position

Returns details for the specified position, including inception information and relationships.

GET /v1/positions/:id

Example: 

GET https://examplefirm.addepar.com/api/v1/positions/100

HTTP/1.1 200

{
  "data":{
    "id":"100",
    "type":"positions",
    "attributes":{
      "incepting_open_position_date":"2010-01-01",
      "incepting_open_position_ownership_percentage":1.0,
      "created_at":"2023-07-28T02:24:30Z",
      "modified_at":"2023-07-30T10:43:21Z"
    },
    "relationships":{
      "owner":{
        "links":{
          "self":"/v1/positions/100/relationships/owner",
          "related":"/v1/positions/100/owner"
        },
        "data":{
          "type":"entities",
          "id":"1"
        }
      },
      "owned":{
        "links":{
          "self":"/v1/positions/100/relationships/owned",
          "related":"/v1/positions/100/owned"
        },
        "data":{
          "type":"entities",
          "id":"2"
        }
      }
    },
    "links":{
      "self":"/v1/positions/100"
    }
  },
  "included":[
    
  ]
}

Response Codes:

  • 200 OK: Success
  • 403 Forbidden: Insufficient application permissions or appropriate scope not granted
  • 404 Not Found: Nonexistent/non-permissioned position ID

Get All Positions

Returns details for all positions, including inception information and relationships.

GET /v1/positions

Example: 

GET https://examplefirm.addepar.com/api/v1/positions

HTTP/1.1 200

{
  "data":[
    {
      "type":"positions",
      "id":"13",
      "attributes":{
        "name":"Bob",
        "display_name":"Bob",
        "incepting_open_position_date":"2016-12-01",
        "incepting_open_position_value":5,
        "created_at":"2023-07-28T02:24:30Z",
        "modified_at":"2023-07-30T10:43:21Z"
      },
      "relationships":{
        "owner":{
          "links":{
            "self":"/v1/positions/13/relationships/owner",
            "related":"/v1/positions/13/owner"
          },
          "data":{
            "type":"entities",
            "id":"1"
          }
        },
        "owned":{
          "links":{
            "self":"/v1/positions/13/relationships/owned",
            "related":"/v1/positions/13/owned"
          },
          "data":{
            "type":"entities",
            "id":"2"
          }
        }
      },
      "links":{
        "self":"/v1/positions/13"
      }
    },
    {
      "type":"positions",
      "id":"14",
      "attributes":{
        "name":"Bob",
        "display_name":"Bob",
        "incepting_open_position_date":"2016-12-01",
        "incepting_open_position_value":5,
        "created_at":"2023-07-28T02:24:30Z",
        "modified_at":"2023-07-30T10:43:21Z"
      },
      "relationships":{
        "owner":{
          "links":{
            "self":"/v1/positions/13/relationships/owner",
            "related":"/v1/positions/13/owner"
          },
          "data":{
            "type":"entities",
            "id":"1"
          }
        },
        "owned":{
          "links":{
            "self":"/v1/positions/13/relationships/owned",
            "related":"/v1/positions/13/owned"
          },
          "data":{
            "type":"entities",
            "id":"2"
          }
        }
      },
      "links":{
        "self":"/v1/positions/14"
      }
    }
  ]
}

Optional parameters

FilterDescriptionExample
fields[entities]Returns only the attributes specified for each position. Ignores spaces.fields[entities]=incepting_open_position_date
created_beforeReturns all positions created on or before a date, formatted as YYYY-MM-DD.filter[created_before]="2023-04-12"
created_afterReturns all positions created on or after a date, formatted as YYYY-MM-DD.filter[created_after]="2023-04-12"
modified_beforeReturns all positions last modified on or before a date, formatted as YYYY-MM-DD.filter[modified_before]="2023-04-12"
modified_afterReturns all positions last modified on or after a date, formatted as YYYY-MM-DD.filter[modified_after]="2023-04-12"

Response Codes:

  • 200 OK: Success
  • 403 Forbidden: Insufficient application permissions or appropriate scope not granted

Get Positon Owner Entity Details

Returns the owner entity.

GET /v1/positions/:id/owner

Example:

GET https://examplefirm.addepar.com/api/v1/positions/9/owner

HTTP/1.1 200

{
  "data":{
    "id":"192",
    "type":"entities",
    "attributes":{
      "currency_factor":"USD",
      "original_name":"Repeated Client",
      "model_type":"PERSON_NODE"
    },
    "links":{
      "self":"/v1/entities/192"
    }
  }
}

Response Codes:

  • 200 OK: Success
  • 403 Forbidden: Insufficient application permissions or appropriate scope not granted
  • 404 Not Found: Nonexistent/non-permissioned entities IDs

Get Position Owned Entity Details

Returns the owned entity.

GET /v1/positions/:id/owned

Example:

GET https://examplefirm.addepar.com/api/v1/positions/9/owned

HTTP/1.1 200

{
  "data":{
    "id":"23",
    "type":"entities",
    "attributes":{
      "currency_factor":"USD",
      "ownership_type":"PERCENT_BASED",
      "original_name":"Trust 1",
      "model_type":"TRUST",
      "is_rolled_up":false,
      "display_name":"Trust 1 Display Name"
    },
    "links":{
      "self":"/v1/entities/23"
    }
  }
}

Response Codes:

  • 200 OK: Success
  • 403 Forbidden: Insufficient application permissions or appropriate scope not granted
  • 404 Not Found: Nonexistent/non-permissioned entities IDs

Get Owner Relationship

Returns the relationship of the owner entity.

GET /v1/positions/:id/relationships/owner

GET https://examplefirm.addepar.com/api/v1/positions/9/relationships/owner

HTTP/1.1 200

{
  "data":{
    "id":192,
    "type":"entities"
  }
}

Response Codes:

  • 200 OK: Success
  • 403 Forbidden: Insufficient application permissions or appropriate scope not granted

Get Owned Relationship

Returns the relationship of the owned entity.

GET /v1/positions/:id/relationships/owned

GET https://examplefirm.addepar.com/api/v1/positions/9/relationships/owned

HTTP/1.1 200

{
  "data":{
    "id":23,
    "type":"entities"
  }
}

Response Codes:

  • 200 OK: Success
  • 403 Forbidden: Insufficient application permissions or appropriate scope not granted

Create a Position

Creates a new open position.

POST /v1/positions

Example:

In this example, we establish a position between an account (entity 27) and a stock (entity 29) with share-based ownership. This request schema also applies when creating a position for an asset with value-based ownership.

POST https://examplefirm.addepar.com/api/v1/positions

{
  "data":{
    "type":"positions",
    "attributes":{
      
    },
    "relationships":{
      "owner":{
        "data":{
          "type":"entities",
          "id":"27"
        }
      },
      "owned":{
        "data":{
          "type":"entities",
          "id":"29"
        }
      }
    }
  }
}

HTTP/1.1 201

{
  "data":{
    "id":"338",
    "type":"positions",
    "relationships":{
      "owner":{
        "links":{
          "self":"/v1/positions/338/relationships/owner",
          "related":"/v1/positions/338/owner"
        },
        "data":{
          "type":"entities",
          "id":"27"
        }
      },
      "owned":{
        "links":{
          "self":"/v1/positions/338/relationships/owned",
          "related":"/v1/positions/338/owned"
        },
        "data":{
          "type":"entities",
          "id":"29"
        }
      }
    },
    "links":{
      "self":"/v1/positions/338"
    }
  },
  "included":[
    
  ]
}

Example:

In this example, we establish a position between a person (entity 22) and a trust (entity 23), which has percent-based ownership. The attribute object of the request requires "incepting_open_position_date" and "incepting_open_position_ownership_percentage" in order to successfully create the position.

POST https://examplefirm.addepar.com/api/v1/positions

{
  "data":{
    "type":"positions",
    "attributes":{
      "incepting_open_position_date":"2001-01-01",
      "incepting_open_position_ownership_percentage":1.0
    },
    "relationships":{
      "owner":{
        "data":{
          "type":"entities",
          "id":"22"
        }
      },
      "owned":{
        "data":{
          "type":"entities",
          "id":"23"
        }
      }
    }
  }
}

HTTP/1.1 201

{
  "data":{
    "id":"340",
    "type":"positions",
    "attributes":{
      "incepting_open_position_date":"2001-01-01",
      "incepting_open_position_ownership_percentage":1.0
    },
    "relationships":{
      "owner":{
        "links":{
          "self":"/v1/positions/340/relationships/owner",
          "related":"/v1/positions/340/owner"
        },
        "data":{
          "type":"entities",
          "id":"22"
        }
      },
      "owned":{
        "links":{
          "self":"/v1/positions/340/relationships/owned",
          "related":"/v1/positions/340/owned"
        },
        "data":{
          "type":"entities",
          "id":"23"
        }
      }
    },
    "links":{
      "self":"/v1/positions/340"
    }
  },
  "included":[
    
  ]
}

Response Codes:

  • 201 Created: Successfully created the given position
  • 400 Bad Request: Invalid payload
  • 403 Forbidden: Insufficient application permissions or appropriate scope not granted
  • 404 Not Found: Nonexistent/non-permissioned entity ID or attribute
  • 409 Conflict: Incorrect "type"

Create Multiple Positions

Creates new open positions.

POST /v1/positions

Example: 

POST https://examplefirm.addepar.com/api/v1/positions

{
  "data":[
    {
      "type":"positions",
      "attributes":{
        "incepting_open_position_date":"2012-12-01",
        "incepting_open_position_ownership_percentage":1.0
      },
      "relationships":{
        "owner":{
          "data":{
            "type":"entities",
            "id":1
          }
        },
        "owned":{
          "data":{
            "type":"entities",
            "id":2
          }
        }
      }
    },
    {
      "type":"positions",
      "attributes":{
        "incepting_open_position_date":"2012-01-01",
        "incepting_open_position_ownership_percentage":1.0
      },
      "relationships ":{
        "owner":{
          "data":{
            "type":"entities",
            "id":3
          }
        },
        "owned":{
          "data":{
            "type":"entities",
            "id":4
          }
        }
      }
    }
  ]
}

HTTP/1.1 201

{
  "data": [ {
    "type": "positions",
    “id”: “100”,
    "attributes": {
      "incepting_open_position_date": "2012-12-01",
      “incepting_open_position_ownership_percentage”: 1.0
    },
    "relationships ": {
        "owner": {
	“links”: {
		     “self”: “/v1/positions/100/relationships/owner”,
		     “related”: “/v1/positions/100/owner”
		     },
            "data": {
   "type": "entities", 
}
      },
        "owned": {
	“links”: {
		     “self”: “/v1/positions/100/relationships/owned”,
		     “related”: “/v1/positions/100/owned”
		     },
            "data": {
    "type": "entities", 
    "id": 2
}
      }
    },
	“links”: {
	      “self”: “/v1/positions/100”
	}
       },
  {
    "type": "positions",
    “id”: “200”,
    "attributes": {
      "incepting_open_position_date": "2012-01-01",
      “incepting_open_position_ownership_percentage”: 1.0
    },
    "relationships ": {
        "owner": {
	“links”: {
		     “self”: “/v1/positions/200/relationships/owner”,
		     “related”: “/v1/positions/200/owner”
		     },
            "data": { 
    "type": "entities", 
    "id": 3 
}
      },
        "owned": {
	“links”: {
		     “self”: “/v1/positions/200/relationships/owned”,
		     “related”: “/v1/positions/200/owned”
		     },
            "data": { 
    "type": "entities", 
    "id": 4
}
   "id": 1
      }
    },
“links”: {
	      “self”: “/v1/positions/200”
	}
       }
   ]
}

Response Codes:

  • 201 OK: Success
  • 400 Bad Request: Invalid payload
  • 403 Forbidden: Insufficient application permissions or appropriate scope not granted
  • 404 Not Found: Nonexistent/non-permissioned entity ID or attribute
  • 409 Conflict: Incorrect "type"

Update a Position

Updates the specified position.

PATCH /v1/positions/:id

Example:

For a percent-based asset, update the open position date and ownership percentage. The response returns all position level attributes that have been assigned.

PATCH https://examplefirm.addepar.com/api/v1/positions/104

{
  "data":{
    "type":"positions",
    "id":"104",
    "attributes":{
      "incepting_open_position_date":"2010-01-01",
      "incepting_open_position_ownership_percentage":0.2
    }
  }
}

HTTP/1.1 200

{
  "data":{
    "id":"104",
    "type":"positions",
    "attributes":{
      "incepting_open_position_date":"2010-01-01",
      "incepting_open_position_ownership_percentage":0.2,
      "_custom_assett_class_1234":[
        {
          "date":null,
          "value":"cash",
          "weight":1.0
        }
      ],
      "display_name":"Did Both"
    },
    "relationships":{
      "owner":{
        "links":{
          "self":"/v1/positions/104/relationships/owner",
          "related":"/v1/positions/61581171/owner"
        },
        "data":{
          "type":"entities",
          "id":"123"
        }
      },
      "owned":{
        "links":{
          "self":"/v1/positions/104/relationships/owned",
          "related":"/v1/positions/104/owned"
        },
        "data":{
          "type":"entities",
          "id":"456"
        }
      }
    },
    "links":{
      "self":"/v1/positions/104"
    }
  },
  "included":[
    
  ]
}

Example:

Updates custom and standard position level attributes.

PATCH https://examplefirm.addepar.com/api/v1/positions/998

{
  "data":{
    "type":"positions",
    "id":"998",
    "attributes":{
      "_custom_balance_sheet_12345":[
        {
          "value":"Below The Line"
        }
      ],
      "display_name":"My Cash Asset"
    }
  }
}

HTTP/1.1 200

{
  "data":{
    "id":"998",
    "type":"positions",
    "attributes":{
      "_custom_balance_sheet_12345":[
        {
          "date":null,
          "value":"Below The Line",
          "weight":1.0
        }
      ],
      "display_name":"My Cash Asset"
    },
    "relationships":{
      "owner":{
        "links":{
          "self":"/v1/positions/998/relationships/owner",
          "related":"/v1/positions/998/owner"
        },
        "data":{
          "type":"entities",
          "id":"99"
        }
      },
      "owned":{
        "links":{
          "self":"/v1/positions/998/relationships/owned",
          "related":"/v1/positions/998/owned"
        },
        "data":{
          "type":"entities",
          "id":"100"
        }
      }
    },
    "links":{
      "self":"/v1/positions/998"
    }
  },
  "included":[
    
  ]
}

Response Codes:

  • 200 OK: Successfully modified the given position
  • 400 Bad Request: Invalid payload
  • 403 Forbidden: Insufficient application permissions or appropriate scope not granted
  • 404 Not Found: Nonexistent/non-permissioned position ID
  • 409 Conflict: IDs in the payload and URL do not match, or incorrect "type"

Update Multiple Positions

Updates the specified open positions.

PATCH /v1/positions

Example: 

PATCH https://examplefirm.addepar.com/api/v1/position

{
  "data":[
    {
      "type":"positions",
      "id":"13",
      "attributes":{
        "name":"Bob",
        "display_name":"Bob",
        "incepting_open_position_date":"2016-12-01",
        "incepting_open_position_value":5
      },
      "relationships":{
        "owner":{
          "data":{
            "type":"entities",
            "id":"1"
          }
        },
        "owned":{
          "data":{
            "type":"entities",
            "id":"2"
          }
        }
      }
    },
    {
      "type":"positions",
      "id":"14",
      "attributes":{
        "name":"Bob",
        "display_name":"Bob",
        "incepting_open_position_date":"2016-12-01",
        "incepting_open_position_value":5
      },
      "relationships":{
        "owner":{
          "data":{
            "type":"entities",
            "id":"1"
          }
        },
        "owned":{
          "data":{
            "type":"entities",
            "id":"2"
          }
        }
      }
    }
  ]
}

HTTP/1.1 200

{
  "data":[
    {
      "type":"positions",
      "id":"13",
      "attributes":{
        "name":"Bob",
        "display_name":"Bob",
        "incepting_open_position_date":"2016-12-01",
        "incepting_open_position_value":5
      },
      "relationships":{
        "owner":{
          "links":{
            "self":"/v1/positions/13/relationships/owner",
            "related":"/v1/positions/13/owner"
          },
          "data":{
            "type":"entities",
            "id":"1"
          }
        },
        "owned":{
          "links":{
            "self":"/v1/positions/13/relationships/owned",
            "related":"/v1/positions/13/owned"
          },
          "data":{
            "type":"entities",
            "id":"2"
          }
        }
      },
      "links":{
        "self":"/v1/positions/13"
      }
    },
    {
      "type":"positions",
      "id":"14",
      "attributes":{
        "name":"Bob",
        "display_name":"Bob",
        "incepting_open_position_date":"2016-12-01",
        "incepting_open_position_value":5
      },
      "relationships":{
        "owner":{
          "links":{
            "self":"/v1/positions/13/relationships/owner",
            "related":"/v1/positions/13/owner"
          },
          "data":{
            "type":"entities",
            "id":"1"
          }
        },
        "owned":{
          "links":{
            "self":"/v1/positions/13/relationships/owned",
            "related":"/v1/positions/13/owned"
          },
          "data":{
            "type":"entities",
            "id":"2"
          }
        }
      },
      "links":{
        "self":"/v1/positions/14"
      }
    }
  ]
}

Response Codes:

  • 200 OK: Success
  • 400 Bad Request: Invalid payload
  • 403 Forbidden: Insufficient application permissions or appropriate scope not granted
  • 404 Not Found: Nonexistent/non-permissioned position ID
  • 409 Conflict: Incorrect "type"

Delete a Position

Removes a specified position.

DELETE /v1/positions/:id

Example: 

DELETE https://examplefirm.addepar.com/api/v1/positions/100

HTTP/1.1 204

Response Codes:

  • 204 No Content: Successfully deleted the position
  • 400 Bad Request: Position is being referenced in transactions
  • 403 Forbidden: Insufficient application permissions or appropriate scope not granted
  • 404 Not Found: Nonexistent/non-permissioned position ID
  • 409 Conflict: IDs in the payload and URL do not match, or incorrect type

Delete Multiple Positions

Removes the specified positions.

DELETE /v1/positions

Example: 

DELETE https://examplefirm.addepar.com/api/v1/positions

{
  "data":[
    {
      "type":"positions",
      "id":"13"
    },
    {
      "type":"positions",
      "id":"14"
    }
  ]
}

HTTP/1.1 204

Response Codes:

  • 204 No Content: Successfully deleted the positions
  • 400 Bad Request: A position is being referenced in transactions
  • 403 Forbidden: Insufficient application permissions or appropriate scope not granted
  • 404 Not Found: Nonexistent/non-permissioned position IDs
  • 409 Conflict: Incorrect "type"

Updated 8 months ago