API Integration Guide

How the API Works

CRiskCo's API is applicant-centric. Before you can query any financial or compliance data, the business (the "Applicant") must be onboarded — either through your own UI via API, through CRiskCo's white-label landing page, or via event-driven webhooks.

Three core concepts:

• Credit Provider — your platform, calling the API using apiId and apiKey.
• Applicant — the business applying for credit. They authorize CRiskCo access to their SAT data.
• Customer — a business that is a customer of the Applicant (used for AR/counterparty analysis).

The three API tiers

Endpoints are organized into the same tiers as the platform. You can start at Tier 1 with just the RFC and move up when you need depth or monitoring.

• Tier 1 — Verify — RFC-first checks, no CIEC: ValidateRFC (single and bulk), e.firma certificates, shareholders (SIGER/RUG) and SatHealthCheck (available on any tier).
• Tier 2 — Financial Intelligence — CIEC onboarding with full depth: tax status, tax regimes and Constancia de Situación Fiscal (these require a completed SAT/CIEC onboarding), CFDI receivables and payables, financial statements (CFSS), payroll and FinScore.
• Tier 3 — Monitoring & Alerts — callback subscriptions and asynchronous payloads as data changes.

Browse every endpoint by tier in the API Explorer.

Tier 1 — Verify endpoints (RFC only)

e.firma certificates

Verify the e.firma certificates of an RFC synchronously, asynchronously (webhook), or in batches of up to 100 items. Leave CertificateSerialNumber empty to check every certificate for the RFC.

POST /apiservice.svc/VerifyEFirmaCertificates
{ "TransactionId": "", "Rfc": "XXXX000000X00", "CertificateSerialNumber": "" }

POST /apiservice.svc/VerifyEFirmaCertificatesWebhook
{ "TransactionId": "", "Rfc": "XXXX000000X00", "CertificateSerialNumber": "", "WebhookSubscriptionId": 1 }

POST /apiservice.svc/VerifyEFirmaCertificatesBatchWebhook
{
  "WebhookSubscriptionId": 1,
  "Items": [
    { "TransactionId": "", "Rfc": "XXXX000000X00", "CertificateSerialNumber": "" },
    { "TransactionId": "", "Rfc": "XXXX11111X11", "CertificateSerialNumber": "" }
  ]
}

Shareholders (SIGER/RUG)

Two-step flow: request the shareholders, then the registry documents using the uuid returned on the callback.

GET /apiservice.svc/siger-webhook?taxId=XXXX000000X00&subscriptionId=1&querySocios=true

GET /apiservice.svc/siger-pdf-webhook?taxId=XXXX000000X00&subscriptionId=1&uuid=YOUR_UUID

Authentication

All requests require these headers on every call:

apiId: YOUR_API_ID
apiKey: YOUR_API_KEY
Content-Type: application/json

apiId and apiKey are issued by CRiskCo upon registration. Test mode keys return sandbox data and incur no cost. There is no environment switch — use the correct key for the correct mode.

Get your sandbox credentials: Register at api-docs.criskco.com → receive apiId + apiKey by email.

Integration Models

CRiskCo supports three integration models. Choose based on how much control you need over the onboarding experience.

Model A — Approve API (Full API Control)

You collect the applicant's RFC and CIEC credentials in your own UI and pass them to CRiskCo via API.

Flow:

1. Your app collects RFC + CIEC from the applicant.
2. POST /OnboardingSatIntegration to register the applicant and connect to SAT.
3. GET /get-applicants to poll for onboardingStatus: "Available".
4. POST /applicantinfo or other endpoints to retrieve data.

Step 1 — Onboard via API

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

{
  "IsAgreeTerms": true,
  "DateAgreeTerms": "2026-03-24",
  "VersionAgreeTerms": "1",
  "Email": "contact@empresa.com",
  "User": "GAPXXXXXXXXX",
  "Password": "CIEC_PASSWORD",
  "RefApplicantId": "your-internal-ref-123"
}

Model B — Fintech Solution (Hosted Page)

You redirect the applicant to CRiskCo's hosted onboarding page. CRiskCo handles SAT connection and validation. You retrieve data via API once the status is Available.

Option 1 — General onboarding page (no white-label setup required)

Direct your applicants to CRiskCo's standard onboarding page and ask them to enter your registered reference code when prompted:

https://app.criskco.com/onboarding/#!/app/referrer-es

The applicant enters your reference code during the flow. CRiskCo associates the completed onboarding with that code, which you can use to query status.

Option 2 — White-label onboarding page (requires white-label setup with CRiskCo)

If CRiskCo has provisioned a white-label instance for your brand, your dedicated URL will be:

https://yourbrand.criskco.com/onboarding/#!/app/

Replace yourbrand with the subdomain assigned by CRiskCo.

In both cases, once onboarding is complete, retrieve the applicant using your reference code:

GET /get-applicants?refApplicantId=YOUR_SUBSCRIPTION_ID

No frontend development required. CRiskCo manages the SAT integration and credential handling.

Model C — Webhook Subscription (Event-Driven)

Instead of polling for status, CRiskCo pushes data updates to your server the moment they are ready. This is the recommended model for automated underwriting platforms.

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

{ "CallbackUrl": "https://yourdomain.com/webhooks/criskco" }

Validation: After receiving your subscription request, CRiskCo immediately sends a GET request to your CallbackUrl. Your server must respond with HTTP 200 OK within 2 seconds.

Successful registration response:

{
  "success": true,
  "responseDetails": "Subscription 1 created successfully",
  "ApiSubscriptionData": [
	{
		"Active": true,
		"CallbackUrl": "https://yourdomain.com/path/webhook",
		"ReferrerId": "your_referrer_id",
		"SubscriptionId": 1
    }
  ]
}

Webhook Payload — Inline JSON

When fileResponse is false, CRiskCo sends the data payload directly in the webhook body:

{
  "SubscriptionId": 1,
  "ReferrerId": "criskco_partner",
  "WebhookUrl": "https://yourdomain.com/path/webhook",
  "ApiServiceName": "GetApplicants",
  "FileType": "JSON",
  "DownloadUrlList": null,
  "applicantId": "123456",
  "refApplicantId": "abc-def",
  "APIResponse": "{ "applicantId": "123456", "onboardingStatus": "Available", ... }"
}

Webhook Payload — Downloadable Link

When fileResponse is true, CRiskCo stores the JSON file and sends a download URL instead:

{
  "SubscriptionId": 1,
  "ReferrerId": "criskco_partner",
  "WebhookUrl": "https://yourdomain.com/path/webhook",
  "ApiServiceName": "GetApplicants",
  "FileType": "JSON_LINK",
  "DownloadUrlList": [
    "https://criskco-files.s3.amazonaws.com/..."
  ],
  "applicantId": "123456",
  "refApplicantId": "abc-def",
  "APIResponse": null
}

The payload shape is identical in both modes. FileType tells you whether to parse APIResponse directly or download from DownloadUrlList.

Manage Subscriptions

List all active subscriptions:

GET https://service.criskco.com/apiservice.svc/Subscriptions
Headers: apiId, apiKey

Delete a subscription:

POST https://service.criskco.com/apiservice.svc/Subscriptions?id=YOUR_SUBSCRIPTION_ID
Headers: apiId, apiKey

Retrieve Applicants and Check Status

Regardless of which integration model you use, retrieve the applicantId here. It is required for all financial data endpoints.

GET https://service.criskco.com/apiservice.svc/get-applicants
Headers: apiId, apiKey

Sample Response

{
  "responseDetails": "Data retrieved successfully",
  "success": true,
  "ApiApplicantData": {
    "applicantId": "1000143693",
    "taxId": "GAPXXXXXXXXX",
    "dateConnected": "2026-03-24T09:15:00Z",
    "onboardingStatus": "Available",
    "financials": { ... },
    "blackLists": ["SAT", "OFAC"]
  }
}

Onboarding Statuses

blackLists: Returned when fullResponse=true. Lists any blacklist sources where the applicant has a flag (e.g. "SAT" = EFOS/EDOS, "OFAC" = US sanctions).

RFC Validation

Single RFC

GET /ValidateRFC?rfc=GAPXXXXXXXXX&name=GAP&postal=12345

Params: rfc (required) · name (optional) · postal (optional)

Response:
{
  "Success": true,
  "ValidParameters": [
    { "Property": "ValidRFC", "Valid": true },
    { "Property": "ValidName", "Valid": true },
    { "Property": "ValidPostal", "Valid": true }
  ],
  "message": "RFC válido, y susceptible de recibir facturas"
}

Bulk RFC Validation (up to 5,000)

Upload a plain-text file with one RFC per line, or pipe-separated RFC|Name|Postal.

POST /ValidateRFCBulk
Body: plain-text file

RFC only:
ABCYYYYYYYYYY
DEFZZZZZZZZZZ

RFC + Name + Postal (pipe-separated):
ABCYYYYYYYYYY|EMPRESA ABC|98765
DEFZZZZZZZZZZ|EMPRESA DEF|12345

SAT Compliance Endpoints

These endpoints query by taxId (RFC) — no applicantId required.

Company Tax Status (Opinión de Cumplimiento)

GET /GetCompanyTaxStatus?taxId=GAPXXXXXXXXX

Returns POSITIVO or NEGATIVO plus outstanding obligations (populated only when NEGATIVO).

Company Tax Regimes

GET /GetCompanyTaxRegimes?taxId=GAPXXXXXXXXX

Returns: RFC, Regime, ReportUpdateDate, PayingTax

Constancia De Fiscal

GET /GetCompanyFiscalDetails?taxId=GAPXXXXXXXXX

Returns: RFC, Name, FirstSurname, SecondSurname, CompanyName, CapitalRegime,
CommercialName, OperationStartDate, FiscalStatus, LastStatusChangeDate,
FiscalRegisteredAddress

Historical FinScore

GET /GetHistoricalFinscore?taxId=GAPXXXXXXXXX

{
  "HistoricalFinscores": [
    { "Year": 2025, "Month": 10, "FinScore": 68.2 },
    { "Year": 2025, "Month": 11, "FinScore": 70.4 },
    { "Year": 2026, "Month": 1, "FinScore": 74.0 }
  ]
}

Applicant Financial Data

All financial endpoints are POST with { "applicantId": "..." }. Optional fromDate/toDate query params filter by date (ISO 8601).

Applicant Info (Summary)

POST /applicantinfo

{ "applicantId": "1000143693" }

Returns verified business info, blacklist status, and summarized financials.

Customers and AR Transactions

Suppliers and AP Transactions

Financial Reports

Raw reports — as they appear in the applicant's ERP:

POST /financialreports/rowdata/balancesheet
POST /financialreports/rowdata/profitandloss
POST /financialreports/rowdata/bankstatement

{ "applicantId": "1000143693" }

Standardized reports — normalized by CRiskCo:

POST /financialreports/standard/balancesheet
POST /financialreports/standard/profitandloss

{ "applicantId": "1000143693", "financialYear": "Current" }

financialYear options:
  Current · FinancialYearEnd · PreviousFinancialYearEnd ·
  SecondPreviousFinancialYearEnd · ThirdPreviousFinancialYearEnd

Consolidated financial statement pulled directly from SAT (filed annual returns):

GET /financialStatement?taxId=GAPXXXXXXXXX

// Returns annual income, expenses, assets and liabilities as reported to SAT.
// Useful as a third-party-validated cross-check against ERP-sourced reports.

All Financials in One Call

POST /grouping/applicant-financials

{ "applicantId": "1000143693", "csvInJson": false }

Returns raw data, standardized reports, documents, analytics, and summaries.
Recommended for initial data pulls.

Documents

POST /Documents

{ "applicantId": "1000143693", "csvInJson": false }

Each document includes a direct HTTP download link.

Additional SAT Endpoints

Company Structure

GET /GetCompanyStructure?taxId=GAPXXXXXXXXX

Returns: owner names, RFC, country, participation % (with/without vote),
tenure periods, loans, capital movements.

Payroll Details

GET /GetPayrollDetails?taxId=GAPXXXXXXXXX

Employee Details

GET /GetEmployeesDetails?taxId=GAPXXXXXXXXX

Returns: name, RFC, CURP, position, start date, total work months,
payment frequency, days paid, gross salary.

Information Report (Judicial Records)

GET /GetInformationReport?taxId=GAPXXXXXXXXX

Returns AntecedentesJudiciales grouped by state, with case numbers,
dates, and court references.

SAT Health Check

GET /SatHealthCheck?serviceName=Declarations&systemType=SAT&unitType=Hours&unitAmount=24

Returns avg/max response times, failure rates, and HTTP status codes per check.
Use before making SAT-dependent calls to diagnose upstream issues.

Lifecycle Management

Update Applicant Status

POST /applicant-status

{ "applicantId": "1000143693", "status": "Approved" }

Statuses: New | UnderEvaluation | Approved | Denied | CancelByApplicant | CompanyDefaulted | Completed

Disconnecting statuses stop SAT data syncing. Moving back to a connected status triggers a reconnection attempt.

Trigger a Monitoring Refresh

POST /RequestMonitoring

{ "applicantId": "1000143693", "Source": "API" }

Forces a fresh SAT data pull for an applicant already in your system.

Best Practices

• Always use HTTPS. Never expose your apiKey client-side.
• Validate incoming webhook calls to prevent spoofing — check that requests originate from CRiskCo's IPs.
• Implement exponential backoff retry logic for failed API calls.
• Cache applicantId locally in your LOS — you will use it in every subsequent call.
• Use fullResponse=true on get-applicants only when necessary — it adds latency.
• Poll onboardingStatus for Available before querying financial endpoints — querying while Processing returns incomplete data.
• For automated pipelines, use the Webhook model instead of polling.

Complete Endpoint Reference