Subscribers API

POST /api/v1/subscribers/upsert

Creates or updates a subscriber record, keyed by external_id. Authenticated with the publishable SDK key (X-SDK-Key header). Idempotent: re-sending the same body converges on the same record, which is what makes retrying pipelines (Zapier, reverse-ETL) safe.

Request Body

{
  "external_id": "user-123",
  "email": "user@example.com",
  "attributes": {
    "plan": "pro",
    "country": "US"
  }
}

external_id is the only required field. An optional consent assertion records an express email opt-in alongside the upsert.

Response

200 with the stored subscriber:

{
  "id": "8a2f6c1e-…",
  "external_id": "user-123",
  "email": "user@example.com",
  "attributes": "{\"plan\":\"pro\",\"country\":\"US\"}",
  "created_at": "2026-07-26T12:00:00Z",
  "updated_at": "2026-07-26T12:00:00Z"
}

attributes travels as a JSONB-encoded string (schemaless by design). 401 — missing or invalid SDK key. 422 — validation failure naming the field.

DELETE /api/v1/subscribers/{id}

Authenticated with a dashboard bearer token (see Authentication). Permanently deletes a single subscriber and all associated devices and list memberships. Delivery log rows are anonymised (foreign keys set to NULL) rather than deleted.

For GDPR compliance details, cascade behaviour, and the operator runbook, see the GDPR Data Retention Policy guide.

Path parameters

Parameter	Type	Description
id	string (UUID)	Hober subscriber UUID

Response

204 No Content on success. No response body.

Error responses

Status	Meaning
401	Missing or invalid bearer token
404	Subscriber not found

POST /api/v1/subscribers/bulk-delete

Permanently deletes up to 1,000 subscribers in one GDPR-compliant transaction. Authenticated with a dashboard bearer token. IDs not found in your workspace are returned in not_found and are not treated as errors.

Request body

{
  "subscriber_ids": ["uuid-1", "uuid-2", "uuid-3"]
}

Field	Type	Description
subscriber_ids	string[]	Hober subscriber UUIDs. 1–1,000 per request.

Response

200 OK:

{
  "deleted": 2,
  "not_found": ["uuid-3"]
}

Error responses

Status	Meaning
401	Missing or invalid bearer token
422	Empty list, or more than 1,000 IDs supplied

For cascade behaviour see the GDPR Data Retention Policy guide.