API overview

The Nybero REST API gives your own systems programmatic access to a workspace: create and update contacts, manage tags, send approved templates, enrol contacts into automations and read segments. Anything your landing page, backend, CRM sync or a tool like Zapier/Make can do with HTTP, it can do against this API.

Base URL:

https://app.nybero.com/api/v1

Authentication

Every request needs an API key. Create one in the app under Integrations → REST API (Admin role required): name the key after the system that will use it, click Create key, and copy the nyb_live_… secret — it is shown exactly once. Store it like a password; anyone holding it can act on your workspace.

Pass the key on every request, either way works:

# Option A — Authorization header
curl https://app.nybero.com/api/v1/workspace \
  -H "Authorization: Bearer nyb_live_YOUR_KEY"

# Option B — X-API-Key header
curl https://app.nybero.com/api/v1/workspace \
  -H "X-API-Key: nyb_live_YOUR_KEY"

Keys are workspace-scoped: a key can only reach the workspace it was created in. If you run several WhatsApp numbers (one workspace each), create one key per workspace.

To rotate a key, create a new one, switch your integration over, then Revoke the old key — revocation takes effect immediately.

Rate limits

Each key may make 120 requests per minute. Above that the API returns 429 Too Many Requests with a Retry-After header — back off and retry after that many seconds.

Errors

Errors are JSON with a human-readable detail:

{ "detail": "Contact has opted out" }

Status	Meaning
`401`	Missing, invalid or revoked API key
`402`	Subscription inactive, or the monthly send limit is reached
`404`	The referenced resource does not exist in this workspace
`409`	Conflict — e.g. contact opted out, already enrolled, automation inactive
`422`	Validation error — malformed body, invalid phone number, missing field
`429`	Rate limit exceeded (see `Retry-After`)
`502`	Meta rejected a send — the `detail` contains Meta’s error

Pagination

List endpoints that can grow large (/contacts, /segments/{id}/contacts) take limit (default 50, max 100) and offset and return the total:

{ "data": [ … ], "total": 1240, "limit": 50, "offset": 0 }

Fetch the next page by increasing offset until you have total items.

Endpoints at a glance

Method & path	What it does
`GET /v1/workspace`	Workspace id + name (good connectivity check)
`GET /v1/contacts`	List/search contacts (Contacts)
`POST /v1/contacts`	Create or update a contact by phone
`GET /v1/contacts/{id}`	One contact
`PATCH /v1/contacts/{id}`	Update name, locale, source, attributes
`DELETE /v1/contacts/{id}`	GDPR delete
`POST /v1/contacts/{id}/tags`	Add a tag
`DELETE /v1/contacts/{id}/tags/{name}`	Remove a tag
`GET /v1/tags`	All tags in the workspace
`GET /v1/templates`	Approved templates (Messaging)
`POST /v1/messages/template`	Send an approved template
`GET /v1/automations`	List automations (Automations & segments)
`POST /v1/automations/{id}/enroll`	Enrol a contact into an automation
`GET /v1/segments`	List segments
`GET /v1/segments/{id}/contacts`	Contacts currently matching a segment
`GET /v1/events`	Available webhook event types (Webhook events)
`GET/POST /v1/subscriptions`	List / create webhook subscriptions
`DELETE /v1/subscriptions/{id}`	Remove a webhook subscription

A 60-second smoke test

export NYBERO_KEY="nyb_live_YOUR_KEY"

# 1. Who am I?
curl -s https://app.nybero.com/api/v1/workspace \
  -H "Authorization: Bearer $NYBERO_KEY"
# → {"id":"…","name":"My workspace"}

# 2. Create a contact with consent
curl -s https://app.nybero.com/api/v1/contacts \
  -H "Authorization: Bearer $NYBERO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+4915112345678","name":"Ada Example","opt_in":true,
       "consent_proof":"Signed up on example.com/webinar"}'

If both return JSON without an error, you’re connected — continue with Contacts.