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
EndpointsGET
/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
ProducesJSON
PaginationNo
Application Permissions Required"API Access: Create, edit, and delete"

"Portfolio Access" determines the entities that are accessible.
OAuth ScopesTRANSACTIONS 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.

AttributeDescriptionExample
typeEither "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"
unitsThe number of shares of a security. Number.

Only required for snapshots on share-based assets.
24.48
amountDefault value of the snapshot or valuation. Number.1000
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 snapshots and valuations. Multiple.

See "Optional Snapshot and Valuation Attributes" below.
"comment": After 2022 acquisition"

Optional Snapshot and Valuation Attributes

AttributeDescription
price_factorA 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_unitAccrued income that the custodian may calculate and provide per-unit. Note that isn't the position's total accrued income. Number.
commentDescribes the snapshot or valuation, with a max length of 4,000 characters. String.

Relationship Overview

RelationshipDescription
ownerThe ID of the owning entity of the snapshot or valuation.
ownedThe ID of the owned entity of the snapshot or valuation.
positionThe 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