# Sparkles API

> Integrate promotional credit claims and attributed lifecycle events with Sparkles.

## Docs

- [Handle API errors](https://docs.sparkles.dev/errors.md): Respond correctly to Sparkles API validation, authorization, conflict, limit, and server errors.
- [Process and reconcile events](https://docs.sparkles.dev/events.md): Understand Sparkles partner event types, ordering, attribution, and replay recovery.
- [Sparkles partner API](https://docs.sparkles.dev/index.md): Create promotional credit claims and receive attributed lifecycle events from Sparkles.
- [Create your first credit claim](https://docs.sparkles.dev/quickstart.md): Create an API key, issue an idempotent promotional credit claim, and check its status.
- [Create an idempotent promotional credit claim](https://docs.sparkles.dev/reference/partner-credits/create-an-idempotent-promotional-credit-claim.md): The leadId is the idempotency key within the API access grant. An exact retry returns the existing claim; a retry with changed claim details returns 409.
- [Get the current status of a credit claim](https://docs.sparkles.dev/reference/partner-credits/get-the-current-status-of-a-credit-claim.md)
- [Reconcile the curated partner event feed](https://docs.sparkles.dev/reference/partner-events/reconcile-the-curated-partner-event-feed.md): Returns a replayable, access-scoped feed for webhook gap recovery and backfills. Webhooks are the primary delivery mechanism. Save each event sequence and use nextCursor as after when reconciling.
- [Prove possession of a webhook signing secret](https://docs.sparkles.dev/reference/partner-webhooks/prove-possession-of-a-webhook-signing-secret.md): Sparkles signs this request with the same Webhook-Id.Webhook-Timestamp.rawRequestBody algorithm as event delivery. Verification requests intentionally omit sequence and Webhook-Attempt. Read data.challenge and return base64(HMAC-SHA256(base64Decode(secret without whsec_), "sparkles.webhook.verify."…
- [Receive an attributed sparkles event](https://docs.sparkles.dev/reference/partner-webhooks/receive-an-attributed-sparkles-event.md): Sparkles sends one event object per request. Read the unmodified request bytes and reject Webhook-Timestamp values outside a five-minute tolerance. Decode the configured signing secret after removing whsec_, then compare HMAC-SHA256(Webhook-Id + "." + Webhook-Timestamp + "." + rawRequestBody) in con…
- [How to set up signed webhooks](https://docs.sparkles.dev/webhooks.md): Verify a Sparkles webhook endpoint, validate every delivery, and handle retries safely.

## OpenAPI Specs

- [openapi](https://docs.sparkles.dev/openapi.json)