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
ProducesJSON
PaginationYes
OAuth scopesGET USERS; POST, PATCH, DELETE USERS_WRITE

📘

Access requirements

Application permissions: "API Access: Create, edit, and delete" and "Full Access" for all operations.

Resource attributes

AttributeTypeDescription
titleStringThe contact's title. Max 10 characters. Example: "Mr."
first_nameStringRequired. The contact's first name. Max 40 characters.
last_nameStringRequired. The contact's last name. Max 80 characters.
suffixStringThe contact's suffix. Max 10 characters. Example: "Jr."
external_user_idStringThe firm's unique ID for the user. Max 31 characters.
login_emailStringThe email address the contact uses to sign in to the Portal. Cannot be deleted once set.
portal_accessStringRead-only. The contact's portal access status. Values: "deactivated", "activated", "invited", "revoked".
birthdayStringThe contact's birthday. Format: YYYY-MM-DD.
employerStringThe contact's employer. Max 80 characters.
occupationStringThe contact's occupation. Max 80 characters.
ssnStringThe contact's Social Security number. Max 9 characters.
is_exempt_from_two_factor_requirementBooleanRead-only. 2FA exemption status. Only returned for active contacts when the firm requires 2FA.
mailing_addressesArrayThe contact's mailing addresses. See nested objects below.
emailsArrayThe contact's email addresses. See nested objects below.
phone_numbersArrayThe contact's phone numbers. See nested objects below.
family_membersArrayThe contact's family members. See nested objects below.
saml_settingsObjectSSO settings (SAML 2.0). Only returned if the firm has SAML enabled.
view_set_overridesArrayRead-only. View set overrides for the contact's portfolios.

Mailing address objects

FieldTypeDescription
streetStringRequired. First line. Max 80 characters.
street2StringSecond line. Max 80 characters.
cityStringRequired. Max 80 characters.
stateStringRequired. Max 80 characters.
zipStringRequired. Max 10 characters.
countryStringMax 80 characters.
address_typeStringAddress type (e.g., "Work", "Home"). Max 80 characters.

Email address objects

FieldTypeDescription
emailStringRequired. The email address.
email_typeStringRequired. Values: PERSONAL, WORK, FAMILY, OTHER.

Phone number objects

FieldTypeDescription
numberStringRequired. Max 15 characters.
phone_typeStringRequired. Values: HOME, WORK, CELL, FAX, OTHER.

Family member objects

FieldTypeDescription
first_nameStringRequired. Max 40 characters.
last_nameStringRequired. Max 80 characters.
relationshipStringRequired. Values: SPOUSE, MOTHER, FATHER, SISTER, BROTHER, DAUGHTER, SON, GRANDMOTHER, GRANDFATHER, GRANDDAUGHTER, GRANDSON, AUNT, UNCLE, COUSIN, OTHER.

Relationships

RelationshipDescription
entity_affiliationsEntities affiliated with this contact.
group_affiliationsGroups affiliated with this contact.
default_view_setThe default view set assigned to this contact.
teamThe 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 -- Success
  • 403 Forbidden -- Insufficient permissions
  • 404 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 -- Success
  • 403 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 -- Success
  • 403 Forbidden -- Insufficient permissions
  • 404 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 -- Success
  • 403 Forbidden -- Insufficient permissions
  • 404 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 -- Success
  • 403 Forbidden -- Insufficient permissions
  • 404 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 -- Success
  • 400 Bad Request -- Missing required fields or invalid login email
  • 403 Forbidden -- Insufficient permissions; team and view set team do not match
  • 404 Not Found -- Group, entity, or view set not found
  • 409 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 -- Success
  • 403 Forbidden -- Insufficient permissions
  • 404 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 -- Success
  • 403 Forbidden -- Insufficient permissions; team and view set team do not match
  • 404 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 -- Success
  • 400 Bad Request -- Missing required fields or invalid login email
  • 403 Forbidden -- Insufficient permissions; team and view set team do not match
  • 404 Not Found -- Contact, group, entity, or view set not found
  • 409 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 -- Success
  • 403 Forbidden -- Insufficient permissions
  • 404 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 -- Success
  • 403 Forbidden -- Insufficient permissions
  • 404 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 -- Success
  • 403 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 -- Success
  • 403 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 -- Success
  • 403 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 -- Success
  • 403 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 -- Success
  • 400 Bad Request -- Missing login email or invalid email
  • 403 Forbidden -- Insufficient permissions
  • 404 Not Found -- Contact not found
  • 409 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 -- Success
  • 400 Bad Request -- Contact has invalid login email or is not currently revoked
  • 403 Forbidden -- Insufficient permissions
  • 404 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 -- Success
  • 400 Bad Request -- Contact has invalid login email or is not currently activated
  • 403 Forbidden -- Insufficient permissions
  • 404 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 -- Success
  • 400 Bad Request -- Contact is not activated, has SSO enabled, or firm does not require 2FA
  • 403 Forbidden -- Insufficient permissions
  • 404 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 -- Success
  • 400 Bad Request -- Contact is not activated, has SSO enabled, or firm does not require 2FA
  • 403 Forbidden -- Insufficient permissions
  • 404 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 -- Success
  • 400 Bad Request -- Missing login email, contact is revoked, or invalid saml_user_id
  • 403 Forbidden -- Insufficient permissions or SAML not enabled for the firm
  • 404 Not Found -- Contact not found
  • 409 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 -- Success
  • 400 Bad Request -- Missing login email or contact is revoked
  • 403 Forbidden -- Insufficient permissions or SAML not enabled for the firm
  • 404 Not Found -- Contact not found

📘

Related


Did this page help you?