# Keikkalasku Partner API

The Partner API lets a gig platform create invoicing requests for its workers through
Keikkalasku. Keikkalasku invoices **you** (the partner), withholds its normal service fee and
pays each worker as a salary — taxes, insurance and reporting included.

## How it works

1. **Invite each worker once** — `POST /v1/connections` with your own id for the worker and their
   email. Keikkalasku emails an invitation; the worker accepts it in Keikkalasku with an account
   under the same email. The invitation is valid for 30 days.
2. **Report gigs** — `POST /v1/gigs` with the gig date, a title, a work type and each worker's
   VAT-excluded share. Each worker becomes one invoicing request, addressed to you.
3. **Follow the status** — `GET /v1/gigs?updated_since=…`. Each worker moves through
   `awaiting_worker → received → invoiced → paid → completed`. When `invoiced`, the response
   carries the invoice number, reference, due date, total and IBAN so you can automate payment.

You never send a receiver or a VAT rate. The receiver is your own billing details, fixed by
Keikkalasku, and the VAT follows from the work type code and the gig date.

## Environments

| | Base URL | Keys |
|---|---|---|
| Test | `https://api-test-pp.keikkis.fi/v1` | `kl_test_…` |
| Production | `https://api-pp.keikkis.fi/v1` | `kl_live_…` |

The **test API** validates every request exactly like production but answers from fixed test
data and stores nothing. Magic values produce every status and error: see
[Test API](/docs/en/test-api). A test key works only on the test host and a live key only on the
production host (`401 wrong_environment`).

Create keys in the [partner portal](https://kumppani-pp.keikkis.fi). Test keys are available right away;
production keys once Keikkalasku has opened production use for you (after the partner agreement,
the data processing agreement and customer due diligence).

## Pages

- [Quickstart](/docs/en/quickstart)
- [Test API and magic values](/docs/en/test-api)
- [Work types and VAT](/docs/en/work-types)
- [Statuses](/docs/en/statuses)
- [Errors](/docs/en/errors)
- [API reference](/docs/reference) · [OpenAPI JSON](/v1/openapi.json) · [llms.txt](/llms.txt)

Every page is also available as Markdown: add `.md` to the address, e.g. `/docs/en/quickstart.md`.