Users

Users are members of your firm that have access to Addepar. The Users API can be used to view, create, and delete users. You can also update user information, tool permissions, and portfolio access.

Base Route

/v1/users

Endpoints

GET
/v1/users/:id
/v1/users
/v1/users/:id/relationships/assigned_role
/v1/users/:id/relationships/permissioned_entities
/v1/users/:id/relationships/permissioned_groups

POST
v1/users/email_query
/v1/users/external_user_id_query
/v1/users
/v1/users/:id/relationships/permissioned_entities
/v1/users/:id/relationships/permissioned_groups

PATCH
/v1/users/:id
/v1/users/:id/relationships/assigned_role

DELETE
/v1/users/:id

Produces

JSON

Pagination

Yes

Application Permissions Required

"API Access: Create, edit, and delete"

"Manage firm settings: Users and permissions" for all operations.

OAuth Scopes

N/A

Resource Overview

Users are described by the below resource object attributes. Attributes required for creating, updating, or deleting Users are noted.

All attributes will be returned in successful GET, POST & PATCH responses containing the Users resource.

Attribute

Description

Example

l

The email address used for authentication. Not editable. String.

"

first_name

String.

"

last_name

String.

"

login_method

Not editable. String.

Supported values:

  • email_password
  • saml
"

saml_user_id

Not editable. String.

Required if login_method is "saml".

"

admin_access

Indicates whether the user has access to all permissions. Boolean.

e

all_data_access

Indicates whether the user has permission to access all current and future portfolio data. Boolean.

e

two_factor_auth_enabled

Indicates whether the user has two-factor authentication enabled. Not editable. Boolean.

e

external_user_id

Reflects the firm’s unique ID for the user, like the employee's ID number or ID from a human resources system, etc. String.

"

Relationships

Relationship

Description

e

The role that the user is assigned to.

s

The client portfolios the user has access to.

s

The groups the user has access to.

"relationships": {
        "permissioned_entities": {
          "links": {
            "self": "/v1/users/2000/relationships/permissioned_entities",
            "related": "/v1/users/2000/permissioned_entities"
          },
          "data": [
            {
               "type": "entities",
               "id": 10000
            },
            {
               "type": "entities",
               "id": 10001
            }
          ]
        },
        "assigned_role": {
          "links": {
            "self": "/v1/users/2000/relationships/assigned_role",
            "related": "/v1/users/2000/assigned_role"
          },
          "data": []
        },
        "permissioned_groups": {
          "links": {
            "self": "/v1/users/2000/relationships/permissioned_groups",
            "related": "/v1/users/2000/permissioned_groups"
          },
          "data": [
            {
               "type": "entities",
               "id": 20000
            },
            {
               "type": "entities",
               "id": 20001
            }
          ]
        }
      }

Get a User

Retrieves details for a specific user.

GET /v1/users/:id

Example:

GET https://examplefirm.addepar.com/api/v1/users/2000
HTTP/1.1 200

{
  "meta":{
    "exclude_self_link":false,
    "link":null,
    "pagination_params":null,
    "included_params":null,
    "filter_params":null,
    "fields_param":null
  },
  "data":{
    "id":"22",
    "type":"users",
    "attributes":{
      "two_factor_auth_enabled":false,
      "admin_access":true,
      "all_data_access":true,
      "login_method":"email_password",
      "email":"[email protected]"
    },
    "relationships":{
      "permissioned_entities":{
        "links":{
          "self":"/v1/users/22/relationships/permissioned_entities",
          "related":"/v1/users/22/permissioned_entities"
        },
        "data":[
          
        ]
      },
      "assigned_role":{
        "links":{
          "self":"/v1/users/22/relationships/assigned_role",
          "related":"/v1/users/22/assigned_role"
        },
        "data":null
      },
      "permissioned_groups":{
        "links":{
          "self":"/v1/users/22/relationships/permissioned_groups",
          "related":"/v1/users/22/permissioned_groups"
        },
        "data":[
          
        ]
      }
    },
    "links":{
      "self":"/v1/users/22"
    }
  },
  "included":[
    
  ]
}

Responses

  • 200 OK: Success
  • 403 Forbidden: User lacks sufficient application permissions
  • 404 Not Found: Nonexistent/non-permissioned user ID

Get All Users

Retrieves details for all users.

GET /v1/users

Example:

GET https://examplefirm.addepar.com/api/v1/users
HTTP/1.1 200

{
  "data": [
    {
      "id": "1000",
      "type": "users",
      "attributes": {
        "email": "[email protected]",
        "first_name": "Adam",
        "last_name": "Smith",
        "login_method": "email_password",
        "two_factor_auth_enabled": true,
        "admin_access": false,
        "all_data_access": true,
        "external_user_id": "A12345"
      },
      "relationships": {
        "permissioned_entities": {
          "links": {
            "self": "/v1/users/1000/relationships/permissioned_entities",
            "related": "/v1/users/1000/permissioned_entities"
          },
          "data": []
        },
        "assigned_role": {
          "links": {
            "self": "/v1/users/1000/relationships/assigned_role",
            "related": "/v1/users/1000/assigned_role"
          },
          "data": []
        },
        "permissioned_groups": {
          "links": {
            "self": "/v1/users/1000/relationships/permissioned_groups",
            "related": "/v1/users/1000/permissioned_groups"
          },
          "data": []
        }
      },
      "links": {
        "self": "/v1/users/1000"
      }
    },
    {
      "id": "2000",
      "type": "users",
      "attributes": {
        "email": "user2[email protected]",
        "first_name": "Jane",
        "last_name": "Smith",
        "login_method": "email_password",
        "two_factor_auth_enabled": true,
        "admin_access": false,
        "all_data_access": false,
        "external_user_id": "A67890"
      },
      "relationships": {
        "permissioned_entities": {
          "links": {
            "self": "/v1/users/2000/relationships/permissioned_entities",
            "related": "/v1/users/2000/permissioned_entities"
          },
          "data": [
            {
               "type": "entities",
               "id": 10000
            },
            {
               "type": "entities",
               "id": 10001
            }
          ]
        },
        "assigned_role": {
          "links": {
            "self": "/v1/users/2000/relationships/assigned_role",
            "related": "/v1/users/2000/assigned_role"
          },
          "data": []
        },
        "permissioned_groups": {
          "links": {
            "self": "/v1/users/2000/relationships/permissioned_groups",
            "related": "/v1/users/2000/permissioned_groups"
          },
          "data": [
            {
               "type": "entities",
               "id": 20000
            },
            {
               "type": "entities",
               "id": 20001
            }
          ]
        }
      },
      "links": {
        "self": "/v1/users/2000"
      }
    }
  ],
  "links": {
    "next": null
  }
}

Responses:

  • 200 OK: Success
  • 403 Forbidden: Lacking permission to view users

Get a User's Assigned Role

If no role is assigned to a user, data will return as null.

GET /v1/users/:user-id/relationships/assigned_role

Example:

GET https://examplefirm.addepar.com/api/v1/users/101/relationships/assigned_role
HTTP/1.1 200
      
{
  "data":{
    "id":"1",
    "type":"role"
  }
}

Response Codes:

  • 200 OK: Success
  • 400 Bad Request: Invalid relationship queried
  • 403 Forbidden: User lacks sufficient application permissions
  • 404 Not Found: Nonexistent/non-permissioned user ID

Get a User's Permissioned Entities Or Groups

Retrieves a list of IDs for the clients or group portfolios that the user has access to.

GET /v1/users/:user-id/relationships/permissioned_entities

GET /v1/users/:user-id/relationships/permissioned_groups

Example:

GET https://examplefirm.addepar.com/api/v1/users/5678/relationships/permissioned_groups
HTTP/1.1 200
      
{
  "data":[
    {
      "id":"10000",
      "type":"entities"
    }
  ]
}

Response Codes:

  • 200 OK: Success
  • 400 Bad Request: Invalid relationship queried
  • 403 Forbidden: User lacks sufficient application permissions
  • 404 Not Found: Nonexistent/non-permissioned user ID

Get Users by Email

Retrieves details for a specific user.

POST /v1/email_query

Example:

POST https://examplefirm.addepar.com/api/v1/email_query
      
{
  "data":{
    "type":"email_query",
    "attributes":{
      "email_ids":[
        "[email protected]",
        "[email protected]"
      ]
    }
  }
}
HTTP/1.1 200

{
  "data": [
    {
      "id": "1000",
      "type": "users",
      "attributes": {
        "email": "[email protected]ar.com",
        "first_name": "Adam",
        "last_name": "Smith",
        "login_method": "email_password",
        "two_factor_auth_enabled": true,
        "admin_access": false,
        "all_data_access": true,
        "external_user_id": "A12345"
      },
      "relationships": {
        "permissioned_entities": {
          "links": {
            "self": "/v1/users/1000/relationships/permissioned_entities",
            "related": "/v1/users/1000/permissioned_entities"
          },
          "data": []
        },
        "assigned_role": {
          "links": {
            "self": "/v1/users/1000/relationships/assigned_role",
            "related": "/v1/users/1000/assigned_role"
          },
          "data": []
        },
        "permissioned_groups": {
          "links": {
            "self": "/v1/users/1000/relationships/permissioned_groups",
            "related": "/v1/users/1000/permissioned_groups"
          },
          "data": []
        }
      },
      "links": {
        "self": "/v1/users/1000"
      }
    },
    {
      "id": "2000",
      "type": "users",
      "attributes": {
        "email": "[email protected]",
        "first_name": "Jane",
        "last_name": "Smith",
        "login_method": "email_password",
        "two_factor_auth_enabled": true,
        "admin_access": false,
        "all_data_access": false,
        "external_user_id": "A67890"
      },
      "relationships": {
        "permissioned_entities": {
          "links": {
            "self": "/v1/users/2000/relationships/permissioned_entities",
            "related": "/v1/users/2000/permissioned_entities"
          },
          "data": [
            {
               "type": "entities",
               "id": 10000
            },
            {
               "type": "entities",
               "id": 10001
            }
          ]
        },
        "assigned_role": {
          "links": {
            "self": "/v1/users/2000/relationships/assigned_role",
            "related": "/v1/users/2000/assigned_role"
          },
          "data": []
        },
        "permissioned_groups": {
          "links": {
            "self": "/v1/users/2000/relationships/permissioned_groups",
            "related": "/v1/users/2000/permissioned_groups"
          },
          "data": [
            {
               "type": "entities",
               "id": 20000
            },
            {
               "type": "entities",
               "id": 20001
            }
          ]
        }
      },
      "links": {
        "self": "/v1/users/2000"
      }
    }
  ],
  "links": {
    "next": null
  }
}

Response Codes:

  • 200 OK: Success
  • 403 Forbidden: User lacks sufficient application permissions

Get Users by External User ID

Retrieves details for a specific user.

POST /v1/external_user_id_query

Example:

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

{
  "data":{
    "type":"external_user_id_query",
    "attributes":{
      "external_user_ids":[
        "A12345",
        "A67890"
      ]
    }
  }
}
HTTP/1.1 200

{
  "data": [
    {
      "id": "1000",
      "type": "users",
      "attributes": {
        "email": "[email protected]",
        "first_name": "Adam",
        "last_name": "Smith",
        "login_method": "email_password",
        "two_factor_auth_enabled": true,
        "admin_access": false,
        "all_data_access": true,
        "external_user_id": "A12345"
      },
      "relationships": {
        "permissioned_entities": {
          "links": {
            "self": "/v1/users/1000/relationships/permissioned_entities",
            "related": "/v1/users/1000/permissioned_entities"
          },
          "data": []
        },
        "assigned_role": {
          "links": {
            "self": "/v1/users/1000/relationships/assigned_role",
            "related": "/v1/users/1000/assigned_role"
          },
          "data": []
        },
        "permissioned_groups": {
          "links": {
            "self": "/v1/users/1000/relationships/permissioned_groups",
            "related": "/v1/users/1000/permissioned_groups"
          },
          "data": []
        }
      },
      "links": {
        "self": "/v1/users/1000"
      }
    },
    {
      "id": "2000",
      "type": "users",
      "attributes": {
        "email": "[email protected]",
        "first_name": "Jane",
        "last_name": "Smith",
        "login_method": "email_password",
        "two_factor_auth_enabled": true,
        "admin_access": false,
        "all_data_access": false,
        "external_user_id": "A67890"
      },
      "relationships": {
        "permissioned_entities": {
          "links": {
            "self": "/v1/users/2000/relationships/permissioned_entities",
            "related": "/v1/users/2000/permissioned_entities"
          },
          "data": [
            {
               "type": "entities",
               "id": 10000
            },
            {
               "type": "entities",
               "id": 10001
            }
          ]
        },
        "assigned_role": {
          "links": {
            "self": "/v1/users/2000/relationships/assigned_role",
            "related": "/v1/users/2000/assigned_role"
          },
          "data": []
        },
        "permissioned_groups": {
          "links": {
            "self": "/v1/users/2000/relationships/permissioned_groups",
            "related": "/v1/users/2000/permissioned_groups"
          },
          "data": [
            {
               "type": "entities",
               "id": 20000
            },
            {
               "type": "entities",
               "id": 20001
            }
          ]
        }
      },
      "links": {
        "self": "/v1/users/2000"
      }
    }
  ],
  "links": {
    "next": null
  }
}

Responses:

  • 200 OK: Success
  • 403 Forbidden: User lacks sufficient application permissions

Create a User

By default, users are created in custom mode with no permissions. You can keep them in custom mode and manually assign permissions to each user in the Addepar application.

If you want to assign user permissions based upon a specific role, you can do so using the Update User Relationships method in the Users API or the Assign Role to Users method in the Roles API.

POST /v1/users

Example:

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

{
  "data":{
    "type":"users",
    "attributes":{
      "email":"[email protected]",
      "first_name":"Example",
      "last_name":"User",
      "login_method":"email_password"
    }
  }
}
HTTP/1.1 201

{
  "data":{
    "id":"82",
    "type":"users",
    "attributes":{
      "two_factor_auth_enabled":false,
      "admin_access":false,
      "all_data_access":false,
      "login_method":"email_password",
      "last_name":"User",
      "first_name":"Example",
      "email":"[email protected]"
    },
    "relationships":{
      "permissioned_entities":{
        "links":{
          "self":"/v1/users/82/relationships/permissioned_entities",
          "related":"/v1/users/82/permissioned_entities"
        },
        "data":[
          
        ]
      },
      "assigned_role":{
        "links":{
          "self":"/v1/users/82/relationships/assigned_role",
          "related":"/v1/users/82/assigned_role"
        },
        "data":null
      },
      "permissioned_groups":{
        "links":{
          "self":"/v1/users/82/relationships/permissioned_groups",
          "related":"/v1/users/82/permissioned_groups"
        },
        "data":[
          
        ]
      }
    },
    "links":{
      "self":"/v1/users/82"
    }
  },
  "included":[
    
  ]
}

Response Codes:

  • 201 Created: Success
  • 400 Bad Request: Invalid email provided
  • 400 Bad Request: SAML User ID already in use
  • 400 Bad Request: Email is already in use
  • 403 Forbidden: User lacks sufficient application permissions
  • 409 Conflict: A duplicate external_user_id exists for the firm

Add User's Access to Entities or Groups

Grants a user access to a specific client or group of portfolios.

POST /v1/users/:id/relationships/permissioned_entities

POST /v1/users/:id/relationships/permissioned_groups

Example:

POST https://examplefirm.addepar.com/api/v1/users/101/relationships/permissioned_groups

{
  "data":{
    "id":"10",
    "type":"groups"
  }
}
HTTP/1.1 204
  • 204 No Content: Success
  • 400 Bad Request: Nonexistent/non-permissioned client IDs
  • 404 Not Found: Nonexistent/non-permissioned user ID

Update a User

Updates the user's first_name, last_name, all_data_access, or admin_access.

PATCH /v1/users/:id

Example:

PATCH https://examplefirm.addepar.com/api/v1/users/101

{
  "data":{
    "type":"users",
    "id":"621500",
    "attributes":{
      "first_name":"Second",
      "last_name":"User"
    }
  }
}
HTTP/1.1 200

{
  "data":{
    "id":"621500",
    "type":"users",
    "attributes":{
      "two_factor_auth_enabled":false,
      "admin_access":false,
      "all_data_access":false,
      "login_method":"email_password",
      "last_name":"User",
      "first_name":"Second",
      "email":"[email protected]"
    },
    "relationships":{
      "permissioned_entities":{
        "links":{
          "self":"/v1/users/621500/relationships/permissioned_entities",
          "related":"/v1/users/621500/permissioned_entities"
        },
        "data":[
          
        ]
      },
      "assigned_role":{
        "links":{
          "self":"/v1/users/621500/relationships/assigned_role",
          "related":"/v1/users/621500/assigned_role"
        },
        "data":{
          "type":"roles",
          "id":"455914"
        }
      },
      "permissioned_groups":{
        "links":{
          "self":"/v1/users/621500/relationships/permissioned_groups",
          "related":"/v1/users/621500/permissioned_groups"
        },
        "data":[
          {
            "type":"groups",
            "id":"1020871"
          },
          {
            "type":"groups",
            "id":"1021710"
          },
          {
            "type":"groups",
            "id":"9559"
          }
        ]
      }
    },
    "links":{
      "self":"/v1/users/621500"
    }
  },
  "included":[
    
  ]
}

Response Codes

  • 200 OK: Success
  • 400 Bad Request: Attempted to update relationships
  • 403 Forbidden: User lacks sufficient application permissions
  • 404 Not Found: Nonexistent/non-permissioned user ID
  • 409 Conflict: A duplicate external user ID exists for the firm

Update a User's Role

📘

Note

Before using this method, you must assign a role to a user in the Addepar application.

PATCH /v1/users/:id/relationships/assigned_role

Example:

PATCH https://examplefirm.addepar.com/api/v1/users/101/relationships/assigned_role

{
  "data":{
    "id":"1",
    "type":"role"
  }
}
HTTP/1.1 204

Responses

  • 204 No Content: Success
  • 400 Bad Request: Nonexistent/non-permissioned role ID
  • 404 Not Found: Nonexistent/non-permissioned user ID

Delete a User

Removes a specified user.

DELETE /v1/users/:id

Example:

DELETE https://examplefirm.addepar.com/api/v1/users/101

{
  "data":{
    "type":"users",
    "id":"users",
    "attributes":{
      "first_name":"Example",
      "last_name":"User"
    }
  }
}
HTTP/1.1 204

Response Codes:

  • 204 No Content: Success
  • 403 Forbidden: User lacks sufficient application permissions
  • 404 Not Found: Nonexistent/non-permissioned user ID

Delete a User's Access to Entities or Groups

Removes access to specific client and group portfolios.

DELETE /v1/users/:id/relationships/permissioned_entities

DELETE /v1/users/:id/relationships/permissioned_groups

Example:

DELETE https://examplefirm.addepar.com/api/v1/users/101/relationships/permissioned_groups

{
  "data":[
    {
      "id":"1",
      "type":"groups"
    }
  ]
}
HTTP/1.1 204

Response Codes:

  • 400 Bad Request: Invalid relationship queried
  • 403 Forbidden: User lacks sufficient application permissions
  • 404 Not Found: Nonexistent/non-permissioned user ID

Updated 18 days ago


Users


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.