Contacts
Contacts are individuals who can access the Client Portal. Use the Contacts API to create, view, update, and delete contacts, manage their entity and group affiliations, and control portal access, 2FA, and SSO settings.
Overview
| Base route | /v1/contacts |
| Produces | JSON |
| Pagination | Yes |
| OAuth scopes | GET USERS; POST, PATCH, DELETE USERS_WRITE |
Access requirements
Application permissions: "API Access: Create, edit, and delete" and "Full Access" for all operations.
Resource attributes
| Attribute | Type | Description |
|---|---|---|
title | String | The contact's title. Max 10 characters. Example: "Mr." |
first_name | String | Required. The contact's first name. Max 40 characters. |
last_name | String | Required. The contact's last name. Max 80 characters. |
suffix | String | The contact's suffix. Max 10 characters. Example: "Jr." |
external_user_id | String | The firm's unique ID for the user. Max 31 characters. |
login_email | String | The email address the contact uses to sign in to the Portal. Cannot be deleted once set. |
portal_access | String | Read-only. The contact's portal access status. Values: "deactivated", "activated", "invited", "revoked". |
birthday | String | The contact's birthday. Format: YYYY-MM-DD. |
employer | String | The contact's employer. Max 80 characters. |
occupation | String | The contact's occupation. Max 80 characters. |
ssn | String | The contact's Social Security number. Max 9 characters. |
is_exempt_from_two_factor_requirement | Boolean | Read-only. 2FA exemption status. Only returned for active contacts when the firm requires 2FA. |
mailing_addresses | Array | The contact's mailing addresses. See nested objects below. |
emails | Array | The contact's email addresses. See nested objects below. |
phone_numbers | Array | The contact's phone numbers. See nested objects below. |
family_members | Array | The contact's family members. See nested objects below. |
saml_settings | Object | SSO settings (SAML 2.0). Only returned if the firm has SAML enabled. |
view_set_overrides | Array | Read-only. View set overrides for the contact's portfolios. |
Mailing address objects
| Field | Type | Description |
|---|---|---|
street | String | Required. First line. Max 80 characters. |
street2 | String | Second line. Max 80 characters. |
city | String | Required. Max 80 characters. |
state | String | Required. Max 80 characters. |
zip | String | Required. Max 10 characters. |
country | String | Max 80 characters. |
address_type | String | Address type (e.g., "Work", "Home"). Max 80 characters. |
Email address objects
| Field | Type | Description |
|---|---|---|
email | String | Required. The email address. |
email_type | String | Required. Values: PERSONAL, WORK, FAMILY, OTHER. |
Phone number objects
| Field | Type | Description |
|---|---|---|
number | String | Required. Max 15 characters. |
phone_type | String | Required. Values: HOME, WORK, CELL, FAX, OTHER. |
Family member objects
| Field | Type | Description |
|---|---|---|
first_name | String | Required. Max 40 characters. |
last_name | String | Required. Max 80 characters. |
relationship | String | Required. Values: SPOUSE, MOTHER, FATHER, SISTER, BROTHER, DAUGHTER, SON, GRANDMOTHER, GRANDFATHER, GRANDDAUGHTER, GRANDSON, AUNT, UNCLE, COUSIN, OTHER. |
Relationships
| Relationship | Description |
|---|---|
entity_affiliations | Entities affiliated with this contact. |
group_affiliations | Groups affiliated with this contact. |
default_view_set | The default view set assigned to this contact. |
team | The contact's team assignment. |
Get a contact
Returns a single contact with all attributes and relationships.
GET /v1/contacts/:id
curl -X GET "https://{firm}.addepar.com/api/v1/contacts/2000" \
-H "Authorization: Basic {credentials}" \
-H "Addepar-Firm: 1" \
-H "Accept: application/vnd.api+json"
{
"data": {
"id": "2000",
"type": "contacts",
"attributes": {
"title": "Mr.",
"first_name": "Adam",
"last_name": "Smith",
"suffix": "Jr.",
"external_user_id": "abc123",
"login_email": "[email protected]",
"portal_access": "deactivated",
"birthday": "1990-10-31",
"employer": "Addepar",
"occupation": "Financial Services",
"ssn": "123456789",
"mailing_addresses": [
{
"street": "335 Madison Ave",
"street2": "25th Floor",
"city": "New York",
"state": "New York",
"zip": "10017",
"country": "United States",
"address_type": "Work"
}
],
"emails": [
{ "email": "[email protected]", "email_type": "WORK" }
],
"phone_numbers": [
{ "number": "0987654321", "phone_type": "WORK" }
],
"family_members": [
{ "first_name": "Addison", "last_name": "Smith", "relationship": "SISTER" }
],
"view_set_overrides": []
},
"relationships": {
"entity_affiliations": {
"links": {
"self": "/v1/contacts/2000/relationships/entity_affiliations",
"related": "/v1/contacts/2000/entity_affiliations"
},
"data": [
{ "type": "entities", "id": "22" }
]
},
"group_affiliations": {
"links": {
"self": "/v1/contacts/2000/relationships/group_affiliations",
"related": "/v1/contacts/2000/group_affiliations"
},
"data": []
},
"default_view_set": {
"data": null
},
"team": {
"data": null
}
},
"links": { "self": "/v1/contacts/2000" }
}
}
{
"errors": [
{
"id": "not_found",
"status": "404",
"title": "Not Found",
"detail": "Contact with id 2000 not found."
}
]
}
Response codes:
200 OK-- Success403 Forbidden-- Insufficient permissions404 Not Found-- Contact not found
Get all contacts
Returns all contacts. Results are paginated.
GET /v1/contacts
curl -X GET "https://{firm}.addepar.com/api/v1/contacts" \
-H "Authorization: Basic {credentials}" \
-H "Addepar-Firm: 1" \
-H "Accept: application/vnd.api+json"
{
"data": [
{
"id": "2000",
"type": "contacts",
"attributes": {
"title": "Mr.",
"first_name": "Adam",
"last_name": "Smith",
"suffix": "Jr.",
"login_email": "[email protected]",
"portal_access": "deactivated"
},
"links": { "self": "/v1/contacts/2000" }
},
{
"id": "2001",
"type": "contacts",
"attributes": {
"title": "Ms.",
"first_name": "Jane",
"last_name": "Doe",
"suffix": null,
"login_email": "[email protected]",
"portal_access": "activated"
},
"links": { "self": "/v1/contacts/2001" }
}
],
"links": {
"next": "/v1/contacts?page%5Bnumber%5D=2&page%5Bsize%5D=25"
}
}
Response codes:
200 OK-- Success403 Forbidden-- Insufficient permissions
Get entity or group affiliations
Returns the IDs of entities or groups affiliated with a contact.
GET /v1/contacts/:id/relationships/entity_affiliations
GET /v1/contacts/:id/relationships/group_affiliations
curl -X GET "https://{firm}.addepar.com/api/v1/contacts/2000/relationships/entity_affiliations" \
-H "Authorization: Basic {credentials}" \
-H "Addepar-Firm: 1" \
-H "Accept: application/vnd.api+json"
{
"data": [
{ "id": "10000", "type": "entities" },
{ "id": "10001", "type": "entities" }
],
"links": {
"self": "/v1/contacts/2000/relationships/entity_affiliations"
}
}
Response codes:
200 OK-- Success403 Forbidden-- Insufficient permissions404 Not Found-- Contact not found
Get the default view set
Returns the ID of the default view set assigned to a contact.
GET /v1/contacts/:id/relationships/default_view_set
curl -X GET "https://{firm}.addepar.com/api/v1/contacts/2000/relationships/default_view_set" \
-H "Authorization: Basic {credentials}" \
-H "Addepar-Firm: 1" \
-H "Accept: application/vnd.api+json"
{
"data": {
"id": "10000",
"type": "view_sets"
},
"links": {
"self": "/v1/contacts/2000/relationships/default_view_set"
}
}
Response codes:
200 OK-- Success403 Forbidden-- Insufficient permissions404 Not Found-- Contact not found
Get team
Returns the ID of the contact's team.
GET /v1/contacts/:id/relationships/team
curl -X GET "https://{firm}.addepar.com/api/v1/contacts/2000/relationships/team" \
-H "Authorization: Basic {credentials}" \
-H "Addepar-Firm: 1" \
-H "Accept: application/vnd.api+json"
{
"data": {
"id": "1",
"type": "teams"
},
"links": {
"self": "/v1/contacts/2000/relationships/team"
}
}
Response codes:
200 OK-- Success403 Forbidden-- Insufficient permissions404 Not Found-- Contact or team not found
Create a contact
Creates a new contact. first_name and last_name are required.
POST /v1/contacts
curl -X POST "https://{firm}.addepar.com/api/v1/contacts" \
-H "Authorization: Basic {credentials}" \
-H "Addepar-Firm: 1" \
-H "Content-Type: application/vnd.api+json" \
-H "Accept: application/vnd.api+json" \
-d '{
"data": {
"type": "contacts",
"attributes": {
"title": "Mr.",
"first_name": "Adam",
"last_name": "Smith",
"suffix": "Jr.",
"external_user_id": "abc123",
"login_email": "[email protected]",
"birthday": "1990-10-31",
"employer": "Addepar",
"occupation": "Financial Services",
"ssn": "123456789",
"mailing_addresses": [
{
"street": "335 Madison Ave",
"street2": "25th Floor",
"city": "New York",
"state": "New York",
"zip": "10017",
"country": "United States",
"address_type": "Work"
}
],
"emails": [
{ "email": "[email protected]", "email_type": "WORK" }
],
"phone_numbers": [
{ "number": "0987654321", "phone_type": "WORK" }
],
"family_members": [
{ "first_name": "Addison", "last_name": "Smith", "relationship": "SISTER" }
]
}
}
}'
{
"data": {
"id": "2000",
"type": "contacts",
"attributes": {
"title": "Mr.",
"first_name": "Adam",
"last_name": "Smith",
"suffix": "Jr.",
"external_user_id": "abc123",
"login_email": "[email protected]",
"portal_access": "deactivated",
"birthday": "1990-10-31",
"employer": "Addepar",
"occupation": "Financial Services",
"ssn": "123456789",
"mailing_addresses": [
{
"street": "335 Madison Ave",
"street2": "25th Floor",
"city": "New York",
"state": "New York",
"zip": "10017",
"country": "United States",
"address_type": "Work"
}
],
"emails": [
{ "email": "[email protected]", "email_type": "WORK" }
],
"phone_numbers": [
{ "number": "0987654321", "phone_type": "WORK" }
],
"family_members": [
{ "first_name": "Addison", "last_name": "Smith", "relationship": "SISTER" }
],
"view_set_overrides": []
},
"relationships": {
"entity_affiliations": {
"links": {
"self": "/v1/contacts/2000/relationships/entity_affiliations",
"related": "/v1/contacts/2000/entity_affiliations"
},
"data": []
},
"group_affiliations": {
"links": {
"self": "/v1/contacts/2000/relationships/group_affiliations",
"related": "/v1/contacts/2000/group_affiliations"
},
"data": []
},
"default_view_set": {
"data": null
},
"team": {
"data": null
}
},
"links": { "self": "/v1/contacts/2000" }
}
}
Response codes:
201 Created-- Success400 Bad Request-- Missing required fields or invalid login email403 Forbidden-- Insufficient permissions; team and view set team do not match404 Not Found-- Group, entity, or view set not found409 Conflict-- Duplicate external user ID or login email
Add entity or group affiliations
Appends entities or groups to a contact's affiliations.
POST /v1/contacts/:id/relationships/entity_affiliations
POST /v1/contacts/:id/relationships/group_affiliations
curl -X POST "https://{firm}.addepar.com/api/v1/contacts/2000/relationships/group_affiliations" \
-H "Authorization: Basic {credentials}" \
-H "Addepar-Firm: 1" \
-H "Content-Type: application/vnd.api+json" \
-H "Accept: application/vnd.api+json" \
-d '{
"data": [
{ "id": "10000", "type": "groups" }
]
}'
Response: 204 No Content on success.
Response codes:
204 No Content-- Success403 Forbidden-- Insufficient permissions404 Not Found-- Contact, group, or entity not found
Set the default view set
Assigns a view set as the default for a contact.
POST /v1/contacts/:id/relationships/default_view_set
curl -X POST "https://{firm}.addepar.com/api/v1/contacts/2000/relationships/default_view_set" \
-H "Authorization: Basic {credentials}" \
-H "Addepar-Firm: 1" \
-H "Content-Type: application/vnd.api+json" \
-H "Accept: application/vnd.api+json" \
-d '{
"data": {
"id": "10000",
"type": "view_sets"
}
}'
Response: 204 No Content on success.
Response codes:
204 No Content-- Success403 Forbidden-- Insufficient permissions; team and view set team do not match404 Not Found-- Contact or view set not found
Edit a contact
Updates a contact. Include only the attributes you want to change.
PATCH /v1/contacts/:id
curl -X PATCH "https://{firm}.addepar.com/api/v1/contacts/2000" \
-H "Authorization: Basic {credentials}" \
-H "Addepar-Firm: 1" \
-H "Content-Type: application/vnd.api+json" \
-H "Accept: application/vnd.api+json" \
-d '{
"data": {
"id": "2000",
"type": "contacts",
"attributes": {
"first_name": "Second",
"last_name": "User"
}
}
}'
{
"data": {
"id": "2000",
"type": "contacts",
"attributes": {
"title": "Mr.",
"first_name": "Second",
"last_name": "User",
"suffix": "Jr.",
"external_user_id": "abc123",
"login_email": "[email protected]",
"portal_access": "deactivated",
"birthday": "1990-10-31",
"employer": "Addepar",
"occupation": "Financial Services",
"ssn": "123456789",
"mailing_addresses": [
{
"street": "335 Madison Ave",
"street2": "25th Floor",
"city": "New York",
"state": "New York",
"zip": "10017",
"country": "United States",
"address_type": "Work"
}
],
"emails": [
{ "email": "[email protected]", "email_type": "WORK" }
],
"phone_numbers": [
{ "number": "0987654321", "phone_type": "WORK" }
],
"family_members": [
{ "first_name": "Addison", "last_name": "Smith", "relationship": "SISTER" }
],
"view_set_overrides": []
},
"relationships": {
"entity_affiliations": {
"data": []
},
"group_affiliations": {
"data": []
},
"default_view_set": {
"data": null
},
"team": {
"data": null
}
},
"links": { "self": "/v1/contacts/2000" }
}
}
Response codes:
200 OK-- Success400 Bad Request-- Missing required fields or invalid login email403 Forbidden-- Insufficient permissions; team and view set team do not match404 Not Found-- Contact, group, entity, or view set not found409 Conflict-- Duplicate external user ID or login email
Replace entity or group affiliations
Replaces all of a contact's entity or group affiliations with the provided list.
PATCH /v1/contacts/:id/relationships/entity_affiliations
PATCH /v1/contacts/:id/relationships/group_affiliations
curl -X PATCH "https://{firm}.addepar.com/api/v1/contacts/2000/relationships/group_affiliations" \
-H "Authorization: Basic {credentials}" \
-H "Addepar-Firm: 1" \
-H "Content-Type: application/vnd.api+json" \
-H "Accept: application/vnd.api+json" \
-d '{
"data": [
{ "id": "10000", "type": "groups" }
]
}'
Response: 204 No Content on success.
Response codes:
204 No Content-- Success403 Forbidden-- Insufficient permissions404 Not Found-- Contact, group, or entity not found
Replace team
Replaces a contact's team assignment.
PATCH /v1/contacts/:id/relationships/team
curl -X PATCH "https://{firm}.addepar.com/api/v1/contacts/2000/relationships/team" \
-H "Authorization: Basic {credentials}" \
-H "Addepar-Firm: 1" \
-H "Content-Type: application/vnd.api+json" \
-H "Accept: application/vnd.api+json" \
-d '{
"data": {
"id": "1",
"type": "teams"
}
}'
Response: 204 No Content on success.
Response codes:
204 No Content-- Success403 Forbidden-- Insufficient permissions404 Not Found-- Contact or team not found
Delete a contact
Permanently deletes a contact.
DELETE /v1/contacts/:id
curl -X DELETE "https://{firm}.addepar.com/api/v1/contacts/2000" \
-H "Authorization: Basic {credentials}" \
-H "Addepar-Firm: 1" \
-H "Accept: application/vnd.api+json"
Response: 204 No Content on success.
Response codes:
204 No Content-- Success403 Forbidden-- Insufficient permissions
Remove entity or group affiliations
Removes specified entities or groups from a contact's affiliations.
DELETE /v1/contacts/:id/relationships/entity_affiliations
DELETE /v1/contacts/:id/relationships/group_affiliations
curl -X DELETE "https://{firm}.addepar.com/api/v1/contacts/2000/relationships/group_affiliations" \
-H "Authorization: Basic {credentials}" \
-H "Addepar-Firm: 1" \
-H "Content-Type: application/vnd.api+json" \
-H "Accept: application/vnd.api+json" \
-d '{
"data": [
{ "id": "10000", "type": "groups" }
]
}'
Response: 204 No Content on success.
Response codes:
204 No Content-- Success403 Forbidden-- Insufficient permissions
Remove the default view set
Removes the default view set from a contact.
DELETE /v1/contacts/:id/relationships/default_view_set
curl -X DELETE "https://{firm}.addepar.com/api/v1/contacts/2000/relationships/default_view_set" \
-H "Authorization: Basic {credentials}" \
-H "Addepar-Firm: 1" \
-H "Accept: application/vnd.api+json"
Response: 204 No Content on success.
Response codes:
204 No Content-- Success403 Forbidden-- Insufficient permissions
Remove team
Removes the team from a contact.
DELETE /v1/contacts/:id/relationships/team
curl -X DELETE "https://{firm}.addepar.com/api/v1/contacts/2000/relationships/team" \
-H "Authorization: Basic {credentials}" \
-H "Addepar-Firm: 1" \
-H "Accept: application/vnd.api+json"
Response: 204 No Content on success.
Response codes:
204 No Content-- Success403 Forbidden-- Insufficient permissions
Invite to Client Portal
Sends or resends a Client Portal invitation to a contact's login email.
POST /v1/contacts/:id/invite
curl -X POST "https://{firm}.addepar.com/api/v1/contacts/2000/invite" \
-H "Authorization: Basic {credentials}" \
-H "Addepar-Firm: 1" \
-H "Accept: application/vnd.api+json"
Response: 204 No Content on success.
Response codes:
204 No Content-- Success400 Bad Request-- Missing login email or invalid email403 Forbidden-- Insufficient permissions404 Not Found-- Contact not found409 Conflict-- Contact is already activated or revoked
Restore portal access
Re-enables portal access for a contact whose access was previously revoked.
PATCH /v1/contacts/:id/restore
curl -X PATCH "https://{firm}.addepar.com/api/v1/contacts/2000/restore" \
-H "Authorization: Basic {credentials}" \
-H "Addepar-Firm: 1" \
-H "Accept: application/vnd.api+json"
Response: 204 No Content on success.
Response codes:
204 No Content-- Success400 Bad Request-- Contact has invalid login email or is not currently revoked403 Forbidden-- Insufficient permissions404 Not Found-- Contact not found
Revoke portal access
Prevents a contact from signing in to the Client Portal. Only contacts with activated access can be revoked.
PATCH /v1/contacts/:id/revoke
curl -X PATCH "https://{firm}.addepar.com/api/v1/contacts/2000/revoke" \
-H "Authorization: Basic {credentials}" \
-H "Addepar-Firm: 1" \
-H "Accept: application/vnd.api+json"
Response: 204 No Content on success.
Response codes:
204 No Content-- Success400 Bad Request-- Contact has invalid login email or is not currently activated403 Forbidden-- Insufficient permissions404 Not Found-- Contact not found
Exempt from 2FA
Makes two-factor authentication optional for a contact. The firm must require 2FA for portal contacts, and the contact must be active.
PATCH /v1/contacts/:id/exempt_two_factor_authentication
curl -X PATCH "https://{firm}.addepar.com/api/v1/contacts/2000/exempt_two_factor_authentication" \
-H "Authorization: Basic {credentials}" \
-H "Addepar-Firm: 1" \
-H "Accept: application/vnd.api+json"
Response: 204 No Content on success.
Response codes:
204 No Content-- Success400 Bad Request-- Contact is not activated, has SSO enabled, or firm does not require 2FA403 Forbidden-- Insufficient permissions404 Not Found-- Contact not found
Require 2FA
Re-requires two-factor authentication for a previously exempted contact.
PATCH /v1/contacts/:id/require_two_factor_authentication
curl -X PATCH "https://{firm}.addepar.com/api/v1/contacts/2000/require_two_factor_authentication" \
-H "Authorization: Basic {credentials}" \
-H "Addepar-Firm: 1" \
-H "Accept: application/vnd.api+json"
Response: 204 No Content on success.
Response codes:
204 No Content-- Success400 Bad Request-- Contact is not activated, has SSO enabled, or firm does not require 2FA403 Forbidden-- Insufficient permissions404 Not Found-- Contact not found
Enable SSO
Enables SAML single sign-on for a contact. The firm must have SAML configured and the contact's portal access must not be revoked.
PATCH /v1/contacts/:id/enable_saml
curl -X PATCH "https://{firm}.addepar.com/api/v1/contacts/2000/enable_saml" \
-H "Authorization: Basic {credentials}" \
-H "Addepar-Firm: 1" \
-H "Content-Type: application/vnd.api+json" \
-H "Accept: application/vnd.api+json" \
-d '{
"data": {
"id": "2000",
"type": "saml_settings",
"attributes": {
"saml_user_id": "[email protected]"
}
}
}'
Response: 204 No Content on success.
Response codes:
204 No Content-- Success400 Bad Request-- Missing login email, contact is revoked, or invalidsaml_user_id403 Forbidden-- Insufficient permissions or SAML not enabled for the firm404 Not Found-- Contact not found409 Conflict-- Duplicate SAML user ID
Disable SSO
Disables SAML single sign-on for a contact. The firm must have SAML configured and the contact's portal access must not be revoked.
PATCH /v1/contacts/:id/disable_saml
curl -X PATCH "https://{firm}.addepar.com/api/v1/contacts/2000/disable_saml" \
-H "Authorization: Basic {credentials}" \
-H "Addepar-Firm: 1" \
-H "Accept: application/vnd.api+json"
Response: 204 No Content on success.
Response codes:
204 No Content-- Success400 Bad Request-- Missing login email or contact is revoked403 Forbidden-- Insufficient permissions or SAML not enabled for the firm404 Not Found-- Contact not found
Related
- Entities -- The entities that contacts can be affiliated with
- Groups -- The groups that contacts can be affiliated with
- View Sets -- Control what contacts see in the Client Portal
- Pagination -- Paginate through contact lists
- Access & Authentication -- API key setup
Updated 15 days ago