Documentación pública del API

Marketplace API para financieras

Guía técnica para consumir expedientes validados desde idcredit.mx por medio de API REST y API Key. Todos los datos mostrados en esta página son ficticios y se usan únicamente como ejemplo de integración.

Español English

Entrar al portal Ver endpoints

Base URL https://idcredit.mx

Versión Marketplace API v1

Autenticación API Key sobre HTTPS

Formato JSON UTF-8

Resumen rápido

Qué puede hacer una financiera

1. Listar Consultar inventario anonimizado sin datos personales directos.

2. Descargar Tomar un expediente puntual por su identificador único.

3. Siguiente disponible Recibir el expediente más antiguo que cumpla ciertos criterios.

4. Feedback Reportar comportamiento bueno o malo por expediente o CURP.

Modo standard vs exclusive

Si un expediente se toma como exclusive, deja de estar disponible para cualquier otra financiera. Si se toma como standard, puede seguir disponible para otros clientes.

Re-descarga idempotente

Si la misma financiera vuelve a pedir un expediente que ya compró, la API puede devolver el mismo claim con reused: true en lugar de fallar por conflicto.

Autenticación

Cómo enviar la API Key

Las API Keys se generan desde el portal de cliente. La llave completa solo se muestra en el momento de creación, por lo que debe resguardarse por la financiera.

Encabezado	Ejemplo	Notas
`X-API-Key`	`X-API-Key: idc_live_demo_4f6f8e...`	Forma recomendada.
`Authorization`	`Authorization: ApiKey idc_live_demo_4f6f8e...`	Alias soportado.
`Authorization`	`Authorization: Bearer idc_live_demo_4f6f8e...`	También soportado.

Filtros compartidos

Campos de búsqueda disponibles

El endpoint de listado y el endpoint de siguiente expediente aceptan los siguientes filtros. Todos son opcionales. Si next no recibe filtros, devuelve el expediente disponible más antiguo.

Campo	Tipo	Descripción
`date`	date	Fecha exacta de creación en formato `YYYY-MM-DD`.
`created_from`	date/datetime	Fecha u hora mínima de creación.
`created_to`	date/datetime	Fecha u hora máxima de creación.
`fraud_score_min`	int	Score antifraude mínimo.
`fraud_score_max`	int	Score antifraude máximo.
`email_risk_score_min`	number	Score Email Risk mínimo.
`email_risk_score_max`	number	Score Email Risk máximo.
`age_min`	int	Edad mínima calculada desde CURP.
`age_max`	int	Edad máxima calculada desde CURP.
`postal_code`	string	Código postal del expediente.
`socioeconomic_level`	string	Nivel socioeconómico derivado de Geo Insights.
`has_employment`	bool	`true` si IMSS refleja empleo activo.
`has_blocklist_hits`	bool	`true` si hubo coincidencias en PEPs/listas negras.
`blocklists_clear`	bool	Alias inverso de `has_blocklist_hits`.
`face_match_passed`	bool	Resultado de la comparación facial.
`ine_validated`	bool	Éxito conjunto de OCR+ y lista nominal.
`curp_validated`	bool	Resultado del servicio de validación de CURP.
`rfc_validated`	bool	Resultado no bloqueante de validación RFC SAT.
`clabe_validated`	bool	Resultado de validación de la cuenta CLABE.
`clabe_name_match_passed`	bool	Coincidencia de nombre titular vs cuenta CLABE.
`name_match_passed`	bool	Coincidencia nombre credencial vs CURP.
`limit`	int	Paginación del listado. Default `50`, máximo `200`.
`offset`	int	Desplazamiento del listado.

Alias adicionales soportados: created_date, date_from, date_to, geo_insights_level, face_match, name_match y clabe_name_match.

GET /api/marketplace/v1/cases

1. Listado de expedientes disponibles

Devuelve inventario anonimizado. No expone nombres, CURP completo, RFC, NSS, teléfono ni correo, pero sí señales de riesgo, validaciones, atributos comerciales y el prefijo de 10 caracteres del CURP para deduplicación operativa.

Ejemplo de request

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'

Orden y disponibilidad

Solo incluye expedientes completed.
No incluye expedientes ya descargados por el mismo cliente.
No incluye expedientes tomados como exclusive por otro cliente.
El orden es por creación descendente.

Ejemplo de respuesta

{
  "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. Descargar expediente específico

Reserva y entrega un expediente puntual. Si el body incluye {"exclusive": true}, el sistema intenta tomarlo como exclusivo.

Campo	Tipo	Requerido	Descripción
`exclusive`	bool	No	Si es `true`, intenta comprar el expediente como exclusivo.

Ejemplo de request

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

Ejemplo de respuesta

{
  "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. Descargar el siguiente expediente disponible

Busca y toma el siguiente expediente disponible según los criterios enviados. Si no se mandan filtros, el servicio intenta devolver el expediente disponible más antiguo.

Ejemplo de request

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

La respuesta de next usa exactamente la misma estructura que Descargar expediente específico.

POST /api/marketplace/v1/behavior-feedback

4. Reportar comportamiento bueno o malo

Recibe retroalimentación posterior al alta del usuario. La financiera puede identificar a la persona por application_id o por curp. Si el CURP ya existe en idcredit, el sistema enlaza el expediente más reciente; si no existe, el reporte se guarda de todos modos con el CURP externo.

Campo	Tipo	Requerido	Descripción
`application_id`	uuid	Condicional	Expediente sobre el cual se reporta. Opcional si se envía `curp`.
`curp`	string	Condicional	CURP del usuario. Puede usarse aunque todavía no exista expediente en idcredit.
`behavior`	string	Sí	`good` o `bad`.
`bad_reason`	string	Condicional	Obligatorio cuando `behavior = "bad"`. Valores: `payment_default`, `late_payment`, `fraud`, `identity_theft`, `chargeback`, `other`.
`external_report_id`	string	No	Identificador único del evento en la financiera. Recomendado para idempotencia en reintentos.
`account_reference`	string	No	ID interno del cliente, cuenta, crédito o contrato dentro del sistema de la financiera.
`occurred_at`	date/datetime	No	Momento en que ocurrió el comportamiento reportado.
`notes`	string	No	Comentario libre para contexto adicional.
`metadata`	object	No	JSON libre para atributos específicos, por ejemplo monto vencido, días de atraso o identificador del chargeback.

Regla de identificación

Debes enviar application_id o curp. Puedes mandar ambos para validación cruzada; si no coinciden, la API rechaza el request.

Idempotencia recomendada

Si envías external_report_id, el endpoint puede devolver el mismo registro con reused: true en lugar de duplicarlo.

Ejemplo de request

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": "Cliente llegó a 90+ DPD.",
    "metadata": {
      "days_past_due": 96,
      "amount_mxn": 8420.55
    }
  }'

Ejemplo de respuesta

{
  "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": "Cliente llegó a 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
  }
}

Campos clave del listado

Qué devuelve el inventario anonimizado

Campo	Tipo	Descripción
`application_id`	uuid	Identificador único del expediente.
`curp_first10`	string	Primeros 10 caracteres del CURP. Sirve para deduplicar sin exponer el CURP completo.
`created_at`	datetime	Fecha ISO 8601.
`fraud_score`	int	Score antifraude interno.
`fraud_risk`	string	Nivel de riesgo antifraude.
`email_risk_score`	string	Score del servicio Email Risk.
`geo_insights_level`	string	Nivel general reportado por Geo Insights.
`age`	int	Edad calculada desde CURP.
`postal_code`	string	Código postal.
`socioeconomic_level`	string	Nivel socioeconómico derivado.
`has_employment`	bool	Empleo activo según IMSS.
`employment_status`	string	Estatus textual IMSS.
`has_blocklist_hits`	bool	Coincidencias en listas negras/PEPs.
`blocklists_clear`	bool	Bandera inversa de listas negras.
`face_match_passed`	bool	Resultado de comparación facial.
`ine_validated`	bool	Éxito de OCR+ y lista nominal.
`curp_validated`	bool	Resultado de validación CURP.
`rfc_validated`	bool	Resultado de validación RFC SAT.
`clabe_validated`	bool	Resultado de validación CLABE.
`clabe_name_match_passed`	bool	Coincidencia nombre titular vs CLABE.
`name_match_passed`	bool	Coincidencia de nombre INE vs CURP.
`expediente_completo`	bool	Indica si el expediente está completo.
`exclusive_available`	bool	Siempre `true` en expedientes disponibles.

Errores y consideraciones

Códigos de respuesta esperados

HTTP	Cuándo sucede	Lectura recomendada
`200`	Operación exitosa.	Procesar el payload normalmente.
`201`	Se creó un nuevo reporte de comportamiento.	Alta exitosa en `POST /behavior-feedback`.
`400`	Parámetros inválidos o malformed request.	Corregir request.
`401`	API Key ausente, inválida o inactiva.	Revisar credenciales.
`402`	Cuenta con adeudos vencidos después del día 15.	Liquidar facturas vencidas y reintentar.
`403`	Perfil de pago incompleto para descargar expedientes.	Capturar tarjeta, datos fiscales y precios vigentes.
`404`	No se encontró el expediente o no hay uno disponible con esos criterios.	Condición de negocio, no error de transporte.
`409`	Conflicto comercial, por ejemplo un expediente tomado como exclusivo por otro cliente.	Condición de negocio.
`503`	Dependencia operativa no disponible.	Aplicar retry con backoff.

Imágenes y JSONs embebidos

El payload de descarga puede ser grande porque incluye imágenes en base64 y artefactos JSON completos. Se recomienda consumirlo backend-to-backend y persistirlo internamente.

Reglas previas al claim

GET /cases permanece disponible para consulta. Para POST /cases/{id}/download y POST /cases/next, idcredit.mx exige tarjeta guardada, datos fiscales mínimos y precios configurados. Si existe un adeudo vencido, solo las operaciones de descarga quedan bloqueadas hasta liquidarlo. POST /behavior-feedback no depende de ese bloqueo comercial.

Trazabilidad y facturación

Cada listado, claim y entrega queda registrado con partner, API key, IP, user-agent, claim ID, tipo de compra y precio cotizado para conciliación y facturación posterior.