Snapshots

Snapshots record the value of a position on a specific date. A snapshot applies to share-based or percent-based assets (recording units and amount). A valuation applies to value-based assets like real estate, hedge funds, and private equity (recording amount only). Both use the same API endpoint and share the same resource structure.

Use this API to create, read, update, and delete point-in-time value records on positions.

Overview


Base route	`/v1/snapshots`
Produces	JSON
Pagination	No
Batch limit	500 per request (create, edit, delete)
OAuth scopes	`TRANSACTIONS` or `TRANSACTIONS_WRITE`

📘
Access requirements
API Access: Create, edit, and delete. Portfolio Access determines which entities' snapshots are visible.

Resource attributes

Attribute	Type	Description
`type`	String	`"snapshot"` (share/percent-based) or `"valuation"` (value-based). Required.
`currency`	String	Three-letter currency code. Required. Example: `"USD"`
`trade_date`	String	Date the value was recorded. Format: `YYYY-MM-DD`. Required.
`units`	Number	Number of shares. Required for snapshots, omit for valuations.
`amount`	Number	Total value. Required.
`created_at`	String	Read-only. ISO 8601 timestamp.
`modified_at`	String	Read-only. ISO 8601 timestamp.

Optional attributes:

Attribute	Description
`price_factor`	Multiplier affecting total value ("Principal Factor" in UI). Bonds only.
`accrued_income_per_unit`	Per-unit accrued income from custodian.
`comment`	Description, max 4,000 characters.
`knowledge_date`	Date the value was known or reported. Enables multiple snapshots on the same position and trade date. When set, the snapshot ID becomes `{computedId}_{knowledgeDate}` (e.g., `37483253353524_2026-03-31`).

Relationships

Every snapshot links to three entities:

Relationship	Description
`owner`	The owning entity (account, client).
`owned`	The owned entity (security, fund).
`position`	The position between owner and owned.

Access these via:

GET /v1/snapshots/:id/owner or /v1/snapshots/:id/owned or /v1/snapshots/:id/position for full entity/position details.
GET /v1/snapshots/:id/relationships/owner (or owned, position) for ID-only linkage data.

Get a snapshot

Returns a single snapshot or valuation by ID.

GET /v1/snapshots/:id

curl -X GET "https://{firm}.addepar.com/api/v1/snapshots/37483253353524" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Accept: application/vnd.api+json"

{
  "data": {
    "id": "37483253353524",
    "type": "snapshots",
    "attributes": {
      "created_at": "2023-07-28T02:24:30Z",
      "modified_at": "2023-07-30T10:43:21Z",
      "amount": -1000000.0,
      "currency": "USD",
      "comment": "",
      "units": 1000.0,
      "type": "snapshot",
      "trade_date": "2023-05-31"
    },
    "relationships": {
      "owner": {
        "links": {
          "self": "/v1/snapshots/37483253353524/relationships/owner",
          "related": "/v1/snapshots/37483253353524/owner"
        },
        "data": { "type": "entities", "id": "7644" }
      },
      "owned": {
        "links": {
          "self": "/v1/snapshots/37483253353524/relationships/owned",
          "related": "/v1/snapshots/37483253353524/owned"
        },
        "data": { "type": "entities", "id": "54" }
      },
      "position": {
        "links": {
          "self": "/v1/snapshots/37483253353524/relationships/position",
          "related": "/v1/snapshots/37483253353524/position"
        },
        "data": { "type": "positions", "id": "17454" }
      }
    },
    "links": { "self": "/v1/snapshots/37483253353524" }
  },
  "included": []
}

Response codes:

200 OK -- Success
404 Not Found -- Snapshot does not exist or not accessible

Create snapshots

Creates one or more snapshots or valuations (up to 500 per request). The request body is always an array.

POST /v1/snapshots

Required fields: type, currency, trade_date, amount. Also units for snapshots (not valuations).

Required relationships: owner and owned entity IDs. The position relationship is derived automatically.

curl -X POST "https://{firm}.addepar.com/api/v1/snapshots" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
  "data": [
    {
      "type": "snapshots",
      "attributes": {
        "amount": 1000.00,
        "currency": "USD",
        "comment": "Q1 valuation",
        "units": 10.0,
        "type": "snapshot",
        "trade_date": "2024-01-31"
      },
      "relationships": {
        "owner": { "data": { "type": "entities", "id": "22" } },
        "owned": { "data": { "type": "entities", "id": "34" } }
      }
    }
  ]
}'

{
  "data": [
    {
      "id": "344671144892",
      "type": "snapshots",
      "attributes": {
        "amount": 1000.0,
        "created_at": "2024-01-31T18:29:05Z",
        "currency": "USD",
        "comment": "Q1 valuation",
        "units": 10.0,
        "type": "snapshot",
        "modified_at": "2024-01-31T18:29:05Z",
        "trade_date": "2024-01-31"
      },
      "relationships": {
        "owner": { "data": { "type": "entities", "id": "22" } },
        "owned": { "data": { "type": "entities", "id": "34" } },
        "position": { "data": { "type": "positions", "id": "160" } }
      },
      "links": { "self": "/v1/snapshots/344671144892" }
    }
  ]
}

Response codes:

201 Created -- Success
400 Bad Request -- Missing required field, invalid type, or validation failure
403 Forbidden -- No write access for transactions

Edit snapshots

Updates one or more existing snapshots. Single snapshot uses /v1/snapshots/:id; bulk uses /v1/snapshots with an array body (up to 500).

PATCH /v1/snapshots/:id or PATCH /v1/snapshots

Immutable fields (cannot be updated):

type, trade_date, knowledge_date (these determine the snapshot ID)
vendor_id, created_at, modified_at (system-managed)
owner, owned, position relationships

Set an attribute to null to clear it.

curl -X PATCH "https://{firm}.addepar.com/api/v1/snapshots/344671144892" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
  "data": {
    "id": "344671144892",
    "type": "snapshots",
    "attributes": {
      "amount": 1200.00,
      "comment": null
    }
  }
}'

Response codes:

200 OK -- Success
400 Bad Request -- Invalid payload or validation failure
403 Forbidden -- No write access for transactions
404 Not Found -- Snapshot does not exist or not accessible

Delete snapshots

Deletes one or more existing snapshots. Single: /v1/snapshots/:id. Bulk: /v1/snapshots with array body (up to 500).

DELETE /v1/snapshots/:id or DELETE /v1/snapshots

curl -X DELETE "https://{firm}.addepar.com/api/v1/snapshots" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
  "data": [
    { "id": "344671144892", "type": "snapshots" },
    { "id": "344671144893", "type": "snapshots" }
  ]
}'

Response codes:

204 No Content -- Deleted
400 Bad Request -- Invalid payload
403 Forbidden -- No delete permission
404 Not Found -- Snapshot does not exist or not accessible
409 Conflict -- Incorrect type value

📘
Related

Positions -- The ownership links that snapshots record values for

Entities -- The owner and owned entities referenced in snapshot relationships

Transactions -- Financial events that create or modify position values

Transactions Query -- Retrieve snapshot data via bulk queries

Snapshots

Overview

📘
Access requirements

Resource attributes

Relationships

Get a snapshot

Create snapshots

Edit snapshots

Delete snapshots

📘
Related

Overview

📘Access requirements

Resource attributes

Relationships

Get a snapshot

Create snapshots

Edit snapshots

Delete snapshots

📘Related

📘
Access requirements

📘
Related