> For the complete documentation index, see [llms.txt](https://yutax.gitbook.io/developer/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://yutax.gitbook.io/developer/api-reference/inquiries.md).

# Inquiries

Endpoints para crear inquiries (soft / hard) y obtener snapshots

## Crear inquiry (soft/hard) y obtener snapshot

> Crea un inquiry (soft o hard) y retorna snapshot.<br>

```json
{"openapi":"3.0.3","info":{"title":"Yutax API","version":"1.0.0"},"tags":[{"name":"Inquiries","description":"Endpoints para crear inquiries (soft / hard) y obtener snapshots"}],"servers":[{"url":"https://business.yutax.net","description":"Host placeholder (cambia por tu dominio)"}],"security":[{"HmacHeaders":[]}],"components":{"securitySchemes":{"HmacHeaders":{"type":"apiKey","in":"header","name":"X-SIGNATURE","description":"Auth por headers.\nHeaders: - X-PUBLIC-KEY: public key del business (test o live) - X-TIMESTAMP: unix timestamp (string numérico) - X-NONCE: opcional - X-SIGNATURE: Base64(HMAC-SHA256(stringToSign, privateKey))\nstringToSign:\n  POST\\n{path}\\n{timestamp}\\n{nonce}\\n{sha256(body)}\\n\n\nNota: en NDJSON bulk, el server usa sha256 del body gzip real.\n"}},"parameters":{"XPublicKey":{"name":"X-PUBLIC-KEY","in":"header","required":true,"schema":{"type":"string"},"description":"Public key (ej- yk_live_pk_...)"},"XTimestamp":{"name":"X-TIMESTAMP","in":"header","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Unix timestamp (string numérico)"},"XNonce":{"name":"X-NONCE","in":"header","required":false,"schema":{"type":"string"},"description":"Nonce opcional"},"XSignature":{"name":"X-SIGNATURE","in":"header","required":true,"schema":{"type":"string"},"description":"Firma HMAC base64"}},"schemas":{"InquiriesRequest":{"type":"object","additionalProperties":false,"required":["type","use_case","fullname","email","phone","ci"],"properties":{"type":{"type":"string","enum":["soft","hard"],"description":"Pull type"},"use_case":{"type":"string","maxLength":500,"description":"Código del inquiry purpose (debe existir en inquiry_purpose_catalog)"},"fullname":{"type":"string","maxLength":500,"description":"Nombre provisto por el cliente"},"phone":{"type":"string","maxLength":50},"email":{"type":"string","maxLength":160},"ci":{"type":"string","maxLength":20},"ip":{"type":"string","maxLength":60,"description":"IP opcional"}}},"InquiriesResponseSoft":{"type":"object","additionalProperties":false,"required":["meta","identity","contact_signals","fraud_signals","credit_snapshot"],"properties":{"meta":{"$ref":"#/components/schemas/InquiriesMeta"},"identity":{"$ref":"#/components/schemas/IdentityBlock"},"contact_signals":{"$ref":"#/components/schemas/ContactSignals"},"fraud_signals":{"$ref":"#/components/schemas/FraudSignals"},"credit_snapshot":{"$ref":"#/components/schemas/CreditSnapshot"}}},"InquiriesMeta":{"type":"object","additionalProperties":false,"required":["pull_type","use_case","generated_at"],"properties":{"pull_type":{"type":"string","enum":["soft","hard"]},"use_case":{"type":"string"},"generated_at":{"type":"string","format":"date-time"}}},"IdentityBlock":{"type":"object","additionalProperties":false,"required":["status","full_name","query_name","match_confidence"],"properties":{"status":{"type":"string","enum":["match","verify","insufficient"]},"full_name":{"type":"string"},"query_name":{"type":"string"},"match_confidence":{"type":"number","format":"float","description":"Score/porcentaje (según tu name_match)"}}},"ContactSignals":{"type":"object","additionalProperties":false,"required":["phones","emails"],"properties":{"phones":{"type":"array","items":{"$ref":"#/components/schemas/ContactSignalPhone"}},"emails":{"type":"array","items":{"$ref":"#/components/schemas/ContactSignalEmail"}}}},"ContactSignalPhone":{"type":"object","additionalProperties":false,"required":["number","status"],"properties":{"number":{"type":"string","description":"Teléfono normalizado o como venga"},"status":{"type":"string","enum":["match","provided","unknown"]}}},"ContactSignalEmail":{"type":"object","additionalProperties":false,"required":["email","status"],"properties":{"email":{"type":"string"},"status":{"type":"string","enum":["match","provided","unknown"]}}},"FraudSignals":{"type":"object","additionalProperties":false,"required":["fraud_alert"],"properties":{"fraud_alert":{"type":"object","additionalProperties":false,"required":["present"],"properties":{"present":{"type":"boolean"}}}}},"CreditSnapshot":{"type":"object","additionalProperties":false,"required":["score","score_range","risk_level","negative_indicator_present"],"properties":{"score":{"type":"integer"},"score_range":{"type":"object","additionalProperties":false,"required":["min","max"],"properties":{"min":{"type":"integer"},"max":{"type":"integer"}}},"risk_level":{"type":"string","description":"Nivel según tu bucket"},"negative_indicator_present":{"type":"boolean","description":"true si bucket.max < 400 (según tu lógica)"}}},"InquiriesResponseHard":{"allOf":[{"$ref":"#/components/schemas/InquiriesResponseSoft"},{"type":"object","additionalProperties":false,"required":["accounts","negative_items","inquiries"],"properties":{"accounts":{"type":"object","additionalProperties":false,"required":["count","oldest_account_date","items"],"properties":{"count":{"type":"integer"},"oldest_account_date":{"type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/InquiriesAccountItem"}}}},"negative_items":{"type":"object","additionalProperties":false,"required":["counts","chargebacks","chargeoffs"],"properties":{"counts":{"type":"object","additionalProperties":false,"required":["chargebacks","chargeoffs"],"properties":{"chargebacks":{"type":"integer"},"chargeoffs":{"type":"integer"}}},"chargebacks":{"type":"array","items":{"$ref":"#/components/schemas/NegativeChargebackItem"}},"chargeoffs":{"type":"array","items":{"$ref":"#/components/schemas/NegativeChargeoffItem"}}}},"inquiries":{"type":"array","items":{"$ref":"#/components/schemas/InquiriesHistoryItem"}}}}]},"InquiriesAccountItem":{"type":"object","additionalProperties":false,"required":["report_id","type","status"],"properties":{"report_id":{"type":"integer"},"type":{"type":"string","enum":["debit","credit","wallet","saving","loan","store","subscription","unknown"]},"status":{"type":"string","enum":["open","closed","pending","inactive","suspended","blocked","unknown"]}}},"NegativeChargebackItem":{"type":"object","additionalProperties":false,"required":["chargeback_id","transaction_type","amount","posting_date","notes"],"properties":{"chargeback_id":{"type":"integer"},"transaction_type":{"type":"string","description":"El server lo manda en lowercase del code (ej- p2p_transfer)"},"amount":{"type":"object","additionalProperties":false,"required":["value","currency"],"properties":{"value":{"type":"number","format":"float"},"currency":{"$ref":"#/components/schemas/CurrencyCode"}}},"posting_date":{"type":"string","description":"DateTime string"},"notes":{"type":"string"}}},"CurrencyCode":{"type":"string","description":"Si no viene, default USD","enum":["USD","EUR","GBP","DOP","CUP","MLC","OTHER"]},"NegativeChargeoffItem":{"type":"object","additionalProperties":false,"required":["chargeoff_id","original_amount","open_date","posting_date","chargeoff_reason","notes"],"properties":{"chargeoff_id":{"type":"integer"},"original_amount":{"type":"object","additionalProperties":false,"required":["value","currency"],"properties":{"value":{"type":"number","format":"float"},"currency":{"$ref":"#/components/schemas/CurrencyCode"}}},"open_date":{"type":"string","nullable":true},"posting_date":{"type":"string"},"chargeoff_reason":{"type":"string","enum":["fraud","non_payment","other"]},"notes":{"type":"string"}}},"InquiriesHistoryItem":{"type":"object","additionalProperties":false,"required":["inquiry_id","business_name","type","inquiry_purpose","date"],"properties":{"inquiry_id":{"type":"integer"},"business_name":{"type":"string"},"type":{"type":"string","enum":["HARD"]},"inquiry_purpose":{"type":"string"},"date":{"type":"string","format":"date"}}},"ErrorResponse":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Código de error"},"message":{"type":"string","description":"Mensaje legible (cuando aplique)"}}}}},"paths":{"/api/v1/inquiries":{"post":{"tags":["Inquiries"],"summary":"Crear inquiry (soft/hard) y obtener snapshot","description":"Crea un inquiry (soft o hard) y retorna snapshot.\n","parameters":[{"$ref":"#/components/parameters/XPublicKey"},{"$ref":"#/components/parameters/XTimestamp"},{"$ref":"#/components/parameters/XNonce"},{"$ref":"#/components/parameters/XSignature"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InquiriesRequest"}}}},"responses":{"200":{"description":"OK (soft o hard)","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/InquiriesResponseSoft"},{"$ref":"#/components/schemas/InquiriesResponseHard"}]}}}},"400":{"description":"Error de validación / JSON / parámetros","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Auth inválida / headers faltantes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"405":{"description":"Método no permitido (solo POST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```