Skip to content
AvelinLabs

Response Field Reference

AvelinLabs responses are decision-support signals for AI-native hiring and workforce systems.

Use response fields to rank results, decide what to display, route uncertain outputs to review, support workflow automation, and explain why a result was returned. Do not treat scores or labels as absolute truth. They are signals your product should combine with its own risk policy, review process, and user experience.

This page focuses on fields already present in the public API docs or public example responses. It does not add fields, endpoints, response schemas, or runtime behavior.

For a practical 30-60 minute workflow evaluation that uses these fields, see Evaluate AvelinLabs in your workflow.

For examples of how response signals may change across strong, weak, ambiguous, vague, and noisy inputs, see Input quality examples.

How to Use This Reference

Section titled “How to Use This Reference”

Each field block includes:

  • Field path
  • Type
  • Appears in
  • Meaning
  • How to use it
  • Do not use it for
  • Stability / beta note
  • Example value

Optional fields may be absent for some responses. During beta, clients should ignore unknown additive fields and avoid relying on debug-only fields.

Metrics you can derive from AvelinLabs responses

Section titled “Metrics you can derive from AvelinLabs responses”

AvelinLabs does not only return a classification result. Each response includes decision-support signals that help customer products measure confidence, uncertainty, ambiguity, weak input quality, review routing, occupation alignment, and evidence coverage.

Customers can use these signals to decide what can be automated, what needs review, what lacks evidence, and what can be explained to a user, reviewer, or client. Thresholds are customer-defined: use the fields below with your own workflow policy, risk tolerance, and review process. AvelinLabs outputs should support routing and human judgment, not final automated hiring decisions.

Classification and normalization coverage

Section titled “Classification and normalization coverage”

Use these metrics to understand how often raw role text becomes a usable structured occupation signal.

Classification coverage

analyzed roles with usable occupation output / total analyzed roles

Define “usable” for your product. A common beta policy is to require at least one ranked result with an O*NET code plus enough confidence, quality, or review context for display.

O*NET mapping coverage

responses with results[].onet_code / total responses

This measures how often responses include a structured occupation code that can be stored, compared, enriched, or linked to occupation profile data.

High-confidence occupation coverage

responses with confidence_level == "HIGH" or confidence above a customer-defined threshold / total responses

Use this to estimate how often role text produces a strong enough occupation signal for your chosen workflow.

Relevant fields:

  • results[].onet_code
  • results[].title
  • confidence
  • confidence_level
  • job_signals

Review-routing metrics

Section titled “Review-routing metrics”

Use these metrics to measure how much output can move through low-risk workflow automation and how much should be routed to human review.

Auto-accept rate

count(decision.decision == "AUTO_ACCEPT") / total responses

Use AUTO_ACCEPT-like outcomes for routing, display defaults, enrichment, or other low-risk workflow automation. Do not use them as final hiring decisions.

Review rate

count(decision.decision == "REVIEW") / total responses

This is a practical measure of how often your workflow should ask a human to inspect the output before using it downstream.

Ambiguity rate

count(is_ambiguous == true OR domain_is_ambiguous == true) / total responses

This helps identify unclear role text, unclear domain fit, or cases where multiple interpretations may be plausible.

Reject / low-usability rate

count(decision.decision == "REJECT") / total responses

Use this as a signal that the input or returned evidence may not meet your minimum usability threshold.

Human-review workload

responses routed to review or ambiguity workflows

A practical implementation can count responses with decision.decision equal to REVIEW or AMBIGUOUS, plus responses where is_ambiguous or domain_is_ambiguous is true.

Relevant fields:

  • decision.decision
  • decision.reason
  • decision.decision_score
  • is_ambiguous
  • domain_is_ambiguous

Confidence and uncertainty metrics

Section titled “Confidence and uncertainty metrics”

Use these metrics to tune thresholds, monitor confidence drift, and separate strong outputs from outputs that need review.

Average confidence

average(confidence)

Track this over batches, endpoints, customer workflows, or role families. Do not treat a higher average as proof of correctness without review data.

Average uncertainty

average(uncertainty.total)

Use this to watch whether incoming role text is becoming harder to interpret or less well supported by available evidence.

Low-confidence rate

responses below a customer-defined confidence threshold / total responses

Set this threshold based on your workflow. A review-heavy product may accept lower confidence than an automated enrichment workflow.

High-uncertainty rate

responses above a customer-defined uncertainty threshold / total responses

Use this to route outputs to review, request better input, or prevent automatic display in sensitive workflows.

Trust distribution

distribution of trust_score values across analyzed roles

Use the distribution, not only the average, to see whether outputs cluster into high-support, borderline, or low-support groups.

Relevant fields:

  • confidence
  • confidence_level
  • trust_score
  • uncertainty.aleatoric
  • uncertainty.epistemic
  • uncertainty.total

Input quality and weak-signal metrics

Section titled “Input quality and weak-signal metrics”

Use these metrics to understand whether upstream job descriptions, intake forms, or role prompts provide enough evidence for reliable decision support.

Weak-signal rate

count(weak_signal_detected == true) / total responses

This helps identify sparse, generic, or poorly grounded role text.

Ambiguous-input rate

count(is_ambiguous == true OR domain_is_ambiguous == true) / total responses

Track this alongside weak-signal rate to identify intake flows that need clearer job responsibilities, required skills, seniority, or domain context.

Insufficient-evidence rate

customer-defined combination of low confidence, high uncertainty, weak signals, or ambiguous domain signals

Example policy inputs include low confidence, high uncertainty.total, weak_signal_detected == true, is_ambiguous == true, or domain_is_ambiguous == true. Choose the combination that matches your workflow.

Relevant fields:

  • weak_signal_detected
  • weak_signal_reason
  • is_ambiguous
  • domain_is_ambiguous
  • job_signals

Explainability and evidence metrics

Section titled “Explainability and evidence metrics”

Use these metrics to measure whether outputs include enough visible evidence for reviewers, users, or client-facing reports.

Skill-evidence coverage

responses with non-empty results[].matching_skills / total responses

This measures how often the output includes explicit skill or capability evidence supporting the occupation match.

Explanation coverage

responses with results[].explanation.why_match / total responses

Use this to check whether responses include a plain-English explanation suitable for review or display.

Review-ready output rate

responses with occupation, confidence, decision reason, and explanation available / total responses

Define the exact field combination for your workflow. A common review-ready minimum is results[].onet_code, confidence, decision.reason, and results[].explanation.why_match.

Relevant fields:

  • results[].matching_skills
  • results[].explanation.why_match
  • results[].quality_score
  • results[].domain_grounding
  • decision.reason

Practical workflow guidance

Section titled “Practical workflow guidance”
  • Use AUTO_ACCEPT-like decisions only for routing, display defaults, enrichment, or low-risk workflow automation, not final hiring decisions.
  • Use REVIEW, AMBIGUOUS, is_ambiguous, and domain_is_ambiguous outcomes to create human review queues.
  • Use weak-signal and ambiguity rates to improve upstream job descriptions, intake questions, or required context fields.
  • Use confidence, uncertainty, and trust distributions to tune customer-defined thresholds over time.
  • Use skill evidence and explanations to support transparency for users, reviewers, and client-facing teams.
  • Keep threshold choices in your product configuration so they can evolve as your beta evaluation data grows.

Shared Decision and Confidence Fields

Section titled “Shared Decision and Confidence Fields”

confidence

  • Type: number
  • Appears in: job-analyze, job-classify, ranked occupation outputs
  • Meaning: Overall confidence signal for the top result or candidate result.
  • Use it for: Ranking, display thresholds, review routing, and automation policy decisions.
  • Do not use it for: Treating the result as absolute truth or making high-risk final decisions without review.
  • Stability: Public beta stable concept; numeric calibration may evolve.
  • Example: 0.88

confidence_level

  • Type: string
  • Appears in: job-analyze, job-classify
  • Meaning: Human-readable confidence category derived from the response confidence family.
  • Use it for: UI labels, reviewer triage, and coarse routing logic.
  • Do not use it for: Replacing numeric thresholds where your product needs fine-grained policy control.
  • Stability: Public beta stable concept; labels may evolve additively.
  • Example: "HIGH"

trust_score

  • Type: number
  • Appears in: job-analyze, job-classify
  • Meaning: Trust-oriented score combining result strength and quality support.
  • Use it for: Deciding whether the selected output has enough support to display, route, or review.
  • Do not use it for: Assuming the output is validated ground truth.
  • Stability: Public beta stable concept; scoring calibration may evolve.
  • Example: 0.84

uncertainty.aleatoric

  • Type: number
  • Appears in: job-analyze, job-classify
  • Meaning: Signal for uncertainty associated with noisy, vague, or ambiguous input evidence.
  • Use it for: Detecting inputs that may need cleaner job text, better role context, or human review.
  • Do not use it for: A standalone rejection rule without considering confidence, decision labels, and workflow risk.
  • Stability: Public beta stable concept; numeric calibration may evolve.
  • Example: 0.21

uncertainty.epistemic

  • Type: number
  • Appears in: job-analyze, job-classify
  • Meaning: Signal for uncertainty associated with limited support in available evidence.
  • Use it for: Identifying cases where the system has less evidence for the returned result.
  • Do not use it for: Inferring a specific missing data source or implementation detail.
  • Stability: Public beta stable concept; numeric calibration may evolve.
  • Example: 0.16

uncertainty.total

  • Type: number
  • Appears in: job-analyze, job-classify
  • Meaning: Combined uncertainty signal.
  • Use it for: Review routing, automation guardrails, and display warnings when uncertainty is high.
  • Do not use it for: Treating low uncertainty as proof that the output is correct.
  • Stability: Public beta stable concept; numeric calibration may evolve.
  • Example: 0.185

decision.decision

  • Type: string
  • Appears in: job-analyze, job-classify
  • Meaning: Routing label such as AUTO_ACCEPT, REVIEW, REJECT, or AMBIGUOUS.
  • Use it for: Deciding whether your workflow should display, review, reject, or request more input.
  • Do not use it for: Skipping your own product policy, compliance policy, or human review requirements.
  • Stability: Public beta stable concept; additional labels may appear later.
  • Example: "AUTO_ACCEPT"

decision.decision_score

  • Type: number
  • Appears in: job-analyze, job-classify
  • Meaning: Numeric signal supporting the routing label.
  • Use it for: Understanding relative decision strength when a decision block is present.
  • Do not use it for: Replacing confidence, uncertainty, or your product’s workflow thresholds.
  • Stability: Beta field; numeric calibration may evolve.
  • Example: 0.61

decision.reason

  • Type: string
  • Appears in: job-analyze, job-classify
  • Meaning: Human-readable explanation for the routing label.
  • Use it for: Reviewer context, logs, support diagnostics, and user-facing explanations where appropriate.
  • Do not use it for: Machine parsing or stable policy branching.
  • Stability: Stable concept, but wording may change during beta.
  • Example: "Confidence 0.880 meets minimum 0.750 and uncertainty 0.160 stays below maximum 0.250."

decision.applied_rule

  • Type: string
  • Appears in: job-analyze, job-classify
  • Meaning: Rule identifier for the routing decision.
  • Use it for: Debugging, audit notes, and understanding which routing policy fired.
  • Do not use it for: Long-term product logic that assumes rule names never change.
  • Stability: Metadata that may evolve during beta.
  • Example: "auto_accept.min_confidence+max_uncertainty"

is_ambiguous

  • Type: boolean
  • Appears in: job-analyze, job-classify
  • Meaning: Indicates whether the overall result should be treated as ambiguous.
  • Use it for: Review routing and UI warnings when the result may have multiple interpretations.
  • Do not use it for: Automatically rejecting a result without considering the full response.
  • Stability: Public beta stable concept.
  • Example: false

domain_is_ambiguous

  • Type: boolean
  • Appears in: job-analyze, job-classify
  • Meaning: Indicates ambiguity about whether the input fits the supported domain.
  • Use it for: Routing inputs to review when the domain fit is uncertain.
  • Do not use it for: Assuming the role is outside scope without checking confidence, domain confidence, and result evidence.
  • Stability: Public beta stable concept.
  • Example: false

Job and Occupation Analysis Fields

Section titled “Job and Occupation Analysis Fields”

job_signals

  • Type: array of strings
  • Appears in: job-analyze, job-classify
  • Meaning: Skill, tool, task, or domain signals detected from the input.
  • Use it for: Showing reviewers what evidence the analysis used and helping users improve weak job descriptions.
  • Do not use it for: Treating the list as an exhaustive skill inventory.
  • Stability: Public beta stable concept; extraction details may evolve.
  • Example: ["Structured Query Language (SQL)", "dashboards", "reporting"]

results[]

  • Type: array of objects
  • Appears in: job-analyze
  • Meaning: Ranked occupation candidates for the input job text.
  • Use it for: Comparing plausible occupation matches, showing alternatives, and routing uncertain cases to review.
  • Do not use it for: Assuming every possible occupation candidate is returned.
  • Stability: Public beta stable concept; additive fields may appear in result objects.
  • Example: an array containing a Business Intelligence Analysts candidate.

results[].onet_code

  • Type: string
  • Appears in: job-analyze ranked results
  • Meaning: O*NET occupation code for a ranked candidate.
  • Use it for: Normalization, downstream enrichment, storage, comparison, and linking to occupation profiles.
  • Do not use it for: Replacing review when confidence is low or ambiguity is high.
  • Stability: Public beta stable concept.
  • Example: "15-2051.01"

results[].title

  • Type: string
  • Appears in: job-analyze ranked results
  • Meaning: Occupation title for the ranked candidate.
  • Use it for: Display labels and reviewer context.
  • Do not use it for: A stable primary key; use onet_code for normalization.
  • Stability: Public beta stable concept; display wording follows current occupation data.
  • Example: "Business Intelligence Analysts"

results[].confidence

  • Type: number
  • Appears in: job-analyze ranked results
  • Meaning: Per-result confidence within the returned ranked set.
  • Use it for: Comparing candidates and deciding whether a candidate is strong enough to display or review.
  • Do not use it for: Comparing across unrelated requests as if it were a calibrated probability.
  • Stability: Public beta stable concept; numeric calibration may evolve.
  • Example: 0.88

results[].matching_skills

  • Type: array of strings
  • Appears in: job-analyze ranked results
  • Meaning: Skills or capabilities from the input or context that support the candidate match.
  • Use it for: Reviewer evidence, client-facing explanations, and role-intake improvement.
  • Do not use it for: A complete canonical skill profile for the occupation.
  • Stability: Public beta stable concept; extraction and normalization may evolve.
  • Example: ["Structured Query Language (SQL)", "Microsoft Power BI", "Tableau"]

results[].quality_score

  • Type: number
  • Appears in: job-analyze ranked results
  • Meaning: Aggregate quality signal for the candidate result.
  • Use it for: Assessing whether the match has enough supporting evidence to be useful.
  • Do not use it for: Certifying that a match is correct without considering other response fields.
  • Stability: Beta field; numeric calibration and supporting components may evolve.
  • Example: 0.81

results[].domain_grounding

  • Type: string
  • Appears in: job-analyze ranked results
  • Meaning: Categorical support level for the candidate within the supported domain.
  • Use it for: Identifying whether the candidate is strongly grounded or should be treated cautiously.
  • Do not use it for: A standalone acceptance or rejection decision.
  • Stability: Public beta stable concept; labels may evolve additively.
  • Example: "HIGH"

results[].explanation.why_match

  • Type: string
  • Appears in: job-analyze ranked results
  • Meaning: Plain-English explanation of why the candidate occupation matches the input.
  • Use it for: Reviewer context, user-facing explanation, and client-facing role intelligence.
  • Do not use it for: Machine parsing or strict policy branching.
  • Stability: Stable concept, but wording may change during beta.
  • Example: "This role matches because it strongly aligns with core skills in SQL, Power BI and reporting."

How to Apply the Response in a Product

Section titled “How to Apply the Response in a Product”

Use the response as a set of signals, not as a single answer.

  • Display the top result when confidence is high, uncertainty is low, ambiguity is false, and your product policy allows automatic display.
  • Route the result to review when confidence is lower, uncertainty is higher, decision.decision is REVIEW or AMBIGUOUS, or the response flags ambiguity.
  • Use O*NET codes for normalization, storage, comparison, and downstream enrichment.
  • Use matching skills and explanations as reviewer-facing or user-facing evidence.
  • Use decision labels as workflow hints, then apply your own risk, compliance, and human-review policy.
  • Avoid treating any score as final truth.
  • Ignore unknown additive fields during beta.
  • Do not depend on debug-only fields for production workflows.

Stability During Beta

Section titled “Stability During Beta”

AvelinLabs is currently in beta / early access.

Core response concepts are intended to remain stable: job inputs, occupation outputs, ranked matches, confidence, uncertainty, skill evidence, explanations, and market context.

During beta:

  • Optional fields may be absent.
  • Additive fields may appear.
  • Clients should ignore unknown fields.
  • Clients should not depend on debug-only fields.
  • Numeric calibration may evolve.
  • Explanation wording may change.
  • Examples are illustrative and may evolve with the beta.

For endpoint-specific response shape details, see the Job Analyze API reference and Output Interpretation.