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

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.