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
2. Go to Settings → API keys
3. Copy your TEST API key

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.

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

A successful response:

{
  "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

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:

{
    "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

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:

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.

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 walks through the complete primitive chain: meter → product → pricing plan → subscription → usage event → invoice.
• Build a B2C subscription product — Bill your first B2C customer adds payment collection via Adyen or Stripe.
• Understand the flow — Onboarding guide covers the setup sequence at a high level.