@extends('layouts.app')

@section('title', 'healthcareers API: send your jobs | healthcareers.app')
@section('description', 'How a Health System plan organization sends its jobs to healthcareers.app with the healthcareers API: keys, endpoints, job fields, states and errors.')
@section('robots', 'noindex, follow')

@php $base = url('/api/v1'); $rate = (int) config('sync.api_rate_per_minute', 600); @endphp

@section('content')
    <article class="prose">
        <h1>The healthcareers API</h1>
        <p>For organizations on the Job Sync <strong>Health System plan</strong>. Your own system sends your jobs to healthcareers.app as they open, change and close. Each job goes up as your organization's own post, in your words: we fill in details like the category and shift, but we don't rewrite your description. It's the same pipeline as our applicant tracking system connections: jobs with a problem wait for a fix instead of going up wrong, and if your plan has a limit on live jobs, the rest wait for a free slot.</p>
        <p>Everything is JSON over HTTPS at <code>{{ $base }}</code>.</p>

        <h2 id="auth">Authentication</h2>
        <p>Owners and admins of a verified organization create keys under <strong>My organization → Job Sync → API keys</strong>. A key looks like <code>hc_live_</code> followed by 40 letters and digits. It's shown once, when you create it; we keep only a scrambled copy. Send it with every request:</p>
        <pre><code>Authorization: Bearer hc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</code></pre>
        <p>Use one key per system, so you can revoke one without stopping the others. A revoked key stops working straight away. Keys also stop working while your organization isn't verified, isn't on the Health System plan, or its API connection is paused.</p>

        <h2 id="rate">Rate limit</h2>
        <p>{{ $rate }} requests a minute per key. Every answer has <code>X-RateLimit-Limit</code> and <code>X-RateLimit-Remaining</code> headers. Over the limit you get <code>429</code> with <code>Retry-After</code> (seconds to wait). Sending a whole list of jobs one by one at the start is fine: just wait when you get a 429.</p>

        <h2 id="job">A job</h2>
        <p>Only <code>external_id</code>, <code>title</code>, <code>description</code> and <code>url</code> are required. Send everything you have; the more you send, the less we have to guess.</p>
        <div class="tablewrap"><table>
            <thead><tr><th>Field</th><th>What it is</th></tr></thead>
            <tbody>
                <tr><td><code>external_id</code></td><td>Your own ID for the job (a requisition number, for example). 1 to 180 letters, digits, dots, dashes, underscores or tildes. It must stay the same for the life of the job.</td></tr>
                <tr><td><code>title</code></td><td>The job title, 2 to 250 characters.</td></tr>
                <tr><td><code>description</code></td><td>The full description, HTML or plain text, 30 to 30,000 characters. HTML is turned into plain text with its lists and paragraphs kept.</td></tr>
                <tr><td><code>url</code></td><td>The job's page on your site, <code>https://</code>.</td></tr>
                <tr><td><code>apply_url</code></td><td>Where candidates apply, if not the same page. <code>https://</code>.</td></tr>
                <tr><td><code>department</code></td><td>Optional, up to 160 characters.</td></tr>
                <tr><td><code>location</code></td><td>An object with any of <code>city</code>, <code>region</code> (state or province, like <code>VA</code>), <code>country</code> (like <code>US</code>), <code>remote</code> (true or false), <code>text</code> (free text, like <code>"Fairfax, VA"</code>).</td></tr>
                <tr><td><code>employment_type</code></td><td>Like <code>Full-time</code>, <code>Part-time</code>, <code>PRN</code>, <code>Contract</code>.</td></tr>
                <tr><td><code>pay</code></td><td>An object with any of <code>min</code>, <code>max</code> (numbers), <code>unit</code> (<code>hour</code>, <code>year</code>...), <code>currency</code> (3 letters, like <code>USD</code>), <code>text</code> (free text, like <code>"$38 - $52 an hour"</code>).</td></tr>
                <tr><td><code>date_posted</code>, <code>valid_through</code></td><td>Optional dates, like <code>2026-10-01</code> or <code>2026-10-01T09:00:00Z</code>.</td></tr>
            </tbody>
        </table></div>

        <h2 id="put">Create or update a job</h2>
        <p><strong>PUT /api/v1/jobs/{external_id}</strong>. The simplest way to keep a job in step: send it whenever it changes (or every time, it doesn't matter). If nothing changed, nothing happens and you get the same answer.</p>
        <p><strong>How long a job stays up.</strong> A job stays up until you close it with DELETE, or until 90 days after you last sent it. To keep a job up longer, send it again with PUT at least every 90 days. Sending an unchanged job is free: it isn't prepared or reviewed again, it just counts as sent.</p>
        <pre><code>curl -X PUT {{ $base }}/jobs/REQ-1042 \
  -H "Authorization: Bearer $HC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Registered Nurse - Med/Surg Nights",
    "description": "&lt;p&gt;Join our 32-bed Medical/Surgical unit...&lt;/p&gt;",
    "url": "https://careers.example-health.org/jobs/REQ-1042",
    "department": "Nursing",
    "location": {"city": "Fairfax", "region": "VA", "country": "US", "remote": false},
    "employment_type": "Full-time",
    "pay": {"min": 38, "max": 52, "unit": "hour", "currency": "USD"}
  }'</code></pre>
        <p><code>201</code> when the job is new, <code>200</code> when it was already there:</p>
        <pre><code>{
  "job": {
    "external_id": "REQ-1042",
    "title": "Registered Nurse - Med/Surg Nights",
    "description": "&lt;p&gt;Join our 32-bed Medical/Surgical unit...&lt;/p&gt;",
    "url": "https://careers.example-health.org/jobs/REQ-1042",
    "apply_url": null,
    "department": "Nursing",
    "location": {"city": "Fairfax", "region": "VA", "country": "US"},
    "employment_type": "Full-time",
    "pay": {"min": 38, "max": 52, "unit": "hour", "currency": "USD"},
    "date_posted": null,
    "valid_through": null,
    "status": {
      "state": "pending",
      "label": "Being prepared",
      "reason": null,
      "post_id": null,
      "url": null
    },
    "received_at": "2026-10-03T14:05:11+00:00"
  }
}</code></pre>
        <p>A new job is usually live within a minute or two. Check it with GET (below): <code>status.url</code> is the post's address on healthcareers.app once it's live.</p>

        <h2 id="post">Create a job (POST)</h2>
        <p><strong>POST /api/v1/jobs</strong>, with <code>external_id</code> in the body. If you already sent a job with that <code>external_id</code>, it's updated, exactly as with PUT, and the answer says so in <code>note</code>. So retrying a POST is safe.</p>
        <pre><code>curl -X POST {{ $base }}/jobs \
  -H "Authorization: Bearer $HC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "REQ-1043", "title": "Respiratory Therapist", "description": "...", "url": "https://careers.example-health.org/jobs/REQ-1043"}'</code></pre>
        <pre><code>{
  "job": { "external_id": "REQ-1043", ..., "status": {"state": "pending", "label": "Being prepared", ...} },
  "note": "A job with this external_id already existed, so it was updated (as with PUT)."
}</code></pre>

        <h2 id="delete">Close a job</h2>
        <p><strong>DELETE /api/v1/jobs/{external_id}</strong>. The post comes down straight away. Closing a closed job again is fine. To reopen it, send it again with PUT.</p>
        <pre><code>curl -X DELETE {{ $base }}/jobs/REQ-1042 -H "Authorization: Bearer $HC_API_KEY"</code></pre>
        <pre><code>{
  "job": { "external_id": "REQ-1042", ..., "status": {"state": "closed", "label": "Closed", "reason": "Closed by the employer (API)", "post_id": 5120, "url": null} }
}</code></pre>
        <p>An <code>external_id</code> we've never had gets <code>404</code>.</p>

        <h2 id="get">See your jobs</h2>
        <p><strong>GET /api/v1/jobs/{external_id}</strong> for one job, with its description. <strong>GET /api/v1/jobs</strong> for all of them, newest first, 50 a page (<code>?per_page=</code> up to 100, <code>?page=2</code>...), without descriptions. Filter by state with <code>?state=attn</code>, for example.</p>
        <pre><code>curl "{{ $base }}/jobs?state=attn" -H "Authorization: Bearer $HC_API_KEY"</code></pre>
        <pre><code>{
  "data": [
    {
      "external_id": "REQ-0977",
      "title": "Medical Assistant",
      ...,
      "status": {"state": "attn", "label": "Needs a fix", "reason": "No pay given: add a pay range", "post_id": null, "url": null},
      "received_at": "2026-10-01T09:12:40+00:00"
    }
  ],
  "meta": {"page": 1, "per_page": 50, "total": 1, "last_page": 1},
  "links": {"next": null, "prev": null}
}</code></pre>

        <h2 id="states">What the states mean</h2>
        <div class="tablewrap"><table>
            <thead><tr><th>state</th><th>label</th><th>What it means</th></tr></thead>
            <tbody>
                <tr><td><code>pending</code></td><td>Being prepared</td><td>Received. We're filling in its details; it's usually live within a minute or two.</td></tr>
                <tr><td><code>live</code></td><td>Live</td><td>Up on healthcareers.app as your post. <code>status.url</code> is its address.</td></tr>
                <tr><td><code>held</code></td><td>Waiting for review</td><td>Something in it needs a person to look (a pay or equal-opportunity question, for example). We review within one business day.</td></tr>
                <tr><td><code>attn</code></td><td>Needs a fix</td><td>It can't go up as it is. <code>status.reason</code> says why; fix it in your system and send it again.</td></tr>
                <tr><td><code>over</code></td><td>Waiting for a free slot</td><td>All the live-job slots in your plan are in use. It goes up by itself when one frees up (when you close a job).</td></tr>
                <tr><td><code>linked</code></td><td>Same as a job already on the board</td><td>Someone on your team already posted this job by hand. We keep that post and don't double it.</td></tr>
                <tr><td><code>skipped</code></td><td>Not posted</td><td>It doesn't read as a healthcare job opening (or isn't in English). <code>status.reason</code> says why.</td></tr>
                <tr><td><code>closed</code></td><td>Closed</td><td>You closed it, you hadn't sent it for 90 days, or the connection was disconnected.</td></tr>
            </tbody>
        </table></div>

        <h2 id="errors">Errors</h2>
        <p>Every error has the same shape, with a <code>code</code> for your code and a <code>message</code> for people:</p>
        <pre><code>{"error": {"code": "invalid_key", "message": "That API key isn't valid. Check it was copied in full, or create a new one."}}</code></pre>
        <div class="tablewrap"><table>
            <thead><tr><th>HTTP</th><th>code</th><th>What to do</th></tr></thead>
            <tbody>
                <tr><td>400</td><td><code>bad_json</code></td><td>The body isn't a JSON object. Check the quoting.</td></tr>
                <tr><td>401</td><td><code>missing_key</code>, <code>invalid_key</code>, <code>revoked_key</code></td><td>Send a valid key in the <code>Authorization</code> header.</td></tr>
                <tr><td>403</td><td><code>not_allowed</code>, <code>plan</code>, <code>no_connection</code>, <code>paused</code></td><td>The organization isn't verified, isn't on the Health System plan, its API connection was removed, or it's paused. The message says which. Contact us.</td></tr>
                <tr><td>404</td><td><code>not_found</code></td><td>No job with that <code>external_id</code>, or no such address.</td></tr>
                <tr><td>409</td><td><code>too_many_jobs</code></td><td>The connection already has more open jobs than it can keep: 500, or 5 for each job slot in your plan if that's more. Closed and skipped jobs don't count. Close (DELETE) filled jobs, then send new ones again.</td></tr>
                <tr><td>422</td><td><code>invalid</code></td><td>Some fields need fixing. <code>fields</code> lists each one with its message.</td></tr>
                <tr><td>429</td><td><code>rate_limited</code></td><td>Wait <code>Retry-After</code> seconds and try again.</td></tr>
                <tr><td>5xx</td><td></td><td>Our side. Try again in a minute; PUT and DELETE are safe to repeat.</td></tr>
            </tbody>
        </table></div>
        <pre><code>{
  "error": {
    "code": "invalid",
    "message": "url must be a full https:// address of the job's page, up to 990 characters.",
    "fields": {
      "url": ["url must be a full https:// address of the job's page, up to 990 characters."],
      "pay.currency": ["pay.currency must be a 3-letter currency code, like USD."]
    }
  }
}</code></pre>

        <h2 id="help">Help</h2>
        <p>Questions, or need the Health System plan? <a href="{{ route('contact') }}">Contact us</a>.</p>
    </article>
@endsection