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	GET `USERS_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: Success
403 Forbidden: You need full access permissions to perform this action
404 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: Success
403 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: Success
403 Forbidden: You need full access permissions to perform this action
404 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: Success
403 Forbidden: You need full access permissions to perform this action
404 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: Success
400 Bad Request: Missing required fields or invalid login email
403 Forbidden: You need full access permissions to perform this action
404 Not Found: Group, entity, or view set not found
409 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: Success
403 Forbidden: You need full access permissions to perform this action
404 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: Success
403 Forbidden: You need full access permissions to perform this action
404 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: Success
400 Bad Request: Missing required fields or invalid login email
403 Forbidden: You need full access permissions to perform this action
404 Not Found: Contact, group, entity, or view set not found
409 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: Success
403 Forbidden: You need full access permissions to perform this action
404 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: Success
403 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: Success
403 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: Success
403 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: Success
400 Bad Request: Missing required fields or invalid login email
403 Forbidden: You need full access permissions to perform this action
404 Not Found: Contact not found
409 Conflict: Contact is already activated or revoked