API reference

Record a verdict and notes

Record your team’s verdict on someone a search found (accept, reject, maybe, or null to clear) with reason codes and private notes, e.g. “Ask about work authorization”. The same judgement the candidate panel in the app records. Verdicts, reason codes and notes are private to your workspace: they never appear on the share link, the client portal, a shortlist email or any export. Each call is kept (get_candidate_verdicts reads the latest per person) and lands with review_state pending: Revcenter reviews verdicts to calibrate scoring, so recording one does not move the shortlist; to take someone off, use remove_shortlist_member. reason_codes are keys from list_decline_reasons. Send an Idempotency-Key to make a retry safe: the same key and body return the first verdict. Does not use credits.

Needs scope shortlists:write.

POST

searches

{searchId}

candidates

{candidateId}

verdict

Record a verdict and notes

curl --request POST \
  --url https://api.revcenter.ai/v1/searches/{searchId}/candidates/{candidateId}/verdict \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "verdict": "maybe",
  "reason_codes": [
    "tenure_concern"
  ],
  "notes": "Ask about work authorization: contract via staffing vendor."
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    verdict: 'maybe',
    reason_codes: ['tenure_concern'],
    notes: 'Ask about work authorization: contract via staffing vendor.'
  })
};

fetch('https://api.revcenter.ai/v1/searches/{searchId}/candidates/{candidateId}/verdict', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.revcenter.ai/v1/searches/{searchId}/candidates/{candidateId}/verdict"

payload = {
    "verdict": "maybe",
    "reason_codes": ["tenure_concern"],
    "notes": "Ask about work authorization: contract via staffing vendor."
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "data": {
    "id": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6e",
    "search_id": "0b9e7d6c-5a4f-4e3d-8c2b-1a0f9e8d7c61",
    "candidate_id": "3c2b1a09-8f7e-4d6c-9b5a-4e3d2c1b0a99",
    "verdict": "maybe",
    "reason_codes": [
      "tenure_concern"
    ],
    "notes": "Ask about work authorization: contract via staffing vendor.",
    "review_state": "pending"
  },
  "meta": {
    "request_id": "req_01JABCDEF"
  }
}

{
  "error": {
    "code": "search_not_found",
    "message": "No search with that id in this workspace.",
    "details": null,
    "request_id": "req_01JABCDEF"
  },
  "meta": {
    "request_id": "req_01JABCDEF"
  }
}

{
  "error": {
    "code": "search_not_found",
    "message": "No search with that id in this workspace.",
    "details": null,
    "request_id": "req_01JABCDEF"
  },
  "meta": {
    "request_id": "req_01JABCDEF"
  }
}

{
  "error": {
    "code": "search_not_found",
    "message": "No search with that id in this workspace.",
    "details": null,
    "request_id": "req_01JABCDEF"
  },
  "meta": {
    "request_id": "req_01JABCDEF"
  }
}

{
  "error": {
    "code": "search_not_found",
    "message": "No search with that id in this workspace.",
    "details": null,
    "request_id": "req_01JABCDEF"
  },
  "meta": {
    "request_id": "req_01JABCDEF"
  }
}

{
  "error": {
    "code": "search_not_found",
    "message": "No search with that id in this workspace.",
    "details": null,
    "request_id": "req_01JABCDEF"
  },
  "meta": {
    "request_id": "req_01JABCDEF"
  }
}

{
  "error": {
    "code": "search_not_found",
    "message": "No search with that id in this workspace.",
    "details": null,
    "request_id": "req_01JABCDEF"
  },
  "meta": {
    "request_id": "req_01JABCDEF"
  }
}

{
  "error": {
    "code": "search_not_found",
    "message": "No search with that id in this workspace.",
    "details": null,
    "request_id": "req_01JABCDEF"
  },
  "meta": {
    "request_id": "req_01JABCDEF"
  }
}

{
  "error": {
    "code": "search_not_found",
    "message": "No search with that id in this workspace.",
    "details": null,
    "request_id": "req_01JABCDEF"
  },
  "meta": {
    "request_id": "req_01JABCDEF"
  }
}

{
  "error": {
    "code": "search_not_found",
    "message": "No search with that id in this workspace.",
    "details": null,
    "request_id": "req_01JABCDEF"
  },
  "meta": {
    "request_id": "req_01JABCDEF"
  }
}

Authorizations

Authorization

string

header

required

An API key from Settings → Usage → API (rvc_live_…).

Headers

Idempotency-Key

string

Optional, 8-160 printable characters: a retry with the same key and body records nothing new.

Path Parameters

searchId

string

required

A search id

candidateId

string

required

A candidate id

Body

application/json

verdict

enum<string> | null

required

null clears the verdict.

Available options:

accept,

reject,

maybe,

null

reason_codes

string[]

Keys from list_decline_reasons, e.g. wrong_seniority.

Maximum array length: 30

Maximum string length: 120

notes

string | null

Private notes for your team.

Maximum string length: 4000

Response

data

object

Show child attributes

meta

object

Show child attributes

Record a verdict and notes

curl --request POST \
  --url https://api.revcenter.ai/v1/searches/{searchId}/candidates/{candidateId}/verdict \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "verdict": "maybe",
  "reason_codes": [
    "tenure_concern"
  ],
  "notes": "Ask about work authorization: contract via staffing vendor."
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    verdict: 'maybe',
    reason_codes: ['tenure_concern'],
    notes: 'Ask about work authorization: contract via staffing vendor.'
  })
};

fetch('https://api.revcenter.ai/v1/searches/{searchId}/candidates/{candidateId}/verdict', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.revcenter.ai/v1/searches/{searchId}/candidates/{candidateId}/verdict"

payload = {
    "verdict": "maybe",
    "reason_codes": ["tenure_concern"],
    "notes": "Ask about work authorization: contract via staffing vendor."
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "data": {
    "id": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6e",
    "search_id": "0b9e7d6c-5a4f-4e3d-8c2b-1a0f9e8d7c61",
    "candidate_id": "3c2b1a09-8f7e-4d6c-9b5a-4e3d2c1b0a99",
    "verdict": "maybe",
    "reason_codes": [
      "tenure_concern"
    ],
    "notes": "Ask about work authorization: contract via staffing vendor.",
    "review_state": "pending"
  },
  "meta": {
    "request_id": "req_01JABCDEF"
  }
}

{
  "error": {
    "code": "search_not_found",
    "message": "No search with that id in this workspace.",
    "details": null,
    "request_id": "req_01JABCDEF"
  },
  "meta": {
    "request_id": "req_01JABCDEF"
  }
}

{
  "error": {
    "code": "search_not_found",
    "message": "No search with that id in this workspace.",
    "details": null,
    "request_id": "req_01JABCDEF"
  },
  "meta": {
    "request_id": "req_01JABCDEF"
  }
}

{
  "error": {
    "code": "search_not_found",
    "message": "No search with that id in this workspace.",
    "details": null,
    "request_id": "req_01JABCDEF"
  },
  "meta": {
    "request_id": "req_01JABCDEF"
  }
}

{
  "error": {
    "code": "search_not_found",
    "message": "No search with that id in this workspace.",
    "details": null,
    "request_id": "req_01JABCDEF"
  },
  "meta": {
    "request_id": "req_01JABCDEF"
  }
}

{
  "error": {
    "code": "search_not_found",
    "message": "No search with that id in this workspace.",
    "details": null,
    "request_id": "req_01JABCDEF"
  },
  "meta": {
    "request_id": "req_01JABCDEF"
  }
}

{
  "error": {
    "code": "search_not_found",
    "message": "No search with that id in this workspace.",
    "details": null,
    "request_id": "req_01JABCDEF"
  },
  "meta": {
    "request_id": "req_01JABCDEF"
  }
}

{
  "error": {
    "code": "search_not_found",
    "message": "No search with that id in this workspace.",
    "details": null,
    "request_id": "req_01JABCDEF"
  },
  "meta": {
    "request_id": "req_01JABCDEF"
  }
}

{
  "error": {
    "code": "search_not_found",
    "message": "No search with that id in this workspace.",
    "details": null,
    "request_id": "req_01JABCDEF"
  },
  "meta": {
    "request_id": "req_01JABCDEF"
  }
}

{
  "error": {
    "code": "search_not_found",
    "message": "No search with that id in this workspace.",
    "details": null,
    "request_id": "req_01JABCDEF"
  },
  "meta": {
    "request_id": "req_01JABCDEF"
  }
}

Get started

Concepts

Tools

Guides

Recipes

Use cases

API reference

Record a verdict and notes

Authorizations

Headers

Path Parameters

Body

Response