Skip to main content

​
Submitting Jobs

All Nexio evaluations are submitted as jobs to POST /api/v1/jobs. The API accepts your request immediately and processes it asynchronously in the background.

​
The Basic Request

curl -X POST https://api.usenexio.com/api/v1/jobs \
  -H "Content-Type: application/json" \
  -H "X-API-Key: nx_live_YOUR_KEY" \
  -d '{
    "profile": {
      "entity": "acme-manufacturing",
      "state": "CA",
      "line": "professional_liability",
      "revenue": 12000000
    },
    "pool": "carriers:all",
    "webhook_url": "https://your-app.com/hooks/nexio"
  }'

​
Request Fields

​
profile
object
required
The entity profile to evaluate. Contains the attributes describing the subject of the evaluation. Fields are domain-specific — see your account configuration for the schema.
​
pool
string
required
The candidate pool identifier to evaluate against. Contact support@usenexio.com to get your available pool identifiers.Example: "carriers:all", "carriers:tier1", "providers:network"
​
webhook_url
string
URL to deliver results to when the evaluation completes. Must be a publicly accessible HTTPS endpoint.If omitted, poll GET /api/v1/jobs/{eval_id} for results.

​
Immediate Response

The API returns 202 Accepted immediately: 
{
  "eval_id": "eval_7xKp2mNc",
  "status": "queued"
}
Save the eval_id — you’ll need it to poll for status or correlate webhook deliveries.

​
Webhook Delivery

When evaluation completes, Nexio sends a POST request to your webhook_url with the full result: 
{
  "eval_id": "eval_7xKp2mNc",
  "status": "completed",
  "pool_size": 1847,
  "filtered": 53,
  "candidates": [
    {
      "tier": "STRONG_FIT",
      "name": "Hartford Financial",
      "confidence": "HIGH",
      "scores": {
        "appetite": "L1",
        "coverage": "L2",
        "financial": "L1",
        "pricing": "L1",
        "placement": "L1",
        "service": "L2"
      },
      "reasoning": "Strong CA prof. liability appetite, $10–15M band..."
    },
    {
      "tier": "MODERATE_FIT",
      "name": "Travelers Companies",
      "confidence": "MEDIUM",
      "scores": {
        "appetite": "L2",
        "coverage": "L2",
        "financial": "L1",
        "pricing": "L2",
        "placement": "L2",
        "service": "L2"
      },
      "reasoning": "Viable CA market, slightly above preferred pricing band."
    }
  ],
  "audit": "https://api.usenexio.com/traces/eval_7xKp2mNc"
}
Your webhook handler should return a 2xx status code to acknowledge delivery. Design your handler to be idempotent — use eval_id as the deduplication key, as Nexio may retry in future versions.

​
Processing Time

Evaluations typically complete in 15–60 seconds depending on pool size and complexity. The pool_size and filtered fields in the response show how many candidates were evaluated.

​
Error Handling

If your request is malformed, the API returns 400 Bad Request: 
{
  "error": {
    "code": "invalid_request",
    "message": "Missing required field: profile.entity",
    "details": []
  }
}
See the API Reference for the full list of error codes.

​
Code Examples

import httpx

def submit_evaluation(api_key: str, profile: dict, pool: str, webhook_url: str) -> str:
    response = httpx.post(
        "https://api.usenexio.com/api/v1/jobs",
        headers={
            "Content-Type": "application/json",
            "X-API-Key": api_key,
        },
        json={
            "profile": profile,
            "pool": pool,
            "webhook_url": webhook_url,
        },
    )
    response.raise_for_status()
    return response.json()["eval_id"]