Jobs and application references
Reuse saved roles and connect reports to your own application IDs.
Use this workflow when your ATS already has an application ID and the hiring team maintains job descriptions in ProBB AI. You need job-descriptions:read, analyses:write, and reports:read; add interviews:read to find interview attempts by the same reference.
Discover and select the job
Request GET /api/v1/job-descriptions?status=ACTIVE&limit=25 with job-descriptions:read. Search titles/companies with search; follow nextCursor without changing filters. Fetch /api/v1/job-descriptions/{id} for the full text and content revision. Archived jobs remain discoverable with status=ARCHIVED but cannot admit new work.
Prepare a resume using the selected job and revision:
{
"fileName": "resume.pdf",
"fileSize": 1024,
"mimeType": "application/pdf",
"externalReference": { "source": "my-ats", "id": "application-42" },
"jobDescription": { "kind": "existing", "id": "JOB_ID", "expectedRevision": "REVISION" }
}Use the actual byte length of your file. source is a lowercase slug of up to 64 characters; id is a case-sensitive identifier of up to 128 characters. The pair identifies one report in your workspace. A second preparation using that pair with a different request key returns EXTERNAL_REFERENCE_CONFLICT. Retry the original body and idempotency key to recover its report. A changed job revision returns JD_REVISION_CHANGED; read the job and deliberately accept its changes before retrying with a new identity.
Filter reports or interviews with both externalReferenceSource and externalReferenceId. Add include=reference when reading a single report to preserve compatibility with the default summary. References are not credentials and are excluded from webhook payloads. Use an application/submission ID rather than an email address.
Example discovery request
curl --fail-with-body --get "$PROBB_URL/api/v1/job-descriptions" \
-H "Authorization: Bearer $PROBB_API_KEY" \
--data-urlencode 'status=ACTIVE' --data-urlencode 'search=Backend' \
--data-urlencode 'limit=25'Read the selected job using Get a job description. Copy the actual returned revision, not the placeholder in the preparation example.
Find the application later
curl --fail-with-body --get "$PROBB_URL/api/v1/reports" \
-H "Authorization: Bearer $PROBB_API_KEY" \
--data-urlencode 'externalReferenceSource=my-ats' \
--data-urlencode 'externalReferenceId=application-42' \
--data-urlencode 'include=reference'Both reference filters must be supplied together. Keep the reference stable for retries; use a new reference for a new application. Once preparation succeeds, continue with the storage upload and quote in the quickstart.