The Bank API

Quickstart

1. In Portfolio → Settings → Developers, mint a sandbox key (ak_test_…). Sandbox keys only ever touch fixture applicants.
2. Invite an applicant from your server. Idempotency-Key is required, so a retried request never invites twice.
3. Advance the sandbox applicant and watch your webhook endpoint receive each event, signed.
4. Mint a live key (ak_live_…) when you are ready. Nothing else changes.

curl https://apparently.cc/api/v1/bank/invites \
  -H "Authorization: Bearer $APPARENTLY_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "email": "founder+conditions@example.com", "name": "Lantern Row", "external_ref": "APP-1042" }'

# → 201 { "data": { "id": "…", "status": "invited", "lane": "invited", "invite_url": null, … } }

curl https://apparently.cc/api/v1/bank/applicants?external_ref=APP-1042 -H "Authorization: Bearer $APPARENTLY_KEY"

Authentication

Every request carries Authorization: Bearer ak_live_… (or ak_test_…). Keys belong to your organisation, are shown once and stored hashed; an owner or admin revokes one from the Developers page and it stops working at once. A key without a route's scope gets 403; a missing, revoked or unknown key gets 401. Each key may make 120 requests a minute and 20,000 a day.

Endpoints

Base URL https://apparently.cc/api/v1/bank. The whole API as OpenAPI 3.1: openapi.json. Every success is { data, meta }; every refusal is { error: { type, code, message } }.

A review is the client-safe projection: findings with their title, tier, state and source, counsel's notes to the applicant, the decision and any conditions. Internal notes between you and counsel, and a finding's detail, never leave the Portfolio.

Webhooks

Register an https endpoint with POST /webhooks (or on the Developers page). The signing secret (whsec_…) is shown once. A sandbox key's endpoints hear sandbox events only; a live key's, live events only.

Every delivery carries Apparently-Signature: t=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256 of t + "." + raw body with your secret. Refuse a timestamp more than 300 seconds from your clock (a captured request cannot be replayed later), compare in constant time, and deduplicate on Apparently-Event-Id: a delivery that got no 2xx within 10 seconds is retried after 1 min, 5 min, 30 min, 2 h, 6 h (8 h 36 min in all), then abandoned.

Every delivered event is also in the log at GET /events, so a missed delivery can be caught up from it. GET /events lists newest first. For the next page pass the last event's id as starting_after (meta.next_starting_after holds it) until meta.has_more is false. Do not page by created_at: an event's created_at is when the fact became true, which can be earlier than when it was recorded, so paging by it skips events.

Node

import crypto from 'node:crypto'

// rawBody: the request body exactly as received (a Buffer or string), before JSON.parse.
export function verifyApparently(rawBody, header, secret, toleranceSeconds = 300) {
  let t = null
  const sigs = []
  for (const kv of String(header || '').split(',')) {
    const [k, v] = kv.split('=')
    if (k === 't') t = Number(v)
    if (k === 'v1') sigs.push(v)
  }
  if (!t || !sigs.length) return false
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > toleranceSeconds) return false // replay window
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex')
  return sigs.some(s => s.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(s), Buffer.from(expected)))
}

Python

import hmac, hashlib, time

def verify_apparently(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    t, sigs = None, []
    for kv in (header or "").split(","):
        k, _, v = kv.partition("=")
        if k == "t" and v.isdigit():
            t = int(v)
        elif k == "v1":
            sigs.append(v)
    if t is None or not sigs or abs(int(time.time()) - t) > tolerance:  # replay window
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(s, expected) for s in sigs)

The widget

Put the review inside your own onboarding flow. Your server mints a widget token for an invitation (it lives 15 minutes and opens one applicant's status, nothing else); your page mounts the widget with it. Your API key never reaches a browser. List the origins your page is served from on the Developers page: the widget can only be framed there.

<!-- your onboarding page -->
<div id="apparently-review"></div>
<script src="https://apparently.cc/embed/apparently-bank.js"></script>
<script>
  // From YOUR server: POST https://apparently.cc/api/v1/bank/invites/{id}/widget-token
  // → { token, frame_url, expires_at }. Never call it from the browser.
  const widget = ApparentlyBank.mount('#apparently-review', {
    token: TOKEN_FROM_YOUR_SERVER,
    frameUrl: FRAME_URL_FROM_YOUR_SERVER,
    onStatus: (status) => console.log('review status:', status),
    onExpired: async () => widget.setToken(await fetchFreshTokenFromYourServer()),
  })
</script>

Statuses sent to onStatus: invited, accepted, linking, submitted, in_review, action_needed, conditionally_approved, approved, denied, withdrawn. The widget wears your brand (see the apply mode below), with a small "Powered by Apparently" footer.

The apply widget

Put the whole upload-for-review step inside your merchant onboarding, white-labelled as your brand: your name, logo, primary colour and support email (Dashboard → White label), a small "Powered by Apparently" footer, and the statement that the review is performed independently. The applicant:

1. confirms the email you invited with a 6-digit code we send to that address (no third-party cookies: the session lives in the frame's sessionStorage and travels as a header);
2. uploads the legal opinion (PDF or .docx) and any supporting public documents, and gives the website; linking code and database in the Apparently app is shown as optional and is not required to submit;
3. agrees to "Share the results of this review with {your name}", which is recorded before anything is submitted;
4. submits. Every file is type-checked and virus-scanned before the review starts; a file the scanner has not yet checked is held, never skipped.

Your server mints an apply token for the invitation with POST /invites/{id}/apply-token (it lives 60 minutes and opens that one invitation). Mount with mode: 'apply'. A partner that cannot frame sends the applicant to hosted_url (in the invitation answer and the apply-token answer) instead; return_url, on one of your proved origins, is where the "Return" button goes.

<div id="apparently-apply"></div>
<script src="https://apparently.cc/embed/apparently-bank.js"></script>
<script>
  // From YOUR server: POST https://apparently.cc/api/v1/bank/invites/{id}/apply-token  { "return_url": "https://onboarding.you.example/next" }
  // → { token: "bws_…", frame_url, hosted_url, expires_at }. Never call it from the browser.
  const widget = ApparentlyBank.mount('#apparently-apply', {
    mode: 'apply',
    token: APPLY_TOKEN_FROM_YOUR_SERVER,
    frameUrl: FRAME_URL_FROM_YOUR_SERVER,
    returnUrl: 'https://onboarding.you.example/next',
    onEvent: (type, detail) => console.log(type),   // started, consented, document_uploaded, submitted, completed
    onSubmitted: () => showNextStep(),
    onExpired: async () => widget.setToken(await fetchFreshApplyTokenFromYourServer()),
  })
</script>

Events: started, consented, document_uploaded, submitted, completed, plus the status events above. The iframe's sandbox allows forms and, on a click only, navigating your page to returnUrl. With a sandbox key nothing is emailed and the code is always 000000.

Sandbox

With an ak_test_ key, invitations are fixture applicants: no email, no real review, no charge. The outcome follows the email you invite, like a test card: an address containing +deny is denied, +conditions is approved on conditions, anything else is approved. Move one along with POST /sandbox/applicants/{id}/advance (optionally { "to": "approved" }), and raise monitoring.breach, document.requested or document.received with POST /sandbox/applicants/{id}/simulate. Each move delivers its webhooks at once.