HTTP API integration

The HTTP API connects your own website, app or backend to Kirora. Add and update contacts when people sign up, record what they do as events, and use both in segments, journeys and reports.

Before you start

Maintained by: Kirora.
Availability: built in to Kirora, with nothing to install. Use the HTTP API directly, or an official server library; see Is there a library for my language?
Direction: into Kirora, from your server. To send what happens in Kirora back to your systems, use Webhooks.
You need: a backend that can make HTTPS requests, and a Kirora API key, which admins, developers and the owner can create. For plans, see Which plans include it?

What it does

Identify contacts: create a contact, or update the one with the same external ID or email, with their details, attributes and consent. Sync many at once, up to 100 a request.
Track events: record what people do, such as signing up, booking or upgrading, with any properties. Journeys can start on them, segments can filter by them, conversion goals can count them and goals can measure from them.
A key for each source: give every app, environment or tool its own key with only the permissions it needs, so traffic can be traced and one source revoked without touching the rest.
See every call: Developer › Request log shows each key’s calls, with the status and the reason anything failed.

Matching: identify finds the contact by externalId, then email, then phone, and creates one if none matches. A request whose identifiers point to two different contacts is refused with 409, rather than overwriting either.
Consent: a new contact has no marketing consent. Consent you leave out of a request keeps its current value. Granting consent needs a consent.statement saying how the person agreed; withdrawing it doesn’t.

Connect your app

In Kirora, open Developer › API keys and create a key with the scopes your app needs, such as contacts:write, and events:write to track events. Copy it now: it’s shown once.
From your backend, identify a contact when someone signs up:

curl https://api.kirora.io/v1/contacts/identify \
  -H "Authorization: Bearer $KIRORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"externalId":"user_123","email":"[email protected]","firstName":"Ada"}'

Track events as they happen.

Keep the key on your server: never put it in a browser or a mobile app.

Test it

Check the key: GET /v1/me answers with your workspace and the key’s scopes, whatever scopes it has.

curl https://api.kirora.io/v1/me \
  -H "Authorization: Bearer $KIRORA_API_KEY"

Identify yourself, with your own email address. Kirora answers 201 when it creates the contact and 200 when it updates one.
In Kirora, find the contact in Contacts: its Timeline shows the events you track. Developer › Request log shows each call and its status.

Use it for

Onboarding that reacts to what people do: start a welcome journey on sign-up, and nudge people who haven’t finished setting up. See Journeys.
Audiences from your own data: build segments from the attributes and events your app sends. See Contacts and segments.
Receipts and alerts: send transactional email from the same API. See Transactional.

Limitations

Tracking an event on a contact that doesn’t exist is refused with 404: identify the contact first.
An event more than 72 hours old starts no journey.
A workspace tracks up to 1,000 event names, so keep IDs and prices in an event’s properties, not its name.

Get help

Developer › Request log shows the reason any call failed, and the API reference lists every error. For anything else, contact us.

Questions

Which plans include it?

Every plan, Free included, has HTTP API access. Tracking events counts against your plan’s monthly allowance, and conversion goals require Starter or above. Contact management and transactional sending remain available on Free, within its limits.

Your plan’s usual limits apply, such as contacts, emails and up to 1,000 event names per workspace.

Is there a library for my language?

Official server libraries are available for Node.js, Go, .NET and PHP, with a package for Laravel. Every request is plain HTTPS, so any other language works too. See SDKs.

What if my app sends the same request twice?

Campaign triggers require an Idempotency-Key. Tracked events and transactional sends accept one: send it on any request you might retry, because without it every retry repeats the action. A retry with the same key and body returns the existing result without repeating the action. See Idempotency.

Next steps

API quickstart: send your first test email.
API reference: every endpoint and its fields.