Workforce Evidence Pack API

The controlled-beta Workforce API packages official occupation and industry evidence into an account-scoped JSON document and standalone HTML buyer report.

The service is live in production as an authenticated controlled beta for the approved U.S./Connecticut snapshot. Before creating a pack, call capabilities and confirm that features.evidence_pack_creation is available for your Runtime API Key and requested country.

Endpoints

• GET /api/v1/workforce/capabilities
• GET /api/v1/workforce/occupations
• GET /api/v1/workforce/occupations/{soc_code}
• POST /api/v1/workforce/evidence-packs
• GET /api/v1/workforce/evidence-packs/{evidence_pack_id}
• GET /api/v1/workforce/evidence-packs/{evidence_pack_id}/report

Every route requires a Runtime API Key:

Authorization: Bearer <runtime-api-key>

The hosted base URL is:

https://api.avelinlabs.com

Confirm the live boundary before building a request:

curl --fail-with-body --silent --show-error \\
  "https://api.avelinlabs.com/api/v1/workforce/capabilities?country_code=US" \\
  -H "Authorization: Bearer $AVELIN_API_KEY" \\
  -H "Accept: application/json"

Canonical identifiers

U.S. occupations use six-digit 2018 Standard Occupational Classification (SOC) codes such as 51-4121. See the official BLS Standard Occupational Classification site.

SOC, O*NET-SOC, and NAICS are different taxonomies:

• SOC classifies occupations;
• ONET-SOC supplies the governed ONET 30.3 occupational reference;
• NAICS classifies establishments and industries.

Avelin does not infer NAICS from SOC and does not attribute QWI industry rows to individual occupations.

Create or reuse a pack

{
  "country_code": "US",
  "region": {
    "type": "state",
    "code": "CT"
  },
  "decision": "workforce_investment",
  "industries": ["311", "334"],
  "occupations": [
    "17-2112",
    "51-1011",
    "51-4041",
    "51-4121",
    "49-9041"
  ],
  "language": "en"
}

The first generated resource returns 201. An identical canonical request with unchanged approved source lineage returns 200, the same evidence_pack_id, and cache_status=reused. Input order does not change the identity.

The service packages approved normalized OEWS and QWI snapshots with governed O*NET reference data. Every source exposes an approved source ID and raw checksum for reproducible review.

Schema 1.1 requests may opt into approved cached O*NET enrichment, attach one caller-supplied relevance hypothesis to each selected occupation, and provide program workshop rules:

{
  "include_onet_enrichment": true,
  "contextual_relevance_hypotheses": [
    {
      "soc_code": "17-2112",
      "statement": "Validate this occupation's relevance with employers in the target service area.",
      "validation_required": true
    }
  ],
  "workshop_rules": {
    "decision_rule": "ADVANCE, HOLD, or REMOVE after the program review is documented.",
    "minimum_validation_requirement": "Complete the program's local validation record for every occupation."
  }
}

Hypotheses and workshop rules are caller/program context, not OEWS, QWI, or O*NET evidence. They affect deterministic pack identity when supplied. The HTML report displays up to five source-ordered tasks and eight source-ordered skills per occupation, plus one concise Decision validation matrix with accessible detail; the JSON keeps the complete structured evidence and validation records.

The HTML labels this section Decision validation matrix. Avelin prepopulates available public and authorized market evidence; employers confirm local hiring needs and operational requirements; training providers confirm capacity, cost and outcomes; and the accountable program reviewer records the final decision.

Interpret the result

• OEWS employment and wage rows are occupation evidence.
• QWI rows are separate industry workforce-flow evidence.
• O*NET tasks and skills are occupational reference evidence.
• buyer_review_ready means the pack is suitable for structured buyer review.
• decision_readiness=not_ready means it is not an investment recommendation.

Human review and local employer validation remain required.

Current availability boundary

The production-live approved example is US / state / CT, in English, using 2018 SOC, O*NET 30.3, reviewed OEWS evidence, and separate Census QWI evidence. The renderer is reusable, but that does not establish data availability for an arbitrary country or region.

Unsupported or unavailable requests fail closed. Important safe error details include unsupported_country, unsupported_geography, unknown_occupation_code, invalid_naics_code, evidence_snapshot_unavailable, and evidence_pack_not_found.

Executable lifecycle

The public examples repository contains Python, PowerShell, and cURL entry points, the canonical Connecticut request, deterministic cache checks, JSON and HTML retrieval, and a static buyer-facing report fixture:

Run the Workforce Evidence Pack example