Snapshots

Snapshots are used to record the value of a share-based or percent-based asset on a single day. Valuations, on the other hand, are used to record the value of value-based assets like real estate, hedge funds, private equity, venture capital, and private funds.

Use the Snapshots API to get, create, update, and delete snapshots and valuations in Addepar. You can use the View API to extract existing saved views and Query API to retrieve snapshot and valuation data.


Base route	/v1/snapshots
Endpoints	GET /v1/snapshots/:id /v1/snapshots/:id/owner /v1/snapshots/:id/relationships/owner /v1/snapshots/:id/owned /v1/snapshots/:id/relationships/owned /v1/snapshots/:id/position /v1/snapshots/:id/relationships/position POST /v1/snapshots PATCH /v1/snapshots/:id /v1/snapshots DELETE /v1/snapshots/:id
Produces	JSON
Pagination	No
Application Permissions Required	"API Access: Create, edit, and delete" "Portfolio Access" determines the entities that are accessible.
OAuth Scopes	`TRANSACTIONS` or `TRANSACTIONS_WRITE`

Resource Overview

Snapshots and valuations are described by the below resource object attributes.

All attributes will be returned in successful GET responses.

Attribute	Description	Example
`type`	Either "snapshot" or "valuation". String.	`"snapshot"`
`currency`	Three-letter currency code, representing the snapshot or valuation's currency. String.	`"USD"`
`trade_date`	The date the snapshot or valuation occurred. String. "YYYY-MM-DD "	`"2023-01-25"`
`units`	The number of shares of a security. Number. Only required for snapshots on share-based assets.	`24.48`
`amount`	Default value of the snapshot or valuation. Number.	`1000`
`created_at`	Not editable and cannot be passed in. String.	`"2023-07-28T02:24:30Z"`
`modified_at`	Not editable and cannot be passed in. String.	`"2023-07-30T10:43:21Z"`
Optional Attributes	Additional attributes can be applied to snapshots and valuations. Multiple. See "Optional Snapshot and Valuation Attributes" below.	`"comment": After 2022 acquisition"`

Optional Snapshot and Valuation Attributes

Attribute	Description
`price_factor`	A multiplier affecting a security's total value. Note that this is called "Principal Factor" in Addepar. Number. Only applies to bond snapshots.
`accrued_income_per_unit`	Accrued income that the custodian may calculate and provide per-unit. Note that isn't the position's total accrued income. Number.
`comment`	Describes the snapshot or valuation, with a max length of 4,000 characters. String.

Relationship Overview

Relationship	Description
`owner`	The ID of the owning entity of the snapshot or valuation.
`owned`	The ID of the owned entity of the snapshot or valuation.
`position`	The ID of the position between the owner and owned entities.

"relationships": {
      "owner": {
        "links": {
          "self": "/v1/snapshots/1079/relationships/owner",
          "related": "/v1/snapshots/1079/owner"
        },
        "data": {
          "type": "entities",
          "id": "124"
        }
      },
      "position": {
        "links": {
          "self": "/v1/snapshots/1079/relationships/position",
          "related": "/v1/snapshots/1234/position"
        },
        "data": {
          "type": "positions",
          "id": "128"
        }
      },
      "owned": {
        "links": {
          "self": "/v1/snapshots/1079/relationships/owned",
          "related": "/v1/snapshots/1079/owned"
        }
      }
    }

Get a Snapshot

Returns a snapshot or valuation with the given ID.

GET /v1/snapshots/:id

Example:

GET https://examplefirm.addepar.com/api/v1/snapshots/37483253353524

HTTP/1.1 200 Success

{
    "data": {
        "id": "37483253353524",
        "type": "snapshots",
        "attributes": {
          	"created_at":"2023-07-28T02:24:30Z",
            "amount": -1000000.0,
            "currency": "USD",
            "comment": "",
            "units": 1000.0,
            "type": "snapshot",
            "trade_date": "2023-05-31",
            "modified_at":"2023-07-30T10:43:21Z"
        },
        "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: Nonexistent/non-permissioned snapshot or valuation

Get Snapshot Owner Entity

Returns the owner entity of the snapshot or valuation.

GET /v1/snapshots/:id/owner

Example:

GET https://examplefirm.addepar.com/api/v1/transactions/37483253353524/owner

HTTP/1.1 200 Success

{
  "data": {
    "id": "7644",
    "type": "entities",
    "attributes": {
      "last_verified_date": "2023-01-31",
      "currency_factor": "USD",
      "is_archived": false,
      "online_status": "OFFLINE",
      "ownership_type": "PERCENT_BASED",
      "original_name": "Test Account",
      "model_type": "FINANCIAL_ACCOUNT",
      "is_rolled_up": false,
      "wrapper": false
    },
    "links": {
      "self": "/v1/entities/7644"
    }
  },
  "included": []
}

Response Codes

200 OK: Success
404 Not Found: Nonexistent/non-permissioned snapshot or valuation
404 Not Found: Nonexistent/non-permissioned entity

Get Snapshot Owner Relationship

Returns the relationship of the owner entity.

GET /v1/snapshots/:id/relationships/owner

Example:

GET https://examplefirm.addepar.com/api/v1/snapshots/37483253353524/relationships/owned

HTTP/1.1 200 Success

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

Response Codes

200 OK: Success
404 Not Found: Nonexistent/non-permissioned snapshot or valuation

Get Snapshot Owned Entity

Returns the owned entity of the snapshot or valuation.

GET /v1/snapshots/:id/owned

Example:

GET https://examplefirm.addepar.com/api/v1/snapshots/37483253353524/owned

HTTP/1.1 200 Success

{
  "data": {
    "id": "54",
    "type": "entities",
    "attributes": {
      "currency_factor": "EUR",
      "is_archived": false,
      "ownership_type": "SHARE_BASED",
      "original_name": "Convertible Note 3",
      "model_type": "CONVERTIBLE_NOTE",
      "created_at": "2014-08-07T23:37:18Z",
      "modified_at": "2017-09-14T23:06:08Z"
    },
    "links": {
      "self": "/v1/entities/54"
    }
  },
  "included": []
}

Response Codes

200 OK: Success
404 Not Found: Nonexistent/non-permissioned snapshot or valuation
404 Not Found: Nonexistent/non-permissioned entity

Get Snapshot Owned Relationship

Returns the relationship of the owned entity.

GET /v1/snapshots/:id/relationships/owned

Example:

GET https://examplefirm.addepar.com/api/v1/snapshots/37483253353524/relationships/owned

HTTP/1.1 200 Success

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

Response Codes

200 OK: Success
404 Not Found: Nonexistent/non-permissioned snapshot or valuation

Get Snapshot Position

Returns the snapshot or valuation's position with the given ID.

GET /v1/snapshots/:id/cash_position

Example:

GET https://examplefirm.addepar.com/api/v1/snapshots/37483253353524/position

HTTP/1.1 200 Success

{
    "data": {
        "id": "17454",
        "type": "positions",
        "relationships": {
            "owner": {
                "links": {
                    "self": "/v1/positions/17454/relationships/owner",
                    "related": "/v1/positions/17454/owner"
                },
                "data": {
                    "type": "entities",
                    "id": "7644"
                }
            },
            "owned": {
                "links": {
                    "self": "/v1/positions/17454/relationships/owned",
                    "related": "/v1/positions/17454/owned"
                },
                "data": {
                    "type": "entities",
                    "id": "54"
                }
            }
        },
        "links": {
            "self": "/v1/positions/17454"
        }
    },
    "included": []
}

Response Codes

200 OK: Success
404 Not Found: Nonexistent/non-permissioned snapshot or valuation
404 Not Found: Nonexistent/non-permissioned entity

Get Snapshot Position Relationship

Returns the snapshot or valuation's position relationship.

GET /v1/snapshots/:id/relationships/position

Example:

GET https://examplefirm.addepar.com/api/v1/snapshots/3748325335352/relationships/position

HTTP/1.1 200 Success

{
  "data": {
    "id": 17454,
    "type": "positions"
  }
}

Response Codes

200 OK: Success
404 Not Found: Nonexistent/non-permissioned snapshot or valuation

Create a New Snapshot

Adds a new snapshot or valuation to your firm.

POST/v1/snapshots

Required Fields

type
currency
trade_date
amount
units required for snapshots, but not valuations

The following fields should be omitted from the object in the payload, since they will be generated when we save the object:

id
vendor_id
created_at
modified_at

Optional Fields

See "Optional Snapshot and Valuation Attributes" above.

Example:

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

{
  "data": [
    {
      "type": "snapshots",
      "attributes": {
        "amount": 1000.00,
        "currency": "USD",
        "comment": "This is a comment",
        "units": 10.0,
        "type": "snapshot",
        "trade_date": "2023-01-31"
      },
      "relationships": {
        "owner": {
          "data": {
            "type": "entities",
            "id": "22"
          }
        },
        "owned": {
          "data": {
            "type": "entities",
            "id": "34"
          }
        }
      }
    },
    {
      "type": "snapshots",
      "attributes": {
        "amount": 1000.00,
        "currency": "USD",
        "comment": "This is a comment",
        "units": 10.0,
        "type": "snapshot",
        "trade_date": "2023-02-01"
      },
      "relationships": {
        "owner": {
          "data": {
            "type": "entities",
            "id": "22"
          }
        },
        "owned": {
          "data": {
            "type": "entities",
            "id": "34"
          }
        }
      }
    }
  ]
}

HTTP/1.1 200 Success

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

Response Codes

201 Created: Success. Snapshot created and returns snapshot JSON
400 Bad Request: If a required field is missing
400 Bad Request: Non-supported type. Supported types are SNAPSHOT or VALUATION
400 Bad Request: If the snapshot fails to validate
403 Forbidden: If the user does not have write access for transactions

Update a Snapshot

Modifies an existing snapshot or valuation.

PATCH /v1/snapshots/:id

The following attribute fields cannot be updated:

vendor_id
created_at
modified_at
type
trade_date This will change the snapshot ID, so this update cannot be made via API.

The following relationship fields cannot be updated:

owner
owned
position

To remove an attribute field from a snapshot, set value to null.

Example:

This example removes a comment from a snapshot.

PATCH /v1/snapshots/:id

{
  "data": {
    "id": "344671144892",
    "type": "snapshots",
    "attributes": {
      "amount": 1000,
      "currency": "USD",
      "comment": null,
      "trade_date": "2023-01-31"
    }
  }
}

HTTP/1.1 200 Success

Response Codes

200 OK: Successfully modified the snapshot
400 Bad Request: Invalid payload
400 Bad Request: If the snapshot fails to validate
403 Forbidden: If the user does not have write access for transactions
404 Not Found: Nonexistent/non-permissioned transaction or snapshot

Update Multiple Snapshots

Modifies existing snapshots or valuations.

PATCH /v1/snapshots

The following attribute fields cannot be updated:

vendor_id
created_at
modified_at
type
trade_date This will change the snapshot ID, so this update cannot be made via API

The following relationship fields can not be updated:

owner
owned
position

To remove an attribute field from a snapshot, set value to null.

Example:

This example removes a comment from multiple snapshots.

PATCH /v1/snapshots

{
  "data": [
    {
      "id": "344671144892",
      "type": "snapshots",
      "attributes": {
        "comment": null
      }
    },
    {
      "id": "344671144893",
      "type": "snapshots",
      "attributes": {
        "comment": null
      }
    }
  ]
}

{
    "data": [
        {
            "id": "344671144892",
            "type": "snapshots",
            "attributes": {
                "amount": 1000.0,
                "created_at": "2023-08-23T03:05:03Z",
                "currency": "USD",
                "comment": "",
                "units": 10.0,
                "type": "snapshot",
                "modified_at": "2023-08-23T03:05:03Z",
                "trade_date": "2023-01-31"
            },
            "relationships": {
                "owner": {
                    "links": {
                        "self": "/v1/snapshots/344671144892/relationships/owner",
                        "related": "/v1/snapshots/344671144892/owner"
                    },
                    "data": {
                        "type": "entities",
                        "id": "22"
                    }
                },
                "owned": {
                    "links": {
                        "self": "/v1/snapshots/344671144892/relationships/owned",
                        "related": "/v1/snapshots/344671144892/owned"
                    },
                    "data": {
                        "type": "entities",
                        "id": "34"
                    }
                },
                "position": {
                    "links": {
                        "self": "/v1/snapshots/344671144892/relationships/position",
                        "related": "/v1/snapshots/344671144892/position"
                    },
                    "data": {
                        "type": "positions",
                        "id": "160"
                    }
                }
            },
            "links": {
                "self": "/v1/snapshots/344671144892"
            }
        },
        {
            "id": "344671144893",
            "type": "snapshots",
            "attributes": {
                "amount": 1000.0,
                "created_at": "2023-08-23T03:05:03Z",
                "currency": "USD",
                "comment": "",
                "units": 10.0,
                "type": "snapshot",
                "modified_at": "2023-08-23T03:05:03Z",
                "trade_date": "2023-02-01"
            },
            "relationships": {
                "owner": {
                    "links": {
                        "self": "/v1/snapshots/344671144893/relationships/owner",
                        "related": "/v1/snapshots/344671144893/owner"
                    },
                    "data": {
                        "type": "entities",
                        "id": "22"
                    }
                },
                "owned": {
                    "links": {
                        "self": "/v1/snapshots/344671144893/relationships/owned",
                        "related": "/v1/snapshots/344671144893/owned"
                    },
                    "data": {
                        "type": "entities",
                        "id": "34"
                    }
                },
                "position": {
                    "links": {
                        "self": "/v1/snapshots/344671144893/relationships/position",
                        "related": "/v1/snapshots/344671144893/position"
                    },
                    "data": {
                        "type": "positions",
                        "id": "160"
                    }
                }
            },
            "links": {
                "self": "/v1/snapshots/344671144893"
            }
        }
    ],
    "included": [],
    "links": {
        "prev": null,
        "next": null
    }
}

Response Codes

200 OK: Successfully modified the snapshots
400 Bad Request: Invalid payload
400 Bad Request: If the snapshot fails to validate
403 Forbidden: If the user does not have write access for transactions
404 Not Found: Nonexistent/non-permissioned snapshot

Delete Snapshot

Deletes an existing snapshot or valuation if it exists.

DELETE v1/snapshots/:id

DELETE https://examplefirm.addepar.com/api/v1/snapshots/1968

HTTP/1.1 204 No Content

Response Codes

204 No Content: Successfully deleted the snapshot
403 Forbidden: If the user does not have permission to delete the snapshot
404 Not Found: Nonexistent/non-permissioned snapshot ID