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

# Claim Codes

> Transfer staged images to agent dashboards

# Claim Codes

Every image staged via the API gets a **claim code** (e.g., `SS-7X9K2M`). Estate agents use this code to transfer the staged images into their StagingSpaces dashboard.

## How It Works

```mermaid theme={null}
sequenceDiagram
    participant Partner as Your Platform
    participant API as StagingSpaces API
    participant Agent as Estate Agent

    Partner->>API: POST /api/v1/stage
    API-->>Partner: image_url + claim_code "SS-7X9K2M"
    Partner->>Agent: "Here's your staged image. Claim code: SS-7X9K2M"
    Agent->>API: POST /api/v1/claim { code: "SS-7X9K2M" }
    API-->>Agent: Images transferred to dashboard
```

## Claim code lifecycle

1. **Generated** — Created automatically when you stage an image
2. **Active** — Valid for 30 days
3. **Claimed** — Agent redeems the code, images transfer to their dashboard
4. **Expired** — Unclaimed after 30 days

## Preview before claiming

Agents can check what's in a claim code before redeeming:

```bash theme={null}
curl -X POST .../api/v1/claim/preview \
  -H "Authorization: Bearer <firebase-token>" \
  -H "Content-Type: application/json" \
  -d '{"code": "SS-7X9K2M"}'
```

```json theme={null}
{
  "valid": true,
  "code": "SS-7X9K2M",
  "image_count": 3,
  "is_claimed": false,
  "expires_at": "2026-04-24T12:00:00Z",
  "days_until_expiry": 30
}
```

## Revenue sharing

When an agent claims images with product placement enabled, they earn **50% of ad impression revenue** from those images. This incentivizes agents to use and share staged images.