Getting Started

Your first API call in 5 minutes — authentication, company setup, and invoice submission.

Prerequisites

API credentials (client ID and client secret) — provided during onboarding
A registered company NIP in the system
curl or any HTTP client

1. Get an access token

Authenticate using your client credentials to obtain a JWT token:

curl -X POST https://demo-auth.ksefapi.com/realms/ksef-realm/protocol/openid-connect/token \
  -d 'client_id=YOUR_CLIENT_ID' \
  -d 'client_secret=YOUR_CLIENT_SECRET' \
  -d 'grant_type=client_credentials'

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 300
}

Save the access_token — you'll use it in every subsequent request.

2. Verify your identity

curl -H "Authorization: Bearer $TOKEN" \
  https://demo.ksefapi.com/api/auth/me

This returns your user/client details and available company associations.

3. List your companies

curl -H "Authorization: Bearer $TOKEN" \
  https://demo.ksefapi.com/api/companies

Each company has a company_id (UUID) which you'll use for all KSeF operations.

4. Initialize a KSeF token

Before sending invoices, your company needs an active KSeF authorization token:

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  https://demo.ksefapi.com/api/companies/{company_id}/ksef/init-token \
  -d '{"type": "authorisation"}'

5. Open a KSeF session

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  https://demo.ksefapi.com/api/companies/{company_id}/ksef/session/init

The response includes a session_reference_number — KSeF sessions are required for sending invoices.

6. Submit your first invoice

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  https://demo.ksefapi.com/api/companies/{company_id}/invoices/submit-sync \
  -d '{
    "invoice_type": "VAT",
    "seller": {
      "nip": "YOUR_NIP",
      "name": "Your Company Sp. z o.o.",
      "street": "ul. Przykładowa 1",
      "city": "Warszawa",
      "postal_code": "00-001"
    },
    "buyer": {
      "nip": "BUYER_NIP",
      "name": "Buyer Company Sp. z o.o.",
      "street": "ul. Testowa 2",
      "city": "Kraków",
      "postal_code": "30-001"
    },
    "items": [
      {
        "description": "Consulting services",
        "quantity": 1,
        "unit_price": 1000.00,
        "vat_rate": "23",
        "net_amount": 1000.00,
        "vat_amount": 230.00,
        "gross_amount": 1230.00
      }
    ]
  }'

The synchronous endpoint waits for KSeF confirmation and returns the KSeF reference number directly.

7. Check invoice status

curl -H "Authorization: Bearer $TOKEN" \
  https://demo.ksefapi.com/api/companies/{company_id}/invoices/{invoice_id}/status

What's next?

Topic	Description
Authentication	OAuth2 flows, token refresh, M2M setup
Companies	Multi-tenancy, company registration
Sessions	KSeF session lifecycle
Invoice Submission	JSON and XML submission options
Webhooks	Real-time status notifications

Getting Started

On this page