createContact

Overview

This method creates one or more contacts in a single request. Contacts can be allocated to clients, client groups, cost centres or divisions, and given contact types, in the same request.

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

Permissions

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

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

HTTP Method

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

URL Examples

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

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

Input Fields (JSON)

Send an array of contacts.

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.	Yes
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. The swagger does not define the fields for this array on create.	No

allocations

Key	Format	Notes	Mandatory
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

Example

[ { "salutation": "Ms", "given_name": "[GIVEN-NAME]", "surname": "[SURNAME]", "email": "[EMAIL]", "mobile": "[MOBILE-E164]", "allocations": [ { "table_name": "fm_clients", "record_id": "1234", "status_flag": "active" } ] } ]

Response Details

Success

201 - Created

Returns the new contacts. 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" } }, "_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
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" }