getContacts

Overview

This method returns the contacts allocated to a specified client, client group, cost centre or division.

By default only active contacts are returned. Records with a status of 'deleted' are never returned.

This method requires the Contacts:Get permission to be associated with your role.

Permissions

The permission for this api is stored in [gb_api_permissions]permission as 'Contacts:Get'.

Only roles with a stored link to this permission in [gb_role_api_permissions] can run this api.

HTTP Method

Use the HTTP Method 'GET' for consuming this web service.

URL Examples

https://api.demo.catch-e.com/fm/contacts?table_name=fm_clients&record_id=1234 https://api.{{environment}}.catch-e.com/fm/contacts?table_name=fm_clients&record_id=1234 https://api.test.catch-e.com/fm/contacts?table_name=fm_clients&record_id=1234

Query Parameters

Key	Format	Notes	Mandatory
table_name	string	The table the record belongs to. Allowed values: `fm_clients`, `fm_client_groups`, `fm_client_cost_centres`, `fm_client_divisions`.	Yes
record_id	string	The record id in that table. A positive whole number, up to 10 digits, with no leading zeros.	Yes
include_inactive_flag	string	Set to `yes` to include inactive contacts in the list. 'Deleted' records cannot be returned. Allowed values: `yes`, `no`. Default `no`.	No
page	integer	Page number. Default `1`.	No
page_size	integer	Number of records per page. Default `25`. Use `-1` to return all records.	No

Response Details

Success

200 - OK

Each record in _embedded.contacts contains:

Field	Format	Notes
contact_id	string	Contact Id.
contact_job_title_id	string	Contact Job Title Id. See the Contact / Job Titles APIs.
salutation	string	Values: `Mr`, `Mrs`, `Ms`, `Miss`, `Mx`, `Dr`, `Prof`, `Rev`, `Capt`.
given_name	string	Given name.
surname	string	Surname.
phone	string	Phone number. Should follow E.164 format.
mobile	string	Mobile number. Should follow E.164 format.
email	string	Email address.
address1	string	Address line 1.
address2	string	Address line 2.
area	string
state_id	string	State Id.
postcode	string	Postcode.
country_id	string	Country Id.
note	string	Note.
status_flag	string	Values: `active`, `inactive`.
allocations	array	The records the contact is allocated to. Each has `contact_id`, `table_name`, `record_id` and `status_flag`.
contact_type_allocations	array	The contact types allocated to the contact. Each has `contact_id`, `contact_type_id` and `email_type`.

{ "_links": { "self": { "href": "https://api.catch-e.loc/fm/contacts?table_name=fm_clients&record_id=1234&page=1" } }, "_embedded": { "contacts": [ { "_links": { "self": { "href": "https://api.catch-e.loc/fm/contacts/345" }, "job_title": { "href": "https://api.catch-e.loc/fm/contact/job-titles/12" } }, "contact_id": "345", "contact_job_title_id": "12", "salutation": "Ms", "given_name": "[GIVEN-NAME]", "surname": "[SURNAME]", "phone": "[PHONE-E164]", "mobile": "[MOBILE-E164]", "email": "[EMAIL]", "address1": "[ADDRESS-LINE-1]", "address2": "", "area": "[SUBURB]", "state_id": "2", "postcode": "2000", "country_id": "1", "note": "string", "status_flag": "active", "allocations": [ { "contact_id": "345", "table_name": "fm_clients", "record_id": "1234", "status_flag": "active" } ], "contact_type_allocations": [ { "contact_id": "345", "contact_type_id": "6", "email_type": "to" } ] } ] }, "page_count": 1, "page_size": 25, "total_items": 1, "page": 1 }

Error Response Details

Validation Message	Comments
401 - Unauthorized	1. You have not authenticated before running this API or 2. The token_timeout of the current session has passed. You need to authenticate again.

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unauthorized", "status": 401, "detail": "Unauthorized" }

Validation Message	Comments
403 - Forbidden	- You do not have permissions for this request. - Go to System Roles and enter 'web_services' - Navigate to the Roles / APIs tab to make sure the permission you need to run this API is checked.

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Forbidden", "status": 403, "detail": "Forbidden" }

Validation Message	Comments
404 - Not Found	No contacts were found for the record.

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Not Found", "status": 404, "detail": "Not Found" }

Validation Message	Comments
406 - Not Acceptable	The Accept header of the request does not match a response format this API supports.

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Not Acceptable", "status": 406, "detail": "Not Acceptable" }

Validation Message	Comments
409 - Conflict	The request conflicts with the current state of the data.

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Conflict", "status": 409, "detail": "Conflict" }

Validation Message	Comments
422 - Unprocessable Entity	One or more input fields failed validation. The field name and message are returned in `validation_messages`.

{ "warning_messages": {}, "validation_messages": { "fieldName": { "validationExceptionCode": "A textual description of the validation exception" } }, "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 422, "detail": "Failed Validation" }

Validation Message	Comments
500 - Internal Error	An unexpected error occurred on the server.

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "string", "status": 599, "detail": "string" }

Validation Message	Comments
default - Unexpected Error	Any other unexpected error.

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "string", "status": 599, "detail": "string" }