Contact Accounts

Contact Account is the common entity between Customers, Suppliers, Resources, Legal Entities, Staff, etc. that iplicit can transact with.

Name Type Path
GetContactAccounts GET /api/ContactAccount
Gets a list of contact accounts with a search filter
GetContactAccount GET /api/ContactAccount/{contactAccountRef}
Get a contact account
GetContactAccountBankAccounts GET /api/ContactAccount/{contactAccountRef}/bankDetails
Get all the bank details
GetContactAccountMainContact GET /api/ContactAccount/{contactAccountRef}/contact
Get the main contact details of the contact account
GetContactAccountRelatedContacts GET /api/ContactAccount/{contactAccountRef}/contacts
Get the related contacts
GetContactAccountRelatedContact GET /api/ContactAccount/{contactAccountRef}/contacts/{contactRef}
Get an existing related contact
GetContactAccountCustomerDetails GET /api/ContactAccount/{contactAccountRef}/customer
Get the customer details of the contact account
GetContactAccountDefaultBankAccount GET /api/ContactAccount/{contactAccountRef}/defaultBankDetails
Get the default bank details
GetContactAccountResource GET /api/ContactAccount/{contactAccountRef}/resource
Get the resource details of the contact account
GetContactAccountSupplierDefaults GET /api/ContactAccount/{contactAccountRef}/supplier
Get the supplier details of the contact account
CreateContactAccount POST /api/ContactAccount
Create a contact account
AddContactToContactAccount POST /api/ContactAccount/{ca}/contactLinks/{cb}
Add an existing contact to a contact account.
AddContactAccountContact POST /api/ContactAccount/{contactAccountRef}/contacts
Add related contacts
LockCustomer POST /api/ContactAccount/{contactAccountRef}/customer/lock
Lock the customer
UnlockCustomer POST /api/ContactAccount/{contactAccountRef}/customer/unlock
Unlock the customer
LockContactAccount POST /api/ContactAccount/{contactAccountRef}/lock
Lock the Contact Account
LockContactAccountResource POST /api/ContactAccount/{contactAccountRef}/resource/lock
Lock the contact account resource
UnlockContactAccountResource POST /api/ContactAccount/{contactAccountRef}/resource/unlock
Unlock the contact account resource
LockSupplier POST /api/ContactAccount/{contactAccountRef}/supplier/lock
Lock the supplier
UnlockSupplier POST /api/ContactAccount/{contactAccountRef}/supplier/unlock
Unlock the supplier
UnlockContactAccount POST /api/ContactAccount/{contactAccountRef}/unlock
Unlock the contact account
UpdateContactAccount PATCH /api/ContactAccount/{contactAccountRef}
Update a contact account
UpdateContactAccountBankDetails PATCH /api/ContactAccount/{contactAccountRef}/bankDetails/default
Replace bank details
UpdateContactAccountMainContact PATCH /api/ContactAccount/{contactAccountRef}/contact
Update the main contact details
UpdateContactAccountRelatedContacts PATCH /api/ContactAccount/{contactAccountRef}/contacts
Update existing contacts. Existing contacts are matched to request contacts by ID, IntRef or Description and updated. Existing contacts that do not match any request contact are left unchanged. Request contacts that do not match any existing contact are added.
UpdateContactAccountContact PATCH /api/ContactAccount/{contactAccountRef}/contacts/{contactRef}
Update an existing related contact
DeleteContactFromContactAccount DELETE /api/ContactAccount/{ca}/contactLinks/{cb}
Remove an existing contact from a contact account.
DeleteContactAccount DELETE /api/ContactAccount/{contactAccountRef}/contacts/{contactRef}
Delete a related contact.

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 details
  • contacts: all related persons
  • defaultBankDetails or all bankDetails

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 Contact Accounts 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 Contact Accounts 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 the bankDetails 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.

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.

A single related contact can be updated using its id:

PATCH /api/contactAccount/{{contactAccountRef}}/contacts/{{relatedContactId}}

{
  "emails": [ /*...*/ ]
}

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.

DELETE /api/contactAccount/{{contactAccountRef}}/contacts/{{id}}

Set bank details

PATCH /api/contactAccount/{{contactAccountRef}}

{ 
    "bankDetails": [
        { "sortCode": "22-22-33", "accountNo": "4567890123" }
    ]
}

Any existing bank details are replaced with the specified ones.

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.


Updated September 2025