Audit

Audit logs track changes to attribute values, transactions, reports, and user roles and permissions. Each entry represents an addition, modification, or deletion.

Overview


Base route	`/v1/audit_trail`
Produces	JSON
Pagination	Yes
OAuth scopes	`AUDIT_TRAIL`

📘
Access requirements
Requires "API Access: Create, edit, and delete" and "Manage firm settings: Audit logs" application permissions.

Resource attributes

These fields are common across audit trail response objects. Specific endpoints may return additional fields as documented in their respective sections.

Attribute	Description
`id`	String -- Unique identifier for the audit trail entry Example: `"AXhvvXcZjFzsG3PMeBgm"`
`type`	String -- Always `"audit_trail"` Example: `"audit_trail"`
`action`	String -- Operation performed (varies by object type) Example: `"login_attempt"`
`performed_by_user_id`	String -- User ID of the person who performed the action Example: `"993434"`
`source`	String -- Origin of the change. Values: `Manual` (in-app actions), `v1 API` (REST API calls), `In App Import` (Import Tool), `Import` (legacy import, may appear in older records) Example: `"Manual"`
`timestamp`	String -- Date and time in ISO 8601 format based on firm timezone Example: `"2021-03-26T18:13:11.059332Z"`
`old_value`	Object -- Value before the change (empty for add actions) Example: `{}`
`new_value`	Object -- Value after the change (empty for remove actions) Example: `{"value": "Ami Smith IRA"}`

Get login attempts

POST /v1/audit_trail

Retrieves a list of attempts by each user to sign into the application, Help Center, or Client Portal using Addepar credentials, SSO, or two-factor authentication.

📘
Authentication
All requests require a base64-encoded API key pair:
Authorization: Basic {base64(key_id:key_secret)}
See Access & Authentication for setup.

Request body parameters

Parameter	Description
`object_type`	Required. Must be `login_attempt`. Example: `"login_attempt"`
`start_date`	Required. First date of the audit period. Formats: `YYYY-MM-DD` (UTC assumed) or `YYYY-MM-DDThh:mm:ss` with timezone. If both dates are missing, defaults to today. Example: `"2021-03-26"`
`end_date`	Required. Last date of the audit period. Same format rules as `start_date`. Example: `"2021-03-30"`
`actions`	Operation filter. Valid: `Add`. If missing, all actions are included. Example: `["Add"]`
`user_type`	User scope. Valid: `firmusers`, `addeparusers`, `anyone`, `custom`. Example: `"firmusers"`
`users`	List of user IDs to query. Used when `user_type` is `custom`. If empty, defaults to all firm users. Example: `["993434", "429647"]`

curl -X POST "https://{firm}.addepar.com/api/v1/audit_trail" \
  -H "Authorization: Basic {base64(key_id:key_secret)}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
  "data": {
    "type": "audit_trail",
    "attributes": {
      "object_type": "login_attempt",
      "start_date": "2021-03-26",
      "end_date": "2021-03-30"
    }
  }
}'

{
  "data": [
    {
      "id": "AXhvvXcZjFzsG3PMeBgm",
      "type": "audit_trail",
      "attributes": {
        "performed_by_user_id": "993434",
        "action": "login_attempt",
        "source": "Manual",
        "timestamp": "2021-03-26T18:13:11.059332Z",
        "status": "successful"
      },
      "links": {
        "self": "/v1/audit_trail/AXhvvXcZjFzsG3PMeBgm"
      }
    },
    {
      "id": "AXhvvXcZjFzsG3PMeBgn",
      "type": "audit_trail",
      "attributes": {
        "performed_by_user_id": "429647",
        "action": "login_attempt",
        "source": "Manual",
        "timestamp": "2021-03-27T09:04:22.118442Z",
        "status": "password_incorrect"
      },
      "links": {
        "self": "/v1/audit_trail/AXhvvXcZjFzsG3PMeBgn"
      }
    }
  ],
  "included": [],
  "links": {
    "next": null
  }
}

{
  "errors": [
    {
      "id": "forbidden",
      "status": "403",
      "title": "Forbidden",
      "detail": "User does not have permission to see audit trails"
    }
  ]
}

Response-specific attributes

Attribute	Description
`status`	String -- Indicates whether the attempt was successful. Outputs for Addepar credentials: `locked_out`, `password_incorrect`, `successful`, `username_invalid`. Outputs for SSO: `sso_successful`, `sso_token_incorrect`. Outputs for two-factor: `two_factor_code_incorrect`, `two_factor_successful`, `two_factor_username_invalid`. Example: `"successful"`

Response codes

200 OK -- Success
403 Forbidden -- User does not have permission to see audit trails

Get attribute value changes

POST /v1/audit_trail

Retrieves a list of user changes to attribute values applied at the asset- and position-level. You can specify which actions to query.

Request body parameters

Parameter	Description
`object_type`	Required. Must be `attribute`. Example: `"attribute"`
`start_date`	Required. First date of the audit period. Formats: `YYYY-MM-DD` (UTC assumed) or `YYYY-MM-DDThh:mm:ss` with timezone. If both dates are missing, defaults to today. Example: `"2021-02-01"`
`end_date`	Required. Last date of the audit period. Same format rules as `start_date`. Example: `"2021-02-02"`
`actions`	Operation filter. Valid: `Add`, `Modify`, `Remove`. If missing, all actions are included. Example: `["Add"]`
`user_type`	User scope. Valid: `firmusers`, `addeparusers`, `anyone`, `custom`. Example: `"firmusers"`
`users`	List of user IDs to query. Used when `user_type` is `custom`. If empty, defaults to all firm users. Example: `["429647"]`

curl -X POST "https://{firm}.addepar.com/api/v1/audit_trail" \
  -H "Authorization: Basic {base64(key_id:key_secret)}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
  "data": {
    "type": "audit_trail",
    "attributes": {
      "object_type": "attribute",
      "start_date": "2021-02-01",
      "end_date": "2021-02-02",
      "actions": ["Add"]
    }
  }
}'

{
  "data": [
    {
      "id": "AXdjWf3wBGo8qwhMY-GY",
      "type": "audit_trail",
      "attributes": {
        "entity_type": "FINANCIAL_ACCOUNT",
        "entity_name": "Ami Smith IRA",
        "performed_by_user_id": "429647",
        "action": "add_entity_attribute",
        "attribute_name": "displayName",
        "old_value": {},
        "source": "Manual",
        "object_id": 1521518,
        "new_value": {
          "value": "Ami Smith IRA"
        },
        "timestamp": "2021-02-02T15:26:18.093818Z"
      },
      "links": {
        "self": "/v1/audit_trail/AXdjWf3wBGo8qwhMY-GY"
      }
    },
    {
      "id": "AXVWDBrDBGo8qwhMU1Qq",
      "type": "audit_trail",
      "attributes": {
        "performed_by_user_id": "489308",
        "owner_id": 9172603,
        "action": "add_position_attribute",
        "attribute_name": "Position name",
        "old_value": {},
        "source": "Manual",
        "object_id": 67285723,
        "owned_id": 9172604,
        "new_value": {},
        "timestamp": "2020-02-02T15:20:35.254635Z"
      },
      "links": {
        "self": "/v1/audit_trail/AXVWDBrDBGo8qwhMU1Qq"
      }
    }
  ],
  "included": [],
  "links": {
    "next": null
  }
}

{
  "errors": [
    {
      "id": "forbidden",
      "status": "403",
      "title": "Forbidden",
      "detail": "User does not have permission to see audit trails"
    }
  ]
}

Response-specific attributes

Attribute	Description
`action`	String -- Entity-level outputs: `add_entity_attribute`, `modify_entity_attribute`, `remove_entity_attribute`. Position-level outputs: `add_position_attribute`, `modify_position_attribute`, `remove_position_attribute`. Example: `"add_entity_attribute"`
`attribute_name`	String -- Name of the attribute. Example: `"displayName"`
`entity_name`	String -- Name of the entity. Only for entity-level changes. Example: `"Ami Smith IRA"`
`entity_type`	String -- Type of entity. Only for entity-level changes. Example: `"FINANCIAL_ACCOUNT"`
`new_value`	Object -- Value after the change. Empty for remove actions. Example: `{"value": "Ami Smith IRA"}`
`object_id`	Integer -- Attribute's unique identifier. Example: `1521518`
`old_value`	Object -- Value before the change. Empty for add actions. Example: `{}`
`owned_id`	Integer -- Unique identifier of the asset where the attribute is applied. Only for position-level changes. Example: `9172604`
`owned_name`	String -- Name of the asset where the attribute is applied. Only for position-level changes. Example: `"Abc Def LP"`
`owned_type`	String -- Type of entity where the attribute is applied. Only for position-level changes. Example: `"ASSET"`
`owner_id`	Integer -- Unique identifier of the entity that owns the asset. Only for position-level changes. Example: `9172603`
`owner_name`	String -- Name of the entity that owns the asset. Only for position-level changes. Example: `"Main Account"`
`owner_type`	String -- Type of the entity that owns the asset. Only for position-level changes. Example: `"FINANCIAL_ACCOUNT"`

Response codes

200 OK -- Success
403 Forbidden -- User does not have permission to see audit trails

Get transaction changes

POST /v1/audit_trail

Retrieves a list of user changes to transactions, snapshots, and valuations. You can specify which actions to query.

Request body parameters

Parameter	Description
`object_type`	Required. Must be `transaction`. Example: `"transaction"`
`start_date`	Required. First date of the audit period. Formats: `YYYY-MM-DD` (UTC assumed) or `YYYY-MM-DDThh:mm:ss` with timezone. If both dates are missing, defaults to today. Example: `"2021-03-15"`
`end_date`	Required. Last date of the audit period. Same format rules as `start_date`. Example: `"2021-04-30"`
`actions`	Operation filter. Valid: `Add`, `Modify`, `Remove`. If missing, all actions are included. Example: `["Modify"]`
`user_type`	User scope. Valid: `firmusers`, `addeparusers`, `anyone`, `custom`. Example: `"firmusers"`
`users`	List of user IDs to query. Used when `user_type` is `custom`. If empty, defaults to all firm users. Example: `["568215"]`

curl -X POST "https://{firm}.addepar.com/api/v1/audit_trail" \
  -H "Authorization: Basic {base64(key_id:key_secret)}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
  "data": {
    "type": "audit_trail",
    "attributes": {
      "object_type": "transaction",
      "start_date": "2021-03-15",
      "end_date": "2021-04-30",
      "actions": ["Modify"]
    }
  }
}'

{
  "data": [
    {
      "id": "AXkTzXRPIxTCzqh13ZoS",
      "type": "audit_trail",
      "attributes": {
        "transaction_id": "1050036245",
        "performed_by_user_id": "568215",
        "action": "modify_transaction",
        "old_value": {
          "values": {
            "base": 5000000.0
          },
          "units": {
            "cash": 5000000.0
          }
        },
        "source": "Manual",
        "new_value": {
          "values": {
            "base": 5100000.0
          },
          "units": {
            "cash": 5100000.0
          }
        },
        "timestamp": "2021-04-27T14:48:22.329990Z"
      },
      "links": {
        "self": "/v1/audit_trail/AXkTzXRPIxTCzqh13ZoS"
      }
    },
    {
      "id": "AXMlgAy1adBDjZjM5RMX",
      "type": "audit_trail",
      "attributes": {
        "performed_by_user_id": "589138",
        "action": "modify_snapshot",
        "old_value": {
          "entities": {
            "owner_id": 3433411,
            "owned_id": 3433415
          },
          "values": {
            "base": 397831.61
          },
          "comment": ""
        },
        "source": "Manual",
        "new_value": {
          "entities": {
            "owner_id": 3433411,
            "owned_id": 3433415
          },
          "values": {
            "base": 397832.61
          },
          "comment": "Test Edit"
        },
        "timestamp": "2020-04-27T19:00:15.668508Z"
      },
      "links": {
        "self": "/v1/audit_trail/AXMlgAy1adBDjZjM5RMX"
      }
    }
  ],
  "included": [],
  "links": {
    "next": null
  }
}

{
  "errors": [
    {
      "id": "forbidden",
      "status": "403",
      "title": "Forbidden",
      "detail": "User does not have permission to see audit trails"
    }
  ]
}

Response-specific attributes

Attribute	Description
`action`	String -- Transaction outputs: `add_transaction`, `modify_transaction`, `remove_transaction`. Snapshot outputs: `add_snapshot`, `modify_snapshot`, `remove_snapshot`. Valuation outputs: `add_valuation`, `modify_valuation`, `remove_valuation`. Example: `"modify_transaction"`
`new_value`	Object -- Value after the change. Empty for `remove_transaction`, `remove_snapshot`, `remove_valuation`. Example: `{"values": {"base": 5100000.0}}`
`old_value`	Object -- Value before the change. Empty for `add_transaction`, `add_snapshot`, `add_valuation`. Example: `{"values": {"base": 5000000.0}}`
`transaction_id`	String -- Unique identifier of the transaction. Only for transaction changes (not snapshots or valuations). Example: `"1050036245"`

Response codes

200 OK -- Success
403 Forbidden -- User does not have permission to see audit trails

Get role and permission changes

POST /v1/audit_trail

Retrieves a list of user changes to roles and user permissions.

Request body parameters

Parameter	Description
`object_type`	Required. Must be `permission`. Example: `"permission"`
`start_date`	Required. First date of the audit period. Formats: `YYYY-MM-DD` (UTC assumed) or `YYYY-MM-DDThh:mm:ss` with timezone. If both dates are missing, defaults to today. Example: `"2021-03-15"`
`end_date`	Required. Last date of the audit period. Same format rules as `start_date`. Example: `"2021-03-30"`
`actions`	Operation filter. Valid: `Add`, `Modify`, `Remove`. If missing, all actions are included. Example: `["Remove"]`
`user_type`	User scope. Valid: `firmusers`, `addeparusers`, `anyone`, `custom`. Example: `"anyone"`
`users`	List of user IDs to query. Used when `user_type` is `custom`. If empty, defaults to all firm users. Example: `["627858"]`

curl -X POST "https://{firm}.addepar.com/api/v1/audit_trail" \
  -H "Authorization: Basic {base64(key_id:key_secret)}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
  "data": {
    "type": "audit_trail",
    "attributes": {
      "object_type": "permission",
      "start_date": "2021-03-15",
      "end_date": "2021-03-30"
    }
  }
}'

{
  "data": [
    {
      "id": "AXg0eEfajFzsG3PMdPKT",
      "type": "audit_trail",
      "attributes": {
        "user_email": "[email protected]",
        "user_id": 826728,
        "user_name": "Addepar User",
        "action": "remove_user_permissions",
        "old_value": {
          "user_role": "FULL_ACCESS"
        },
        "source": "Manual",
        "new_value": {},
        "timestamp": "2021-03-15T06:00:01.241144Z"
      },
      "links": {
        "self": "/v1/audit_trail/AXg0eEfajFzsG3PMdPKT"
      }
    },
    {
      "id": "AXUOmW0sBGo8qwhMUyVP",
      "type": "audit_trail",
      "attributes": {
        "role_id": 400103,
        "performed_by_user_id": "627858",
        "action": "modify_role",
        "old_value": {},
        "source": "Manual",
        "new_value": {},
        "timestamp": "2020-03-15T18:22:17.387804Z"
      },
      "links": {
        "self": "/v1/audit_trail/AXUOmW0sBGo8qwhMUyVP"
      }
    }
  ],
  "included": [],
  "links": {
    "next": null
  }
}

{
  "errors": [
    {
      "id": "forbidden",
      "status": "403",
      "title": "Forbidden",
      "detail": "User does not have permission to see audit trails"
    }
  ]
}

Response-specific attributes

Attribute	Description
`action`	String -- Operation performed on roles or permissions. Example: `"remove_user_permissions"`
`new_value`	Object -- Value after the change. Example: `{}`
`old_value`	Object -- Value before the change. Example: `{"user_role": "FULL_ACCESS"}`
`role_id`	Integer -- Unique identifier of the role (for role changes). Example: `400103`
`user_email`	String -- Email address of the user. Example: `"[email protected]"`
`user_id`	Integer -- User ID of the user. Example: `826728`
`user_name`	String -- Name of the user. Example: `"Addepar User"`

Response codes

200 OK -- Success
403 Forbidden -- User does not have permission to see audit trails

Get a specific audit log entry

GET /v1/audit_trail/:id

Retrieves details about a specific user action. Use the POST endpoints above to obtain entry IDs.

curl -X GET "https://{firm}.addepar.com/api/v1/audit_trail/AXifSBFEeYH1_Q0j5iiH" \
  -H "Authorization: Basic {base64(key_id:key_secret)}" \
  -H "Accept: application/vnd.api+json"

{
  "data": {
    "id": "AXifSBFEeYH1_Q0j5iiH",
    "type": "audit_trail",
    "attributes": {
      "transaction_id": "150170",
      "performed_by_user_id": "3254",
      "vendor_id": "5f44be6d-9cb9-48cb-8cf0-3e7c9c2689d0",
      "action": "add_transaction",
      "old_value": {},
      "source": "Manual",
      "type": "TRANSFER_IN",
      "new_value": {
        "date": "2021-04-04",
        "settlement_date": "2021-04-02",
        "entities": {
          "owner_id": 1101,
          "owned_id": 1104
        },
        "values": {
          "base": 100.0
        },
        "currency": "USD",
        "units": {
          "base": 1.0
        },
        "affects_value": false,
        "affects_cost_basis": false,
        "affects_unfunded": false
      },
      "timestamp": "2021-04-04T23:46:43.622124Z",
      "is_reversal": false
    },
    "links": {
      "self": "/v1/audit_trail/AXifSBFEeYH1_Q0j5iiH"
    }
  },
  "included": []
}

{
  "errors": [
    {
      "id": "not_found",
      "status": "404",
      "title": "Not Found",
      "detail": "No audit trail found for the specified ID"
    }
  ]
}

Response codes

200 OK -- Success
403 Forbidden -- User does not have permission to see the audit trail
404 Not Found -- No audit trail found or non-permissioned audit trail ID

📘
Related resources

Access & Authentication

Entities

Transactions

Users