📘 2025 Report:Mexico Economic Review 2025 — outlook, charts, and sector signalsRead

    API Integration Guide

    Onboarding, SAT data extraction, financial reports, and webhooks. Everything you need to integrate CRiskCo.

    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.

    ModelOnboarding managed byAPI usageBest for
    Approve APIPartner (your UI)Full — registration, data retrievalBanks & fintechs wanting full UX control
    White-LabelCRiskCo (hosted page)Minimal — status + data retrievalFast deployment, minimal frontend work
    WebhookEvent-driven/Subscriptions managementReal-time automation, automated underwriting

    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"
}
    FieldRequiredDescription
    IsAgreeTerms✅Applicant has accepted CRiskCo terms
    DateAgreeTerms✅Date terms were accepted (ISO 8601)
    VersionAgreeTerms✅Terms version
    Email✅Applicant's email
    User✅Applicant's RFC
    Password✅Applicant's CIEC (SAT password)
    RefApplicantId❌Your own internal reference ID

    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
    ParamDescription
    taxIdFilter by RFC
    refApplicantIdFilter by your own reference ID
    onboardingStatusInclude onboarding status in response (true/false)
    fullResponseReturn full dataset including financials and blacklists (true/false). Use only when necessary — adds latency.

    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

    StatusMeaning
    AvailableConnected and data processed — ready to query
    ProcessingConnected but data still being processed
    Not ConnectedApplicant has not yet completed onboarding

    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).
    FieldTypeDescription
    RFCstringTax ID
    PayingTaxstring"POSITIVO" or "NEGATIVO"
    CompanyObligationsListarrayOutstanding obligations if NEGATIVO
    ReportUpdateDatedateReport date

    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

    MethodEndpointDescription
    POST/customersCustomer list + financials
    POST/ar-transactions/invoicesSales invoices
    POST/ar-transactions/paymentsPayments received
    POST/ar-transactions/creditmemosCredit memos issued
    POST/grouping/customersAll AR data in one call

    Suppliers and AP Transactions

    MethodEndpointDescription
    POST/suppliersSupplier list + financials
    POST/ap-transactions/invoicesSupplier invoices
    POST/ap-transactions/paymentsPayments to suppliers
    POST/ap-transactions/creditmemosSupplier credit memos
    POST/ap-transactions/expensesNon-invoiced expenses
    POST/grouping/suppliersAll AP data in one call

    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 }
    report_typeDescription
    SAT_FINANCIAL_DECLARATIONAnnual tax declarations submitted to SAT
    SAT_CONTRIBUYENTEOpinión de Contribuyente from SAT
    SAT_ANALYTICSSummarized company report by CRiskCo
    APPLICANT_FILESFiles uploaded during onboarding
    MONTHLY_GENERATED_REPORTMonthly report by CRiskCo

    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

    MethodEndpointDescription
    GET/get-applicantsList applicants, get applicantId and status
    POST/OnboardingSatIntegrationOnboard applicant (Model A)
    POST/applicantinfoFinancial + business data
    GET/ValidateRFCValidate a single RFC against SAT
    POST/ValidateRFCBulkValidate up to 5,000 RFCs
    GET/GetCompanyTaxStatusOpinión de Cumplimiento (tax compliance)
    GET/GetCompanyTaxRegimesTax regimes
    GET/GetCompanyFiscalDetailsConstancia De Fiscal (fiscal details)
    GET/GetHistoricalFinscoreFinScore history
    GET/GetCompanyStructureOwnership structure
    GET/GetPayrollDetailsPayroll records
    GET/GetEmployeesDetailsEmployee list
    GET/GetInformationReportJudicial records
    GET/SatHealthCheckSAT uptime and latency
    POST/GET/DELETE/SubscriptionsManage webhook subscriptions
    POST/customersCustomer list + financials
    POST/ar-transactions/invoicesAR invoices
    POST/ar-transactions/paymentsAR payments
    POST/ar-transactions/creditmemosAR credit memos
    POST/grouping/customersAll AR data in one call
    POST/suppliersSupplier list + financials
    POST/ap-transactions/invoicesAP invoices
    POST/ap-transactions/paymentsAP payments
    POST/ap-transactions/creditmemosAP credit memos
    POST/ap-transactions/expensesNon-invoiced expenses
    POST/grouping/suppliersAll AP data in one call
    POST/financialreports/rowdata/balancesheetRaw balance sheet
    POST/financialreports/rowdata/profitandlossRaw P&L
    POST/financialreports/rowdata/bankstatementBank statement
    POST/financialreports/standard/balancesheetStandardized balance sheet
    POST/financialreports/standard/profitandlossStandardized P&L
    POST/DocumentsDocuments (declarations, reports)
    POST/grouping/applicant-financialsAll financials in one call
    POST/applicant-statusUpdate applicant status
    POST/RequestMonitoringTrigger SAT data refresh