Update Candidate Status
Partner ProgramAuthentication requiredupdate_candidate_status
Pin, target, hold, dismiss, or reopen a whitespace candidate. Targeted candidates require a durable action reference for attribution.
Access: Partner Program or approved access with read_brand permission
When to use
Use after a human or agent decides how to handle a whitespace opportunity.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| candidate_id | uuid | Yes | Candidate ID returned by get_whitespace_candidates. |
| status |
string
newpinnedtargetedhelddismissed |
Yes | New workflow status. |
| action_ref | string | No | Required for targeted; URL, ticket, content ID, or other durable reference. |
| brand_slug | string | No | Brand selector for internal superadmin keys. Brand-scoped keys ignore it; OAuth users select an authorized brand with brand_id. |
Try this in Claude
Mark this whitespace candidate as targeted and attach our content ticket.Example request
{
"candidate_id": "00000000-0000-4000-8000-000000000000",
"status": "targeted",
"action_ref": "MKT-204"
}Example response coming soon.
Side effects and safety
Changes the candidate's workflow status and attribution metadata.