> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.solvimon.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.solvimon.com/_mcp/server.

# API quickstart

By the end of this tutorial you will have made an API call to Solvimon and received a response. No billing setup required — just get talking to the API.

**What you'll need:**

* A Solvimon sandbox account
* `curl` or any HTTP client

---

## Step 1: Get your API key

1. Log in to the [Solvimon Sandbox](https://test.desk.solvimon.com/)
2. Go to **Settings → API keys**
3. Copy your `TEST` API key

## > **Warning**
>
> Keep your API key secret. Do not commit it to source control or expose it in client-side code.

## Step 2: Make your first request

List your customers. On a fresh sandbox account this returns an empty list — that's expected.

```bash
curl https://test.api.solvimon.com/v1/customers \
  -H "X-API-KEY: <apiKey>"
```

A successful response:

```json
{
  "data": [],
  "page": 1,
  "limit": 10,
  "links": {
    "first": "https://test.api.solvimon.com/v1/customers?page=1",
    "previous": null,
    "current": "https://test.api.solvimon.com/v1/customers?page=1",
    "next": null
  }
}
```

A `200` with an empty `data` array means you're authenticated and connected.

---

## Step 3: Create your first customer

```bash
curl -X POST https://test.api.solvimon.com/v1/customers \
  -H "X-API-KEY: <apiKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "superstore-001",
    "type": "ORGANIZATION",
    "email": "invoices@superstore.de",
    "roles": [
        "DEFAULT"
    ],
    "status": "DRAFT",
    "timezone": "Europe/Berlin",
    "organization": {
        "legal_name": "SuperStore GmbH",
        "tax_ids": [
            {
                "id": "368807022",
                "type": "GENERIC_TAX_ID"
            }
        ],
        "registered_address": {
            "line1": "Hasengarten 14",
            "city": "Berlin",
            "postal_code": "79341",
            "state": "",
            "country": "DE"
        }
    }
}'
```

Response:

```json
{
    "object_type": "CUSTOMER",
    "id": "cust_abc",
    "created_at": "2026-03-31T08:39:02Z",
    "reference": "superstore-001",
    "status": "DRAFT",
    "timezone": "Europe/Berlin",
    "type": "ORGANIZATION",
    "email": "invoices@superstore.de",
    "organization": {
        "legal_name": "SuperStore GmbH",
        "tax_id": "368807022",
        "tax_ids": [
            {
                "id": "368807022",
                "type": "GENERIC_TAX_ID"
            }
        ],
        "registered_address": {
            "line1": "Hasengarten 14",
            "city": "Berlin",
            "postal_code": "79341",
            "state": "",
            "country": "DE"
        }
    },
    "roles": [
        "DEFAULT"
    ]
}
```

The `id` is Solvimon's internal identifier. The `reference` is your own — use it to look this customer up from your system.

---

## Step 4: Fetch the customer back

```bash
curl "https://test.api.solvimon.com/v1/customers?reference=superstore-001" \
  -H "X-API-KEY: <apiKey>"
```

---

## Step 5: Activate the customer

The customer was created in `DRAFT` status. Before you can create a subscription, you need to activate them:

```bash
curl -X POST https://test.api.solvimon.com/v1/customers/superstore-001/activate \
  -H "X-API-KEY: <apiKey>"
  -d '{}'
```

A `200` response means the customer is now `ACTIVE`. Resources in Solvimon follow a `DRAFT → ACTIVE` lifecycle — drafts exist so you can configure them before they're used in billing.

## > **Note**
>
> All API requests must be made over HTTPS. Requests without a valid `X-API-KEY` header return `401 UNAUTHORISED`.

## What to do next

* **Build a complete billing setup** — [Configure your first meters and prices](/platform-guides/getting-started/onboarding-and-tutorials/configure-your-first-meters-and-prices) walks through the complete primitive chain: meter → product → pricing plan → subscription → usage event → invoice.
* **Build a B2C subscription product** — [Bill your first B2C customer](/platform-guides/getting-started/onboarding-and-tutorials/bill-your-first-b2c-customer) adds payment collection via Adyen or Stripe.
* **Understand the flow** — [Onboarding guide](/platform-guides/getting-started/onboarding-and-tutorials) covers the setup sequence at a high level.