Positions

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

Endpoints

GET
/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

Produces

JSON

Pagination

Yes

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 Scopes

S

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.

Attribute

Description

Example

e

Position name. String.

Required for cash positions.

Names must be different for cash positions that have the same owner and owned entities.

"

incepting_open_position_date

Date that ownership was established. String. “YYYY-MM-DD”

Required for Percent Based Assets.

Not applicable for Share Based Assets or Value Based Assets.

incepting_open_position_ownership_percentage

Percentage ownership. Number. (Percent, represented as a decimal)

Required for Percent Based Assets.

Not applicable for Share Based Assets or Value Based Assets.

5

Optional Attributes

Additional attributes can be applied to positions.

See Addepar Attributes

Relationships

Relationship

Description

r

The entity that holds the position.

d

The 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
    },
    "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
      },
      "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
  • 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 13 days ago


Positions


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.