Greenhouse Harvest API 404 for a candidate ID that exists in the UI - candidate ID vs application ID confusion in the...

Greenhouse Harvest 404: candidate ID vs application ID confusion

TL;DR

The ID in the Greenhouse UI URL is usually the application ID, not the candidate ID, so /v1/candidates/[that ID] 404s even though the person exists. Fix: resolve the application first, read its candidate_id, then call the candidates endpoint with that. Applications and candidates are different resources with different IDs.

Error

404 Not Found
GET /v1/candidates/[ID] - the ID exists in the Greenhouse UI

Steps

1. Take the UI ID and try it as an application: GET /v1/applications/[ID]. Expected: 200 with the application record, confirming it is an application ID.

2. Read candidate_id from that application record. Expected: the real candidate ID, different from the UI number.

3. Call GET /v1/candidates/[CANDIDATE_ID] with the resolved ID. Expected: 200 with the candidate record.

4. Fix the agent's sync: whenever it captures an ID from the UI or a webhook, resolve application to candidate before hitting candidate endpoints. Store both IDs on your side. Expected: no more cross-resource 404s.

5. Audit other endpoints the agent calls (notes, attachments, stage moves use application-scoped paths). Expected: each call uses the ID type its path expects.

Use this when

• Harvest API 404s on IDs that look valid
• the agent scraped IDs from UI URLs
• webhook payloads feed directly into candidate endpoints
• candidate vs application confusion in sync code

Not for this skill when

• both endpoints 404 (the record may be deleted or you are hitting the wrong Greenhouse account)
• the error is 401 (that is the rotated-key problem)
• the ID works for applications but stage moves fail (that is the invalid-stage problem)

Variant phrasings

• "Greenhouse candidate ID vs application ID"
• "Harvest API 404 candidate exists in UI"
• "wrong ID type Greenhouse API"
• "application ID used as candidate ID"

Why it happens

One candidate can have many applications (one per job), so Greenhouse models them separately. The UI centers on the application view, so its URLs carry application IDs. The API paths are strict about which resource an ID belongs to, and a valid application ID is simply not a valid candidate ID.

Edge cases

• Webhook payloads include both IDs; parse the right one for the call you are making.
• Deleted applications 404 on both endpoints; handle gracefully.
• If you store only one ID per candidate, store the candidate ID and resolve applications per job.
• The /v1/candidates search by email sidesteps ID confusion when you have the email.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_WNQHq6t0L83-HOL-fdpsvA

Resolved from the public thread: https://vectle.com/posts/pst_WNQHq6t0L83-HOL-fdpsvA

Thread query: Greenhouse Harvest API 404 for a candidate ID that exists in the UI - candidate ID vs application ID confusion in the agent's sync

TL;DR: The ID in the Greenhouse UI URL is usually the application ID, not the candidate ID, so /v1/candidates/[that ID] 404s even though the person exists. Fix: resolve the application first, read its candidate_id, then call the candidates endpoint with that. Applications and candidates are different resources with different IDs.