Skip to main content

CareerOneStop job-signal ingestion — setup

The Business Development Pipeline ingests skilled-nursing job postings (MDS Coordinator, PDPM/RAC, chart reviewer, etc.) as buying signals from the CareerOneStop Web API (U.S. DOL / National Labor Exchange). It's free but requires a registered API token + User ID, and manual approval by email. Until both are set, "Refresh pipeline" recomputes scores but ingests zero signals.

Adapter: src/server/integrations/jobs/careeronestop.ts · CLI mirror: scripts/ingest-job-signals.mjs.

Status (2026-06-17): APPROVED. Credentials received by email. New enrollment, so the granted Jobs API is /v2/jobsearch (CAREERONESTOP_JOBS_API_VERSION="v2"). License expires 2029-06-17 — renew before then (Type of Request: Renewal + your User ID) or all Web API services are discontinued. The User ID + token live in .env.local only (see §2); they are not stored in git.

1. Register for credentials (one-time, ~a few business days)​

  1. Go to https://www.careeronestop.org/Developers/WebAPI/web-api.aspx → "Data Requests" / "Request data access".

  2. Open the Web API Registration form: https://www.careeronestop.org/Developers/WebAPI/registration.aspx

  3. Type of Request: New Request. (Use "Renewal" + your User ID only if you already have one — the license expires 36 months after issue.)

  4. Fill in all required (*) fields: Organization Name, Organization URL, First/Last Name, Address, City, State, Zip, Phone, Email (this is where the credentials are sent).

  5. In "Where and how will data be used or displayed?", state the use plainly, e.g.:

    Internal business-development tool that ingests skilled-nursing job-posting existence as market signals; we store only that a posting exists (employer, title, location, posting date, source URL) and display source attribution; no applicant/candidate data is collected.

    The license restricts use to exactly what you write here — keep it accurate.

  6. Accept the DEED CareerOneStop Data Sharing and Use/Display Click License checkbox.

  7. Accept the CareerOneStop Terms & Conditions checkbox.

  8. Submit. Approval is manual — submitting does not grant access. You wait for an email.

  9. Jobs API (critical, post-Aug-2024): Jobs/job-search data now comes from the National Labor Exchange (NLX). New accounts must also request Jobs API access via the NLX data request form (linked from the Technical Information page) or email webservices@careeronestop.org. The legacy /v1/jobsearch path is only for accounts enrolled before 2024-08-27; new enrollees receive /v2/jobsearch (identical fields + auth). Confirm which version you're granted.

  10. When approved, the email contains two values:

    • API Token → set as CAREERONESTOP_API_KEY (the Authorization: Bearer <token> value).
    • User ID → set as CAREERONESTOP_USER_ID (the first path segment of every request; not secret).

2. Configure the app​

In .env.local (gitignored; never commit real keys):

CAREERONESTOP_API_KEY="<API Token from the email>"
CAREERONESTOP_USER_ID="<User ID from the email>"
CAREERONESTOP_JOBS_API_VERSION="v2"   # use "v1" only if your account predates 2024-08-27

Restart the dev server (or redeploy) so the new env is loaded.

3. Verify, then ingest​

  • Smoke-test the credentials with one call (replace {...}): 
    curl -H "Authorization: Bearer {API_TOKEN}" \
      "https://api.careeronestop.org/v2/jobsearch/{USER_ID}/MDS%20Coordinator/NY/200/0/0/0/50/30"
    A JSON body with a Jobs array = working. 401/403 = token/User-ID or Jobs-API access issue.
  • Dry run (no writes): node scripts/ingest-job-signals.mjs --live
  • Ingest (writes via the cron route; app must be running): node scripts/ingest-job-signals.mjs --live --commit --url http://localhost:3005
  • Or just click "Refresh pipeline" in the UI — once the keys are set it pulls live postings and recomputes scores. The daily cron (/api/cron/job-signals) does the same automatically.

4. Compliance notes (already implemented / required)​

  • Display the CareerOneStop logo on every page that surfaces its Web API data/tools — a hard license term in the approval email. The email provides the logo; add the asset (e.g. public/brand/careeronestop-logo.png) and render it on the Signal Inbox / any view showing CareerOneStop-sourced postings. Not yet implemented — required before that data ships in the UI.
  • Public / free / no-login term — REVIEW BEFORE LAUNCH. The license states Web API services launched "on your site" must be "available to the public, at no cost and with no log-in requirements." Nightingale is a login-gated internal admin tool, so confirm with CareerOneStop (webservices@careeronestop.org) that internal-only consumption of job-signal existence (not a public-facing job-search tool) satisfies this, or scope any CareerOneStop-powered view accordingly. Flag for owner/counsel sign-off.
  • Store existence only — employer, title, location, posting date, source URL. No applicant PII. (The API doesn't return candidate data; we don't persist the description snippet.)
  • Attribution is mandatory wherever the data appears — the Signal Inbox shows: "Job-posting data via NLX, courtesy of DOLETA and DEED." Keep it if you re-surface signals elsewhere.
  • Do not persist geocodes (Bing Maps terms) — storing the textual "City, ST" is fine.
  • Renew the license before the 36-month expiry; notify webservices@careeronestop.org if your org details change.
  • Limits: no published call-rate cap; per request pageSize ≤ 250, startRecord ≤ 500. The adapter fires 5 sequential keyword queries (polite) and degrades to "fewer signals" on any error.