API Reference - Client Contacts – Trackops Support Center

Client contacts are the individual user accounts that are configured in your system. Personal information about these individuals, such as their phone number and email address are stored in these objects.

Listing Client Contacts

Returns a collection of client contact records, optionally filtered by the available request parameters.

GET /api/v1/client/contacts

Available Request Parameters:

Name	Type	Required	Description
id	integer	no	ID of the contact.
last_name	string	no	Last name of the contact.
first_name	string	no	First name of the contact.
email	string	no	Email address of the contact.
client	integer	no	ID of the parent (root) client.
client_location	integer	no	ID of the client location for this contact.
role	integer	no	ID of the role this contact belongs to.
salesperson	integer	no	ID of the default salesperson assigned to this client.
created_from	timestamp	no	Created on or after the date.
created_to	timestamp	no	Created on or before the date.
updated_from	timestamp	no	Updated on or after the date.
updated_to	timestamp	no	Updated on or before the date.
expand_field_values	boolean	no	Instructs the API to return values as JSON for applicable custom fields.

Note: All timestamp parameters are queried and returned in UTC.

Getting a Client Contact

Returns a single client contact record, based on the numeric ID.

GET /api/v1/client/contacts/{client_contact_id}

Creating a Client Contact

Creates a new client contact (i.e. a user) based on the given criteria. Upon success, returns a client object. See the example request at the bottom of this section for a better idea of how a fully formed request should look.

Note: Client contacts in Trackops are always assigned to client locations and cannot be assigned to top level clients via the client_id parameter.

POST /api/v1/client/contacts

Available Parameters

Name	Type	Required	Description
client_id	integer	yes	The ID of the client location (not the root client) that this contact belongs to (see API Reference - Client Locations)
role_id	integer	yes	The role ID that contains the permissions this contact will inherit. Only roles that are designated as available for Client Contacts are valid. Please visit Settings > User Roles from within the app for more information.
first_name	string	no	First name
middle_name	string	no	Middle name
last_name	string	yes	Last name
title	string	no	Job title or other title
email	email	no	The primary email address
address_1	string	no	Primary street address
address_2	string	no	Unit, apartment number, etc...
address_3	string	no	Additional address info
city	string	no	City
state	string	no	2-3 character State code (if in US, CA, AU), otherwise a string
zip	string	no	Zip code or postal code
country	string	no	2 Character ISO country code
phone_home	string	no	The home phone number
phone_mobile	string	no	The mobile phone number
phone_office	string	no	The office phone number
phone_fax	string	no	The fax number
language	string	no	2-character ISO language code
birthday	date	no	ISO formatted date of birth (YYYY-MM-DD)
account_code	string	no	Alternate reference ID or lookup code
notes	string	no	General notes (visible to the contact)
admin_notes	string	no	Private notes (not visible by the contact)

Allowing Duplicate Records

By default, the system will check for users with the same name and consider these records to be duplicates, which are rejected. If you wish to skip conflict checking and always create new records, you can pass the allow_duplicates parameter along with the request body. When this value is true, the the system will always create the new contact. See the example request body below.

Example New Client Contact Request

A new client contact (i.e. user) is created by POSTing a JSON object to the specified end point using the above criteria. The JSON object must contain the required fields (as shown above) and must be nested under a contact object. See the following example request:

{
  "allow_duplicates": false,
  "contact": {
    "client_id": 12345,
    "role_id": 6,
    "first_name": "Susie",
    "middle_name": "B",
    "last_name": "Smith",
    "title": "Claims Adjuster",
    "email": "example@trackops.com",
    "phone_home": "555-555-55555",
    "phone_mobile": "555-555-5555",
    "phone_office": "+1 404-555-5555 x501",
    "phone_fax": "999-999-9999",
    "birthday": "1979-01-01",
    "account_code": "12345",
    "notes": "These are some general notes!",
    "admin_notes": "This is a VIP contact."
  } 
}

Note: The above request is for demonstration purposes only, your implementation will require unique data provided by your account.

Updating a Client Contact

Note: Client contacts in Trackops are always assigned to client locations and cannot be assigned to top level clients.

PUT /api/v1/client/contacts/{contact_id}

Available Parameters

Name	Type	Required	Description
client_id	integer	yes	The ID of the client location (not the root client) that this contact belongs to (see API Reference - Client Locations)
role_id	integer	yes	The role ID that contains the permissions this contact will inherit. Only roles that are designated as available for Client Contacts are valid. Please visit Settings > User Roles from within the app for more information.
first_name	string	no	First name
middle_name	string	no	Middle name
last_name	string	yes	Last name
title	string	no	Job title or other title
email	email	no	The primary email address
address_1	string	no	Primary street address
address_2	string	no	Unit, apartment number, etc...
address_3	string	no	Additional address info
city	string	no	City
state	string	no	2-3 character State code (if in US, CA, AU), otherwise a string
zip	string	no	Zip code or postal code
country	string	no	2 Character ISO country code
phone_home	string	no	The home phone number
phone_mobile	string	no	The mobile phone number
phone_office	string	no	The office phone number
phone_fax	string	no	The fax number
language	string	no	2-character ISO language code
birthday	date	no	ISO formatted date of birth (YYYY-MM-DD)
account_code	string	no	Alternate reference ID or lookup code
notes	string	no	General notes (visible to the contact)
admin_notes	string	no	Private notes (not visible by the contact)

Allowing Duplicate Records

Example Update Client Contact Request

A client contact (i.e. user) is updated by sending a JSON object to the specified end point using the above criteria. The JSON object must contain the required fields (as shown above) and must be nested under a contact object. See the following example request:

{
  "allow_duplicates": false,
  "contact": {
    "account_code": "123456",
  } 
}

Note: The above request is for demonstration purposes only, your implementation will require unique data provided by your account.