API Reference
Match Customer
Resolve an inbound case to a customer, ship-to, and contact in master data.
Authorization
bearerAuth AuthorizationBearer <token>
OAuth2 client credentials flow. Token obtained from /oauth2/token on the auth host.
In: header
Header Parameters
X-Correlation-Id*string
Caller-supplied correlation ID. Propagated end-to-end and returned in responses and audit logs.
Idempotency-Key?string
Optional. If reused within 24 hours with the same payload, the cached response is returned. Reuse with a different payload yields 409.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://api.eu.faction.ai/v1/match/customer" \ -H "X-Correlation-Id: 8f3c-b21" \ -H "Idempotency-Key: case-CRM-2026-04-29-00417-intent-v1" \ -H "Content-Type: application/json" \ -d '{ "case_id": "string", "sender": "user@example.com" }'{
"customer_id": "CUST-UK-1042",
"ship_to_id": "SHIP-UK-1042-BHM",
"contact_id": "CON-29871",
"confidence_score": 0.95,
"match_rationale": "Exact email domain match (acme-engineering.co.uk to CUST-UK-1042). Sender 'buyer@' matches active contact CON-29871. Birmingham depot maps to known ship-to.",
"alternatives": [],
"branch_hint": "BR-UK-014",
"recommended_action": "auto_accept"
}{
"error_code": "MISSING_REQUIRED_FIELD",
"message": "Field 'case_id' is required.",
"correlation_id": "8f3c-b21",
"request_id": "req_01JZP4..."
}{
"error_code": "EXPIRED_TOKEN",
"message": "Bearer token expired at 2026-04-29T13:00:00Z.",
"correlation_id": "8f3c-b21",
"request_id": "req_01JZP4..."
}{
"error_code": "SCOPE_INSUFFICIENT",
"message": "Token lacks scope 'extract.quote'.",
"correlation_id": "8f3c-b21",
"request_id": "req_01JZP4..."
}{
"error_code": "IDEMPOTENCY_KEY_CONFLICT",
"message": "Idempotency key was previously used with a different request payload.",
"correlation_id": "8f3c-b22",
"request_id": "req_01JZP4..."
}{
"error_code": "RATE_LIMITED",
"message": "Per-tenant per-module rate limit exceeded.",
"correlation_id": "8f3c-b21",
"request_id": "req_01JZP4..."
}{
"error_code": "INTERNAL_ERROR",
"message": "An unexpected error occurred.",
"correlation_id": "8f3c-b21",
"request_id": "req_01JZP4..."
}Notes
- Combines deterministic (email domain, phone, prior-thread), structured (address, name normalization), and behavioral (prior orders, typical branch) signals.
- Generic email domains (gmail.com etc.) cause email-domain weight to drop near zero; matcher falls back to other signals.
- New customers return empty
customer_id,confidence_score: 0, and anunmatched_reason. - Multiple ship-tos: best inferred from request body; otherwise the customer default with reduced confidence.
- Always sync; default p50 under 400 ms.