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

# Credits and reveals

> How contact reveals spend shared contact credits.

Contact previews do not expose private contact channels. Use `POST /contacts/reveal` to reveal full contact data for selected preview IDs.

Reveals use the same shared monthly contact credits as the StoreInspect web app.

Trial users receive 250 contact credits during the trial. Paid Pro includes 1,000 monthly contact credits. Use `GET /usage` to distinguish the current trial cap from the paid-plan limit.

## Reveal flow

1. Search contacts with `POST /contacts/search`.
2. Select contact IDs from preview results. If you need email, search with `person.has_verified_email: true` and check each preview's `has_verified_email` field.
3. Check remaining credits with `GET /usage`.
4. Reveal selected contacts with `POST /contacts/reveal`.

One credit is spent when a new contact has any revealable channel, including phone or LinkedIn without email. In that case the response can contain `emails: []`.

If a trial user exhausts the 250 trial credits, `POST /contacts/reveal` returns `402 insufficient_contact_credits` with a `billing.action` of `end_trial_to_unlock_pro_credits`. The `billing.url` points to the billing page where the user can end the trial and unlock paid Pro credits immediately.

## Idempotency

Reveal requests support an optional `Idempotency-Key` header.

Use the same idempotency key when retrying the exact same reveal request after a network failure.

```bash theme={null}
curl https://storeinspect.com/api/v1/contacts/reveal \
  -H "Authorization: Bearer $STOREINSPECT_API_KEY" \
  -H "Idempotency-Key: reveal_batch_001" \
  -H "Content-Type: application/json" \
  -d '{"contact_ids":["ct_Example_AbCdEfGhIjKlMnOp"]}'
```

<Warning>
  Revealed emails, phones, and profile URLs are sensitive. Keep them out of client logs and public analytics tools.
</Warning>