Update a contact

PUT https://app.speybooks.com/api/v1/contacts/{id}

Updates one or more fields on an existing contact. Only the fields included in the request body are modified — omitted fields are unchanged (partial update semantics).

Metadata uses merge semantics: existing keys are preserved unless explicitly overwritten. Send a key with value null to remove it.

Path parameters

id string required
Contact ID (e.g. cont_3). Must use the contact prefix.

Body parameters

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.
contactType string optional
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.
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.
name string optional
Primary display name. Required. Used for search matching alongside company and email.
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

200 Contact updated.
Show response fields
updated boolean

Error codes

400 Invalid ID format, validation error, or invalid metadata.
404 Contact not found.