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 POST /v1/contacts /v1/contacts/:id/relationships/entity_affiliations /v1/contacts/:id/relationships/group_affiliations 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
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"`
`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.

"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"
            }
        ]
    }
}

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",
            "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": []
            }
        },
        "links": {
            "self": "/v1/contacts/20"
        }
    }
}

Response codes

200 OK: Success
403 Forbidden: User lacks sufficient permissions
404 Not Found: Nonexistent contact ID

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",
            "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": []
            }
        },
        "links": {
            "self": "/v1/contacts/20"
        }
      }
    ]
}

Response codes

200 OK: Success
403 Forbidden: User lacks sufficient permissions

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: User lacks sufficient permissions
404 Not Found: Nonexistent contact ID

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",
            "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",
            "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": [
                
                ]
            }
        },
        "links": {
            "self": "/v1/contacts/20"
        }
    }
}

Response codes

201 Created: Success
400 Bad Request: Missing required fields
403 Forbidden: User lacks sufficient permissions
404 Not Found: Nonexistent entity or group ID in affiliations
409 Conflict: Duplicate external user ID 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: User lacks sufficient permissions
404 Not Found: Nonexistent contact ID, entity ID, or group ID

Update a contact

Updates a contact with the specified details.

PATCH /v1/contacts

Example:

PATCH https://examplefirm.addepar.com/api/v1/contacts

{
    "data":{
        "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",
            "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": [
                
                ]
            }
        },
        "links": {
            "self": "/v1/contacts/20"
        }
    }
}

Response codes

200 OK: Success
400 Bad Request: Missing required fields
403 Forbidden: User lacks sufficient permissions
404 Not Found: Nonexistent entity or group ID in affiliations
409 Conflict: Duplicate external user ID 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: User lacks sufficient permissions
404 Not Found: Nonexistent contact ID, entity ID, or group ID

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: User lacks sufficient permissions

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: User lacks sufficient permissions