Actions

The three writes on the v1 surface. All of them require the candidate’s job to be inside the key’s workspace and claims (404 V1_RESOURCE_NOT_FOUND otherwise).

Move a candidate to another stage

PATCH /api/v1/applications/:applicationId/stage

curl -X PATCH https://api.reordinal.com/api/v1/applications/app_123/stage \
  -H "X-API-Key: $REORDINAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "stage": "stage_interview" }'

• stage (alias stageId): required. The target stage’s public ID, from the job’s stages (see Get a job).

Returns the updated stage info under data.

Tag a candidate

PATCH /api/v1/applications/:applicationId/tags

Two body forms:

Add/remove (merge), the convenient form; merges against current tags:

{ "add": ["strong-system-design"], "remove": ["maybe"], "color": "#6366f1" }

• add: tag names to add; newly created tags get color (or a default).
• remove: tag names to remove, case-insensitive.

Replace sets the full tag list; each tag needs a name and hex color:

{
  "tags": [{ "name": "strong-system-design", "color": "#6366f1" }],
  "addToJobTags": [{ "name": "strong-system-design", "color": "#6366f1" }]
}

• addToJobTags: optional; also register these tags at the job level.

Returns { "application": { "id", "jobId", "tags": [...] } }.

Rerun ATS scoring

POST /api/v1/applications/:applicationId/ats/rerun

Re-scores the candidate against the job’s current description and criteria. Use it after the job changed.

{ "status": "success", "data": { "message": "ATS re-run triggered" } }

Scoring is asynchronous; poll GET /api/v1/applications/:id/ats for the new result.

Comment on a candidate

POST /api/v1/applications/:applicationId/comments

Adds a note to the candidate’s comment thread, visible to every collaborator on the job in the dashboard. This is the plugin’s flagship write: Claude’s assessment becomes a durable, team-visible note.

curl -X POST https://api.reordinal.com/api/v1/applications/app_123/comments \
  -H "X-API-Key: $REORDINAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Strong on distributed systems; thin on ownership.\nProbe incident response in the interview." }'

• text: required, plain text, 1 to 10,000 characters. Newlines become paragraphs, so the note renders naturally next to human comments.

Returns 201 with the created comment under data.comment. The comment is attributed to the key’s workspace owner and stored with source: "claude_plugin" so it stays distinguishable from human notes. Collaborators receive their normal comment notifications.

To read the thread first, see list comments.