{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/corebee-ai/json-schema/corebee-ai-caller-id-pool-number-schema.json",
  "title": "CallerIdPoolNumber",
  "description": "One number in your caller-ID pool, with the verdict on whether it may be displayed. Retired rows are included and refused, not hidden.",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/corebee-ai-openapi.yml#/components/schemas/CallerIdPoolNumber",
  "type": "object",
  "required": [
    "e164",
    "kind",
    "selectable",
    "refusal"
  ],
  "properties": {
    "e164": {
      "type": "string",
      "description": "The number as it would be displayed."
    },
    "kind": {
      "type": "string",
      "enum": [
        "owned",
        "dealer_verified"
      ],
      "description": "owned, a Telnyx number we hold. dealer_verified, a DEALERSHIP's own number we have permission to display on their behalf. Any other value is refused as unknown_kind rather than ignored."
    },
    "market_key": {
      "type": [
        "string",
        "null"
      ],
      "description": "The market this row was filed under. Optional, a row may be region-only. A key this system does not recognise is refused (market_key_unknown), because it could never match anything and is almost always a typo."
    },
    "market_label": {
      "type": [
        "string",
        "null"
      ],
      "description": "⛔ DERIVED FROM THE NUMBER'S OWN AREA CODE, NOT FROM market_key. So it can disagree with market_key on a mis-keyed row, and it can be present on a row whose market_key is null. Display only."
    },
    "npa": {
      "type": [
        "string",
        "null"
      ],
      "description": "The area code recorded on the row. When present it must equal the number's ACTUAL area code or the row is refused (npa_mismatch), pasting the consumer's area code here would otherwise create a row that matches confidently and displays the wrong number."
    },
    "region_code": {
      "type": [
        "string",
        "null"
      ],
      "description": "Two-letter state the row was filed under. Informational."
    },
    "expected_attestation": {
      "type": [
        "string",
        "null"
      ],
      "description": "What we EXPECT the carrier to attest for this display. An expectation carried forward from how the number was obtained, not a measurement, and not verified against live calls."
    },
    "verification_method": {
      "type": [
        "string",
        "null"
      ],
      "description": "How a dealer_verified row was verified. Required together with verified_at for that kind; missing either is refused (dealer_verification_incomplete), an unstamped row is not \"not yet recorded\", it is a number we have no permission to display."
    },
    "verified_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "business_e164": {
      "type": [
        "string",
        "null"
      ],
      "description": "For dealer_verified: the DEALERSHIP LINE this display is bound to. A dealership has many lines and a verification covers one of them, so without this binding the only available scope would be organization-wide, which would show one dealership's number on another's call. Missing or malformed is refused (dealer_binding_missing)."
    },
    "callback_handling": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "staffed",
        "ivr_dnc",
        null
      ],
      "description": "What happens when somebody calls the displayed number back. staffed, it rings the dealership. ivr_dnc, it lands on our own answering line. Unset, or any other value, is refused (callback_handling_unset)."
    },
    "callback_reachable_verified_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When an operator verified OUT OF BAND that calling this number reaches something. Absent stamp, absent from the pool (callback_unverified). There is no flag that overrides this."
    },
    "daily_dial_ceiling": {
      "type": [
        "integer",
        "null"
      ],
      "description": "⛔ REPORTED HERE, ENFORCED ELSEWHERE. Passing this ceiling does NOT make a row unselectable and never reassigns a call to a different number; it raises an alert on the call so an operator can add capacity or retire the number. A row at its ceiling still reads selectable:true here, correctly."
    },
    "retired_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When an operator retired the row. Set means refusal \"retired\"."
    },
    "selectable": {
      "type": "boolean",
      "description": "May the selector display this number? True means ELIGIBLE, not chosen, see the path description for the three per-call refusals that cannot appear here."
    },
    "refusal": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "retired",
        "malformed_e164",
        "unknown_kind",
        "no_channel_binding",
        "callback_unverified",
        "callback_handling_unset",
        "callback_line_disarmed",
        "dealer_verification_incomplete",
        "dealer_binding_missing",
        "market_key_unknown",
        "npa_mismatch",
        "not_an_owned_telnyx_did",
        null
      ],
      "description": "Null when selectable. Otherwise the FIRST screen that refused, in screen order: retired (an operator retired it); malformed_e164 (not a valid E.164 number); unknown_kind (kind is neither owned nor dealer_verified); no_channel_binding (the row names no channel, so a call would originate from this number while reading another number's voice and spoken lines, a call that works and is wrong); callback_unverified (nobody has verified that calling it back reaches anything); callback_handling_unset (it does not say what happens on a call-back); callback_line_disarmed (it routes call-backs to our answering line and that line is not armed on this deployment, a property of OUR deployment, not of your row); dealer_verification_incomplete (a dealer_verified row missing its verification stamp or method); dealer_binding_missing (a dealer_verified row with no valid dealership line bound to it); market_key_unknown (a market key this system does not recognise); npa_mismatch (the recorded area code is not the number's own); not_an_owned_telnyx_did (kind is owned but the number is not among the Telnyx numbers we hold for you, checked against up to 50 of them, so treat it as advisory if you hold more)."
    }
  }
}