Estimated returns represent projected or expected return values for entities on specific dates. They can be used for forecasting and scenario analysis.

Resource overview

Estimated returns are described by the below attributes.

Get estimated returns

Returns estimated returns filtered by one or more entity IDs.

GET /v1/estimated_returns

• filter[entity_id]: Comma-separated list of entity IDs to filter by (required).
• page[after]: Cursor for pagination. The cursor is the composite ID of the last item from the previous page (optional).
• page[limit]: Maximum number of items to return per page (optional).

Example

GET https://examplefirm.addepar.com/api/v1/estimated_returns?filter[entity_id]=123

HTTP/1.1 200 OK

{
    "data": [
        {
            "id": "123_2024-01-15",
            "type": "estimated_returns",
            "attributes": {
                "entity_id": 123,
                "date": "2024-01-15",
                "return_value": 0.05
            }
        }
    ],
    "links": {
        "prev": null,
        "next": null
    }
}

Response codes

• 200 OK: Success
• 400 Bad Request: Missing or invalid filter[entity_id] parameter
• 403 Forbidden: Lacking necessary permissions
• 404 Not Found: Entity ID is nonexistent or not permissioned

Get a single estimated return

Returns a single estimated return by its composite ID.

GET /v1/estimated_returns/:id

• id: The composite ID in format {entityId}_{date} (e.g., 123_2024-01-15) (required).

Example

GET https://examplefirm.addepar.com/api/v1/estimated_returns/123_2024-01-15

HTTP/1.1 200 OK

{
    "data": {
        "id": "123_2024-01-15",
        "type": "estimated_returns",
        "attributes": {
            "entity_id": 123,
            "date": "2024-01-15",
            "return_value": 0.05
        }
    }
}

Response codes

• 200 OK: Success
• 400 Bad Request: Invalid ID format
• 403 Forbidden: Lacking necessary permissions
• 404 Not Found: Estimated return not found or entity not permissioned

Create or update estimated returns

Creates or updates estimated returns using upsert semantics. If an estimated return with the same entity ID and date already exists, it will be updated; otherwise, a new one will be created.

POST /v1/estimated_returns

Example (single)

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

{
    "data": {
        "type": "estimated_returns",
        "attributes": {
            "entity_id": 123,
            "date": "2024-01-15",
            "return_value": 0.05
        }
    }
}

Example (bulk)

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

{
    "data": [
        {
            "type": "estimated_returns",
            "attributes": {
                "entity_id": 123,
                "date": "2024-01-15",
                "return_value": 0.05
            }
        },
        {
            "type": "estimated_returns",
            "attributes": {
                "entity_id": 123,
                "date": "2024-02-15",
                "return_value": 0.03
            }
        }
    ]
}

HTTP/1.1 201 Created

{
    "data": [
        {
            "id": "123_2024-01-15",
            "type": "estimated_returns",
            "attributes": {
                "entity_id": 123,
                "date": "2024-01-15",
                "return_value": 0.05
            }
        }
    ]
}

Response codes

• 201 Created: Success
• 400 Bad Request: Invalid payload or missing required attributes
• 403 Forbidden: Lacking the required permissions to write estimated returns
• 404 Not Found: Entity ID is nonexistent or not permissioned

Update a single estimated return

Updates the return value of an existing estimated return. Only the return_value attribute can be modified; entity_id and date are immutable.

PATCH /v1/estimated_returns/:id

• id: The composite ID in format {entityId}_{date} (e.g., 123_2024-01-15) (required).

Example

PATCH https://examplefirm.addepar.com/api/v1/estimated_returns/123_2024-01-15

{
    "data": {
        "id": "123_2024-01-15",
        "type": "estimated_returns",
        "attributes": {
            "return_value": 0.07
        }
    }
}

HTTP/1.1 200 OK

{
    "data": {
        "id": "123_2024-01-15",
        "type": "estimated_returns",
        "attributes": {
            "entity_id": 123,
            "date": "2024-01-15",
            "return_value": 0.07
        }
    }
}

Response codes

• 200 OK: Success
• 400 Bad Request: Invalid payload or attempting to modify immutable attributes
• 403 Forbidden: Lacking the required permissions to write estimated returns
• 404 Not Found: Estimated return not found or entity not permissioned

Delete a single estimated return

Deletes a single estimated return.

DELETE /v1/estimated_returns/:id

• id: The composite ID in format {entityId}_{date} (e.g., 123_2024-01-15) (required).

Example

DELETE https://examplefirm.addepar.com/api/v1/estimated_returns/123_2024-01-15

HTTP/1.1 204 No Content

Response codes

• 204 No Content: Successfully deleted the estimated return
• 400 Bad Request: Invalid ID format
• 403 Forbidden: Lacking the required permissions to write estimated returns
• 404 Not Found: Estimated return not found or entity not permissioned

Delete all estimated returns for an entity

Deletes all estimated returns for a specific entity.

DELETE /v1/estimated_returns/entity/:entityId

• entityId: The entity ID (integer) (required).

Example

DELETE https://examplefirm.addepar.com/api/v1/estimated_returns/entity/123

HTTP/1.1 204 No Content

Response codes

• 204 No Content: Successfully deleted all estimated returns for the entity
• 400 Bad Request: Invalid entity ID format
• 403 Forbidden: Lacking the required permissions to write estimated returns
• 404 Not Found: Entity ID is nonexistent or not permissioned