Add/Update Contact

Use this when a customer has more than one person who should get texts and emails, such as an owner and a bookkeeper.


The following endpoint can be used to add or update a contact within the Hyfin application.


Endpoint

The following endpoint can be used to add or update a contact. You must replace the {base_url} and {site_id} variable with the id of the customer that this contact belongs to.

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

Request
Field
Type
Description
_id
String
The id we assign to this contact. Leave it out when creating a contact, and send it when updating one.
externalId
String
Your own id for this contact, from your software. Send the same externalId again to update this contact instead of adding a new one. We match on this value but do not stop duplicates, so keep it unique within the site.
firstName
String
The first name of the contact.
lastName
String
The last name of the contact.
displayName
String
The name that will be displayed for the contact. If left blank, it will default to the first and last name.
language
String
The preferred language for the contact. Uses ISO 639-1 language codes.
Default = en
emails
A list of email addresses for the contact.
phoneNumbers
A list of phone numbers for the contact.
addresses
A list of addresses for the contact.
Sample Request (Add a Contact)
			
{
  "externalId": "58810342",
  "firstName": "John",
  "lastName": "Doe",
  "displayName": "John Doe",
  "language": "en",
  "emails": [
    {
      "label": "work",
      "address": "johndoe@abc.com",
      "isPrimary": true
    }
  ],
  "phoneNumbers": [
    {
      "label": "mobile",
      "number": "333-444-5555",
      "isPrimary": true
    }
  ],
  "addresses": [
    {
      "label": "billing",
      "isPrimary": true,
      "address": {
        "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