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

# REST API

> Integrate Tilta's full REST API. Build any UX you need with complete access to buyers, orders, invoices, and credit facilities.

The REST API gives you unrestricted access to Tilta's entire feature set. You implement all UI yourself, which means you have complete freedom over the buyer experience – but you are also responsible for every screen, validation, and state transition. This approach suits teams with engineering capacity and complex or highly bespoke requirements.

## Prerequisites

Before you start, make sure you have the following in place:

* A registered Tilta account
* Sandbox API credentials – contact [support@tilta.io](mailto:support@tilta.io) to request access
* A server environment capable of making outbound HTTPS requests

<Note>
  Tilta provides a full sandbox environment at `https://api.tilta-sandbox.io` so you can develop and test without affecting production data or real credit facilities.
</Note>

## API base URLs

| Environment    | Base URL                       |
| -------------- | ------------------------------ |
| **Production** | `https://api.tilta.io`         |
| **Sandbox**    | `https://api.tilta-sandbox.io` |

All endpoints are versioned under `/v1/`. Use the sandbox URL during development and switch to the production URL only when you are ready to go live.

## Authentication

Tilta uses Bearer token authentication. Include your API key in the `Authorization` header on every request.

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

<Warning>
  Never expose your API key in client-side code, public repositories, or logs. Always make Tilta API calls from your server, not directly from the browser.
</Warning>

To retrieve your API key:

<Steps>
  <Step title="Log in to the Platform Portal">
    Navigate to [admin.tilta.io](https://admin.tilta.io) and sign in with your Tilta account credentials.
  </Step>

  <Step title="Open API settings">
    Go to **Settings → API** in the left-hand navigation menu.
  </Step>

  <Step title="Copy your API key">
    Copy the key for the environment you need (sandbox or production). Store it securely in your environment variables or secrets manager.
  </Step>
</Steps>

## Making your first request

The example below creates a buyer – the first step in most Tilta integrations. A buyer represents a business that will receive a credit facility and make purchases on your platform.

```bash theme={null}
curl --request POST \
     --url https://api.tilta.io/v1/buyers \
     --header 'Authorization: Bearer YOUR_API_KEY' \
     --header 'Content-Type: application/json' \
     --data '{
       "external_id": "buyer_001",
       "legal_name": "Acme GmbH",
       "registered_at": "DE"
     }'
```

A successful response returns a `201 Created` status with the new buyer object:

```json theme={null}
{
  "id": "byr_xxxxxxxxxxxxxxxx",
  "external_id": "buyer_001",
  "legal_name": "Acme GmbH",
  "registered_at": "DE",
  "status": "pending",
  "created_at": "2024-01-15T10:30:00Z"
}
```

<Tip>
  Use the `external_id` field to store your own internal identifier for the buyer. This makes it easy to look up Tilta resources by your platform's native IDs.
</Tip>

## Core integration flow

A typical REST API integration follows this sequence of API calls:

<Steps>
  <Step title="Create and onboard a buyer">
    Submit the buyer's business details (legal name, registration country, address, and so on) via `POST /v1/buyers`. Tilta's automated underwriting engine assesses the buyer and, if approved, opens a credit facility.
  </Step>

  <Step title="Request a credit facility">
    Once the buyer is onboarded, request a credit facility via `POST /v1/buyers/{external_id}/facility`. The facility defines the credit limit (up to €250,000) and is renewed automatically every three months.
  </Step>

  <Step title="Create an order">
    When the buyer is ready to purchase, create an order via `POST /v1/orders`. The order records the buyer's purchase intent and must be authorised before it can proceed to invoicing.
  </Step>

  <Step title="Capture an invoice">
    After the goods or services are delivered, capture an invoice via `POST /v1/invoices`. This is the legally effective financing step – it triggers payout to the merchant and starts the buyer's repayment clock based on the agreed payment terms (e.g., `DEFER_30D`).
  </Step>
</Steps>

## Error handling

Tilta uses standard HTTP status codes. Always check the response body for a machine-readable `code` and a human-readable `error`:

```json theme={null}
{
  "code": "NOT_FOUND",
  "error": "No buyer found"
}
```

| Status code   | Meaning                                                                        |
| ------------- | ------------------------------------------------------------------------------ |
| `200` / `201` | Request succeeded                                                              |
| `400`         | Validation error – check the request body, and `issues` for the specific field |
| `401`         | Invalid or missing API key                                                     |
| `404`         | The requested resource does not exist                                          |
| `409`         | Conflict – the resource already exists or is in an incompatible state          |
| `424`         | An external dependency failed – retry after a short delay                      |
| `500`         | Tilta internal error – retry with exponential back-off                         |

See [API errors](/docs/errors) for the full list of status codes and error codes.

## Resources

<CardGroup cols={3}>
  <Card title="API reference" icon="book" href="/api-reference">
    Browse full endpoint documentation including request and response schemas, required fields, and example payloads.
  </Card>

  <Card title="Integration guides" icon="map" href="/docs/introduction">
    Step-by-step guides for common flows: buyer onboarding, credit facility requests, order creation, and invoice capture.
  </Card>

  <Card title="Recipes" icon="flask-conical" href="/docs/introduction">
    Ready-to-use code snippets and end-to-end examples for the most common integration scenarios.
  </Card>
</CardGroup>