Organization Configuration

Two singleton resources scoped to your organization control the defaults every job posting inherits, and the policy that governs outbound phone-interview dialing. Both are auto-created when your organization is created, so they are always readable via GET and updatable via PATCH. There is no POST or DELETE.

Endpoints

Method · Path	Purpose
`GET /api/v2/organization/interview-defaults`	Read the org-wide interview defaults.
`PATCH /api/v2/organization/interview-defaults`	Partially update org-wide interview defaults.
`GET /api/v2/organization/call-policy`	Read the org-wide phone-interview call policy.
`PATCH /api/v2/organization/call-policy`	Partially update the phone-interview call policy.

PATCH is partial: omit a field to leave it unchanged, or send an empty string to clear a text field.

Interview defaults

The defaults act as fallbacks for every job posting. When a job’s own interview configuration leaves a field blank (for example prompt_intro), the interview runtime uses the value from this endpoint. Clearing a field here reverts every job that has not set its own override to the platform default.

Field	Type	Description
`prompt_intro`	string	Opening script the voice assistant reads at the start of an interview.
`prompt_outro`	string	Closing script the voice assistant reads at the end of an interview.
`prompt_additional_instructions`	string	Free-form behavior guidance (tone, off-limit topics, style). Applied in addition to per-job instructions.
`interviewer_name_override`	string	Name the voice assistant introduces itself with. Blank falls back to the platform default.
`organization_name_override`	string	Name the voice assistant uses to refer to your organization. Blank falls back to your organization’s display name.

Clearing a field on this endpoint immediately changes the voice-assistant behavior for every job posting that has not set its own override. Verify the effect on a test job before rolling out changes broadly.

Example

curl -X PATCH https://api.talentunveiled.com/api/v2/organization/interview-defaults \
    -H "Authorization: Bearer $TALENTUNVEILED_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "prompt_intro": "Welcome. This is a short interview for the role you applied for.",
        "interviewer_name_override": "Aria"
    }'

{
    "id": "e7211749-...",
    "prompt_intro": "Welcome. This is a short interview for the role you applied for.",
    "prompt_outro": "",
    "prompt_additional_instructions": "",
    "interviewer_name_override": "Aria",
    "organization_name_override": "",
    "created_at": "2026-01-05T12:00:00Z",
    "updated_at": "2026-07-05T09:30:00Z"
}

Phone-interview call policy

The call policy governs outbound dialing for phone interviews. It applies to the entire organization; there is no per-job override. Changes apply to calls scheduled after the PATCH. Call sequences already in progress continue under the policy that was in force when they started. Each candidate receives one initial dial plus one retry per entry in retry_delay_sequence — the number of retries equals the number of entries. Retries are only placed during the calling window (weekdays between start_time and end_time, in the candidate’s local timezone). Setting retries_enabled to false disables retries but still permits the initial dial. max_retries and retry_window_days are deprecated and no longer read.

Field	Type	Description
`retries_enabled`	boolean	Master switch for retry attempts. `false` disables retries; the initial dial still happens.
`max_retries`	integer, read-only	Deprecated, no longer read. Still returned; writes are ignored. The retry budget is now the length of `retry_delay_sequence`.
`retry_window_days`	integer, read-only	Deprecated, no longer read. Still returned; writes are ignored. `retry_delay_sequence` now bounds the campaign.
`start_time`	string, `HH:MM:SS`	Calling-window start, in the candidate’s local timezone.
`end_time`	string, `HH:MM:SS`	Calling-window end, in the candidate’s local timezone. Must be greater than `start_time`.
`weekdays`	array of weekday names, lowercase	Weekdays on which dials may be placed (for example `["monday", "tuesday"]`). Must not be empty.
`retry_delay_sequence`	array of duration strings, format `[D ]HH:MM:SS`	Delays between successive retries (for example `["00:30:00", "03:00:00", "1 00:00:00"]`); one entry per retry, so the number of entries is the retry budget.

Duration strings follow Django’s serialization format: HH:MM:SS for sub-day delays, or D HH:MM:SS for delays that span one or more days. "00:30:00" is 30 minutes; "1 00:00:00" is 24 hours.

Validation

PATCH returns HTTP 400 with the offending field name in attr when:

end_time is not strictly greater than start_time.
weekdays is an empty array.

Example

curl -X PATCH https://api.talentunveiled.com/api/v2/organization/call-policy \
    -H "Authorization: Bearer $TALENTUNVEILED_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "retry_delay_sequence": ["00:30:00", "03:00:00", "1 00:00:00"],
        "start_time": "08:00:00",
        "end_time": "18:00:00",
        "weekdays": ["monday", "tuesday", "wednesday", "thursday"]
    }'

{
    "id": "550e8400-...",
    "retries_enabled": true,
    "max_retries": 4,
    "retry_window_days": 7,
    "start_time": "08:00:00",
    "end_time": "18:00:00",
    "weekdays": ["monday", "tuesday", "wednesday", "thursday"],
    "retry_delay_sequence": ["00:30:00", "03:00:00", "1 00:00:00"],
    "created_at": "2026-01-05T12:00:00Z",
    "updated_at": "2026-07-05T09:30:00Z"
}

API v2 Reference

Meta