{
  "openapi": "3.1.0",
  "info": {
    "title": "Quad State SMS API",
    "version": "2026-09-30",
    "description": "Customer-scoped messaging, per-number channel capabilities, message history, and signed webhooks. SMS is implemented. MMS, RCS, and iMessage are reserved channels and report unavailable until implemented and provisioned.",
    "contact": {
      "name": "Quad State"
    }
  },
  "servers": [
    {
      "url": "https://api.quadstate.us"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/account": {
      "get": {
        "operationId": "getAccount",
        "summary": "Get your customer account",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "id",
                    "name"
                  ]
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/numbers": {
      "get": {
        "operationId": "listNumbers",
        "summary": "List assigned numbers and channel capabilities",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Number"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/messages": {
      "post": {
        "operationId": "sendMessage",
        "summary": "Submit a message with a channel and idempotency key",
        "responses": {
          "202": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Message"
                }
              }
            },
            "headers": {
              "Idempotency-Replayed": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "true",
                    "false"
                  ]
                },
                "description": "Whether this returns a previous request."
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "200": {
            "description": "Idempotent replay; no new SMS sent",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Message"
                }
              }
            },
            "headers": {
              "Idempotency-Replayed": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "true",
                    "false"
                  ]
                },
                "description": "Whether this returns a previous request."
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "from": {
                    "type": "string"
                  },
                  "to": {
                    "type": "string"
                  },
                  "text": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 1600
                  },
                  "channel": {
                    "type": "string",
                    "enum": [
                      "sms",
                      "mms",
                      "rcs",
                      "imessage"
                    ],
                    "default": "sms",
                    "description": "SMS is implemented now. Other channels are reserved and return channel_unavailable until activated."
                  }
                },
                "required": [
                  "from",
                  "to",
                  "text"
                ]
              }
            }
          }
        },
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9._:-]{1,128}$"
            }
          }
        ],
        "description": "202 acknowledges a stored submission result, not handset delivery. Inspect status: accepted, failed, submitting, or unknown. Never use a new key to retry an uncertain result. channel defaults to sms for existing clients. Check your number capabilities before submitting. Unavailable channels return 422 channel_unavailable and are never downgraded to SMS. Pending sending activation returns 503 sending_unavailable."
      },
      "get": {
        "operationId": "listMessages",
        "summary": "List your messages",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Message"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "next_cursor"
                  ]
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "before",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/messages/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "operationId": "getMessage",
        "summary": "Get a message from your account",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Message"
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/webhook": {
      "get": {
        "operationId": "getWebhook",
        "summary": "Get webhook settings",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "configured": {
                      "type": "boolean"
                    },
                    "events": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "url",
                    "configured",
                    "events"
                  ]
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "setWebhook",
        "summary": "Set the account default HTTPS URL, or null to pause numbers inheriting it",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "configured": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "url",
                    "configured"
                  ]
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "uri"
                  }
                },
                "required": [
                  "url"
                ]
              }
            }
          }
        }
      }
    },
    "/webhook/rotate-secret": {
      "post": {
        "operationId": "rotateWebhookSecret",
        "summary": "Immediately rotate the webhook signing secret",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "secret": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "secret"
                  ]
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/webhook/deliveries": {
      "get": {
        "operationId": "listWebhookDeliveries",
        "summary": "List the latest 100 webhook delivery records",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Delivery"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/webhook/deliveries/{id}/retry": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "operationId": "retryWebhookDelivery",
        "summary": "Queue a webhook replay with the same event ID",
        "responses": {
          "202": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "status": {
                      "const": "pending",
                      "type": "string"
                    }
                  },
                  "required": [
                    "id",
                    "status"
                  ]
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "operationId": "health",
        "summary": "Check service health",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "service": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "service",
                    "status"
                  ]
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": []
      }
    },
    "/numbers/{number}": {
      "parameters": [
        {
          "name": "number",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "pattern": "^\\+1[2-9]\\d{2}[2-9]\\d{6}$"
          },
          "example": "+12705551234"
        }
      ],
      "get": {
        "operationId": "getNumber",
        "summary": "Get an assigned number and its capabilities",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Number"
                }
              }
            }
          },
          "404": {
            "description": "Number not assigned to this customer",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/numbers/{number}/capabilities": {
      "parameters": [
        {
          "name": "number",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "pattern": "^\\+1[2-9]\\d{2}[2-9]\\d{6}$"
          },
          "example": "+12705551234"
        }
      ],
      "get": {
        "operationId": "getNumberCapabilities",
        "summary": "Get SMS, MMS, RCS, and iMessage availability",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "number": {
                      "type": "string"
                    },
                    "capabilities": {
                      "$ref": "#/components/schemas/NumberCapabilities"
                    },
                    "activation": {
                      "oneOf": [
                        {
                          "$ref": "#/components/schemas/Activation"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "number",
                    "capabilities"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Number not assigned to this customer",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/numbers/{number}/webhook": {
      "parameters": [
        {
          "name": "number",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "pattern": "^\\+1[2-9]\\d{2}[2-9]\\d{6}$"
          },
          "example": "+12705551234"
        }
      ],
      "description": "Customer-scoped settings. Inbound events use the destination number; outbound status events use the source number. Overrides use the account signing secret. Current settings also apply to pending deliveries.",
      "get": {
        "operationId": "getNumberWebhook",
        "summary": "Get number webhook settings",
        "responses": {
          "200": {
            "description": "Current number settings and effective receiving URL",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NumberWebhook"
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "setNumberWebhook",
        "summary": "Set a number URL, inherit the account default, or pause a number",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "mode": {
                    "type": "string",
                    "enum": [
                      "inherit",
                      "override",
                      "disabled"
                    ]
                  },
                  "url": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "uri"
                  }
                },
                "anyOf": [
                  {
                    "required": [
                      "mode"
                    ]
                  },
                  {
                    "required": [
                      "url"
                    ]
                  }
                ],
                "description": "Defaults to inherit. A non-null URL selects override; null restores inherit. Explicit override requires a public HTTPS/443 URL. Inherit and disabled accept only a null or omitted URL."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Current number settings and effective receiving URL",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NumberWebhook"
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/messaging-policy": {
      "get": {
        "operationId": "getMessagingPolicy",
        "summary": "Read active account wording and keywords",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MessagingPolicy"
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/messaging-policy/requests": {
      "get": {
        "operationId": "listMessagingPolicyRequests",
        "summary": "Read your request box, with review status and notes",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "approved",
                "rejected",
                "cancelled"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "before",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PolicyRequestList"
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "requestMessagingPolicyChange",
        "summary": "Request Quad State review; does not change the active policy",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9._:-]{1,128}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PolicyRequestCreate"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PolicyRequest"
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "200": {
            "description": "Idempotent replay of the original request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PolicyRequest"
                }
              }
            }
          }
        }
      }
    },
    "/messaging-policy/requests/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "pattern": "^pcr_[a-f0-9]{32}$"
          }
        }
      ],
      "get": {
        "operationId": "getMessagingPolicyRequest",
        "summary": "Retrieve a customer-scoped request",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PolicyRequest"
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/messaging-policy/requests/{id}/cancel": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "pattern": "^pcr_[a-f0-9]{32}$"
          }
        }
      ],
      "post": {
        "operationId": "cancelMessagingPolicyRequest",
        "summary": "Cancel a pending request; active wording remains unchanged",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PolicyRequest"
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "webhooks": {
    "smsEvent": {
      "post": {
        "summary": "Quad State SMS event delivery",
        "description": "Verify HMAC-SHA256 of timestamp + dot + raw UTF-8 body using your webhook secret; reject timestamps outside 300 seconds and deduplicate event IDs. At least once; ordering is not guaranteed. Up to 12 attempts with exponential backoff from 30s to 1h. Return 2xx after durable storage.",
        "parameters": [
          {
            "name": "X-Quad-State-Event-ID",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Quad-State-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "t=UNIX_TIMESTAMP,sha256=HMAC_SHA256_HEX"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Event saved and acknowledged"
          }
        },
        "security": []
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Quad State customer Bearer token; new tokens contain 48 uppercase hexadecimal characters"
      }
    },
    "schemas": {
      "Message": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "object": {
            "const": "sms_message",
            "type": "string"
          },
          "direction": {
            "type": "string",
            "enum": [
              "inbound",
              "outbound"
            ]
          },
          "from": {
            "type": "string"
          },
          "to": {
            "type": "string"
          },
          "text": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "submitting",
              "accepted",
              "failed",
              "unknown",
              "received"
            ]
          },
          "error_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "channel": {
            "type": "string",
            "enum": [
              "sms",
              "mms",
              "rcs",
              "imessage"
            ],
            "default": "sms",
            "description": "SMS is implemented now. Other channels are reserved and return channel_unavailable until activated."
          },
          "error": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/MessageError"
              },
              {
                "type": "null"
              }
            ]
          },
          "compliance": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/ComplianceAction"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "id",
          "object",
          "direction",
          "from",
          "to",
          "text",
          "status",
          "error_code",
          "created_at",
          "updated_at",
          "channel"
        ],
        "description": "accepted means an explicit sending acknowledgment only. It is not confirmation of registration approval, an outgoing usage record, or handset delivery."
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "request_id": {
                "type": "string"
              },
              "details": {
                "$ref": "#/components/schemas/Activation"
              }
            },
            "required": [
              "code",
              "message",
              "request_id"
            ]
          }
        },
        "required": [
          "error"
        ]
      },
      "Event": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "sms.received",
              "sms.status_updated"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "data": {
            "$ref": "#/components/schemas/Message"
          }
        },
        "required": [
          "id",
          "type",
          "created_at",
          "data"
        ]
      },
      "Delivery": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "event_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "processing",
              "delivered",
              "failed"
            ]
          },
          "attempts": {
            "type": "integer"
          },
          "last_http_status": {
            "type": [
              "integer",
              "null"
            ]
          },
          "last_error": {
            "type": [
              "string",
              "null"
            ]
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "event_id",
          "status",
          "attempts",
          "last_http_status",
          "last_error",
          "updated_at"
        ]
      },
      "CapabilityDirection": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "available",
              "unavailable"
            ]
          },
          "reason": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "number_disabled",
              "not_supported",
              "not_enabled",
              "activation_pending",
              null
            ]
          }
        },
        "required": [
          "status",
          "reason"
        ],
        "description": "Check send and receive independently. SMS receive can be available while send is unavailable with activation_pending. New sends then return 503 sending_unavailable with an activation explanation, without submitting a message."
      },
      "ChannelCapability": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "available",
              "unavailable"
            ]
          },
          "send": {
            "$ref": "#/components/schemas/CapabilityDirection"
          },
          "receive": {
            "$ref": "#/components/schemas/CapabilityDirection"
          }
        },
        "required": [
          "status",
          "send",
          "receive"
        ],
        "description": "Overall status is available if either direction is available. It does not imply sending is activated; always inspect send.status and receive.status separately."
      },
      "NumberCapabilities": {
        "type": "object",
        "properties": {
          "sms": {
            "$ref": "#/components/schemas/ChannelCapability"
          },
          "mms": {
            "$ref": "#/components/schemas/ChannelCapability"
          },
          "rcs": {
            "$ref": "#/components/schemas/ChannelCapability"
          },
          "imessage": {
            "$ref": "#/components/schemas/ChannelCapability"
          }
        },
        "required": [
          "sms",
          "mms",
          "rcs",
          "imessage"
        ],
        "description": "Reports implemented support and provisioning for this assigned number. Future channels remain unavailable until their adapters and number provisioning are enabled."
      },
      "Number": {
        "type": "object",
        "properties": {
          "number": {
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          },
          "send_enabled": {
            "type": "boolean",
            "description": "Legacy SMS sending availability."
          },
          "capabilities": {
            "$ref": "#/components/schemas/NumberCapabilities"
          },
          "activation": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Activation"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "number",
          "enabled",
          "send_enabled",
          "capabilities"
        ]
      },
      "NumberWebhook": {
        "type": "object",
        "properties": {
          "number": {
            "type": "string"
          },
          "mode": {
            "type": "string",
            "enum": [
              "inherit",
              "override",
              "disabled"
            ]
          },
          "url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "effective_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "signing_secret_scope": {
            "type": "string",
            "const": "account"
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "sms.received",
                "sms.status_updated"
              ]
            }
          }
        },
        "required": [
          "number",
          "mode",
          "url",
          "effective_url",
          "signing_secret_scope",
          "events"
        ]
      },
      "Activation": {
        "type": "object",
        "properties": {
          "number": {
            "type": "string"
          },
          "channel": {
            "type": "string"
          },
          "reason": {
            "type": "string",
            "enum": [
              "activation_pending"
            ]
          },
          "activation_reason": {
            "type": "string"
          },
          "send_status": {
            "type": "string"
          },
          "receive_status": {
            "type": "string"
          },
          "registration_status": {
            "type": "string",
            "enum": [
              "pending_verification",
              "pending",
              "approved",
              "not_required"
            ]
          },
          "activation_status": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "action": {
            "type": "string"
          }
        },
        "required": [
          "number",
          "channel",
          "reason",
          "activation_reason",
          "send_status",
          "receive_status",
          "registration_status",
          "activation_status",
          "message",
          "action"
        ],
        "description": "Quad State activation explanation. pending_verification means approval is unverified, not rejected."
      },
      "MessageError": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "action": {
            "type": "string"
          }
        },
        "required": [
          "code",
          "message",
          "action"
        ]
      },
      "ComplianceAction": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "opt_in",
              "opt_out",
              "help"
            ]
          },
          "keyword": {
            "type": "string"
          },
          "policy_revision": {
            "type": "integer",
            "minimum": 0
          },
          "response_text": {
            "type": [
              "string",
              "null"
            ]
          },
          "automatically_sent": {
            "type": "boolean",
            "const": false
          }
        },
        "required": [
          "action",
          "keyword",
          "policy_revision",
          "response_text",
          "automatically_sent"
        ],
        "description": "Snapshot of the active keyword policy when received. Replies are not automatically sent."
      },
      "PolicyContent": {
        "type": "object",
        "properties": {
          "opt_in_message": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 20,
            "maxLength": 255
          },
          "opt_out_message": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 20,
            "maxLength": 255
          },
          "help_message": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 20,
            "maxLength": 255
          },
          "opt_in_keywords": {
            "type": "array",
            "minItems": 1,
            "maxItems": 32,
            "items": {
              "type": "string",
              "pattern": "^[A-Za-z0-9]{1,20}$"
            },
            "description": "Case-insensitive. Standard keywords cannot be removed; actions must not overlap."
          },
          "opt_out_keywords": {
            "type": "array",
            "minItems": 1,
            "maxItems": 32,
            "items": {
              "type": "string",
              "pattern": "^[A-Za-z0-9]{1,20}$"
            },
            "description": "Case-insensitive. Standard keywords cannot be removed; actions must not overlap."
          },
          "help_keywords": {
            "type": "array",
            "minItems": 1,
            "maxItems": 32,
            "items": {
              "type": "string",
              "pattern": "^[A-Za-z0-9]{1,20}$"
            },
            "description": "Case-insensitive. Standard keywords cannot be removed; actions must not overlap."
          }
        },
        "required": [
          "opt_in_message",
          "opt_out_message",
          "help_message",
          "opt_in_keywords",
          "opt_out_keywords",
          "help_keywords"
        ],
        "additionalProperties": false
      },
      "PolicyChanges": {
        "type": "object",
        "properties": {
          "opt_in_message": {
            "type": "string",
            "minLength": 20,
            "maxLength": 255
          },
          "opt_out_message": {
            "type": "string",
            "minLength": 20,
            "maxLength": 255
          },
          "help_message": {
            "type": "string",
            "minLength": 20,
            "maxLength": 255
          },
          "opt_in_keywords": {
            "type": "array",
            "minItems": 1,
            "maxItems": 32,
            "items": {
              "type": "string",
              "pattern": "^[A-Za-z0-9]{1,20}$"
            },
            "description": "Case-insensitive. Standard keywords cannot be removed; actions must not overlap."
          },
          "opt_out_keywords": {
            "type": "array",
            "minItems": 1,
            "maxItems": 32,
            "items": {
              "type": "string",
              "pattern": "^[A-Za-z0-9]{1,20}$"
            },
            "description": "Case-insensitive. Standard keywords cannot be removed; actions must not overlap."
          },
          "help_keywords": {
            "type": "array",
            "minItems": 1,
            "maxItems": 32,
            "items": {
              "type": "string",
              "pattern": "^[A-Za-z0-9]{1,20}$"
            },
            "description": "Case-insensitive. Standard keywords cannot be removed; actions must not overlap."
          }
        },
        "minProperties": 1,
        "additionalProperties": false
      },
      "MessagingPolicy": {
        "type": "object",
        "properties": {
          "customer_id": {
            "type": "string"
          },
          "scope": {
            "type": "string",
            "const": "account"
          },
          "revision": {
            "type": "integer",
            "minimum": 0
          },
          "approval_status": {
            "type": "string",
            "enum": [
              "approved",
              "not_configured"
            ]
          },
          "active": {
            "$ref": "#/components/schemas/PolicyContent"
          },
          "pending_requests": {
            "type": "integer"
          },
          "updated_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "reply_delivery": {
            "type": "string",
            "const": "application_managed"
          },
          "notice": {
            "type": "string"
          }
        },
        "required": [
          "customer_id",
          "scope",
          "revision",
          "approval_status",
          "active",
          "pending_requests",
          "updated_at",
          "reply_delivery",
          "notice"
        ]
      },
      "PolicyRequestCreate": {
        "type": "object",
        "properties": {
          "base_revision": {
            "type": "integer",
            "minimum": 0
          },
          "changes": {
            "$ref": "#/components/schemas/PolicyChanges"
          },
          "reason": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000
          }
        },
        "required": [
          "base_revision",
          "changes",
          "reason"
        ],
        "additionalProperties": false
      },
      "PolicyRequest": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^pcr_[a-f0-9]{32}$"
          },
          "customer_id": {
            "type": "string"
          },
          "base_revision": {
            "type": "integer"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "approved",
              "rejected",
              "cancelled"
            ]
          },
          "changes": {
            "$ref": "#/components/schemas/PolicyChanges"
          },
          "proposed": {
            "$ref": "#/components/schemas/PolicyContent"
          },
          "reason": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "reviewed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "review_note": {
            "type": [
              "string",
              "null"
            ]
          },
          "applied_revision": {
            "type": [
              "integer",
              "null"
            ]
          },
          "previous": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/PolicyContent"
              },
              {
                "type": "null"
              }
            ],
            "description": "Immutable policy snapshot at the base revision. Null only for legacy records whose original policy is unavailable."
          }
        },
        "required": [
          "id",
          "customer_id",
          "base_revision",
          "status",
          "changes",
          "proposed",
          "reason",
          "created_at",
          "reviewed_at",
          "review_note",
          "applied_revision",
          "previous"
        ]
      },
      "PolicyRequestList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PolicyRequest"
            }
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "data",
          "next_cursor"
        ]
      }
    }
  }
}
