Contact accounts
A Contact Account is the common entity between Customers, Suppliers, Resources, Legal Entities, Staff, etc. that Iplicit can transact with.
Searching existing customers, suppliers & resources
Existing contact accounts can be searched using GET /api/contactAccount
.
Note this is a paginated response, and will return by default up to 100 results. Use the skip
and take
query parameters to get next pages:
GET /api/contactAccount?skip=300&take=100
See reference for supported search criteria: GET /api/contactAccount
Loading additional details:
A contact account can be retrieved by its id, code or intRef (referred to collectively as contactAccountRef
below and in the reference documentation):
GET /api/contactAccount/11822dbe-9818-48f6-8b3d-21fff150f2bc
GET /api/contactAccount/CU100
GET /api/contactAccount/INTREF100
Additional details can be included:
customer
supplier
resource
contact
: main contact detailscontacts
: all related personsdefaultBankDetails
or allbankDetails
The details can be loaded either in isolation:
GET /api/contactAccount/CU100/customer
GET /api/contactAccount/CU100/defaultBankDetails
or in one request:
GET /api/contactAccount/CU100?include=customer,defaultBankDetails
Creating a new customer
This is the minimal example to create a customer:
POST /api/contactAccount
{
"description": "API1",
"customer": {
"contactGroupCustomerId": "CU"
}
}
See the Field reference below to add additional fields and sections to provide more data, if available.
Creating a new supplier
This is the minimal example to create a supplier:
POST /api/contactAccount
{
"description": "API Customer 1",
"supplier": {
"contactGroupCustomerId": "CU"
}
}
Creating a new resource
This is the minimal example to create a resource:
POST /api/contactAccount
{
"description": "API Customer 1",
"resource": {
"resourceGroupId": "RG"
}
}
See the Field reference below to add additional fields and sections to provide more data, if available.
Complete example:
This is a complete example that contains all supported fields.
Note the codes might vary in your environment so be sure to consult the available reference catalogs in Iplicit or via the catalogs endpoints
POST /api/contactAccount
{
"code": "IPL",
"intRef": "67646487",
"description": "Iplicit Ltd",
"companyNo": "07194134",
"taxNo": "19274745",
"legacyRef": "19028",
"theirRef": "IPLICIT",
"countryCode": "UK",
"contactClassificationId": "CORPORATE",
"customer": {
"contactGroupCustomerId": "CU",
"currency": "GBP",
"creditLimit": 100000,
"discountRate": 15,
"paymentMethodId": "BACS",
"payTermId": "90",
"receiveInvoices": true,
"receiveReminders": true,
"receiveStatements": true,
"taxBandId": "S",
"taxBandFixed": false,
"taxAuthorityId": "EW"
},
"supplier": {
"contactGroupSupplierId": "UK1",
"currency": "GBP",
"creditLimit": 100000,
"paymentMethodId": "BACS",
"payTermId": "90",
"sendRemittance": true,
"taxBandId": "S",
"taxBandFixed": false,
"taxAuthorityId": "EW"
},
"resource": {
"resourceGroupId": "RG",
"departmentId": "DEV",
"locationId": "IPS",
"nationalInsuranceNo": "123",
"currency": "GBP",
"absenceGroupId": "FE9190DF-66B5-489C-B1F7-3E7E5961A7EF",
"costCentreId": "LOND",
"managerResourceId": "MGR1",
"uniqueTaxpayerReference": "abc123",
"isSalesperson": true,
"isBuyer": true,
"isRequestor": true,
"allowExpense": true,
"allowTask": true,
"allowTimesheet": true,
"hasEmployment": true,
"hasUmbrella": true,
"paymentMethodId": "CC",
"paymentTermsId": "0",
"sendRemittance": true,
"resourceEmployments": [
{
"dateFrom": "2023-11-08T00:00:00",
"dateTo": "2023-11-29T00:00:00",
"legalEntityId": "LEGEA",
"employmentTypeId": "P",
"jobTitle": "Developer",
"jobGrade": "A",
"paymentFrequencyId": "M",
"previousEmployer": "RN",
"terminationNoticeDays": 1,
"ExcludeFromIntermediaryReport":false,
"externalReference": "0000"
}
],
"resourceUmbrellas": [
{
"umbrellaContactAccountId": "UID",
"dateFrom": "2023-11-08T00:00:00",
"dateTo": "2023-11-29T00:00:00"
}
],
"ext": {
"DateJoin": "2023-11-08",
"DOB": "2003-09-03",
"Gender": "M",
"Alt": "carringtonj"
}
},
"contact": {
"companyName": "Iplicit Ltd",
"phones": [
{"phone": "020 0123 456", "type": "R"},
{"phone": "020 0123 456", "type": "AC"}
],
"emails": [
{"email": "contact@iplicit.com", "type": "O"},
{"email": "accounts@example.com", "type": "AC"}
],
"addresses": [
{"postCode": "EC1 AAA", "address": "144 Cambridge Heath Rd", "city": "London", "countryCode": "GB", "type": "R" }
]
},
"contacts": [
{
"title": "Mr", "firstName": "John", "lastName": "Doe", "jobTitle": "Director",
"emails": [
{"email": "john.doe@example.com"}
],
"phones": [
{"phone": "020 0123 456 (int 1)", "type": "O"}
]
},
{
"title": "Mrs", "firstName": "Jane", "lastName": "Doe", "jobTitle": "FD",
"emails": [
{"email": "jane.doe@example.com"}
],
"phones": [
{"phone": "020 0123 456 (int 2)"}
]
}
],
"bankDetails": [
{
"iban": "11111",
"accountNo": "12345678",
"sortCode": "11-22-33",
"bic": "11111",
"bankRef": "REF100"
}
]
}
See reference for supported search criteria: POST /api/contactAccount
Updating an existing contact account
The updating of contact accounts is done by patching: only the specified fields will be updated.
Any part of the contact account can be patched:
customer
(if the contact account was not a customer, it will be created as a customer)supplier
(if the contact account was not a supplier, it will be created as a supplier)resource
(if the contact account was not a resource, it will be created as a resource)contact
contacts
(related people)bankDetails
The following sections are completely replaced if they are specified in the patch object:
- contact
phones
,emails
,addresses
lists bankDetails
: if a patch of contact account contains thebankDetails
section, all existing bank details are completely replaced with the provided values)
Examples
Simple update
PATCH /api/contactAccount/{{contactAccountRef}}
{
"CompanyNo": "123456789",
"TheirRef": "C100"
}
This will only update the 2 fields specified, keeping everything else as is.
Updating customer (supplier) fields
PATCH /api/contactAccount/{{contactAccountRef}}
{
"Customer": {
"Currency": "EUR"
}
}
This will update the customer's default currency to EUR, leaving everything as is.
Updating main contact details
PATCH /api/contactAccount/{{contactAccountRef}}/contact
{
"company": "ACME Ltd",
"phones": [
{ "phone": "020 1000 200", "type": "R" }
]
}
In the above example all existing phone numbers are replaced with the specified one. All other fields are preserved, including the list of emails and addresses.
This request is similar to updating the contact account and specifying the contact
section.
PATCH /api/contactAccount/{{contactAccountRef}}/contact
{
"phones": [
{ "phone": "020 1000 200", "type": "R" }
],
"emails": [],
"addresses": []
}
In the above example, all existing phones, emails and addresses are removed and a single phone number is added.
Add a related contact
POST /api/contactAccount/{{contactAccountRef}}/contacts
{
"title": "Mr",
"firstName": "John",
"lastName": "Doe",
"emails": [ /* ... */ ],
"phones": [ /* ... */ ],
"addresses": [ /* ... */ ]
}
The type of contact is inferred from the presence of firstName
, lastName
or companyName
.
Updating a single related contact:
A single related contact can be updated using its id:
PATCH /api/contactAccount/{{contactAccountRef}}/contacts/{{relatedContactId}}
{
"emails": [ /*...*/ ]
}
Updating all related contacts:
PATCH /api/contactAccount/{{contactAccountRef}}/contacts
[
{ "id": "(uuid)", "firstName": "John", "lastName": "Doe", "emails": [ /*...*/ ] },
{ "id": "(uuid)", "firstName": "Name", "lastName": "Doe", "emails": [ /*...*/ ] }
]
Existing contacts merge updates, unmatched contacts are removed.
This request is similar to updating the contact account and specifying the contacts
section.
Removing a related contact
DELETE /api/contactAccount/{{contactAccountRef}}/contacts/{{id}}
Set bank details
PATCH /api/contactAccount/{{contactAccountRef}}
{
"bankDetails": [
{ "sortCode": "22-22-33", "accountNo": "4567890123" }
]
}
A new line is inserted at the bottom of the bank details when you patch through contact account.
Locking
Locking (soft deleting) a customer, supplier or resource:
POST /api/contactAccount/{{contactAccountRef}}/customer/lock
POST /api/contactAccount/{{contactAccountRef}}/supplier/lock
POST /api/contactAccount/{{contactAccountRef}}/resource/lock
Unlocking:
POST /api/contactAccount/{{contactAccountRef}}/customer/unlock
POST /api/contactAccount/{{contactAccountRef}}/supplier/unlock
POST /api/contactAccount/{{contactAccountRef}}/resource/unlock
Locked customers, suppliers and resources have isActive
field set to false
.