Optimly MCP
Update Candidate Status
Pin, target, hold, dismiss, or reopen a whitespace candidate. Targeted candidates require a durable action reference for attribution.
update_candidate_status · Partner Program · Authentication required
Pin, target, hold, dismiss, or reopen a whitespace candidate. Targeted candidates require a durable action reference for attribution.
When to use
Use after a human or agent decides how to handle a whitespace opportunity.
Access
Partner Program or approved access with read_brand permission
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
candidate_id | uuid | Yes | Candidate ID returned by get_whitespace_candidates. |
status | string | Yes | New workflow status. Allowed values: new, pinned, targeted, held, dismissed. |
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. |
Example prompt
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"
}Side effects and safety
Changes the candidate's workflow status and attribution metadata.