Survey preferences

Headers

X-Api-Keyonb_live_<key_id>_<secret>required

Your issued Partner API key — see Authentication.

Status codes

2002xx

null for questionSetId/autoSend means it inherits the account default (see Account settings below); startDate/startDateSource are both null only when not yet enrolled.

4014xx

Missing, malformed, unknown, revoked or expired key. Every authentication failure looks the same — see Authentication.

4034xx

Your account’s plan does not include ChurnGuard.

ChurnGuard is not included in your plan.

4044xx

Unknown, cross-tenant, or (a candidate id) sandbox-hidden. One outcome, never a 403.

Not found

4294xx

Per-key or per-account rate limit exceeded. Retry after the Retry-After header.

Too many requests — please try again shortly.

Headers

X-Api-Keyonb_live_<key_id>_<secret>required

Your issued Partner API key — see Authentication.

Request fields

questionSetIdstring or nulloptional

null clears the pin — falls back to the account default.

autoSendboolean or nulloptional

null inherits the account default (see Account settings below).

startDatestring (YYYY-MM-DD) or nulloptional

A real calendar date, within a year either side of today. null reverts to the candidate’s own compliance completion date — refused (409) if that is not on file yet.

Status codes

2002xx

The value now in effect for every field, not only the ones this request touched.

4004xx

Malformed body, an unrecognised field, an invalid field type, or a questionSetId that does not resolve for your account.

4014xx

Missing, malformed, unknown, revoked or expired key. Every authentication failure looks the same — see Authentication.

4034xx

Your account’s plan does not include ChurnGuard.

ChurnGuard is not included in your plan.

4034xx

The key’s user has the viewer team role, or their account could not be read just then (retry) — or the key was created Read only (code: "key_read_only", refused before anything else). Checked before the body or any id — see Authentication.

Your team role doesn't allow this. Ask your team's admin or owner.This API key is read-only. Create a full-access key to make changes.

4044xx

Unknown, cross-tenant, or (a candidate id) sandbox-hidden. One outcome, never a 403.

Not found

4094xx

This candidate’s preferences row already belongs to a different account; OR startDate: null with no completion date on file yet; OR a schedule-enrolment refusal (e.g. the candidate’s compliance conversation is still in progress).

4294xx

Per-key or per-account rate limit exceeded. Retry after the Retry-After header.

Too many requests — please try again shortly.

5005xx

The write itself failed — retry.

This resource is temporarily unavailable. Try again shortly.