Key Concepts
Evaluations
An evaluation is a request to assess an entity profile against a candidate pool. You submit an evaluation via POST /api/v1/jobs with a profile description and a target pool identifier.
Each evaluation gets a unique eval_id (e.g., eval_7xKp2mNc) and is processed asynchronously. Results are delivered to your webhook and available via the status endpoint.
Profiles
A profile describes the entity being evaluated — the subject of the inference. Profiles are structured objects with fields that describe relevant attributes (entity name, geography, line of business, financial size, etc.).
{
"profile": {
"entity": "acme-manufacturing",
"state": "CA",
"line": "professional_liability",
"revenue": 12000000
}
}
Pools
A pool identifies the set of candidates to evaluate against. Nexio manages candidate pools; you reference them by identifier string (e.g., carriers:all).
{
"pool": "carriers:all"
}
The Evaluation Pipeline
Every evaluation runs through three stages:
1. Filter
Binary eligibility checks — no inference. Candidates that fail hard constraints (licensing, jurisdiction, regulatory requirements) are eliminated from the pool entirely. The filtered field in the response shows how many candidates were removed.
2. Assess
Six-dimension categorical scoring. Each remaining candidate is scored across configured dimensions using a four-level rating:
| Level | Meaning |
|---|
L1 | Ideal / Superior |
L2 | Solid / Good |
L3 | Adequate / Marginal |
L4 | Poor / Disqualifying |
appetite, coverage, financial, pricing, placement, service. Dimensions are configurable per vertical.
3. Rank & Trace
Candidates are bucketed into tiers based on their aggregate dimensional assessment, and reasoning is generated for each.
Tiers
Each candidate in the output is assigned to one of four tiers:
| Tier | Meaning |
|---|
STRONG_FIT | Recommended — strong match across dimensions |
MODERATE_FIT | Viable — good match with some tradeoffs |
WEAK_FIT | Possible — flagged concerns, proceed with review |
NO_FIT | Excluded — does not meet evaluation criteria |
Confidence
Each candidate result includes a confidence signal (HIGH, MEDIUM, LOW) reflecting the certainty of the tier assignment.
Audit Trails
Every evaluation generates a full audit trail accessible at the URL in the audit field of the response. Audit trails show which candidates were filtered, how each dimension was scored, and the reasoning chain.
Jobs vs. Evaluations
Internally, every evaluation runs as an asynchronous job. The terms are used interchangeably in this documentation. The API endpoint is /api/v1/jobs; the response object uses eval_id as the identifier.
Webhooks
Webhook delivery is the recommended way to receive evaluation results. Provide a webhook_url in your job submission request, and Nexio will POST the completed evaluation to that URL when processing is done.
Nexio expects your webhook endpoint to return a 2xx status code. Delivery is attempted once — build idempotency into your handler using eval_id.
Rate Limits
Rate limits are enforced per API key. Limit headers are included in every response:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1708300800
