Push contacts

Create or update contacts in Helios from any external system.

Use the create-or-update endpoint to push contacts into Helios from your website, backend, or any other system. It powers the Webhook integration and is ideal for keeping Helios in sync with a system Helios doesn’t integrate with natively.

Endpoint

POST https://api.sendhelios.com/v1/customer

Unlike the rest of the API, this endpoint takes your API key in the request body rather than a header, so it’s easy to call from form tools and low-code platforms:

curl -X POST https://api.sendhelios.com/v1/customer \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "YOUR_API_KEY",
    "customer": {
      "phoneNumber": "+15555550123",
      "firstName": "Jamie",
      "lastName": "Rivera",
      "email": "jamie@example.com"
    },
    "properties": {
      "values": { "referral_source": "friend" }
    },
    "addToLists": ["665f1c2ab8d3e40012a4f9d1"]
  }'

Field	Description
`apiKey`	Your API key from the Webhook integration. Required.
`customer.phoneNumber`	The contact’s phone number. Required, and used for matching.
`customer.firstName` / `lastName` / `email`	Optional profile fields. Only provided fields are updated.
`properties.values`	Optional custom properties stored on the contact.
`addToLists` / `removeFromLists`	Optional static list IDs to add the contact to or remove them from.

See the full request schema in the API reference.

How it behaves

Matching: Helios matches on phone number within your inbox. An existing contact is updated in place; a new one is created with api as its source.
Asynchronous: the endpoint queues the write and responds immediately with { "status": "OK" }. The contact appears in your workspace within a few seconds.
Silent auth failures: an invalid API key still receives { "status": "OK" }, but nothing is written. Verify your key first with the verify endpoint.
Custom properties: values in properties.values can drive dynamic segments and merge tags in messages.