API Integration Tutorials

A tier-by-tier walkthrough verified against the official docs: day 0 with the RFC only, the CIEC when you need depth, and continuous monitoring a month later.

Developer resources

Six resources, six purposes. Pick the one that matches where you are in your integration.

SAT Integration Hub

Start here: what the SAT API exposes, how CRiskCo abstracts SOAP/CIEC, and technical FAQ.

Go to page

API Integration Guide

End-to-end walkthrough: authentication, integration models (Approve / White-label / Webhook), and the full endpoint catalog.

Go to page

Code Samples

Copy-paste snippets in Python, Node.js, and cURL for every common flow.

Go to page

You are here

Tutorials

Step-by-step beginner guides: first request, authentication, and monitoring.

API Explorer

Every endpoint and every field in one searchable view. Built for teams evaluating or migrating their integration.

Go to page

API Docs

Complete technical reference: every endpoint, parameter, response schema, and error code.

Open docs

Full API Docs Register for apiId/apiKey

The integration journey

TIER 1 — VERIFY

Day 0

Onboard with the RFC only: e.firma/CSD certificates and shareholders. No client credential.

TIER 2

When you need depth

Add the same applicant's CIEC and unlock CFSS financials, AR/AP and FinScore.

TIER 3

A month later

Step-by-Step Guides

Setup — your credentials

Before any tier: get your keys and confirm the connection works. You don't need any client data yet.

1. Get your credentials (apiId + apiKey)

Register with CRiskCo to receive your apiId and apiKey by email. Both travel as headers on every request — there is no OAuth flow or Bearer token. Test-mode keys return sandbox data at no cost.

# Required headers on every API call
apiId: YOUR_API_ID
apiKey: YOUR_API_KEY
Content-Type: application/json

2. Your first authenticated call

Validate your credentials with GET /SatHealthCheck — a platform utility available on every tier, with no applicant, no onboarding and no CIEC. The base URL for all calls is https://service.criskco.com/apiservice.svc.

curl -G "https://service.criskco.com/apiservice.svc/SatHealthCheck" \
  -H "apiId: YOUR_API_ID" \
  -H "apiKey: YOUR_API_KEY" \
  --data-urlencode "serviceName=Declarations" \
  --data-urlencode "systemType=SAT" \
  --data-urlencode "unitType=Hours" \
  --data-urlencode "unitAmount=24"

TIER 1 — VERIFY

Day 0 — start with the RFC only

Your first touch with a client requires no credential from them. With the RFC alone you can already confirm identity, certificate validity and corporate ownership — zero friction for the applicant.

3. Verify e.firma / CSD certificates from the RFC

POST /VerifyEFirmaCertificates responds synchronously with the certificates for that RFC: type (FIEL or SELLO), serial number, status and validity dates. Use TransactionId as an idempotency key — repeat the same value and the earlier result is returned without re-querying SAT.

POST https://service.criskco.com/apiservice.svc/VerifyEFirmaCertificates
Headers: apiId, apiKey, Content-Type: application/json

{
  "TransactionId": "case-00482",
  "Rfc": "XXXX000000X00"
}

# Response (abbreviated)
{
  "success": true,
  "status": "COMPLETED",
  "result": {
    "rfc": "XXXX000000X00",
    "holderName": "Holder Name",
    "certificates": [
      {
        "certificateType": "SELLO",
        "serialNumber": "00001000000709064325",
        "status": "ACTIVE",
        "validFrom": "2024-07-31",
        "validTo": "2028-07-31",
        "revocationDate": null
      }
    ]
  }
}

4. Scale to async and batch

For volume, use the async variants: VerifyEFirmaCertificatesWebhook for a single record and VerifyEFirmaCertificatesBatchWebhook for 1–100 records. Both return 202 Accepted and deliver results to your webhook subscription. In a batch, row-level errors don't fail the rest (ROW_INVALID_RFC_FORMAT, ROW_DUPLICATE_RECORD, etc.).

POST https://service.criskco.com/apiservice.svc/VerifyEFirmaCertificatesBatchWebhook
Headers: apiId, apiKey, Content-Type: application/json

{
  "WebhookSubscriptionId": 1,
  "Items": [
    { "TransactionId": "row-1", "Rfc": "XXXX000000X00" },
    { "TransactionId": "row-2", "Rfc": "YYYY000000Y00" }
  ]
}

# 202 Accepted
{ "batchId": "crk_batch_20260820_e6c5b39a", "itemCount": 2, "status": "processing" }

5. Shareholders and beneficial owner (SIGER/RUG)

GET /siger-webhook requests shareholders from the public registry; the HTTP response only confirms the job was accepted and the payload — including the uuid — arrives at your callback. With that uuid, GET /siger-pdf-webhook delivers the registry documents. With querySocios=true each shareholder is also queried for every company they hold.

# 1) Request shareholders (async)
curl -G "https://service.criskco.com/apiservice.svc/siger-webhook" \
  -H "apiId: YOUR_API_ID" -H "apiKey: YOUR_API_KEY" \
  --data-urlencode "taxId=GAPXXXXXXXXX" \
  --data-urlencode "subscriptionId=0" \
  --data-urlencode "querySocios=true"

# 2) Then request the registry documents with the uuid from the callback
curl -G "https://service.criskco.com/apiservice.svc/siger-pdf-webhook" \
  -H "apiId: YOUR_API_ID" -H "apiKey: YOUR_API_KEY" \
  --data-urlencode "taxId=GAPXXXXXXXXX" \
  --data-urlencode "subscriptionId=0" \
  --data-urlencode "uuid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# At this point you have identity, certificate validity and ownership —
# with no credential requested from the client.

TIER 2 — FULL FINANCIAL INTELLIGENCE

When you need depth — add the CIEC

When a case moves forward and you need financial statements, invoicing and repayment capacity, you ask the taxpayer for their CIEC. It's an upgrade on the same applicant, not a new start.

6. SAT onboarding with the CIEC

SAT onboarding uses the taxpayer's CIEC password (CRiskCo does not require e.firma). Send the RFC and CIEC to OnboardingSatIntegration and reuse the RefApplicantId from Tier 1 to keep the same case file.

POST https://service.criskco.com/apiservice.svc/OnboardingSatIntegration
Headers: apiId, apiKey, Content-Type: application/json

{
  "IsAgreeTerms": true,
  "DateAgreeTerms": "2026-04-16",
  "VersionAgreeTerms": "1",
  "Email": "contact@empresa.com",
  "User": "GAPXXXXXXXXX",
  "Password": "CIEC_PASSWORD",
  "RefApplicantId": "loan-app-00482"
}

7. Poll the onboarding status

After onboarding, poll GET /get-applicants every 5–10 seconds until onboardingStatus is 'Available'. Possible values: NotConnected, Processing, Available.

curl -G "https://service.criskco.com/apiservice.svc/get-applicants" \
  -H "apiId: YOUR_API_ID" \
  -H "apiKey: YOUR_API_KEY" \
  --data-urlencode "taxId=GAPXXXXXXXXX" \
  --data-urlencode "onboardingStatus=true"

# Response includes onboardingStatus: NotConnected | Processing | Available

8. Read the normalized financials (CFSS)

Once the applicant is 'Available', GET /financialStatement returns the CRiskCo Financial Statement Standard: balance sheet, P&L and KPIs in a stable 126-field taxonomy per period.

curl -G "https://service.criskco.com/apiservice.svc/financialStatement" \
  -H "apiId: YOUR_API_ID" \
  -H "apiKey: YOUR_API_KEY" \
  --data-urlencode "taxId=GAPXXXXXXXXX" \
  --data-urlencode "financialYear=2022"   # optional — omit for all available years

# Response: { "FinancialStatements": [ { "ASSET": "3916350.00", "REVENUE": "13478313.00", ... } ] }

See the full CFSS standard

TIER 3 — MONITORING & ALERTS

A month later — turn it into a monitored account

A credit decision ages. After the first month, instead of pulling again by hand, let refreshed data arrive in your system by webhook.

9. Register your callback

Register a CallbackUrl with POST /Subscriptions. CRiskCo will first send a GET validation request to your URL — your server must respond HTTP 200 within 2 seconds. Then you'll receive events with FileType: 'JSON' (inline payload in APIResponse) or 'JSON_LINK' (download URL in DownloadUrlList).

# 1) Register the webhook
POST https://service.criskco.com/apiservice.svc/Subscriptions
Headers: apiId, apiKey, Content-Type: application/json
{ "CallbackUrl": "https://yourdomain.com/webhooks/criskco" }

# 2) CRiskCo then sends a GET to that URL for validation —
#    respond HTTP 200 within 2 seconds.

# 3) Events arrive as POSTs with FileType="JSON" (inline payload)
#    or FileType="JSON_LINK" (signed download URLs).
#    Review your subscriptions with GET /Subscriptions.

10. Receive fresh data instead of polling for it

Every endpoint has a *-webhook variant. With the subscription active, trigger the periodic refresh of the accounts you already onboarded — portfolio, AR/AP invoicing and payments — and process the events as they arrive.

# Portfolio refresh
GET /Get-Applicants-Webhook?taxId=GAPXXXXXXXXX&subscriptionId=1&onboardingStatus=true

# Receivables activity for the last period
GET /ar-transactions/invoices-webhook?taxId=GAPXXXXXXXXX&subscriptionId=1 \
    &fromDate=2026-07-01&toDate=2026-07-31

# Payables activity
GET /ap-transactions/payments-webhook?taxId=GAPXXXXXXXXX&subscriptionId=1 \
    &fromDate=2026-07-01&toDate=2026-07-31

11. From monitoring to your own models

With history accumulating across your portfolio, the next step is building your own scores on the same fields with CRiskCo Labs, and connecting them to your agents via MCP.

# Same fields, your model:
#   Tier 1  RFC only        -> identity, certificates, ownership
#   Tier 2  + CIEC          -> CFSS financials, AR/AP, FinScore
#   Tier 3  + subscription  -> continuous refresh and alerts
#   Tier 4  CRiskCo Labs    -> your own scorecards on the same taxonomy
#   Tier 5  MCP             -> the same data, agent-ready

Explore CRiskCo Labs

Ready to integrate?

Start today with the RFC only, add the CIEC when you need depth, and switch on monitoring as your portfolio grows.

Explore More

Verify — RFC only SAT API Integration API Guide Code Samples Credit Risk