Audit

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

Audit logs can be downloaded directly in the application, or you can use the Audit API to retrieve the information.


Base Route	/v1/audit_trail
Endpoints	GET /v1/audit_trail/:id POST /v1/audit_trail
Produces	JSON
Pagination	Yes
Application Permissions Required	"API Access: Create, edit, and delete" and "Manage firm settings: Audit logs"
OAuth Scopes	`AUDIT_TRAIL`

See 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.

Example

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

{
   "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"
            }
        }
    ],
    "included": [],
    "links": {
        "next": null
    }
}

Request objects

Request Object	Description
`object_type`	Required. Type of audit log you're retrieving. Valid input: `login_attempt`
`start_date`	Required. First date of the time period you want to audit. Valid formats: `YYYY-MM-DD` Example: 2021-01-01. Timezone is assumed to be UTC. `YYYY-MM-DDThh:mm:ss` followed by a timezone. Example 1: 2021-01-01T00:00:00Z timezone is UTC as specified by "Z". Example 2: 2021-01-01T00:00:00-05:00 timezone is EST as specified by offset -05:00. If both `start_date` and `end_date` are missing, the time period will be today only. If one of them is missing, it will be set to equal the other one. You must specify both `start_date` and `end_date` if you want to use the `YYYY-MM-DDThh:mm:ss` format.
`end_date`	Required. Last date of the time period you want to audit. Valid formats: `YYYY-MM-DD` Example: 2021-01-01. Timezone is assumed to be UTC. `YYYY-MM-DDThh:mm:ss` followed by a timezone. Example 1: 2021-01-01T00:00:00Z timezone is UTC as specified by "Z". Example 2: 2021-01-01T00:00:00-05:00 timezone is EST as specified by offset -05:00. If both `start_date` and `end_date` are missing, the time period will be today only. If one of them is missing, it will be set to equal the other one. You must specify both `start_date` and `end_date` if you want to use the `YYYY-MM-DDThh:mm:ss` format.
`actions`	Operation performed. Valid input: `Add` If missing or empty, all actions will be included.
`user_type`	Valid inputs: `firmusers` includes users at your firms `addeparusers` includes Addepar employees `anyone` includes all firm users and Addepar employees `custom` allows you to specify certain `users`
`users`	List of IDs for the specific users you want to query. If `user_type: custom` but no users are specified, then all firm users will be included.

Response objects

Response Object	Description
`action`	Operation performed.
`performed_by_user_id`	User ID of the person who attempted to sign in.
`source`	`Manual` indicates that the action was performed manually in the application. `Import` indicates the action was performed using the Import Tool.
`status`	Indicates whether the attempt was successful. Outputs for attempts using Addepar credentials: `locked_out` `password_incorrect` `successful` `username_invalid` Outputs for attempts using SSO: `sso_successful` `sso_token_incorrect` Outputs for attempts using two-factor authentication: two_factor_code_incorrect``` two_factor_successful ````two_factor_username_invalid
`timestamp`	Date and time the attempt was made (ISO 8601 format) based on your firm's timezone.

Response codes:

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

See changes to attribute values

POST /v1/audit_trail

Retrieves a list user changes to attribute values applied at the asset- and position-level. You have the option to specify which actions you want to query.

Example

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

{
 "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
    }
}

Request objects

Request Object	Description
`object_type`	Required. Type of audit log you're retrieving. Valid input: `attribute`
`start_date`	Required. First date of the time period you want to audit. Valid formats: `YYYY-MM-DD` Example: 2021-01-01. Timezone is assumed to be UTC. `YYYY-MM-DDThh:mm:ss` followed by a timezone. Example 1: 2021-01-01T00:00:00Z timezone is UTC as specified by "Z". Example 2: 2021-01-01T00:00:00-05:00 timezone is EST as specified by offset -05:00. If both `start_date` and `end_date` are missing, the time period will be today only. If one of them is missing, it will be set to equal the other one. You must specify both `start_date` and `end_date` if you want to use the `YYYY-MM-DDThh:mm:ss` format.
`end_date`	Required. Last date of the time period you want to audit. Valid formats: `YYYY-MM-DD` Example: 2021-01-01. Timezone is assumed to be UTC. `YYYY-MM-DDThh:mm:ss` followed by a timezone. Example 1: 2021-01-01T00:00:00Z timezone is UTC as specified by "Z". Example 2: 2021-01-01T00:00:00-05:00 timezone is EST as specified by offset -05:00. If both `start_date` and `end_date` are missing, the time period will be today only. If one of them is missing, it will be set to equal the other one. You must specify both `start_date` and `end_date` if you want to use the `YYYY-MM-DDThh:mm:ss` format.
`actions`	Operation performed. Valid inputs: `Add` `Modify` `Remove` If missing or empty, all actions will be included.
`user_type`	Valid inputs: `firmusers` includes users at your firms `addeparusers` includes Addepar employees `anyone` includes all firm users and Addepar employees `custom` allows you to specify certain `users`
`users`	List of IDs for the specific users you want to query. If `user_type: custom` but no users are specified, then all firm users will be included.

Response objects

Response Object	Description
`action`	Operation performed. Outputs for changes to attributes applied at the entity-level: `add_entity_attribute` `modify_entity_attribute` `remove_entity_attribute` Outputs for changes to attributes applied at the position-level: `add_position_attribute` `modify_position_attribute` `remove_position_attribute`
`attribute_name`	Name of the attribute.
`entity_name`	Name of the entity. Only applicable for changes to attributes at the entity-level.
`entity_type`	Type of entity. Only applicable for changes to attributes at the entity-level.
`new_value`	Value after the change was made. Empty for remove_entity_attribute and remove_position_attribute actions.
`object_id`	Attribute's unique identifier.
`old_value`	Value before the change was made. Empty for add_entity_attribute and add_position_attribute actions.
`owned_id`	Unique identifier of the asset where the attribute is applied. Only applicable for changes to attributes at the position-level.
`owned_name`	Name of the asset where the attribute is applied. Only applicable for changes to attributes at the position-level.
`owned_type`	Type of entity where the attribute is applied. Only applicable for changes to attributes at the position-level.
`owner_id`	Unique identifier of the entity that directly owns the asset where the attribute is applied. Only applicable for changes to attributes at the position-level.
`owner_name`	Name of the entity that directly owns the asset where the attribute is applied. Only applicable for changes to attributes at the position-level.
`owner_type`	Name of the entity that directly owns the asset where the attribute is applied. Only applicable for changes to attributes at the position-level.
`performed_by_user_id`	User ID of the person who made the change.
`source`	`Manual` indicates that the action was performed manually in the application. `Import` indicates the action was performed using the Import Tool.
`timestamp`	Date and time the change was made (ISO 8601 format) based on your firm's timezone.

Response codes:

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

See changes to transactions, snapshots, and valuations

POST /v1/audit_trail

Retrieves a list user changes to transactions, snapshots, and valuations. You have the option to specify which actions you want to query.

Example

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

{
   "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"
            }
        },
        {
            "id": "AXkTzmpFIxTCzqh13ZoT",
            "type": "audit_trail",
            "attributes": {
                "performed_by_user_id": "568215",
                "action": "modify_valuation",
                "old_value": {
                    "entities": {
                        "owner_id": 1304930,
                        "owned_id": 3444734
                    },
                    "values": {
                        "base": 8000002.0
                    }
                },
                "source": "Manual",
                "new_value": {
                    "entities": {
                        "owner_id": 1304930,
                        "owned_id": 3444734
                    },
                    "values": {
                        "base": 8000003.0
                    }
                },
                "timestamp": "2021-04-27T14:49:25.311221Z"
            },
            "links": {
                "self": "/v1/audit_trail/AXkTzmpFIxTCzqh13ZoT"
            }
        }
    ],
    "included": [],
    "links": {
        "next": null
    }
}

Request objects

Request Object	Description
`object_type`	Required. Type of audit log you're retrieving. Valid input: `transaction`
`start_date`	Required. First date of the time period you want to audit. Valid formats: `YYYY-MM-DD` Example: 2021-01-01. Timezone is assumed to be UTC. `YYYY-MM-DDThh:mm:ss` followed by a timezone. Example 1: 2021-01-01T00:00:00Z timezone is UTC as specified by "Z". Example 2: 2021-01-01T00:00:00-05:00 timezone is EST as specified by offset -05:00. If both `start_date` and `end_date` are missing, the time period will be today only. If one of them is missing, it will be set to equal the other one. You must specify both `start_date` and `end_date` if you want to use the `YYYY-MM-DDThh:mm:ss` format.
`end_date`	Required. Last date of the time period you want to audit. Valid formats: `YYYY-MM-DD` Example: 2021-01-01. Timezone is assumed to be UTC. `YYYY-MM-DDThh:mm:ss` followed by a timezone. Example 1: 2021-01-01T00:00:00Z timezone is UTC as specified by "Z". Example 2: 2021-01-01T00:00:00-05:00 timezone is EST as specified by offset -05:00. If both `start_date` and `end_date` are missing, the time period will be today only. If one of them is missing, it will be set to equal the other one. You must specify both `start_date` and `end_date` if you want to use the `YYYY-MM-DDThh:mm:ss` format.
`actions`	Operation performed. Valid inputs: `Add` `Modify` `Remove` If missing or empty, all actions will be included.
`user_type`	Valid inputs: `firmusers` includes users at your firms `addeparusers` includes Addepar employees `anyone` includes all firm users and Addepar employees `custom` allows you to specify certain `users`
`users`	List of IDs for the specific users you want to query. If `user_type: custom` but no users are specified, then all firm users will be included.

Response objects

Response Object	Description
`action`	Operation performed. Outputs for changes to transactions: `add_transaction` `modify_transaction` `remove_transaction` Outputs for changes to snapshots: `add_snapshot` `modify_snapshot` `remove_snapshot` Outputs for changes to valuations: `add_valuation` `modify_valuation` `remove_valuation`
`new_value`	Value after the change was made. Empty for the following actions: `remove_transaction` `remove_snapshot` `remove_valuation`
`old_value`	Value before the change was made. Empty for the following actions: `add_transaction` `add_snapshot` `add_valuation`
`performed_by_user_id`	User ID of the person who made the change.
`source`	`Manual` indicates that the action was performed manually in the application. `Import` indicates the action was performed using the Import Tool.
`timestamp`	Date and time the change was made (ISO 8601 format) based on your firm's timezone.
`transaction_id`	Unique identifier of the transaction. Only applicable for changes to transactions, not snapshots or valuations.

Response codes:

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

See changes to reports

The Audit API is not currently available to retrieve changes to reports. You must use pull these audit logs directly from the application.

See changes to roles and permissions

POST /v1/audit_trail

Retrieves a list user changes to roles and user permissions.

Example

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

{
   "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
    }
}

Request objects

Request Object	Description
`object_type`	Required. Type of audit log you're retrieving. Valid input: `permission`
`start_date`	Required. First date of the time period you want to audit. Valid formats: `YYYY-MM-DD` Example: 2021-01-01. Timezone is assumed to be UTC. `YYYY-MM-DDThh:mm:ss` followed by a timezone. Example 1: 2021-01-01T00:00:00Z timezone is UTC as specified by "Z". Example 2: 2021-01-01T00:00:00-05:00 timezone is EST as specified by offset -05:00. If both `start_date` and `end_date` are missing, the time period will be today only. If one of them is missing, it will be set to equal the other one. You must specify both `start_date` and `end_date` if you want to use the `YYYY-MM-DDThh:mm:ss` format.
`end_date`	Required. Last date of the time period you want to audit. Valid formats: `YYYY-MM-DD` Example: 2021-01-01. Timezone is assumed to be UTC. `YYYY-MM-DDThh:mm:ss` followed by a timezone. Example 1: 2021-01-01T00:00:00Z timezone is UTC as specified by "Z". Example 2: 2021-01-01T00:00:00-05:00 timezone is EST as specified by offset -05:00. If both `start_date` and `end_date` are missing, the time period will be today only. If one of them is missing, it will be set to equal the other one. You must specify both `start_date` and `end_date` if you want to use the `YYYY-MM-DDThh:mm:ss` format.
`action`	Operation performed. Valid inputs: `Add` `Modify` `Remove` If missing or empty, all actions will be included.
`user_type`	Valid inputs: `firmusers` includes users at your firms `addeparusers` includes Addepar employees `anyone` includes all firm users and Addepar employees `custom` allows you to specify certain `users`
`users`	List of IDs for the specific users you want to query. If `user_type: custom` but no users are specified, then all firm users will be included.

Response objects

Response Object	Description
`action`	Operation performed.
`new_value`	Value after the change was made.
`old_value`	Value before the change was made.
`performed_by_user_id`	User ID of the person who made the change.
`source`	`Manual` indicates that the action was performed manually in the application. `Import` indicates the action was performed using the Import Tool.
`timestamp`	Date and time the change was made (ISO 8601 format) based on your firm's timezone.
`user_email`	Email address of the user.
`user_id`	User ID of the user.
`user_name`	Name of the user.

Response codes:

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

Get details about a specific Audit Log Entry ID

GET /v1/audit_trail/:id

Retrieves details about a specific user action. Use the endpoints listed above to get the entry ID.

Example

GET https://examplefirm.addepar.com/api/v1/audit_trail/AXifSBFEeYH1_Q0j5iiH

{
    "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": []
}

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