InboundAPI integration

Let an external system start an orchestration flow for a specific customer in real time.

The Inbound API block lets external systems start a campaign flow for a specific customer in real time. When a CDP, CRM, POS, or any other client system calls the block’s unique URL, that customer enters the flow — so a journey can begin in Nexus the moment something happens outside it.

It is the inbound counterpart to the Outbound API block: where Outbound API sends data out of Nexus, Inbound API lets external systems trigger flows into Nexus. The Inbound API block is a starting block — it begins a flow, like a Customer event block.

Availability: the InboundAPI block is enabled per environment. Contact your Lobyco representative if you don’t see it in the orchestration canvas.

How it works

A marketer (or you, as an integrator) places the InboundAPI block in an orchestration flow on the visual canvas, at the start of the flow. Each time an InboundAPI is called, the platform:

1. Checks the data and idempotency

2. Converts the data into internal event format

3. Sends the event to the downstream block

Calling the endpoint

Once the block is published and within its schedule window, the external system triggers the flow with a single HTTP request.

Method & URL

POST https://integration.<environment>.lobyco.net/inbound/{id}

Headers

API-KEY: <your-api-key>
Content-Type: application/json

The API key is provided by Lobyco (one key per environment). See Authorization.

Body

{
  "CustomerId": "123456",
  "IdempotencyKey": "order-2026-0001"
}

• CustomerId (required) — the Lobyco customer ID to push into the flow.
• IdempotencyKey (optional) — a unique value that guards against duplicate calls. See Idempotency.

Response

A successful call returns 202 Accepted with a requestId you can use to trace the execution. The flow then runs for that customer.

Idempotency

If you include an IdempotencyKey, a repeated call with the same key (for the same block) within 24 hours is silently ignored and returns the original requestId — so a retry or accidental double-send won’t trigger the flow twice. Calls without an IdempotencyKey are always processed.

Response & error codes

Code	Meaning
202 Accepted	Request accepted; the flow is scheduled for the customer. Returns a requestId.
400 Bad Request	The block is not published (still a draft), or the request is malformed.
401 Unauthorized	The API key is missing or invalid.
404 Not Found	No published block matches this URL.
422 Unprocessable Entity	Validation failed — e.g. the call is outside the Start/End window, or a required field is missing.
429 Too Many Requests	Too many requests in a short time; slow down and retry later.

Retries are the caller’s responsibility.

Authorization

Calls are authorized with an API key sent in the API-KEY header.

• One API key is provisioned per environment by Lobyco.
• The same key works for all Inbound API blocks in that environment.
• Need a key, or need one rotated? Contact your Lobyco representative.

Limitations

• One customer per call. Each request triggers the flow for a single CustomerId; batch calls are not supported yet.
• No extra payload data. Only CustomerId and the optional IdempotencyKey are used; additional properties are ignored for now.
• The CustomerId is not validated against the customer base in this version — make sure the external system sends valid Lobyco customer IDs.
• One global API key per environment, provisioned by Lobyco. Self-service key management and detailed request logs are planned for later.
• Calls only succeed when the block is published and the current time is within the Start/End window.