Public API documentation

Marketplace API for lenders

Technical guide for consuming validated application files from idcredit.mx over REST and API keys. Every value shown on this page is fictional and is intended only as an integration example.

Español English

Open portal Jump to endpoints

Base URL https://idcredit.mx

Version Marketplace API v1

Auth API Key

Format JSON UTF-8 over HTTPS

Quick summary

What a lender can do

1. List Browse anonymized inventory without direct personal identifiers.

2. Download Claim one specific case by its unique identifier.

3. Next available Receive the oldest available case that matches a rule set.

4. Feedback Report good or bad downstream behavior by case or CURP.

Standard vs exclusive

If a case is claimed as exclusive, it is no longer available for any other lender. If it is claimed as standard, other lenders may still acquire it later.

Idempotent re-downloads

If the same lender asks for a case it already bought, the API may return the same claim with reused: true instead of raising a conflict.

Authentication

How to send the API key

API keys are created inside the client portal. The full key is shown only once at creation time, so the lender must store it securely on its side.

Header	Example	Notes
`X-API-Key`	`X-API-Key: idc_live_demo_4f6f8e...`	Recommended form.
`Authorization`	`Authorization: ApiKey idc_live_demo_4f6f8e...`	Supported alias.
`Authorization`	`Authorization: Bearer idc_live_demo_4f6f8e...`	Also supported.

Shared filters

Search fields available

The list endpoint and the next-case endpoint accept these filters. Every one of them is optional. If next receives no filters, it returns the oldest available case.

Field	Type	Description
`date`	date	Exact creation date in `YYYY-MM-DD`.
`created_from`	date/datetime	Minimum creation date or timestamp.
`created_to`	date/datetime	Maximum creation date or timestamp.
`fraud_score_min`	int	Minimum internal fraud score.
`fraud_score_max`	int	Maximum internal fraud score.
`email_risk_score_min`	number	Minimum Email Risk score.
`email_risk_score_max`	number	Maximum Email Risk score.
`age_min`	int	Minimum age computed from CURP.
`age_max`	int	Maximum age computed from CURP.
`postal_code`	string	Case postal code.
`socioeconomic_level`	string	Socioeconomic signal derived from Geo Insights.
`has_employment`	bool	`true` when IMSS shows active employment.
`has_blocklist_hits`	bool	`true` when PEP/blocklist hits exist.
`blocklists_clear`	bool	Inverse alias of `has_blocklist_hits`.
`face_match_passed`	bool	Face match result.
`ine_validated`	bool	Combined OCR+ and voter-roll validation success.
`curp_validated`	bool	CURP validation result.
`rfc_validated`	bool	Non-blocking SAT RFC validation result.
`clabe_validated`	bool	CLABE account validation result.
`clabe_name_match_passed`	bool	Account holder name match against the CLABE account.
`name_match_passed`	bool	ID-vs-CURP name match result.
`limit`	int	List pagination. Default `50`, max `200`.
`offset`	int	List pagination offset.

Supported aliases: created_date, date_from, date_to, geo_insights_level, face_match, name_match and clabe_name_match.

GET /api/marketplace/v1/cases

1. List available cases

Returns anonymized inventory. It does not expose names, full CURP, RFC, NSS, phone number or email, but it does expose risk signals, validation outcomes, commercial attributes and the first 10 CURP characters for operational deduplication.

Request example

curl --request GET   --url 'https://idcredit.mx/api/marketplace/v1/cases?created_from=2026-04-01&created_to=2026-04-02&postal_code=11560&has_employment=true&rfc_validated=true&clabe_validated=true&clabe_name_match_passed=true&limit=20'   --header 'X-API-Key: idc_live_demo_4f6f8ea83d7f'

Ordering and availability

Only completed cases are included.
Cases already downloaded by the same lender are excluded.
Cases already claimed as exclusive by another lender are excluded.
Ordering is newest first.

Response example

{
  "ok": true,
  "partner": {
    "partner_code": "fin_demo",
    "partner_name": "Financiera Demo API"
  },
  "result": {
    "items": [
      {
        "application_id": "8f3f7d95-0642-4a34-8e0e-4abf7940d111",
        "curp_first10": "EJLM900101",
        "created_at": "2026-04-02T12:18:41.000000+00:00",
        "fraud_score": 22,
        "fraud_risk": "medium",
        "email_risk_score": "31",
        "geo_insights_level": "C+",
        "age": 35,
        "postal_code": "11560",
        "socioeconomic_level": "C+",
        "has_employment": true,
        "employment_status": "activo",
        "has_blocklist_hits": false,
        "blocklists_clear": true,
        "face_match_passed": true,
        "ine_validated": true,
        "curp_validated": true,
        "rfc_validated": true,
        "clabe_validated": true,
        "clabe_name_match_passed": true,
        "name_match_passed": true,
        "expediente_completo": true,
        "exclusive_available": true
      }
    ],
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}

POST /api/marketplace/v1/cases/{application_id}/download

2. Download one specific case

Reserves and delivers a single case. If the body includes {"exclusive": true}, the system attempts to acquire it as exclusive inventory.

Field	Type	Required	Description
`exclusive`	bool	No	When `true`, attempts an exclusive purchase.

Request example

curl --request POST   --url 'https://idcredit.mx/api/marketplace/v1/cases/8f3f7d95-0642-4a34-8e0e-4abf7940d111/download'   --header 'Content-Type: application/json'   --header 'X-API-Key: idc_live_demo_4f6f8ea83d7f'   --data '{
    "exclusive": true
  }'

Response example

{
  "ok": true,
  "claim": {
    "claim_id": 241,
    "claim_type": "exclusive",
    "access_mode": "api_case",
    "status": "delivered",
    "quoted_price_mxn": 85.0,
    "claimed_at": "2026-04-03T16:10:21.000000+00:00",
    "delivered_at": "2026-04-03T16:10:22.000000+00:00",
    "reused": false
  },
  "case": {
    "application_id": "8f3f7d95-0642-4a34-8e0e-4abf7940d111",
    "created_at": "2026-04-02T12:18:41.000000+00:00",
    "updated_at": "2026-04-02T12:24:12.000000+00:00",
    "requested_amount": 3500,
    "stage": "completed",
    "display_message": "Tu expediente quedó listo.",
    "lead": {
      "full_name": "Mariana Sofia Ejemplo Luna",
      "first_name": "Mariana Sofia",
      "last_name": "Ejemplo",
      "second_last_name": "Luna",
      "curp": "EJLM900101MDFNNA08",
      "rfc": "EJLM900101AB1",
      "nss": "72123456789",
      "clabe": "002010077777777771",
      "phone": "+525500000001",
      "email": "mariana.demo@example.test",
      "postal_code": "11560"
    },
    "age": 35,
    "validation_status": {
      "ocr_plus": "passed",
      "curp": "passed",
      "rfc": "passed",
      "name_match": "passed",
      "nominal_list": "passed",
      "face_match": "passed",
      "blocklists": "passed",
      "sms_otp": "passed",
      "email_otp": "passed",
      "clabe": "passed"
    },
    "fraud_profile": {
      "score": 22,
      "risk": "medium",
      "flags": [
        "reused_fingerprint"
      ]
    },
    "post_otp_checks": {
      "email_risk": {
        "ea_score": "31",
        "fraud_risk": "031 Very Low",
        "ea_advice": "Lower Fraud Risk"
      },
      "geo_insights": {
        "level_code": "C+",
        "match_type": "neighborhood"
      },
      "clabe_validation": {
        "bank_name": "BANCO DEMO",
        "beneficiary_name": "MARIANA SOFIA EJEMPLO LUNA",
        "name_match_status": "matched"
      },
      "imss_nss": {
        "nss": "72123456789"
      },
      "imss_employment": {
        "employment_status": "activo",
        "employer_name": "EMPRESA DEMO SA DE CV",
        "salary_base": "2480.50"
      }
    },
    "artifacts": {
      "validations/02b_rfc.json": {
        "relative_path": "validations/02b_rfc.json",
        "artifact_group": "validations",
        "storage_backend": "s3",
        "bucket_name": "idcredit",
        "object_key": "applications/8f3f7d95-0642-4a34-8e0e-4abf7940d111/validations/02b_rfc.json",
        "object_size": 1180,
        "content_type": "application/json",
        "encoding": "json",
        "data": {
          "request": {
            "rfc": "EJLM900101AB1"
          },
          "response": {
            "estatus": "OK",
            "mensaje": "RFC Valido",
            "informacionAdicional": "RFC válido, y susceptible de recibir facturas",
            "tipoPersona": "F",
            "claveMensaje": "0"
          }
        }
      },
      "evidence/selfie.jpg": {
        "relative_path": "evidence/selfie.jpg",
        "artifact_group": "evidence",
        "storage_backend": "s3",
        "bucket_name": "idcredit",
        "object_key": "applications/8f3f7d95-0642-4a34-8e0e-4abf7940d111/evidence/selfie.jpg",
        "object_size": 182144,
        "content_type": "image/jpeg",
        "encoding": "base64",
        "data": "/9j/4AAQSkZJRgABAQAAAQABAAD..."
      }
    },
    "claim": {
      "claim_id": 241,
      "claim_type": "exclusive",
      "quoted_price_mxn": 85.0,
      "partner_code": "fin_demo",
      "reused": false
    }
  }
}

POST /api/marketplace/v1/cases/next

3. Download the next available case

Searches and claims the next available case based on the provided filters. If no filters are sent, the service attempts to return the oldest available case.

Request example

curl --request POST   --url 'https://idcredit.mx/api/marketplace/v1/cases/next'   --header 'Content-Type: application/json'   --header 'X-API-Key: idc_live_demo_4f6f8ea83d7f'   --data '{
    "created_from": "2026-04-01",
    "fraud_score_max": 30,
    "age_min": 25,
    "age_max": 55,
    "postal_code": "11560",
    "has_employment": true,
    "face_match_passed": true,
    "rfc_validated": true,
    "clabe_validated": true,
    "clabe_name_match_passed": true,
    "exclusive": false
  }'

The next response uses exactly the same schema as Download one specific case.

POST /api/marketplace/v1/behavior-feedback

4. Report good or bad downstream behavior

Accepts downstream feedback after acquisition. The lender can identify the person by application_id or by curp. If the CURP already exists in idcredit, the most recent case is linked automatically; if it does not exist, the external CURP report is still stored.

Field	Type	Required	Description
`application_id`	uuid	Conditional	Case being reported. Optional when `curp` is provided.
`curp`	string	Conditional	Borrower CURP. Can be used even if no idcredit case exists yet.
`behavior`	string	Yes	`good` or `bad`.
`bad_reason`	string	Conditional	Required when `behavior = "bad"`. Values: `payment_default`, `late_payment`, `fraud`, `identity_theft`, `chargeback`, `other`.
`external_report_id`	string	No	Unique event ID from the lender. Recommended for idempotency.
`account_reference`	string	No	Internal customer, loan, contract or account identifier.
`occurred_at`	date/datetime	No	When the reported behavior took place.
`notes`	string	No	Free-form context.
`metadata`	object	No	Flexible JSON for fields such as outstanding amount, days past due or chargeback ID.

Identifier rule

You must provide application_id or curp. You may send both for cross-checking; if they do not match, the API rejects the request.

Recommended idempotency

If you send external_report_id, the endpoint can return the existing record with reused: true instead of creating duplicates.

Request example

curl --request POST   --url 'https://idcredit.mx/api/marketplace/v1/behavior-feedback'   --header 'Content-Type: application/json'   --header 'X-API-Key: idc_live_demo_4f6f8ea83d7f'   --data '{
    "curp": "RAZR811011HVZMPB01",
    "behavior": "bad",
    "bad_reason": "payment_default",
    "external_report_id": "risk-evt-0001842",
    "account_reference": "loan-77821",
    "occurred_at": "2026-04-15T09:30:00-06:00",
    "notes": "Customer reached 90+ DPD.",
    "metadata": {
      "days_past_due": 96,
      "amount_mxn": 8420.55
    }
  }'

Response example

{
  "ok": true,
  "partner": {
    "partner_code": "fin_demo",
    "partner_name": "Financiera Demo API"
  },
  "feedback": {
    "feedback_id": 19,
    "partner_id": 7,
    "api_key_id": 21,
    "portal_user_id": null,
    "application_id": "8f3f7d95-0642-4a34-8e0e-4abf7940d111",
    "lookup_type": "curp",
    "identifier_value": "RAZR811011HVZMPB01",
    "behavior": "bad",
    "bad_reason": "payment_default",
    "external_report_id": "risk-evt-0001842",
    "account_reference": "loan-77821",
    "notes": "Customer reached 90+ DPD.",
    "metadata": {
      "days_past_due": 96,
      "amount_mxn": 8420.55
    },
    "occurred_at": "2026-04-15T09:30:00-06:00",
    "created_at": "2026-04-28T16:04:31.000000+00:00",
    "curp": "RAZR811011HVZMPB01",
    "found_in_idcredit": true,
    "reused": false
  }
}

List payload fields

What the anonymized inventory returns

Field	Type	Description
`application_id`	uuid	Unique case identifier.
`curp_first10`	string	First 10 CURP characters. Useful for deduplication without exposing the full CURP.
`created_at`	datetime	ISO 8601 creation timestamp.
`fraud_score`	int	Internal fraud score.
`fraud_risk`	string	Internal fraud risk tier.
`email_risk_score`	string	Score returned by the Email Risk provider.
`geo_insights_level`	string	General Geo Insights level.
`age`	int	Age computed from CURP.
`postal_code`	string	Postal code.
`socioeconomic_level`	string	Derived socioeconomic signal.
`has_employment`	bool	Active employment according to IMSS.
`employment_status`	string	Textual IMSS employment status.
`has_blocklist_hits`	bool	PEP/blocklist matches.
`blocklists_clear`	bool	Inverse blocklist flag.
`face_match_passed`	bool	Face match result.
`ine_validated`	bool	OCR+ and voter-roll success.
`curp_validated`	bool	CURP validation result.
`rfc_validated`	bool	SAT RFC validation result.
`clabe_validated`	bool	CLABE validation result.
`clabe_name_match_passed`	bool	Account holder name matched the CLABE account.
`name_match_passed`	bool	ID-vs-CURP name match result.
`expediente_completo`	bool	Whether the case is complete.
`exclusive_available`	bool	Always `true` on available listings.

Errors and operational notes

Expected response codes

HTTP	When it happens	Recommended interpretation
`200`	Successful operation.	Process the payload normally.
`201`	A new behavior feedback record was created.	Successful creation in `POST /behavior-feedback`.
`400`	Invalid parameters or malformed request.	Fix the request payload.
`401`	Missing, invalid or inactive API key.	Check credentials.
`402`	Overdue balance after the billing grace period.	Settle overdue invoices and retry.
`403`	Incomplete payment setup for downloads.	Configure card, tax data and pricing.
`404`	Case not found or no case available with those filters.	Business condition, not a transport failure.
`409`	Commercial conflict, for example a case already taken as exclusive by another lender.	Business condition.
`503`	Operational dependency unavailable.	Retry with backoff.

Embedded images and JSON

Download payloads can be large because they include base64 images and full JSON artifacts. Backend-to-backend consumption and internal persistence are strongly recommended.

Rules before a claim

GET /cases remains available for inventory browsing. For POST /cases/{id}/download and POST /cases/next, idcredit.mx requires a stored payment method, minimum tax details and configured pricing. POST /behavior-feedback is not blocked by that commercial rule.

Traceability and billing

Every listing, claim and feedback event is logged with partner, API key, IP, user-agent, claim ID, purchase type and quoted price for reconciliation, audit and billing.