API & Webhooks

Pagination & errors

List endpoints accept ?limit= (max 100, default 50) and ?offset=, and return results newest-first — that ordering makes them usable as Zapier/Make polling triggers out of the box, with no extra "since" parameter needed.

{ "data": [ ... ], "total": 142 }

Errors return a matching HTTP status with a plain message:

{ "error": "client_id not found for this agency" }

Clients

The companies or individuals an agency works with.

Fields

Create a client

curl https://orbinly.com/api/v1/clients \
  -H "Authorization: Bearer ob_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc.",
    "email": "hello@acme.com",
    "company": "Acme Inc."
  }'

Projects

A project belongs to one client.

Fields

Create a project

curl https://orbinly.com/api/v1/projects \
  -H "Authorization: Bearer ob_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Website redesign",
    "client_id": "3c1a...-uuid",
    "status": "active"
  }'

Tasks

A task belongs to one project. Internal-only tasks are never exposed through the API.

Fields

Create a task

curl https://orbinly.com/api/v1/tasks \
  -H "Authorization: Bearer ob_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Design homepage hero",
    "project_id": "9b2e...-uuid",
    "priority": "high"
  }'

Invoices

Invoices always belong to a client, and optionally a project. Line items are required on create.

Fields

Create a invoice

curl https://orbinly.com/api/v1/invoices \
  -H "Authorization: Bearer ob_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "3c1a...-uuid",
    "due_date": "2026-10-15T00:00:00Z",
    "line_items": [
      { "description": "Design work", "quantity": 1, "unit_amount": 150000 }
    ]
  }'

Add an endpoint URL and pick events from Settings → Developer and Orbinly will POST a JSON payload to it in real time as those events happen — no polling required. Failed deliveries are retried automatically for up to 5 attempts.

Event types

Payload shape

{
    "type": "invoice.paid",
    "created_at": "2026-09-16T14:03:00.000Z",
    "data": {
      "id": "0f2c...-uuid",
      "invoice_number": "INV-202609-4821",
      "total_amount": 150000,
      "currency": "USD"
    }
  }

Verifying the signature

Every delivery includes an X-Orbinly-Signature header — an HMAC-SHA256 of the raw request body, signed with the endpoint's own secret (shown once, when you create the endpoint). Recompute it and compare before trusting a payload:

const expected = "sha256=" + crypto
    .createHmac("sha256", endpointSecret)
    .update(rawRequestBody)
    .digest("hex");

  // compare to the X-Orbinly-Signature header

From Admin → Integrations, an agency can embed any tool with its own web page — a booking widget, a dashboard, a form — directly in the client portal via iframe. One URL per tool, shown to every client of that agency. Orbinly appends a short-lived, signed context to the URL so your tool's own backend can verify which agency, client, and contact is viewing.

Agencies can also pick ready-made tools from a gallery — Calendly, Cal.com, Google Calendar, HubSpot Meetings, Typeform, Jotform, Google Forms, YouTube, Vimeo, Loom and Airtable. Those can't use a signed context, so they are added with “Tell this tool who is viewing it” switched off and receive the plain URL with no client details. A custom tool you build keeps it on unless the agency turns it off.

Query parameters appended to your URL

Decoded payload shape

{
    "agencyId": "…-uuid", "agencySlug": "acme",
    "clientId": "…-uuid", "clientName": "Acme Corp",
    "contactId": "…-uuid", "contactName": "Jane Smith", "contactEmail": "jane@acme.com",
    "iat": 1758000000, "exp": 1758000300
  }

Verifying the signature

Same recipe as webhooks — recompute the HMAC over the raw orbinly_ctx value using the signing secret shown once when the integration was added, and compare:

const expected = "sha256=" + crypto
    .createHmac("sha256", integrationSecret)
    .update(orbinlyCtx)
    .digest("hex");

  // compare to orbinly_sig, then check payload.exp hasn't passed

This token travels in a URL, so treat it as something that will end up in your own server logs and possibly your own outbound referrers — it isn't a secret channel. Verify it once on load, then mint your own session rather than re-trusting the URL on every subsequent request.

There's no published Orbinly app in the Zapier directory yet — but because Orbinly is a plain, documented REST API with real webhooks, you can wire up a working Zap today with Zapier's own built-in tools. No code required.

Trigger on an Orbinly event (e.g. "when an invoice is paid")

1. Create a Zap and choose Webhooks by Zapier → Catch Hook as the trigger.
2. Copy the custom webhook URL Zapier gives you.
3. In Orbinly, go to Settings → Developer → Webhooks, add that URL as an endpoint, and check the events you want (e.g. invoice.paid).
4. Trigger a real event in Orbinly once to let Zapier capture a sample payload, then build the rest of your Zap from its fields.

Take an action in Orbinly (e.g. "create a client")

1. Add an action step and choose Webhooks by Zapier → POST.
2. Set the URL to the endpoint you need, e.g. https://orbinly.com/api/v1/clients.
3. Under Headers, add Authorization: Bearer ob_live_... with your API key from Settings → Developer.
4. Set the payload type to JSON and map in the fields from earlier steps in your Zap.