Integration

Exports and app settings

Exports provide time-limited CSV extracts for analysis and data requests. App settings control identity, locale, pacing, quiet hours, and frequency caps.

Create an export#

POST /v1/exports

{"type":"events"}

Valid types are:

audience — users and device audience data;
messages — notification records;
recipients — per-recipient delivery state;
events — lifecycle and custom events; and
audit — auditable app activity.

Creation returns 202 Accepted.

{
  "export_id": "ee80221d-1048-4fcf-8d44-f2e098b4fb7d",
  "status": "pending"
}

Check and download#

GET /v1/exports
GET /v1/exports/{export_id}/download

The list returns up to the 100 newest exports with status, error, creation/completion time, and expiry. Download succeeds only after status is completed and before expires_at; otherwise it returns 404.

Completed downloads use text/csv; charset=utf-8 and a HoneyNotify filename. Export files expire after 24 hours. Download them to appropriately protected storage and delete local copies when no longer needed.

Update app settings#

PATCH /v1/app/settings

Only supplied fields are changed.

Field	Type and limits	Effect
`default_locale`	language tag, max 20	Fallback locale for content
`identity_public_key`	PEM public key or `null`	ES256 verification key
`identity_verification_required`	boolean	Requires verified user association
`frequency_cap_count`	integer `1`–`65535` or `null`	Maximum sends per cap window
`frequency_cap_window_seconds`	integer `1`–`31536000` or `null`	Cap window, up to one year
`throttle_per_minute`	integer `1`–`1000000` or `null`	App delivery pacing
`quiet_hours_start`	`HH:MM` or `null`	Beginning of local quiet period
`quiet_hours_end`	`HH:MM` or `null`	End of local quiet period

Frequency cap count and window must be configured together. Clear both together with JSON null values.

{
  "default_locale": "en-GB",
  "frequency_cap_count": 4,
  "frequency_cap_window_seconds": 86400,
  "throttle_per_minute": 12000,
  "quiet_hours_start": "21:30",
  "quiet_hours_end": "08:00"
}

Quiet hours and local delivery depend on accurate device/user timezones. Decide how your product should treat missing timezone data, and keep profiles refreshed through SDK registration.

Enable identity verification safely#

Identity verification cannot be enabled without a valid public key. A safe cutover is:

Generate an ES256 key pair in your secure backend environment.
Store the private key only in your backend secret manager.
Patch identity_public_key with the PEM public key.
Add identity-token issuance and consumption to every supported client version.
Verify current clients can register successfully.
Patch identity_verification_required to true.

If you submit the public key and identity_verification_required: true in one patch, HoneyNotify validates the combined resulting state.

What is not exposed#

Push-provider credentials remain write-only and are managed through the dashboard or credential tooling. The API never returns APNs keys, FCM credentials, webhook signing secrets after creation/rotation, raw API keys, or device push tokens.