Create a customer

POST/api/v1/customers

property adds their first property in the same request: both are saved, or neither is. When the property is refused, each error's source.pointer names its field under /data/attributes/property. Returns the customer with its contacts and properties.

Needs an API key, and runs with the access of the member who made the key.
Send an Idempotency-Key. The same key with the same request within 24 hours gives the first answer again and changes nothing.
A connected AI assistant can use it too, as createCustomer.

Parameters

Headers

Idempotency-Keystringrequired
Unique user-scoped key for safely retrying this mutation for 24 hours.
At least 1 character. Up to 200 characters.

Request body

Sent as application/json.

customerobjectrequired
Fields(12)
- lock_versioninteger
  At least 0.
- namestringrequired
- company_namestring or null
- emailstring (email) or null
- phonestring or null
- payment_terms_daysinteger
  At least 0.
- notesstring or null
- automatic_emailsboolean
  Deprecated: use `invoice_reminders`, `quote_follow_ups` and `visit_reminders`, which it stands for. It reads false only when all three are `off`. Writing false sets all three to `off`; writing true sets all three to `default` when they were all `off`, and otherwise changes nothing. Sent with any of the three, it is ignored. It changes nothing about emails a person sends.
  Default: true. Deprecated.
- invoice_remindersstring
  Whether this customer is reminded by email about their overdue invoices.
  One of: default, on, off. Default: "default".
- quote_follow_upsstring
  Whether this customer's quotes awaiting an answer are followed up by email.
  One of: default, on, off. Default: "default".
- visit_remindersstring
  Whether this customer is reminded by email of their visits the day before.
  One of: default, on, off. Default: "default".
- billing_addressobject or null
  Fields(6)
  address_line_1stringrequired
  address_line_2string or null
  citystringrequired
  regionstring or null
  postal_codestringrequired
  country_codestringrequired
  At least 2 characters. Up to 2 characters.
propertyobject or null
The customer's first property, with the fields createCustomerProperty takes. Leave it out, or send null, to add one later.
Fields(12)
- lock_versioninteger
  At least 0.
- namestring or null
- address_line_1stringrequired
- address_line_2string or null
- citystringrequired
- regionstring or null
- postal_codestringrequired
- country_codestring
  Defaults to GB.
  Default: "GB". At least 2 characters. Up to 2 characters.
- access_notesstring or null
- lawn_area_m2string or null
  The lawn at the property in square metres, with up to two decimal places, or null when it has not been measured. Use it as the quantity of lawn work priced per square metre, such as turfing. A patio or decking is priced the same way and is some other size.
  Matches ^\d{1,8}(\.\d{1,2})?$.
- billing_namestring or null
  Who quotes and invoices for work here are addressed to, such as a letting agent. Defaults to the customer.
- billing_addressobject or null
  Where quotes and invoices for work here are sent, before the customer's billing address. Omit to keep, null to clear.
  Fields(6)
  address_line_1stringrequired
  address_line_2string or null
  citystringrequired
  regionstring or null
  postal_codestringrequired
  country_codestringrequired
  At least 2 characters. Up to 2 characters.

Responses

201Customer details, contacts, and properties.

dataobjectrequired
Fields(20)
- lock_versioninteger
  At least 0.
- created_atstring (date-time)required
- updated_atstring (date-time)required
- idstring (uuid)required
- account_idstring (uuid)required
- namestringrequired
- company_namestring or null
- emailstring (email) or null
- phonestring or null
- payment_terms_daysintegerrequired
  At least 0.
- notesstring or null
- automatic_emailsboolean
  Deprecated: use `invoice_reminders`, `quote_follow_ups` and `visit_reminders`, which it stands for. It reads false only when all three are `off`. Writing false sets all three to `off`; writing true sets all three to `default` when they were all `off`, and otherwise changes nothing. Sent with any of the three, it is ignored. It changes nothing about emails a person sends.
  Default: true. Deprecated.
- invoice_remindersstring
  Whether this customer is reminded by email about their overdue invoices.
  One of: default, on, off. Default: "default".
- quote_follow_upsstring
  Whether this customer's quotes awaiting an answer are followed up by email.
  One of: default, on, off. Default: "default".
- visit_remindersstring
  Whether this customer is reminded by email of their visits the day before.
  One of: default, on, off. Default: "default".
- billing_addressobject or null
  Fields(6)
  address_line_1stringrequired
  address_line_2string or null
  citystringrequired
  regionstring or null
  postal_codestringrequired
  country_codestringrequired
  At least 2 characters. Up to 2 characters.
- portal_urlstring (uri) or null
  The customer's sign-in link to their customer portal. It signs them in without a password, so it is null for technicians, for AI assistants and for an archived customer. Replace it with rotateCustomerPortalKey.
  Read only.
- archived_atstring (date-time) or null
- contactsarray of objectrequired
  Each item(12)
  lock_versioninteger
  At least 0.
  created_atstring (date-time)required
  updated_atstring (date-time)required
  idstring (uuid)required
  account_idstring (uuid)required
  customer_idstring (uuid)required
  namestringrequired
  job_titlestring or null
  emailstring (email) or null
  phonestring or null
  notesstring or null
  archived_atstring (date-time) or null
- propertiesarray of objectrequired
  Each item(20)
  lock_versioninteger
  At least 0.
  created_atstring (date-time)required
  updated_atstring (date-time)required
  idstring (uuid)required
  account_idstring (uuid)required
  customer_idstring (uuid)required
  namestring or null
  address_line_1stringrequired
  address_line_2string or null
  citystringrequired
  regionstring or null
  postal_codestringrequired
  country_codestringrequired
  access_notesstring or null
  lawn_area_m2string or null
  The lawn at the property in square metres, with up to two decimal places, or null when it has not been measured. Use it as the quantity of lawn work priced per square metre, such as turfing. A patio or decking is priced the same way and is some other size.
  Matches ^\d{1,8}(\.\d{1,2})?$.
  latitudenumber (double) or null
  Where the property is, to the middle of its postcode. Looked up shortly after the property is saved, and null until then. Stays null when the postcode is unknown, in Northern Ireland or outside the United Kingdom.
  At least -90. At most 90. Read only.
  longitudenumber (double) or null
  At least -180. At most 180. Read only.
  billing_namestring or null
  billing_addressobject or null
  Fields(6)
  address_line_1stringrequired
  address_line_2string or null
  citystringrequired
  regionstring or null
  postal_codestringrequired
  country_codestringrequired
  At least 2 characters. Up to 2 characters.
  archived_atstring (date-time) or null

A refusal answers in the one error shape every operation shares.

Example

A request our own tests send. The ids are made up: put your own in their place.

curl -X POST "https://app.tradesender.co.uk/api/v1/customers" \
  -H "Authorization: Bearer $TRADESENDER_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "customer": {
    "name": "Taylor Home",
    "email": "taylor@example.test",
    "phone": "+44 7700 900123",
    "payment_terms_days": 7,
    "notes": "Prefers a text the day before.",
    "billing_address": {
      "address_line_1": "20 Billing Road",
      "city": "London",
      "postal_code": "EC1A 1BB",
      "country_code": "GB"
    }
  },
  "property": {
    "name": "Allotment",
    "address_line_1": "4 Garden Lane",
    "city": "London",
    "postal_code": "N1 2BB",
    "access_notes": "Gate code 2468."
  }
}'