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).

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_REFERENCE_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:

{
  "responseDetails": "Subscription 1 created successfully",
  "success": true,
  "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,
  "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,
  "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:

DELETE https://service.criskco.com/apiservice.svc/Subscriptions/{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

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