Contacts
Contacts are individuals who can access the Client Portal. You can use the Contacts API to create, view, update, and delete contacts. You can also update contact information and manage their affiliations.
Base Route | /v1/contacts |
Endpoints | GET /v1/contacts/:id /v1/contacts /v1/contacts/:id/relationships/entity_affiliations /v1/contacts/:id/relationships/group_affiliations /v1/contacts/:id/relationships/default_view_set POST /v1/contacts /v1/contacts/:id/relationships/entity_affiliations /v1/contacts/:id/relationships/group_affiliations /v1/contacts/:id/relationships/default_view_set /v1/contacts/:id/invite PATCH /v1/contacts/:id /v1/contacts/:id/relationships/entity_affiliations /v1/contacts/:id/relationships/group_affiliations DELETE /v1/contacts/:id /v1/contacts/:id/relationships/entity_affiliations /v1/contacts/:id/relationships/group_affiliations /v1/contacts/:id/relationships/default_view_set |
Produces | JSON |
Pagination | Yes |
Application Permissions Required | "API Access: Create, edit, and delete" "Full Access" for all operations. |
OAuth Scopes | GETUSERS_READ POST, PATCH, and DELETE USERS_WRITE |
Resource overview
Contacts contain the below attributes. Required attributes are noted in the description.
All attributes will be returned in successful GET, POST, and PATCH responses containing the contacts resource.
Attribute | Description | Example |
---|---|---|
title | The contact's title. String. The maximum length is 10 characters. | "Mr." |
first_name | The contact's first name. String. Required. The maximum length is 40 characters. | "Adam" |
last_name | The contact's last name. String. Required. The maximum length is 80 characters. | "Smith" |
suffix | The contact's suffix. String. The maximum length is 10 characters. | "Jr." |
external_user_id | The firm's unique ID for the user, like an employee's ID number. String. The maximum length is 31 characters. | "abc123" |
login_email | The email address a contact uses to sign in to the Portal. This field cannot be deleted. | "[email protected]" |
birthday | The contact’s birthday. String. Format as YYYY-MM-DD. | "1990-10-31" |
employer | The contact’s employer. String. The maximum length is 80 characters. | "Madison Capital" |
occupation | The contact’s occupation. String. The maximum length is 80 characters. | "Financial Services" |
ssn | The contact’s Social Security number. String. The maximum length is 9 characters. | "123456789" |
mailing_addresses | A list of objects forming the contact's mailing addresses. See below for object details. See below for object details. | See below. |
emails | A list of objects forming the contact's email addresses. See below for object details. | See below. |
phone_numbers | A list of objects forming the contact's phone numbers. See below for object details. | See below. |
family_members | A list of objects representing the contact's family members. See below for object details. | See below. |
default_affiliation | The default entity or group affiliated with this contact. See below for object details. | See below. |
Mailing address objects
Attribute | Description | Example |
---|---|---|
street | The first line of the street address. String. Required. The maximum length is 80 characters. | "335 Madison Ave" |
street2 | The second line of the street address. String. The maximum length is 80 characters. | "25th Floor" |
city | The city of the address. String. Required. The maximum length is 80 characters. | "New York" |
state | The state or province of the address. String. Required. The maximum length is 80 characters. | "New York" |
zip | The zip or postal code of the address. String. Required. The maximum length is 10 characters. | "10017" |
country | The country of the address. String. The maximum length is 80 characters. | "United States" |
address_type | The type of the address, such as Work , Home , etc. String. The maximum length is 80 characters. | "Work" |
Email address objects
Attribute | Description | Example |
---|---|---|
email | The email address of the contact. String. Required. | "[email protected]" |
email_type | The type of email address. String. Required. Supported values: - PERSONAL - WORK - FAMILY - OTHER | "WORK" |
Phone number objects
Attribute | Description | Example |
---|---|---|
number | The contact’s phone number. String. Required. The maximum length is 15 characters. | "9179999999" |
phone_type | The type of phone number. String. Required. Supported values: - HOME - WORK - CELL - FAX - OTHER | "CELL" |
Family member objects
Attribute | Description | Example |
---|---|---|
first_name | The family member’s first name. String. Required. The maximum length is 40 characters. | "Addison" |
last_name | The family member’s last name. String. Required. The maximum length is 80 characters. | "Smith" |
relationship | The relationship of the family member to the contact. String. Required. Supported values: - SPOUSE - MOTHER - FATHER - SISTER - BROTHER - DAUGHTER - SON - GRANDMOTHER - GRANDFATHER - GRANDDAUGHTER - GRANDSON - AUNT - UNCLE - COUSIN - OTHER | "SISTER" |
Default affiliation object
The default affiliation is the first portfolio shown to the user in Portal views. A contact must be affiliated to either an entity or a group, not both. Whichever is selected is the default affiliation.
Attribute | Description | Example |
---|---|---|
entity_id | The entity affiliated with the contact, identified by its Entity ID. String. If this affiliation is not an entity, this field must be null. If group_id is null, this field must not be null. | "22" |
group_id | The group affiliated with the contact, identified by its Group ID. String. If this affiliation is not a group, this field must be null. If entity_id is null, this field must not be null. | "7" |
Relationships
Relationship | Description |
---|---|
entity_affiliations | The entities affiliated with this contact. |
group_affiliations | The groups affiliated with this contact. |
default_view_set | The default view set assigned to this contact. |
"relationships": {
"entity_affiliations": {
"links": {
"self": "/v1/contacts/20/relationships/entity_affiliations",
"related": "/v1/contacts/20/entity_affiliations"
},
"data": [
{
"type": "entities",
"id": "22"
}
]
},
"group_affiliations": {
"links": {
"self": "/v1/contacts/20/relationships/group_affiliations",
"related": "/v1/contacts/20/group_affiliations"
},
"data": [
{
"type": "groups",
"id": "7"
}
]
},
"default_view_set": {
"links": {
"self": "/v1/contacts/20/relationships/default_view_set",
"related": "/v1/contacts/20/default_view_set"
},
"data": {
"type": "view_sets",
"id": "11"
}
}
}
Get a contact
Retrieves details for a specific contact.
GET /v1/contacts/:id
Example:
GET https://examplefirm.addepar.com/api/v1/contacts/2000
HTTP/1.1 200
{
"data":{
"id":"2000",
"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"
}
],
"default_affiliation": {
"entity_id": "22",
"group_id": null
}
},
"relationships": {
"entity_affiliations": {
"links": {
"self": "/v1/contacts/20/relationships/entity_affiliations",
"related": "/v1/contacts/20/entity_affiliations"
},
"data": [
{
"type": "entities",
"id": "22"
}
]
},
"group_affiliations": {
"links": {
"self": "/v1/contacts/20/relationships/group_affiliations",
"related": "/v1/contacts/20/group_affiliations"
},
"data": []
},
"default_view_set": {
"links": {
"self": "/v1/contacts/20/relationships/default_view_set",
"related": "/v1/contacts/20/default_view_set"
},
"data": null
}
},
"links": {
"self": "/v1/contacts/20"
}
}
}
Response codes
200 OK
: Success403 Forbidden
: You need full access permissions to perform this action404 Not Found
: Contact not found
Get all contacts
Retrieves details for all contacts.
GET /v1/contacts
Example:
GET https://examplefirm.addepar.com/api/v1/contacts
HTTP/1.1 200
{
"data":[
{
"id":"2000",
"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"
}
],
"default_affiliation": {
"entity_id": "22",
"group_id": null
}
},
"relationships": {
"entity_affiliations": {
"links": {
"self": "/v1/contacts/20/relationships/entity_affiliations",
"related": "/v1/contacts/20/entity_affiliations"
},
"data": [
{
"type": "entities",
"id": "22"
}
]
},
"group_affiliations": {
"links": {
"self": "/v1/contacts/20/relationships/group_affiliations",
"related": "/v1/contacts/20/group_affiliations"
},
"data": []
},
"default_view_set": {
"links": {
"self": "/v1/contacts/20/relationships/default_view_set",
"related": "/v1/contacts/20/default_view_set"
},
"data": null
}
},
"links": {
"self": "/v1/contacts/20"
}
}
]
}
Response codes
200 OK
: Success403 Forbidden
: You need full access permissions to perform this action
Get a contact’s entity or group affiliations
Retrieves a list of IDs for the entities or groups the contact has been affiliated with.
GET /v1/contacts/:contact-id/relationships/entity_affiliations
GET /v1/contacts/:contact-id/relationships/group_affiliations
Example:
GET https://examplefirm.addepar.com/api/v1/contacts/2000/relationships/entity_affiliations
HTTP/1.1 200
{
"data":[
{
"id":"10000",
"type":"entities"
}
]
}
Response codes
200 OK
: Success403 Forbidden
: You need full access permissions to perform this action404 Not Found
: Contact not found
Get a contact’s default view set
Retrieves the ID of the default view set assigned to the contact.
GET /v1/contacts/:contact-id/relationships/default_view_set
Example:
GET https://examplefirm.addepar.com/api/v1/contacts/2000/relationships/default_view_set
HTTP/1.1 200
{
"data":{
"id":"10000",
"type":"view_sets"
}
}
Response codes
200 OK
: Success403 Forbidden
: You need full access permissions to perform this action404 Not Found
: Contact not found
Create a contact
Creates a new contact.
POST /v1/contacts
Example:
POST https://examplefirm.addepar.com/api/v1/contacts
{
"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"
}
],
"default_affiliation": null
}
}
}
HTTP/1.1 201
{
"data":{
"id":"2000",
"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"
}
],
"default_affiliation": null
},
"relationships": {
"entity_affiliations": {
"links": {
"self": "/v1/contacts/20/relationships/entity_affiliations",
"related": "/v1/contacts/20/entity_affiliations"
},
"data": [
]
},
"group_affiliations": {
"links": {
"self": "/v1/contacts/20/relationships/group_affiliations",
"related": "/v1/contacts/20/group_affiliations"
},
"data": [
]
},
"default_view_set": {
"links": {
"self": "/v1/contacts/20/relationships/default_view_set",
"related": "/v1/contacts/20/default_view_set"
},
"data": null
}
},
"links": {
"self": "/v1/contacts/20"
}
}
}
Response codes
201 Created
: Success400 Bad Request
: Missing required fields or invalid login email403 Forbidden
: You need full access permissions to perform this action404 Not Found
: Group, entity, or view set not found409 Conflict
: Duplicate external user ID or login email is supplied
Add an entity or group affiliation to a contact
Affiliates entities or groups with a contact.
POST /v1/contacts/:contact-id/relationships/entity_affiliations
POST /v1/contacts/:contact-id/relationships/group_affiliations
Example:
POST https://examplefirm.addepar.com/api/v1/contacts/2000/relationships/group_affiliations
{
"data":[
{
"id":"10000",
"type":"groups"
}
]
}
HTTP/1.1 204
Response codes
204 No Content
: Success403 Forbidden
: You need full access permissions to perform this action404 Not Found
: Contact, group, or entity not found
Set the default view set for a contact
Assigns a view set as the default for a contact.
POST /v1/contacts/:contact-id/relationships/default_view_set
Example:
POST https://examplefirm.addepar.com/api/v1/contacts/2000/relationships/default_view_set
{
"data":{
"id":"10000",
"type":"view_sets"
}
}
HTTP/1.1 204
Response codes
204 No Content
: Success403 Forbidden
: You need full access permissions to perform this action404 Not Found
: Contact or view set not found
Update a contact
Updates a contact with the specified details.
PATCH /v1/contacts/:contact-id
Example:
PATCH https://examplefirm.addepar.com/api/v1/contacts
{
"data":{
"id":"2000",
"type":"contacts",
"attributes":{
"first_name":"Second",
"last_name":"User"
}
}
}
HTTP/1.1 200
{
"data":{
"id":"2000",
"type":"contacts",
"attributes":{
"title":"Mr.",
"first_name":"Second",
"last_name":"User",
"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"
}
],
"default_affiliation": null
},
"relationships": {
"entity_affiliations": {
"links": {
"self": "/v1/contacts/20/relationships/entity_affiliations",
"related": "/v1/contacts/20/entity_affiliations"
},
"data": [
]
},
"group_affiliations": {
"links": {
"self": "/v1/contacts/20/relationships/group_affiliations",
"related": "/v1/contacts/20/group_affiliations"
},
"data": [
]
},
"default_view_set": {
"links": {
"self": "/v1/contacts/20/relationships/default_view_set",
"related": "/v1/contacts/20/default_view_set"
},
"data": null
}
},
"links": {
"self": "/v1/contacts/20"
}
}
}
Response codes
200 OK
: Success400 Bad Request
: Missing required fields or invalid login email403 Forbidden
: You need full access permissions to perform this action404 Not Found
: Contact, group, entity, or view set not found409 Conflict
: Duplicate external user ID or login email is supplied
Replace a contact's entity or group affiliations
Replaces a contacts entity or group affiliations with the given entities or groups.
PATCH /v1/contacts/:contact-id/relationships/entity_affiliations
PATCH /v1/contacts/:contact-id/relationships/group_affiliations
Example:
PATCH https://examplefirm.addepar.com/api/v1/contacts/2000/relationships/group_affiliations
{
"data":[
{
"id":"10000",
"type":"groups"
}
]
}
HTTP/1.1 204
Response codes
204 No Content
: Success403 Forbidden
: You need full access permissions to perform this action404 Not Found
: Contact, group, or entity not found
Delete a contact
Delete a specific contact.
DELETE /v1/contacts/:contact-id
Example:
DELETE https://examplefirm.addepar.com/api/v1/contacts/2000
HTTP/1.1 204
Response codes
204 No Content
: Success403 Forbidden
: You need full access permissions to perform this action
Remove entity or group affiliations from a contact
Removes entities or groups from a contact’s affiliations.
DELETE /v1/contacts/:contact-id/relationships/entity_affiliations
DELETE /v1/contacts/:contact-id/relationships/group_affiliations
Example:
DELETE https://examplefirm.addepar.com/api/v1/contacts/2000/relationships/group_affiliations
{
"data":[
{
"id":"10000",
"type":"groups"
}
]
}
HTTP/1.1 204
Response codes
204 No Content
: Success403 Forbidden
: You need full access permissions to perform this action
Remove the default view set from a contact
Removes the default view set from a contact.
DELETE /v1/contacts/:contact-id/relationships/default_view_set
Example:
DELETE https://examplefirm.addepar.com/api/v1/contacts/2000/relationships/default_view_set
HTTP/1.1 204
Response codes
204 No Content
: Success403 Forbidden
: You need full access permissions to perform this action
Invite a contact to the Client Portal
Send or resend a Client Portal invite to a contact's login email address.
POST /v1/contacts/:contact-id/invite
Example:
POST https://examplefirm.addepar.com/api/v1/contacts/2000/invite
HTTP/1.1 204
Response codes
204 No Content
: Success400 Bad Request
: Missing required fields or invalid login email403 Forbidden
: You need full access permissions to perform this action404 Not Found
: Contact not found409 Conflict
: Contact is already activated or revoked
Updated 23 days ago