Create a contact

POST https://app.speybooks.com/api/v1/contacts/

Creates a new contact. Only contactType and name are required — all other fields are optional and default to sensible values (country defaults to United Kingdom, payment terms to 30 days, currency to GBP).

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

Body parameters

contactType string required
One of customer, supplier, or both. Determines which transaction flows the contact participates in. Contacts marked both appear in both customer and supplier filtered lists.
name string required
Primary display name. Required. Used for search matching alongside company and email.
addressLine1 string optional
First line of the postal address.
addressLine2 string optional
Second line of the postal address.
bankAccount string optional
Bank account number. Optional, for payment reference.
bankIban string optional
International Bank Account Number. Optional, for international payments.
bankName string optional
Name of the contact's bank. Optional, for payment reference.
bankSortCode string optional
UK sort code. Optional, for payment reference.
city string optional
City or town.
company string optional
Optional company or trading name. Searched alongside name and email in list queries.
country string optional
Country name. Defaults to United Kingdom on creation.
currency string optional
ISO 4217 currency code. 3 characters, defaults to GBP. Determines the currency used on invoices for this contact.
email string optional
Optional email address. Validated format when provided. Used for invoice delivery.
isActive string optional
Whether the contact is active. Inactive contacts are hidden from default list queries but retained for audit. Set to false automatically when a contact with invoices is deleted.
metadata string optional
Custom key-value pairs. Max 50 keys, values must be strings. Keys prefixed _sb_ are reserved. Uses merge semantics on update — send null to remove a key.
notes string optional
Free-text notes. Up to 2,000 characters. Not visible on invoices.
paymentTerms string optional
Default payment terms in days. Integer 0–365, defaults to 30. Applied when creating invoices for this contact.
phone string optional
Optional phone number. Free-text, no format validation.
postalCode string optional
Postal code or ZIP code.
region string optional
County, region, or state.
vatNumber string optional
VAT registration number. Free-text, no format validation. Used on invoices for compliance.

Response

201 Contact created. Returns the prefixed ID and name.
Show response fields
id string
name string

Error codes

400 Validation error in contact data or metadata.