From zero to integrated, in minutes

1. Create a sandbox key in the console. It is free on every plan, and it does not use up a production key slot.
2. Run one command (or one curl). It creates five synthetic subjects with real outcome history, then prints the score each one earned.
3. Read any of them back through the ordinary endpoints. When you are done, DELETE /api/v1/test/data wipes it.

$ export CREDDA_API_KEY=crd_test_…
$ npx @credda/cli quickstart

SUBJECT                 SCORE  BAND
sbx_reliable_courier    81     Excellent
sbx_steady_freelancer   75.5   Good
sbx_unverified_hustler  38.33  Building
sbx_breached_supplier   33.25  Unproven
sbx_new_signup          21.89  Unproven

# No CLI? One HTTP call does the same seeding:
$ curl -X POST https://api.credda.io/api/v1/test/seed \
    -H "Authorization: Bearer $CREDDA_API_KEY"

# Then read one back, the same call your integration will make:
$ curl https://api.credda.io/api/v1/users/sbx_reliable_courier/score/explain \
    -H "Authorization: Bearer $CREDDA_API_KEY"

1. Propose the outcome with POST /api/v1/confirmations. This writes nothing: no event, no score. It returns a one-time confirmationToken, shown once, and a ready-made confirmUrl.
2. Deliver that link to the counterparty over your own channel: email, SMS, in-app inbox. Credda sends nothing and never learns their address. Open confirmUrl yourself to see the hosted page, or build your own UI on previewUrl/respondUrl.
3. They decide. Confirm writes the event with isVerified: true, earned because a distinct token-holder acted. Decline writes nothing at all: the absence of a confirmation is never treated as evidence of a bad outcome.
4. While you are integrating, you hold the token too, so you can call respond yourself and watch the whole loop close in one session before you wire up delivery.

# 1. Propose it (your key). Nothing is on the ledger yet.
$ curl -X POST https://api.credda.io/api/v1/confirmations \
    -H "Authorization: Bearer $CREDDA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"userId":"worker_7","eventType":"CONTRACT_FULFILLED",
         "stakeLevel":"MEDIUM","transactionValue":1200,
         "counterpartyRef":"ops@northside.example",
         "description":"Kitchen refit at 14 Bridge St, completed 12 March."}'

{ "confirmation": { "id": "cnf_…", "status": "PENDING" },
  "confirmationToken": "…",                       # shown ONCE
  "confirmUrl":  "https://api.credda.io/confirm/cnf_…?token=…",
  "previewUrl":  "…/api/v1/confirmations/cnf_…/preview?token=…",
  "respondUrl":  "…/api/v1/confirmations/cnf_…/respond" }

# 2. The counterparty decides. NO Authorization header; they hold a
#    token, not an API key. Single-use.
$ curl -X POST https://api.credda.io/api/v1/confirmations/cnf_…/respond \
    -H "Content-Type: application/json" \
    -d '{"token":"…","decision":"confirm"}'

{ "status": "CONFIRMED", "eventId": "evt_…" }     # verified, on the ledger

// SDK: the two halves, deliberately shown apart
const req = await credda.createConfirmationRequest({ … }, KEY);
const out = await counterparty.respondToConfirmation(req.confirmation.id,
                                                     req.confirmationToken,
                                                     'confirm');

# Got a book of past work? One call turns up to 100 of them into asks:
#   POST /api/v1/confirmations/batch

1. Ask the user for their Credda share link (it ends in a crd_share_… token).
2. Resolve the token, and you get their score, band, confidence and verified-platform count, and nothing personal.
3. For a cryptographic check, fetch the signed export and verify it offline with the SDK.

# public, no key needed
$ curl https://api.credda.io/api/v1/verify/THEIR_SHARE_TOKEN

{ "token": "crd_share_…", "finalScore": 72, "scoreBand": "Good",
  "confidence": 0.9, "verifiedPlatforms": 2, "totalEvents": 18 }

// or with the SDK
import { CreddaClient } from '@credda/js';
const credda = new CreddaClient();
const trust = await credda.resolveToken('THEIR_SHARE_TOKEN');

1. Mint a share token for the user (from your dashboard, or POST to /profiles/me/share on credda.io).
2. Add the widget script and a badge element with that token.
3. That is it. The badge fetches the signed credential and shows a verified score, no backend needed.

<script src="https://api.credda.io/widget/credda-widget.js" async></script>
<credda-badge token="crd_share_…"></credda-badge>

1. Create an API key in the console (Growth tier or above can write events).
2. Report the outcome. It is idempotent, so a retry never double-counts. User ids are YOUR externalIds.
3. Read the score and the factor-level explanation once it recomputes. Recomputation is asynchronous, so a read taken immediately after the write may still be catching up.
4. Note what isVerified: true means here: you are asserting it. Verification depth, the share of a record a third party confirmed, is what moves a score into the earned bands, and only a confirmation earns it.

$ curl -X POST https://api.credda.io/api/v1/events \
    -H "Authorization: Bearer $CREDDA_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: order-4821-fulfilled" \
    -d '{"userId":"seller_88","eventType":"CONTRACT_FULFILLED",
         "stakeLevel":"MEDIUM","isVerified":true}'

$ curl https://api.credda.io/api/v1/users/seller_88/score \
    -H "Authorization: Bearer $CREDDA_API_KEY"
{ "finalScore": 41, "scoreBand": "Building", "confidence": 0.3 }

// SDK
await credda.reportEvent({ userId: 'seller_88', eventType: 'CONTRACT_FULFILLED',
                           stakeLevel: 'MEDIUM', isVerified: true }, KEY);
const explain = await credda.getScoreExplain('seller_88', KEY);

1. Pick any user id (a fresh one projects from an unproven baseline; an existing one projects from its real score).
2. POST up to 20 hypothetical events, and you get the resulting score and the delta, deterministically.
3. Nothing is written: the ledger is untouched, so simulate as much as you like.

$ curl -X POST https://api.credda.io/api/v1/users/anyone/score/project \
    -H "Authorization: Bearer $CREDDA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"events":[{"eventType":"CONTRACT_FULFILLED","isVerified":true},
                   {"eventType":"CONTRACT_FULFILLED","isVerified":true}]}'
{ "delta": 8.4, "current": { "finalScore": 20, "scoreBand": "Unproven" },
  "projected": { "finalScore": 28, "scoreBand": "Unproven" } }