Integration flow

The API call you make. The wire your bank moves. The receipt we keep.

This is the actual sequence a grantor walks through. Six steps, one API integration, no custody change. You keep your bank, you keep your authority, you keep your fiduciary status. We just sit between the decision and the wire and document everything.

Talk about integration →API documentation

In plain English

What is this?

A six-step integration sequence: grantor onboards via the portal, requests a payment attestation that runs entity categorization + BEC + BID + bank-account + IRS classification + the 148-check Verdict Engine, receives a YES/NO/REVIEW, pays the recipient through their own bank if YES, reports the payment back, and pulls a quarterly categorized report on demand.

How does it affect me?

If you're integrating Attestyx, this is the whole map. The first step is portal onboarding; the last is a quarterly report your CFO and board can read. Between those, you're making one POST before each disbursement and one after - both compatible with whatever bank or custodian you already use.

Does it help me?

The sequence is intentionally small. Two synchronous API calls per grant (attestation request, disbursement report), one webhook channel for lifecycle events, one quarterly pull for the report. No middleware, no custody change, no payment-rail dependency.

The sequence

Six steps end-to-end.

Each step shows the actor, the API endpoint, and a status badge:livemeans the endpoint is wired and tested in production,partialmeans the path works but some sub-features ship in a follow-up milestone.

Grantor (your team)

live

Grantor onboards

You sign in to the grantor portal, capture your charter and signers, register a webhook endpoint, and request API credentials. Sandbox keys are issued same-day; production keys after the MSA + DPA are signed.

Onboarding wizard at /portal/auth/signup?type=foundationWebhook URL captured in foundation profile

Grantor → Attestyx

live

Request payment attestation

Before each disbursement you POST recipient + payment context. We run five check streams in parallel: entity categorization (IRS classification for US, OpenCorporates/GLEIF for foreign), BEC (domain age, MX/SPF/DMARC, lookalike), BID (document + registry verification), bank-account structural validation, and the full 148-check Verdict Engine. Returns YES, NO, or REVIEW with evidence.

POST /v1/attestations

Grantor (your bank)

live

On YES, you pay the recipient

Your bank, your wire, your authority. We never touch the money. The attestation we issued is hashed and queued for CourtChain anchoring at issue time - that anchor is what makes the YES defensible later, not whether we held the funds.

(out of band - your bank or custodian moves the money)

Grantor → Attestyx

live

Report payment back

Within 24 hours of settlement, you POST the disbursement details: settled amount, settlement date, bank reference, attestation_id you authorized against. We record it linked to the original attestation, refuse the report if the attestation was NO, and require attestation foundation_id match the caller.

POST /v1/disbursements

Attestyx (continuous)

partial

Lifecycle monitoring

Every recipient you have paid is screened continuously - sanctions re-checks, registry-match monitor, behavioral anomaly detection. If a previously-paid recipient lands on a sanctions list six months later, your registered webhook gets a notification. (Sanctions and registry monitors live; lifecycle webhook events are partial - more event types ship in the next milestone.)

Webhook delivery worker (existing)Lifecycle event types - partial

Attestyx → Grantor

live

Quarterly review report

Pull a categorized aggregate at any time: attestations issued (YES/NO/REVIEW), disbursements settled, by-program totals, by-jurisdiction totals, by-amount-tier breakdown, registry hits during the period. Defaults to the previous full quarter; pass ?from=&to= for any range.

GET /v1/reports/quarterly

What the attestation actually checks

Five parallel verification streams.

Every attestation runs these in parallel. The aggregate decision combines the verdict-engine score with per-stream penalties; any stream returning a hard block forces NO regardless of overall score.

Stream 1 - Categorization

What kind of entity is this?

For US recipients: IRS Tax-Exempt Organization Search lookup against EIN. For foreign: OpenCorporates + GLEIF LEI registry. Output: 501(c)(3) public charity / private foundation / fiscal sponsor / foreign equivalent / individual / unverified.

kyc-service /v1/kyb/verify

Stream 2 - BEC

Is the recipient email/domain legit?

Domain age (RDAP), MX/SPF/DMARC posture, lookalike detection against known charity domains, disposable-email blocklist match. Catches impersonation and grant-solicitation fraud at the email layer.

kyc-service /v1/kyc/bec

Stream 3 - BID

Are the documents real?

Document field parsing, PDF metadata anomaly detection, OpenCorporates registry match, GLEIF LEI, name fuzzy match across registries. Catches forged or fabricated organizational documents.

kyc-service /v1/kyc/bid

Stream 4 - Bank account

Is the receiving account real?

IBAN MOD-97 + format, BIC ISO 9362 format, US routing-number validation. Live bank-of-record verification (GIACT/Plaid) is a planned integration; today this is structural validation only.

internal (structural validation)

Stream 5 - IRS classification

Is tax-exempt status current?

IRS TEOS API check against EIN. Confirms current 501(c)(3) status, public-support test if applicable, and any recent revocations. Surfaces the same data your equivalency-determination counsel would pull.

verdict-engine JUR-002

Plus - 148-check Verdict Engine

Everything else.

The full 148 checks across 15 categories runs alongside the four streams above: governance, programmatic coherence, network effects (cross-foundation registry hits), behavioral anomaly, personnel screening, and so on. See coverage map →

Sample payloads

Three calls. Real schema.

Field names match the live API exactly. Authentication is via session cookie or API key in the X-API-Key header.

POST /v1/attestations

{
  "recipient": {
    "legal_name": "Acme Charitable Trust",
    "ein": "12-3456789",
    "jurisdiction": "us",
    "contact_email": "[email protected]",
    "domain": "acme-charity.org",
    "bank_account": {
      "iban": "GB29 NWBK 6016 1331 9268 19",
      "institution_name": "NatWest"
    }
  },
  "payment": {
    "amount_cents": 50000000,
    "currency": "USD",
    "program_code": "education-rural-2026",
    "purpose": "Q2 milestone disbursement"
  },
  "context": {
    "external_ref": "GRANT-2026-0042"
  }
}

POST /v1/attestations - response

{
  "attestation_id": "att_a3e9f1c0...",
  "decision": "YES",
  "aggregate_score": 12,
  "hard_blocks": [],
  "categorization": { "entity_type": "501(c)(3) public charity", ... },
  "bec":            { "domain_age_days": 4214, "dmarc": "p=reject", ... },
  "bid":            { "matches_found": 2, "confidence": "high", ... },
  "bank_account":   { "iban_format": true, "iban_mod97": true, ... },
  "verdict_summary": {
    "aggregate_score": 8,
    "category_scores": { "SAN": 0, "BEN": 5, "FIN": 8, ... },
    "checks_run": 120,
    "skipped": 28
  },
  "evidence_url": "/v1/creb/att_a3e9f1c0.../receipt",
  "courtchain_anchor": "pending_anchor_worker",
  "issued_at": "2026-05-04T19:42:11.318Z",
  "valid_until": "2026-05-11T19:42:11.318Z",
  "payload_hash": "sha256:..."
}

POST /v1/disbursements

{
  "attestation_id": "att_a3e9f1c0...",
  "settled_at": "2026-05-04T22:18:09Z",
  "settled_amount_cents": 50000000,
  "settled_currency": "USD",
  "bank_reference": "WIRE-2026-05-04-99821",
  "settlement_method": "wire_ach"
}

What the quarterly report contains

PullGET /v1/reports/quarterly at any time. Defaults to the previous full quarter; pass ?from= + ?to=for any range. Same data your CFO and external auditor see.

Summary

Attestations issued (YES / NO / REVIEW counts), disbursements settled (count + total), total disbursed in cents.

By program

Disbursement counts and totals grouped by yourprogram_code. Trend versus prior quarter on request.

By jurisdiction

Country-level breakdown of recipients. Cross-border share. Per-corridor sanctions exposure summary.

By amount tier

Sub-$10K / $10-100K / $100K-1M / $1M+ tiers with count and total. Concentration analysis on the top decile.

Registry hits

Any prior recipient newly added to the bad-actor registry during the period. Count + linked inclusion records.

Format

JSON by default. PDF and CSV exports available; query with ?format=pdf or ?format=csvin the next milestone.

Ready to wire it in?

Sandbox keys issued same-day. Integration runs 1-2 days of engineering time end-to-end. We sit on the call with your engineers if useful.

Start integration →