> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talentunveiled.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Organization Configuration

> Manage org-wide interview defaults and phone-call policy (API v2)

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. |

<Warning>
  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.
</Warning>

### Example

```bash theme={null}
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"
    }'
```

```json theme={null}
{
    "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. |

<Info>
  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.
</Info>

### 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

```bash theme={null}
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"]
    }'
```

```json theme={null}
{
    "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"
}
```