Send candidate feedback
Releases the feedback to the candidate: with channel: email Probb emails them a personal link from the name of your organization followed by via ProBB AI, with the subject Feedback on your application for the role at your organization and no reply-to address, with channel: link nothing is sent and you share the returned url yourself. The candidate sees only the sections that are on and the items that were not removed, plus the personal note; never a score, ranking, decision, integrity finding or anything a rater wrote. The first release is revision 1. Edit the draft and release again to send an update on the same link (revision 2 and on); releasing after a revoke makes a new link. Releasing is allowed before a hiring decision is recorded: the feedback never mentions a decision. The link works for 90 days after the latest release. If any wording reads like a score, a rejection reason or a teammate's name the call answers candidate_kit_warnings; show a person the warnings that GET on the candidate-kit endpoint returns, and send again with acknowledgeWarnings: true only when they agree. Repeating the call with the same Idempotency-Key returns the first result and sends one email. One feedback sends at most five emails a day; after that the call answers rate_limit_exceeded, and the link can still be shared. Copying the link of live, unchanged feedback with channel: link releases nothing and returns the link (unchanged: true). The key's owner must be a member or admin, the job must be open, and channel: email needs an address on file. Answers candidate_feedback_disabled while an admin has turned candidate feedback off in the organization settings; links already released keep working and can still be revoked. The response carries the link, which is a credential: keep it as private as the candidate's email address.
Required scope: candidate_feedback:write.
Errors
- 400:
invalid_content_type,invalid_idempotency_key,invalid_json,request_body_too_large,unknown_field - 401:
authentication_required,invalid_api_key - 403:
api_access_disabled,candidate_feedback_disabled,insufficient_scope,permission_denied - 404:
candidate_kit_not_found,report_not_found - 409:
candidate_kit_not_released,candidate_kit_warnings,idempotency_key_reused,idempotency_request_in_progress,job_closed - 422:
candidate_kit_empty,candidate_kit_no_email,invalid_parameter - 429:
rate_limit_exceeded - 500:
api_error - 503:
maintenance_mode,service_unavailable
ApiKeyAuthorizationBearer <probb_live_<id>_<secret>>id*stringThe report's ID.
1 <= length <= 200Idempotency-Key?stringMakes retries safe. Repeating a request with the same key and body within 24 hours returns the original response with Idempotent-Replayed: true. The same key with a different body, or from a different API key, returns idempotency_key_reused.
1 <= length <= 255application/json- body
channel*stringemail: Probb emails the candidate a link, from the name of your organization followed by via ProBB AI, with no reply-to address. link: nothing is sent; you share the returned url yourself.
"email""link"acknowledgeWarnings?booleanSet to true once a person has seen the wording warnings and wants to send anyway. Without it, any warning refuses the release with candidate_kit_warnings.
Success.
application/json- response
object*stringid*stringThe candidate feedback's ID.
reportId*stringThe report it belongs to.
status*"released"Always released once the call succeeds.
"released"revision*integerThe revision the candidate reads now: 1 for the first release, one more for each update.
-9007199254740991 <= value <= 9007199254740991channel*stringHow it was released.
"email""link"delivery*stringThe email: queued until it is sent, then sent, or failed; not_requested for channel: link. Poll GET /v1/reports/{id}/candidate-kit or subscribe to candidate_kit.* webhooks for changes.
"not_requested""queued""sent""failed"url*stringThe candidate's personal link. It is a credential: anyone with it can read the feedback until it is revoked or expires.
expiresAt*stringWhen the link stops working: 90 days after the release.
date-timeunchanged*booleanTrue when nothing new happened: the request was repeated, or live, unchanged feedback was asked for its link.
# Set PROBB_URL and PROBB_API_KEY. Replace any *_VALUE placeholder and any example ID (such as job_example) with a real one.# Idempotency-Key is optional. Reuse the same key and body when retrying one logical write.curl --fail-with-body -X POST "$PROBB_URL/api/v1/reports/ID_VALUE/candidate-kit/release" \ -H "Authorization: Bearer $PROBB_API_KEY" \ -H "Idempotency-Key: $REQUEST_KEY" \ -H 'Content-Type: application/json' \ --data-binary '{ "channel": "email"}'{ "object": "candidate_kit_release", "id": "string", "reportId": "string", "status": "released", "revision": -9007199254740991, "channel": "email", "delivery": "not_requested", "url": "string", "expiresAt": "2019-08-24T14:15:22Z", "unchanged": true}