---
title: "API Integration Guide — CRiskCo"
description: "Complete technical guide to integrating the CRiskCo API: authentication, integration models, SAT/CFDI endpoints, webhooks, and examples."
lang: en
json-ld: |
  [
    {
      "@context": "https://schema.org",
      "@type": "TechArticle",
      "headline": "API Integration Guide — CRiskCo",
      "description": "Complete technical guide to integrating the CRiskCo API: authentication, integration models, SAT/CFDI endpoints, webhooks, and examples.",
      "author": {
        "@type": "Organization",
        "name": "CRiskCo"
      },
      "publisher": {
        "@type": "Organization",
        "name": "CRiskCo",
        "url": "https://criskco.com"
      },
      "url": "https://criskco.com/developers/api-guide",
      "datePublished": "2026-03-24",
      "dateModified": "2026-03-25",
      "inLanguage": "en-US"
    },
    {
      "@context": "https://schema.org",
      "@type": "BreadcrumbList",
      "itemListElement": [
        {
          "@type": "ListItem",
          "position": 1,
          "name": "Home",
          "item": "https://criskco.com/"
        },
        {
          "@type": "ListItem",
          "position": 2,
          "name": "Developers",
          "item": "https://criskco.com/developers/api-guide"
        },
        {
          "@type": "ListItem",
          "position": 3,
          "name": "API Guide",
          "item": "https://criskco.com/developers/api-guide"
        }
      ]
    }
  ]
---

📘 2025 Report: [Mexico Economic Review 2025  — outlook, charts, and sector signals ](/mexico-economic-review-2025)[Read](/mexico-economic-review-2025)

[![CRiskCo](/assets/criskco-logo-KYPBr-8b.png)](/en)

Solutions

Developers

[Pricing](/en/pricing)

Resources

[Sign In](https://app.criskco.com)ES[Book a Demo](https://meetings.hubspot.com/israel-madrid/lead-discovery)

[Home](/en)[Developers](/en/developers/api-guide) API Guide 

# API Integration Guide

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

## 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 ](/en/integracion-sat-api)[

You are here 

### API Integration Guide

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

](/en/developers/api-guide)[

### Code Samples

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

Go to page ](/en/developers/code-samples)[

### Tutorials

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

Go to page ](/en/tutorials)[

### API Explorer

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

Go to page ](/en/developers/api-explorer)[

### API Docs

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

Open docs ](https://api-docs.criskco.com/)

## 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](/developers/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](https://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

Onboarding managed by

API usage

Best for

Approve API

Partner (your UI)

Full — registration, data retrieval

Banks & fintechs wanting full UX control

White-Label

CRiskCo (hosted page)

Minimal — status + data retrieval

Fast deployment, minimal frontend work

Webhook

Event-driven

/Subscriptions management

Real-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"
}
```

Field

Required

Description

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_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
```

Param

Description

taxId

Filter by RFC

refApplicantId

Filter by your own reference ID

onboardingStatus

Include onboarding status in response (true/false)

fullResponse

Return 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

Status

Meaning

Available

Connected and data processed — ready to query

Processing

Connected but data still being processed

Not Connected

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

Field

Type

Description

RFC

string

Tax ID

PayingTax

string

"POSITIVO" or "NEGATIVO"

CompanyObligationsList

array

Outstanding obligations if NEGATIVO

ReportUpdateDate

date

Report 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

Method

Endpoint

Description

POST

/customers

Customer list + financials

POST

/ar-transactions/invoices

Sales invoices

POST

/ar-transactions/invoices-items

Line items for each AR invoice

POST

/ar-transactions/invoices-by-uuid

AR invoices by UUID (header + items)

POST

/ar-transactions/payments

Payments received

POST

/ar-transactions/creditmemos

Credit memos issued

POST

/grouping/customers

All AR data in one call

### Suppliers and AP Transactions

Method

Endpoint

Description

POST

/suppliers

Supplier list + financials

POST

/ap-transactions/invoices

Supplier invoices

POST

/ap-transactions/invoices-items

Line items for each AP invoice

POST

/ap-transactions/invoices-by-uuid

AP invoices by UUID (header + items)

POST

/ap-transactions/payments

Payments to suppliers

POST

/ap-transactions/creditmemos

Supplier credit memos

POST

/ap-transactions/expenses

Non-invoiced expenses

POST

/grouping/suppliers

All 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
```

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 }
```

report\_type

Description

SAT\_FINANCIAL\_DECLARATION

Annual tax declarations submitted to SAT

SAT\_CONTRIBUYENTE

Opinión de Contribuyente from SAT

SAT\_ANALYTICS

Summarized company report by CRiskCo

APPLICANT\_FILES

Files uploaded during onboarding

MONTHLY\_GENERATED\_REPORT

Monthly 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

Method

Endpoint

Description

GET

/get-applicants

List applicants, get applicantId and status

POST

/OnboardingSatIntegration

Onboard applicant (Model A)

POST

/applicantinfo

Financial + business data

GET

/ValidateRFC

Validate a single RFC against SAT

POST

/ValidateRFCBulk

Validate up to 5,000 RFCs

GET

/GetCompanyTaxStatus

Opinión de Cumplimiento (tax compliance)

GET

/GetCompanyTaxRegimes

Tax regimes

GET

/GetCompanyFiscalDetails

Constancia De Fiscal (fiscal details)

GET

/GetHistoricalFinscore

FinScore history

GET

/GetCompanyStructure

Ownership structure

GET

/GetPayrollDetails

Payroll records

GET

/GetEmployeesDetails

Employee list

GET

/GetInformationReport

Judicial records

GET

/SatHealthCheck

SAT uptime and latency

POST/GET

/Subscriptions

Manage webhook subscriptions

POST

/customers

Customer list + financials

POST

/ar-transactions/invoices

AR invoices

POST

/ar-transactions/invoices-items

AR invoice line items

POST

/ar-transactions/invoices-by-uuid

AR invoices by UUID (header + items)

POST

/ar-transactions/payments

AR payments

POST

/ar-transactions/creditmemos

AR credit memos

POST

/grouping/customers

All AR data in one call

POST

/suppliers

Supplier list + financials

POST

/ap-transactions/invoices

AP invoices

POST

/ap-transactions/invoices-items

AP invoice line items

POST

/ap-transactions/invoices-by-uuid

AP invoices by UUID (header + items)

POST

/ap-transactions/payments

AP payments

POST

/ap-transactions/creditmemos

AP credit memos

POST

/ap-transactions/expenses

Non-invoiced expenses

POST

/grouping/suppliers

All AP data in one call

POST

/financialreports/rowdata/balancesheet

Raw balance sheet

POST

/financialreports/rowdata/profitandloss

Raw P&L

POST

/financialreports/rowdata/bankstatement

Bank statement

POST

/financialreports/standard/balancesheet

Standardized balance sheet

POST

/financialreports/standard/profitandloss

Standardized P&L

GET

/financialStatement

Consolidated financial statement from SAT

POST

/Documents

Documents (declarations, reports)

POST

/grouping/applicant-financials

All financials in one call

POST

/applicant-status

Update applicant status

POST

/RequestMonitoring

Trigger SAT data refresh (a.k.a. Monitoring Company)

### Resources

-   [Full API reference: api-docs.criskco.com](https://api-docs.criskco.com)
-   [Code samples (Python, Node.js, cURL)](/developers/code-samples)
-   [SAT service status](/sat-service-status-mexico)
-   [Security posture: trust.delve.co/criskco](https://trust.delve.co/criskco)
-   [API updates: api@criskco.com](mailto:api@criskco.com)

[Book a technical demo](https://meetings.hubspot.com/israel-madrid/lead-discovery)

[![CRiskCo](/assets/criskco-logo-KYPBr-8b.png)](/en)

Risk and compliance intelligence for Mexico. We connect multi-source regulatory data for reliable enterprise decisions.

[+52 55 6428 4571](tel:+525564284571)[WhatsApp](https://wa.me/525564284571)[contacto@criskco.com](mailto:contacto@criskco.com)

Platform

-   [Platform](/en/#platform)
-   [How It Works](/en/#how-it-works)
-   [Solutions](/en/#solutions)
-   [Pricing](/en/pricing)
-   [SAT Status](/en/sat-service-status-mexico)
-   [Satisfied Customers](/en/success-stories)
-   [Security](https://trust.delve.co/criskco)

Developers

-   [SAT API Integration](/en/integracion-sat-api)
-   [CFSS Standard](/en/cfss)
-   [API Guide](/en/developers/api-guide)
-   [Code Samples](/en/developers/code-samples)
-   [API Tutorials](/en/tutorials)
-   [CRiskCo Labs](/en/solutions/labs)
-   [MCP Integration](/en/solutions/mcp)
-   [API Documentation](https://api-docs.criskco.com/)

Company

-   [About](/en/about)
-   [Success Stories](/en/success-stories)
-   [Careers](/en/careers)
-   [Press](/en/blog)
-   [Contact](/en/about)

© 2026 CRiskCo. All rights reserved.

[Privacy Policy](/en/privacy)[Terms of Service](/en/terms)

[](https://wa.me/525564284571?text=Hola%2C%20me%20gustar%C3%ADa%20conocer%20m%C3%A1s%20sobre%20CRiskCo)