Create an application

Two endpoints let a system you already run, such as an applicant tracking system, a sourcing tool or a careers site, push a candidate into a Tahoe job. POST /uploads reserves a place for a resume file, and POST /applications creates the application. Both need applications:write, an API key that belongs to a Tahoe user, and the expensive rate-limit tier. A Sign in with Tahoe token gets 403 write_requires_api_key, unless writes for connected apps are switched on. Both accept an optional Idempotency-Key header.

To move, reject or annotate an application afterwards, see Change an application.

The order of the calls#

1. If the candidate has a resume, call POST /uploads and PUT the file to the URL it returns.
2. Call POST /applications with the job, the candidate and, if you uploaded a file, its upload_id as resume_upload_id.

POST/uploadsapplications:write

Reserves a short-lived URL for uploading one resume file straight to storage. Request bodies on the API are capped at 256 KB, so a resume can never travel inside POST /applications. Returns 201.

curl -X POST https://tahoe.workonward.com/api/partner/v1/uploads \
  -H "Authorization: Bearer $TAHOE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content_type": "application/pdf",
    "size_bytes": 184320,
    "filename": "ada-lovelace-cv.pdf"
  }'

{
  "object": "upload",
  "upload_id": "upl_3f9c2a7e1b5d4c8f9a0e6b7d2c1a8f54",
  "content_type": "application/pdf",
  "size_bytes": 184320,
  "max_bytes": 5242880,
  "upload": {
    "method": "PUT",
    "url": "https://storage.example.com/partner-uploads/...",
    "headers": {
      "Content-Type": "application/pdf",
      "Content-Length": "184320"
    },
    "expires_at": "2026-10-08T12:15:00.000Z"
  },
  "expires_at": "2026-10-08T13:00:00.000Z"
}

Send a PUT to upload.url with the file bytes as the body and exactly the headers in upload.headers. The type and the length are part of the signature, so storage refuses a file that differs from what you declared.

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @ada-lovelace-cv.pdf

• The URL works for 15 minutes (upload.expires_at). The upload_id can be named in POST /applications for one hour (expires_at), and only once.
• The upload URL points at storage, not at the Tahoe API. Do not send your Authorization header with the PUT.
• A workspace may hold at most 500 uploads that were never attached and have not expired. Past that, the call returns 429 too_many_pending_uploads with Retry-After: 600.
• With an Idempotency-Key, a repeated call returns the first response, including the same URL, with Idempotent-Replayed: true. Without one, every call reserves a new upload. It emits no event.

POST/applicationsapplications:write

Adds a candidate to a job. Returns 201 with the application when one was created, and 200 with the existing application when this candidate is already on the job.

curl -X POST https://tahoe.workonward.com/api/partner/v1/applications \
  -H "Authorization: Bearer $TAHOE_API_KEY" \
  -H "Idempotency-Key: push-cand-991-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "job_id": "job_7Kd2mXq4Rp8v",
    "candidate": {
      "first_name": "Ada",
      "last_name": "Lovelace",
      "email": "[email protected]",
      "phone": "+1 415 555 0142",
      "linkedin_url": "https://www.linkedin.com/in/ada"
    },
    "resume_upload_id": "upl_3f9c2a7e1b5d4c8f9a0e6b7d2c1a8f54",
    "source": { "system": "acme_ats", "external_id": "cand-991" },
    "answers": [
      { "field_id": "field_1696_1", "value": "I like data pipelines." },
      { "field_id": "field_1696_2", "value": ["Python", "SQL"] }
    ],
    "stage_id": "stg_3Rp8vKd2mXq4"
  }'

{
  "object": "application",
  "id": "app_6Qm2xKd4Rp8v",
  "workspace_id": "wsp_4Kd8sPm2Qx7L",
  "job_id": "job_7Kd2mXq4Rp8v",
  "applicant_id": "apl_5Nx3jLm7Qd2s",
  "stage_id": "stg_3Rp8vKd2mXq4",
  "status": "new",
  "source": "partner_api:acme_ats",
  "applied_at": "2026-10-08T12:00:00.000Z",
  "updated_at": "2026-10-08T12:00:00.000Z",
  "parse_status": "pending",
  "has_resume": true,
  "voice_screening_opted_out": false,
  "resume_access": { "state": "open", "...": "..." },
  "restricted": ["rejection_reason"],
  "restricted_reason": { "rejection_reason": "scope_required:applications:internal:read" },
  "links": { "self": "/api/partner/v1/applications/app_6Qm2xKd4Rp8v" }
}

The response is the object GET /applications/{application_handle} returns to a key without the sensitive scopes. It does not repeat the name, email, phone or LinkedIn address you sent. Read them back with the applicant reads, if the key has the contact scopes.

Sending the same candidate twice is safe#

An existing application is found in this order, and it is returned with 200:

1. If source.external_id is given, and an application on this job was already created with the same source.system and external_id.
2. If the candidate’s email (not case sensitive) is already an applicant on this job, whatever the source of that application.

A repeat is answered before the request is validated, so a retry still succeeds after the job’s form has changed. A repeat changes nothing: the candidate’s details are not updated, and a resume named in the repeat is not used. These two keys protect “the ATS re-sent the whole batch”. The Idempotency-Key header protects one HTTP retry.

What this call does not do#

A system pushing a person in cannot give that person’s agreements for them, so the call records none, and has no field that could.

• No consent is recorded. There is no voice-screening consent, no user-agreement acceptance and no equal-opportunity answer. A body that contains such a field is refused as an unknown field. The application’s phone number for the screening call is left empty, so an application made this way cannot be matched to an inbound pre-screening call. The candidate can apply on the job’s public page to take part.
• Nothing is sent to the candidate. No confirmation email, no status link, no text message and no call. The candidate does not know the application exists unless your system tells them. The job owner gets no email either.
• Existing details are kept. If the candidate already exists in the workspace, the application is attached to that person, the details the person already has are kept and only blanks are filled from your request. The public apply form works the other way round, because there the person is the authority on their own details.
• Only a published job takes an application. Tahoe has no recruiter-side way to add a candidate to a draft or closed job, so this call does not add one.
• Erased and unsubscribed people are refused. The check reads the suppression list that the erasure feed publishes. If the list cannot be read, nothing is created and you get a retryable error.

{
  "detail": {
    "code": "applicant_suppressed",
    "type": "conflict",
    "message": "This person has asked Tahoe to stop processing their data. No application was created, and you should stop sending this person.",
    "param": null
  }
}

What recruiters see#

The application appears in the job’s pipeline in the stage you chose (the first stage by default), with status new and source partner_api:<system>. Tahoe adds the partner_api: prefix, so you send only acme_ats. The activity log has an “application received” entry attributed to the person who created the key. The resume is read by the same background worker as board applications, and recruiters read it through Tahoe under the same access rules. The workspace gets an in-app “New application received” notification.

The file is checked again when you create the application: it must exist, be non-empty and be at most 5 MB. It is then copied to the same private location the job board uses. An upload that is never attached expires after one hour.

Events#

Only when an application is created, and never for a 200: application.created with source set to partner_api:<system>, and applicant.created when the candidate did not exist in the workspace before. Both carry identifiers only and an origin.

Errors#