Quickstart

Create a key, issue a pass and add a stamp. With a published card, this takes about five minutes.

About 5 minutes Needs curl

1. Create an API key

In the dashboard, open Developers and choose Create key. Name it after what will use it, pick Test key, and copy it. Korti shows the whole key only once.

Save it in your shell so the examples below work as they are:

Terminal

export KORTI_KEY="sk_test_…"

Heads upYour key can issue and change passes for your whole business. Keep it on your server. Never put it in a web page, a mobile app or a public repository. If it leaks, revoke it in the dashboard and create a new one.

2. Find your card

You need a published card. If you don’t have one yet, follow Your first card first. Then list your cards to get its ID and see which values it takes:

curl https://korti.is/v1/cards \
  -H "Authorization: Bearer $KORTI_KEY"

Response200 OK

{
  "object": "list",
  "data": [
    {
      "id": "3e0c5d1a-8f55-4a62-9a63-2f0b1f6c7d21",
      "object": "card",
      "name": "Kaffi Kría stamp card",
      "type": "stamp",
      "version": 1,
      "shareUrl": "https://korti.is/c/kaffi-kria-x7k2",
      "variables": [
        { "name": "stamps", "type": "integer", "min": 0, "max": 10,
          "description": "Stamps collected so far. At 10 the reward (Free coffee) is ready." }
      ],
      "createdAt": "2026-10-01T09:12:44.000Z",
      "updatedAt": "2026-10-01T09:20:02.000Z"
    }
  ]
}

3. Issue a pass

Put the card’s ID in place of YOUR_CARD_ID and send:

curl https://korti.is/v1/passes \
  -H "Authorization: Bearer $KORTI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "card": "YOUR_CARD_ID",
    "customer": { "name": "Anna Jónsdóttir", "email": "anna@example.is" },
    "values": { "stamps": 1 }
  }'

The response is the new pass. Open its url on your phone: you’ll see the card and a button to add it to Apple Wallet or Google Wallet. Keep the pass’s id for the next step.

4. Add a stamp

Put the pass ID in place of PASS_ID. If the pass is in your wallet, watch it: the stamp appears within a few seconds, with a notification on iPhone.

curl -X POST https://korti.is/v1/passes/PASS_ID/stamps \
  -H "Authorization: Bearer $KORTI_KEY"

The response is the updated pass. When rewardReady is true, the card is full. Give the reward and call POST /v1/passes/PASS_ID/redeem to start a new card.

Next steps

Issue a pass: retries, idempotency keys and every option.
Send updates: points, balances and your own values.
Webhooks: hear when a customer saves or scans their pass.