> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sparkles.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Create your first credit claim

> Create an API key, issue an idempotent promotional credit claim, and check its status.

This guide creates a recipient-specific promotional credit offer and returns a link you can deliver to that recipient.

## Prerequisites

* A Sparkles account with API access enabled.
* Permission to open the [API access page](https://sparkles.dev/api).
* A server-side environment where you can protect a long-lived API key.

## Step 1: Create an API key

Open the [API access page](https://sparkles.dev/api), create a named key, and copy it immediately. Sparkles does not display the secret again.

Store it in your server-side secret manager:

```bash theme={null}
export SPARKLES_API_KEY="<your-api-key>"
```

Never embed this key in frontend JavaScript, mobile applications, logs, or analytics events.

## Step 2: Create a claim

Choose a stable, opaque lead identifier that contains no name, email address, or other personal data. The identifier is the idempotency key for this access grant.

```bash theme={null}
curl https://sparkles.dev/api/public/v1/credit-claims \
  --request POST \
  --header "Authorization: Bearer $SPARKLES_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "leadId": "lead_123",
    "email": "person@example.com",
    "variant": "call-offer",
    "creditAmount": 1000
  }'
```

`creditAmount` is a whole-credit integer. The first successful request returns HTTP `201`:

```json theme={null}
{
	"id": "01890a5d-ac96-774b-bcce-b302099a8057",
	"leadId": "lead_123",
	"variant": "call-offer",
	"creditAmount": 1000,
	"status": "pending",
	"claimUrl": "https://sparkles.dev/claim/CLAIM_TOKEN",
	"statusUrl": "https://sparkles.dev/api/public/v1/credit-claims/01890a5d-ac96-774b-bcce-b302099a8057",
	"createdAt": "2026-08-03T09:30:00.000Z",
	"claimedAt": null
}
```

Save `id` for reconciliation, and send `claimUrl` only to the intended recipient.

## Step 3: Make retries idempotent

Retry the same request with the same `leadId`, email, variant, and amount after a network failure. Sparkles returns the original claim with HTTP `200` and does not reserve credits twice.

Reusing the same `leadId` with different claim details returns HTTP `409` with `idempotency_conflict`. Use the original details or create a new lead identifier.

## Step 4: Check claim status

Use status lookup for manual recovery or to reconcile a missed webhook. Do not poll it as your primary event mechanism.

```bash theme={null}
curl https://sparkles.dev/api/public/v1/credit-claims/01890a5d-ac96-774b-bcce-b302099a8057 \
  --header "Authorization: Bearer $SPARKLES_API_KEY"
```

The claim status is one of:

| Status      | Meaning                                                           |
| ----------- | ----------------------------------------------------------------- |
| `pending`   | The claim link is still available.                                |
| `claimed`   | Credits were added once to the recipient's selected organization. |
| `cancelled` | The claim is terminal and can no longer be redeemed.              |

## Verification

Your integration is working when the create request returns `201`, an identical retry returns `200` with the same `id`, and the returned `statusUrl` returns the same claim.

Next, configure [signed webhook delivery](/webhooks) so you do not need to poll for changes.

## Troubleshooting

* HTTP `401`: replace the bearer key with an active key from the API access page.
* HTTP `409`: preserve the original idempotent request or ask an administrator to increase the access budget.
* HTTP `422`: lower `creditAmount` to the per-claim limit shown on the API access page.
* HTTP `429`: wait for the `Retry-After` duration before retrying.