Customer contacts can exist in two forms:
- Direct contacts - Linked to a specific customer (customerID is set)
- Shared contacts - Not linked to any specific customer (customerID is null) and can be associated with multiple customers
Methods
GET
Retrieve Single Customer Contact
/backend/api/v1/customerContacts/ID - fetch customer contact with specified ID.
List Customer Contacts
/backend/api/v1/customerContacts/ - list all customer contacts (both direct and shared).
/backend/api/v1/customers/ID/customerContacts/ - list all contacts belonging to customer with specified ID (includes both direct contacts and linked shared contacts).
Additional Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
dealerCode |
string | No | Filter shared contacts by dealer code |
POST
/backend/api/v1/customerContacts/ - create a new shared contact (customerID will be null).
/backend/api/v1/customers/ID/customerContacts/ - create a new contact directly linked to the specified customer.
To link an existing shared contact to a customer, use the addSharedContact action on the customer endpoint.
PATCH
/backend/api/v1/customerContacts/ID - update customer contact with specified ID. The modified contact will be returned.
DELETE
/backend/api/v1/customerContacts/ID - delete customer contact with specified ID.
Note: Direct contacts are automatically deleted when their parent customer is deleted. Shared contacts persist even when linked customers are deleted.
Actions
Available Actions
convertToSharedContact
Convert a direct customer contact into a shared contact. This removes the direct link to the customer (sets customerID to null) but maintains the contact’s association with the original customer as a shared contact. The contact can then be shared with other customers as well.
Example:
curl -X POST https://example.com/backend/api/v1/customerContacts/123?action=convertToSharedContact \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'
Fields
| Field | Name | Type | Description |
|---|---|---|---|
| contactType | Contact Type | Preset Value | Type or role of this contact within the customer organisation |
| title | Title | Preset Value | Contact title (e.g., Mr, Mrs, Ms) |
| companyName | Company Name | Text | Name of the company or organisation this contact represents |
| address1 | Address Line 1 | Text | First line of contact address |
| address2 | Address Line 2 | Text | Second line of contact address |
| address3 | Address Line 3 | Text | Third line of contact address |
| address4 | Address Line 4 | Text | Fourth line of contact address (typically city) |
| address5 | Address Line 5 | Text | Fifth line of contact address (typically county/state) |
| postcode | Postcode | Text | Postal/zip code for contact address |
| country | Country | Preset Value | Country code for contact location |
| number1type | Number 1 Type | Preset Value | Type of the first contact number |
| number2type | Number 2 Type | Preset Value | Type of the second contact number |
| number3type | Number 3 Type | Preset Value | Type of the third contact number |
| number4type | Number 4 Type | Preset Value | Type of the fourth contact number |
| Email Address | Text | Email address for the contact | |
| website | Website | Text | Website URL for the contact |
| accountPassword | Account Password | Text | Password for contact account access |
| contactPosition | Position | Text | Job title or position of the contact within the company |
| dealerCode | Dealer Code | Preset Value | Dealer code associated with this customer contact |
| contactRegarding | Contact Regarding | Preset Value(s) | Topics or areas this contact should be contacted about |
| emailBillType | Copy Email Bill | Preset Value | Name of the bill type to generate for email delivery |
| invoiceUsageReportCustomerProfile | Invoice Usage Report | Preset Value | Usage report configuration for invoices sent to this contact |
| copyCorrespondenceTypeIDs | Copy Correspondence | Preset Value(s) | Array of correspondence type names that should be copied to this contact |
| copyTicketTypeIDs | Copy Ticket Updates | Preset Value(s) | Array of ticket type names that should be copied to this contact |
| id | Customer Contact ID | Text | The unique identifier for this customer contact |
| customerID | Customer | Text | The ID of the customer this customer contact belongs to. Will be null for a shared contact. |
Notes on Shared Contacts
Shared contacts provide a way to manage contacts that need to be associated with multiple customers. Common use cases include:
- Accountants who manage multiple customer accounts
- Group company contacts who oversee several related businesses
- Third-party service providers
When listing contacts for a customer via /backend/api/v1/customers/ID/customerContacts/, the response includes:
- All direct contacts where customerID matches the specified customer
- All shared contacts that have been linked to the customer
To manage shared contact relationships, use the customer endpoint actions:
addSharedContact- Link a shared contact to a customerremoveSharedContact- Remove the link between a shared contact and a customer