Candidates

Reconcile a candidate from a membership source

Changed on

Body-keyed membership sync. sourceKey + externalMemberId identify the member; they stay in the body because request paths land in logs. sourceRevision orders writes: equal is a no-op, lower is rejected. Creates, links, or updates the Candidate and optionally applies a profile projection. Pair this push with the candidate.profile.updated webhook and GET /candidates/{id}/profile pull. Requires candidates.manage. The request is idempotent when an Idempotency-Key header is supplied; equal source revisions are also idempotent without the header.

post/candidates/reconcile

Request

  • Base URL: https://api.cavuno.com/v1
  • URL: https://api.cavuno.com/v1/candidates/reconcile
  • Auth: HTTP bearer

Request body

sourceKeystring required

Opaque caller-chosen identifier for the membership system this write comes from (1–64 characters, [a-z0-9._-]). Identifies the source, not the person, and must stay stable: changing it treats the caller as a new source and cannot update an existing link.

externalMemberIdstring required

The member id in the caller's system (1–256 characters). Sent in the body, never the URL: request paths land in logs and traces. Together with sourceKey this is the idempotent membership-sync key.

sourceRevisioninteger required

Monotonically increasing revision per member, typically the source system's change timestamp in milliseconds. An equal revision is an idempotent no-op (unchanged); a lower revision is rejected as stale so a delayed write can never resurrect stale profile data or reactivate a deactivated account. Revisions above 2^53-1 are rejected.

emailstring email required

The candidate's email address. Used to create or link the Board user for this membership source.

displayNamestring required

The candidate's display name.

activeboolean required

When false, deactivates the candidate (sign-in disabled, sessions revoked, profile hidden from talent surfaces). When true, restores sign-in and talent-surface visibility; the candidate signs in again to establish a new session. Profile and application history are preserved either way.

Response

Candidate reconciled.

status'created' | 'updated' | 'unchanged' | 'upgraded' required

created when a new Candidate is provisioned, updated when identity or profile changed, unchanged when the source revision was already applied, upgraded when an existing non-candidate Board user became a Candidate.

Changes

  • c34152c38176Revision changes
    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status