Estimated Returns

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

Access requirements

All requests require an API key with "API Access: Create, edit, and delete" application permissions.

Resource 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).

Authentication

This endpoint requires a valid API key or OAuth token. See Authentication for details.

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

{
    "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).

GET https://{firm}.addepar.com/api/v1/estimated_returns/123_2024-01-15

{
    "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://{firm}.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://{firm}.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
            }
        }
    ]
}

{
    "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).

PATCH https://{firm}.addepar.com/api/v1/estimated_returns/123_2024-01-15

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

{
    "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).

DELETE https://{firm}.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).

DELETE https://{firm}.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

Related resources

Positions | Portfolio Query