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

> ## Agent Instructions
> Use Stable documentation by default. Honor an explicit Beta request or a URL under /docs/beta/. If the requested version conflicts with the installed CLI package or API origin, clarify the target before writing integration code.
> Pages under /docs/beta/ document Beta; other product pages document Stable. Keep the CLI package, commands, API origin, and credentials within the selected version. State the documentation version in your answer.
> For MCP search, always pass version: Stable or version: Beta. Unfiltered search mixes both versions. For filesystem reads, keep Beta queries under /beta/ and exclude /beta/ from Stable queries; discover paths before reading them.
> The public docs base is https://photon.codes/docs. Convert MCP page paths to public URLs under that base, preserving /beta/ when present. Read https://photon.codes/docs/skill.md for version selection and https://photon.codes/docs/llms.txt for the version indexes.

# Call Registry

> Register a project's phone numbers with the Photon Call Registry.

`photon project compliance call-registry` manages a project's Call Registry
profile, its automatic-registration setting, and the registration of individual
phone numbers. It is the first product under the `project compliance`
namespace.

[Browse the automatic command reference](/docs/beta/cli/reference/index).

Every command uses the standard
[project selection order](/docs/beta/cli/projects#select-an-active-project).

## Set the profile

`profile set` creates or completely replaces the profile.

<Tabs>
  <Tab title="Guided builder">
    In an interactive terminal, omit `--profile-file`:

    ```sh theme={null}
    photon project compliance call-registry profile set
    ```

    The builder groups fields into four sections, validates each answer as you
    go, retries invalid fields with a specific explanation, uses numbered menus
    for call purpose and volume, and shows a review before the final
    confirmation. Contact email and phone are masked in that review.
  </Tab>

  <Tab title="File">
    ```sh theme={null}
    photon project compliance call-registry profile set \
      --profile-file ./call-registry-profile.json \
      --idempotency-key acme-call-profile-v1 \
      --force
    ```
  </Tab>

  <Tab title="Piped stdin">
    ```sh theme={null}
    printf '%s\n' "$CALL_REGISTRY_PROFILE_PATCH" |
      photon project compliance call-registry profile edit \
        --idempotency-key acme-call-profile-contact-v2
    ```
  </Tab>
</Tabs>

<Warning>
  The CLI never accepts profile fields as command-line arguments, which keeps
  them out of shell history and process listings. Profile input is never
  written to the operation journal.
</Warning>

<Accordion title="Profile document">
  ```json theme={null}
  {
    "callCount": "1001",
    "category": "health",
    "city": "San Francisco",
    "claimType": "enterprise",
    "companyAddressLine1": "123 Market Street",
    "companyAddressLine2": "Suite 400",
    "companyName": "Example Health",
    "companyUrl": "https://example.com",
    "contactEmail": "operations@example.com",
    "contactName": "Ada Lovelace",
    "contactPhone": "+14155550100",
    "explanation": "Appointment reminders and patient callbacks.",
    "lineType": "wireline",
    "postalCode": "94105",
    "registrationType": "enterprise",
    "secondContactEmail": "compliance@example.com",
    "state": "CA"
  }
  ```

  `companyAddressLine2`, `explanation`, and `secondContactEmail` are optional.
  Everything else is required.
</Accordion>

The same validation applies to interactive, file, stdin, and patch input:

| Field | Accepted value |
| - | - |
| `lineType` | `wireline` |
| `registrationType` | `enterprise` |
| `claimType` | `enterprise` |
| `category` | `attorney_legal`, `financial_service`, `first_responder`, `government`, `health`, `informational`, `pharmacy`, `political`, `real_estate`, `school_college`, `survey`, or `telemarketing` |
| `callCount` | `1`, `101`, `501`, `1001`, `5001`, `10001`, `50001`, or `dontknow` — the lower bounds of the registry's displayed ranges |
| `companyName` | 4–255 printable ASCII characters |
| `companyAddressLine1` | 4–512 printable ASCII characters; PO boxes are rejected |
| `companyAddressLine2` | When present, 1–512 printable ASCII characters; PO boxes are rejected |
| `city` | 2–512 printable ASCII characters |
| `state` | A two-letter US state, District of Columbia, or US territory code; normalized to uppercase |
| `postalCode` | Five-digit ZIP or ZIP+4 |
| `companyUrl` | Absolute HTTP(S) URL with a public hostname and no credentials or fragment |
| `contactName` | 4–50 printable ASCII characters |
| `contactPhone` | Valid US or international E.164 number; normalized to E.164 |
| `contactEmail`, `secondContactEmail` | Valid email address, at most 255 characters |
| `explanation` | When present, 5–1,024 printable ASCII characters |

HTML-like markup, control and format characters, unknown fields, invalid JSON,
and documents larger than 16 KiB are rejected locally.

`profile set` requires confirmation because it replaces the whole profile.
`profile edit` accepts any non-empty subset of the same fields and does not
confirm.

<Note>
  The patch contract cannot explicitly clear an optional field. To remove one,
  use `profile set` with a complete document that omits it.
</Note>

## Automatic registration

```sh theme={null}
photon project compliance call-registry profile auto-register status
photon project compliance call-registry profile auto-register enable
photon project compliance call-registry profile auto-register disable
```

`status` is read-only. `enable` and `disable` confirm unless you pass `--force`
and accept an optional `--idempotency-key`. All three first check that the
project has a Call Registry profile, and the mutating pair skip the write when
the setting already holds the requested value.

<Warning>
  Enabling automatic registration affects only phone numbers provisioned
  **after** it is enabled. It does not register numbers you already have — use
  `registration start` for those.
</Warning>

## Register phone numbers

Start registration for 1 to 20 unique canonical `pho_res_` resource IDs.
Repeat `--resource-id` for each:

```sh theme={null}
photon project compliance call-registry registration start \
  --resource-id pho_res_01k00000000000000000000000 \
  --resource-id pho_res_01k00000000000000000000001 \
  --idempotency-key acme-call-registration-2026-08 \
  --force \
  --json
```

Submission is asynchronous and requires confirmation. A success returns a
`pho_crg_` registration ID. The CLI does not poll — check progress yourself:

```sh theme={null}
photon project compliance call-registry registration view pho_crg_...
photon project compliance call-registry registration list --status pending
photon project compliance call-registry registration list --limit 100 --json
```

Filters use the lowercase statuses `pending`, `awaiting_verification`,
`verifying`, `submitting`, `registered`, `failed`, and `unknown`. JSON keeps
the API's raw `CALL_REGISTRATION_STATUS_*` values; human output strips the
prefix. Lists default to 30 results and accept up to 1,000.

Provider-specific references are omitted from output. Failure codes are
normalized to `verification_exhausted`, `registration_rejected`,
`submission_outcome_unknown`, `legacy_registration_failed`, or
`registration_failed`.

<Note>
  The API exposes no delete, cancel, or retry route. Resolve a failed
  registration using its failure details or Photon support guidance.
</Note>

## Idempotency and private data

All four mutations accept `--idempotency-key`, and the CLI generates a UUIDv4
when you omit one.

Profile replacement and edits stay **out** of the local journal because their
bodies contain private profile data. If a profile request's result is
uncertain, check the current profile, then repeat the exact input with the key
from the error.

Automatic-registration updates and registration starts do use the journal.
Their saved input contains only the project ID, the boolean config value, and
canonical `pho_res_` resource IDs — never profile fields or phone numbers.
Re-running an unresolved command with the same key and input continues it
automatically, and `photon operation replay <operation-id>` also recovers it.
See [Recoverable operations](/docs/beta/cli/operations).

Complete profile request and response bodies are redacted from `--debug`
traces, along with phone numbers, registration feedback, and personal fields.
Keep profile files private and delete temporary copies according to your
organization's retention policy.

<Accordion title="API routes used by these commands">
  | Command | Method and route |
  | - | - |
  | `profile view` | `GET /v1/projects/{projectId}/compliance/call-registry/profile` |
  | `profile set` | `PUT /v1/projects/{projectId}/compliance/call-registry/profile` |
  | `profile edit` | `PATCH /v1/projects/{projectId}/compliance/call-registry/profile` |
  | `profile auto-register status` | `GET .../profile`, then `GET .../config` |
  | `profile auto-register enable` | `GET .../profile`, `GET .../config`, then `PATCH .../config` when needed |
  | `profile auto-register disable` | `GET .../profile`, `GET .../config`, then `PATCH .../config` when needed |
  | `registration start` | `POST /v1/projects/{projectId}/compliance/call-registry/registrations` |
  | `registration list` | `GET /v1/projects/{projectId}/compliance/call-registry/registrations` |
  | `registration view` | `GET /v1/projects/{projectId}/compliance/call-registry/registrations/{registrationId}` |

  The four mutation routes send `Idempotency-Key`.
</Accordion>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.