updateContact

Overview

This method updates an existing contact, including its allocations and contact types.

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

Permissions

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

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

HTTP Method

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

URL Examples

https://api.demo.catch-e.com/fm/contacts/345 https://api.{{environment}}.catch-e.com/fm/contacts/345 https://api.test.catch-e.com/fm/contacts/345

Input Fields (Header)

Key	Format	Notes	Mandatory
Audit-User-Id	string	(Optional) User Id to use for audit purposes. Up to 5 digits. Requires the Audit:UserIdOverride permission.	No

Path Parameters

Key	Format	Notes	Mandatory
contact_id	string	The Contact Id. A positive whole number, up to 20 digits, with no leading zeros.	Yes

Input Fields (JSON)

Key	Format	Notes	Mandatory
contact_job_title_id	string	Contact Job Title Id. See the Contact / Job Titles APIs.	No
salutation	string	Allowed values: `Mr`, `Mrs`, `Ms`, `Miss`, `Mx`, `Dr`, `Prof`, `Rev`, `Capt`.	No
given_name	string	Given name.	No
surname	string	Surname.	No
phone	string	Phone number. Must follow E.164 format.	No
mobile	string	Mobile number. Must follow E.164 format.	No
email	string	Email address.	No
address1	string	Address line 1.	No
address2	string	Address line 2.	No
area	string		No
state_id	string	State Id.	No
postcode	string	Postcode.	No
country_id	string	Country Id.	No
note	string	Note.	No
status_flag	string	Allowed values: `active`, `inactive`. Default `active`.	No
allocations	array	The records the contact is allocated to. See allocations below.	No
contact_type_allocations	array	The contact types allocated to the contact. See contact_type_allocations below.	No

allocations

Key	Format	Notes	Mandatory
contact_id	string	Contact Id.	No
table_name	string	The table the contact is allocated to. Allowed values: `fm_clients`, `fm_client_groups`, `fm_client_cost_centres`, `fm_client_divisions`.	No
record_id	string	The record id in that table, e.g. the client id from `fm_clients`.	No
status_flag	string	Allowed values: `active`, `inactive`.	No

contact_type_allocations

Key	Format	Notes	Mandatory
contact_id	string	The contact to allocate the type to.	Yes
contact_type_id	string	The contact type to allocate. See the Contact / Types APIs.	Yes
email_type	string	Allowed values: `to`, `cc`, `bcc`, `null`.	No

Example

{ "contact_job_title_id": "12", "email": "[EMAIL]", "status_flag": "active" }

Response Details

Success

200 - OK

Returns the updated contact.

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

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	The contact does not exist.

{ "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
415 - Unsupported Media Type	The Content-Type of the request is not supported by this API.

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

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