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/me /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	GET `USERS_WRITE` POST, PATCH, and DELETE `USERS_WRITE`except POST `v1/users/external_user_id_query` which requires `USERS` or `USERS_WRITE`

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
`email`	The email address used for authentication. Not editable. String.	`"[email protected]"`
`first_name`	String.	`"Adam"`
`last_name`	String.	`"Smith"`
`login_method`	Not editable. String. Supported values: - email_password - saml	`"email_password"`
`saml_user_id`	Not editable. String. Required if login_method is "saml".	`"asmith"`
`admin_access`	Indicates whether the user has access to all permissions. Boolean.	`false`
`all_data_access`	Indicates whether the user has permission to access all current and future portfolio data. Boolean.	`true`
`two_factor_auth_enabled`	Indicates whether the user has two-factor authentication enabled. Not editable. Boolean.	`true`
`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.	`"A67890"`

Relationships

Relationship	Description
`assigned_role`	The role that the user is assigned to.
`permissioned_entities`	The client portfolios the user has access to.
`permissioned_groups`	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": "[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 current user

Retrieves details for the currently authenticated user. This is the user who created the API key that was used to authenticate the request.

GET /v1/users/me

Example:

GET https://examplefirm.addepar.com/api/v1/users/me

HTTP/1.1 200
      
{
    "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": {
                "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": []
}

Response Codes:

200 OK: Success
401 Unauthorized: The API key is invalid

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/users/email_query

Example:

POST https://examplefirm.addepar.com/api/v1/users/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]",
        "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/users/external_user_id_query

Example:

POST https://examplefirm.addepar.com/api/v1/users/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

Resource overview

Relationships

Get a user

Get all users

Get current user

Get a user's assigned role

Get a user's permissioned entities or groups

Get users by email

Get users by external user ID

Create a user

Add user's access to entities or groups

Update a user

Update a user's role

📘Note

Delete a user

Delete a user's access to entities or groups

📘
Note