Create a contact

POSThttps://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.

Contacts are not deduplicated: creating two contacts with the same name or email yields two separate records.

Body parameters

contactTypestringrequired
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.
namestringrequired
Primary display name. Required. Used for search matching alongside company and email.
addressLine1stringoptional
First line of the postal address.
addressLine2stringoptional
Second line of the postal address.
bankAccountstringoptional
Bank account number. Optional, for payment reference.
bankIbanstringoptional
International Bank Account Number. Optional, for international payments.
bankNamestringoptional
Name of the contact's bank. Optional, for payment reference.
bankSortCodestringoptional
UK sort code. Optional, for payment reference.
citystringoptional
City or town.
companystringoptional
Optional company or trading name. Searched alongside name and email in list queries.
countrystringoptional
Country name. Defaults to United Kingdom on creation.
currencystringoptional
ISO 4217 currency code. 3 characters, defaults to GBP. Determines the currency used on invoices for this contact.
emailstringoptional
Optional email address. Validated format when provided. Used for invoice delivery.
isActivestringoptional
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.
metadatastringoptional
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.
notesstringoptional
Free-text notes. Up to 2,000 characters. Not visible on invoices.
paymentTermsstringoptional
Default payment terms in days. Integer 0–365, defaults to 30. Applied when creating invoices for this contact.
phonestringoptional
Optional phone number. Free-text, no format validation.
postalCodestringoptional
Postal code or ZIP code.
regionstringoptional
County, region, or state.
vatNumberstringoptional
VAT registration number. Free-text, no format validation. Used on invoices for compliance.

Response

201Contact created. Returns the prefixed ID and name.
Show response fields
idstring
namestring

Error codes

400Validation error in contact data or metadata.