Add/Update Customer

Use this when a customer is created or changes in your system.


The following endpoint can be used to add or update a customer within the Hyfin application. The customer mobile phone number and email address will be used to send payment requests to the customer, as described under Who gets notified below.

Who gets notified

Each customer is under exactly one notification control, worked out from the site and the customer. It is never stored and cannot be set directly.

  • Contact control : each email address and phone number on the customer's contacts carries its own doNotContact flag, and that flag is the only thing that stops automatic messages to it. This is the control for customers created in the app, for every customer on a QuickBooks site that does not map payment methods to notifications, and for integrations on API v4.
  • Customer control : the customer's notificationOptions (one choice each for email, text message and WhatsApp) decide for every address of every contact. A missing choice means notify. This is the control for every customer on a QuickBooks site that maps payment methods to notifications, and for customers whose integration set those options on a version before 4.0.

On API v4:

  • A customer or subscription write that carries notificationOptions is refused with a 400 and the message "notification_options is not accepted on API v4. Set do_not_contact on the contact emails and phone_numbers instead."
  • On an invoice write, notificationOptions is deprecated and will be refused in a future release. It is still applied, exactly as on 3.1: it becomes the invoice's send.to recipients, and the response succeeds with a warnings entry. Sent together with send.to it is refused with a 400. Move to send.to now.
  • A customer write on a site that is not connected to QuickBooks moves that customer to contact control. Its notification options are copied onto doNotContact on every address once, then removed, and the doNotContact values in the request are applied after that.
  • On a QuickBooks site with mapPaymentMethodsToNotifications on, QuickBooks payment methods decide notifications for every customer, so a customer write that carries doNotContact is refused with a 400 that names that setting. Leave the flag out, or have the merchant turn the setting off.
  • onHold: false on an invoice write does not release an invoice that is held because it reaches nobody. Give it a recipient to let it send.
  • The customer read never returns notificationOptions .

Endpoint

The following endpoint can be used to add or update a customer. You must replace the {base_url} and {site_id} variable with the site id that was provided when the site was created.

POST
{base_url}/api/v4/site/{site_id}/customer/addUpdate

Request
Field
Type
Description
_id
String
The id we assign to this customer. Leave it out when creating a customer, and send it when updating one.
externalId
String
Your own id for this customer, from your software. Send the same externalId again to update this customer instead of adding a new one. We match on this value but do not stop duplicates, so keep it unique within the site.
displayName
String
The name that will be displayed for the customer.
accountName
String
The company or household name for the customer, such as ABC Company. It is the name shown for a customer with more than one contact, and for a customer with one contact only when no first or last name is sent.
primaryContact
The customers primary contact information. Required if no contacts are provided.
contacts
A list of customer contacts. Required if primaryContact is not passed in.
parentCustomer
The parent customer, if applicable. A bare _id string is also accepted.
billToParentFlag
Boolean
Set to true to send this customer's invoices to the parent customer to pay. Only applies when parentCustomer is set.
notes
String
Internal customer notes. Visible to merchant only.
attachmentRefs
A list of attachments.
deleted
Boolean
Whether the customer record has been deleted and is no longer active.
Default = false
			
{
  "externalId": "39772634",
  "displayName": "ABC Plumbing",
  "primaryContact": {
    "firstName": "John",
    "lastName": "Doe",
    "mobilePhone": "333-444-5555",
    "email": "johndoe@abc.com",
    "billingAddress": {
      "addressLine1": "123 Main Street",
      "addressLine2": "Suite 123",
      "city": "Naples",
      "stateCode": "FL",
      "zipCode": "34102"
    }
  }
}


		
Response
Field
Type
Description
success
Boolean
Whether the record was added or updated successfully.
action
String
Informs whether the record was added or updated. Will only be returned if success is true.
One of added, updated
_id
String
The id we assign to the record.
updatedAt
The date the record was last updated. A moment in time in ISO 8601, with a time zone. Format = YYYY-MM-DDTHH:mm:ss.SSSZ
errors
String [ ]
A list of errors. Will only be returned if success is false.
			
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "updatedAt": "2025-05-30T19:19:44.143Z"
}


		

Related