Contacts & Directors

Contacts and directors are the people and organisations your company trades with and is run by. Contacts appear on invoices and bills; directors and shareholders control dividend allocation and Director Loan Account (DLA) calculations.

This guide covers both resources together because they work in tandem: contacts are referenced by invoices, and directors are referenced by dividends and director loans. For the full endpoint reference, see Contacts API and Directors API.

Contacts

Contact types

Every contact has a contactType that determines which transaction flows they participate in:

Type filtering is inclusive: filtering for customer returns contacts with type customer or both. Filtering for both returns only contacts explicitly marked as dual-role.

Creating a contact

Only contactType and name are required. All other fields are optional with sensible defaults: country defaults to United Kingdom, payment terms to 30 days (integer, 0-365), and currency to GBP (must be exactly 3 characters, ISO 4217).

The email field accepts an empty string to explicitly clear a previously set email address. All other optional fields accept null.

Listing and filtering contacts

The list endpoint returns contacts paginated (default 50 per page, max 100), sorted alphabetically by name. Use query parameters to filter:

Updating a contact

The update endpoint (PUT /contacts/{id}) uses partial update semantics: only the fields you include in the request body are modified. Omitted fields are left unchanged. (Note: contacts use PUT while directors use PATCH for the same partial-update behaviour - a design quirk that may be aligned in a future API version.)

Metadata merge semantics

Contact metadata uses merge semantics on update, unlike invoice metadata which is replaced entirely. Send a key with a string value to add or overwrite it. Send a key with a null value to remove it. Existing keys not mentioned in the request are preserved.

Keys prefixed with _sb_ are reserved for system use. Maximum 50 keys, all values must be strings.

Contact summary

The summary endpoint returns a contact's identity alongside aggregated invoice statistics: total invoices raised, open (unpaid) invoices, total amount invoiced, and outstanding balance. All monetary values are in minor units (pence). This is useful for contact detail pages and credit control dashboards.

Deleting a contact

The DELETE /contacts/{id} endpoint follows a safe deletion pattern:

Deactivated contacts are hidden from default list queries (where active=true) but retained for audit and reporting. All data and invoice relationships are preserved.

Directors

Directors represent the officers and shareholders of a limited company. The directors resource requires a limited company plan.

Shareholding

The isShareholder flag controls whether a director participates in dividend allocation. When true, the sharesHeld and shareClass fields are used to calculate dividend per-share amounts. Share class defaults to Ordinary.

A person can be a shareholder without being a director (and vice versa), but both are stored in the directors table. The shareholdersOnly query parameter on the list endpoint filters to just shareholders.

Creating a director

Only fullName is required. Defaults: isShareholder is true, shareClass is Ordinary.

To link a connected person for S455 aggregation, provide both connectedToDirectorId and relationship. Both must be present together or both omitted - the API validates this as a pair.

Connected persons and S455

Directors can be linked via connectedToDirectorId and relationship (one of spouse, child, parent, associate). These links are used by the DLA balance endpoints to aggregate connected persons' balances when calculating S455 Corporation Tax exposure, per HMRC connected persons rules.

For the full S455 calculation workflow, see Director Loans & S455 Guide.

Listing directors

The list endpoint returns directors sorted by active status (active first) then alphabetically by name. Two query parameters are available:

Unlike contacts, directors are not paginated - the list returns all matching records.

Updating a director

The update endpoint (PATCH /directors/{id}) uses partial update semantics. Only the fields included in the request body are modified. You can update fullName, email, address, isShareholder, sharesHeld, shareClass, appointedDate, resignedDate, active, connectedToDirectorId, and relationship.

Resigning a director

The DELETE /directors/{id} endpoint is a soft-delete operation. It sets active to false and resignedDate to the current date (using COALESCE to preserve any existing resignation date). No request body is accepted.

The director record is preserved for historical reporting on dividends and director loan accounts. The endpoint returns the updated director object. If the director is already resigned (not active), the endpoint returns 404.

If you created a director by mistake (for example, a typo in the name), use PATCH /directors/{id} to correct the record rather than DELETE. Resignation permanently archives the director as a former officer - there is no hard-delete.

How contacts and directors work together

Contacts and directors serve different purposes but overlap in practice:

Contacts are external trading partners referenced by invoices and quotes. They carry banking details, payment terms, and currency defaults. Every invoice must reference a contact.

Directors are internal officers and shareholders referenced by dividends and director loan accounts. They carry shareholding details, appointment dates, and connected person links.

A director who is also a supplier (for example, billing the company for expenses) would exist as both a director record and a contact record. The two are not linked automatically - they are independent resources.

Worked example: setting up a new company

1. Add directors - POST /directors for each officer and shareholder, setting sharesHeld and shareClass
2. Link connected persons - create the spouse/family member directors with connectedToDirectorId and relationship
3. Add customers - POST /contacts with contactType: "customer" for each client
4. Add suppliers - POST /contacts with contactType: "supplier" for regular vendors
5. Start invoicing - create invoices referencing your contacts (see Invoices & Quotes Guide)
6. Track DLA - record director loan transactions (see Director Loans & S455 Guide)

Related endpoints

• Contacts API - full contact endpoint reference
• Directors API - full director endpoint reference
• Director Loans & S455 Guide - DLA balances, S455, and BiK calculations
• Invoices & Quotes Guide - creating invoices that reference contacts