> ## Documentation Index
> Fetch the complete documentation index at: https://help.lobyco.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/integration/external-integrations/outboundapi-connection): 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.

<Info>
  **Availability:** the InboundAPI block is enabled per environment. Contact your Lobyco representative if you don't see it in the orchestration canvas.
</Info>

## 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:

<Steps>
  <Step>
    ### Checks the data and idempotency
  </Step>

  <Step>
    ### Converts the data into internal event format
  </Step>

  <Step>
    ### Sends the event to the downstream block
  </Step>
</Steps>

## 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](#authorization).

**Body**

```json theme={"system"}
{
  "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](#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.