PhoneNumbersReservation

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/microsoft-azure-communication-services/json-schema/microsoft-azure-communication-services-phone-numbers-reservation-schema.json",
  "title": "PhoneNumbersReservation",
  "description": "Represents a reservation for phone numbers. A reservation is a temporary hold on phone numbers that can later be purchased. The reservation has a limited lifetime after which the phone numbers are released if not purchased. Reservations older than 1 month are automatically deleted.",
  "x-generated": "2026-11-05",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_superseded/microsoft-azure-communication-services-phonenumbers-api-openapi.yml#/components/schemas/PhoneNumbersReservation",
  "type": "object",
  "properties": {
    "id": {
      "description": "The id of the reservation.",
      "type": "string",
      "format": "uuid",
      "readOnly": true
    },
    "expiresAt": {
      "description": "The time at which the reservation will expire. If a reservation is not purchased before this time, all of the reserved phone numbers will be released and made available for others to purchase.",
      "type": "string",
      "format": "date-time",
      "readOnly": true
    },
    "phoneNumbers": {
      "type": "object",
      "description": "A dictionary containing the reservation phone numbers. The key is the ID of the phone number (digits only) and values are AvailablePhoneNumber objects. Not populated when retrieving PhoneNumbersReservation collections.",
      "additionalProperties": {
        "$ref": "#/$defs/AvailablePhoneNumber",
        "x-nullable": true
      }
    },
    "status": {
      "type": "string",
      "description": "Represents the status of the reservation. Possible values include: 'active', 'submitted', 'completed', 'expired'.",
      "readOnly": true,
      "enum": [
        "active",
        "submitted",
        "completed",
        "expired"
      ],
      "x-ms-enum": {
        "name": "ReservationStatus",
        "modelAsString": true
      }
    }
  },
  "$defs": {
    "AvailablePhoneNumber": {
      "required": [
        "countryCode",
        "capabilities",
        "phoneNumberType",
        "assignmentType"
      ],
      "type": "object",
      "description": "Represents a phone number available in inventory",
      "properties": {
        "id": {
          "description": "The id of the phone number.",
          "type": "string",
          "readOnly": true
        },
        "countryCode": {
          "description": "The ISO 3166-2 country code, e.g. US.",
          "type": "string"
        },
        "phoneNumber": {
          "description": "The phone number in E.164 format, e.g. +11234567890.",
          "type": "string",
          "readOnly": true
        },
        "capabilities": {
          "$ref": "#/$defs/PhoneNumberCapabilities"
        },
        "phoneNumberType": {
          "description": "Represents the number type of the offering.",
          "enum": [
            "geographic",
            "tollFree",
            "mobile"
          ],
          "type": "string",
          "x-ms-enum": {
            "name": "PhoneNumberType",
            "modelAsString": true
          }
        },
        "assignmentType": {
          "description": "Represents the assignment type of the offering. Also known as the use case.",
          "enum": [
            "person",
            "application"
          ],
          "type": "string",
          "x-ms-enum": {
            "name": "PhoneNumberAssignmentType",
            "modelAsString": true
          }
        },
        "cost": {
          "readOnly": true,
          "type": "object",
          "description": "The incurred cost for this phone number.",
          "allOf": [
            {
              "$ref": "#/$defs/PhoneNumberCost"
            }
          ]
        },
        "status": {
          "readOnly": true,
          "description": "Represents the status of the phone number. Possible values include: 'available', 'reserved', 'expired', 'error', 'purchased'.",
          "type": "string",
          "enum": [
            "available",
            "reserved",
            "expired",
            "error",
            "purchased"
          ],
          "x-ms-enum": {
            "name": "AvailablePhoneNumberStatus",
            "modelAsString": true
          }
        },
        "isAgreementToNotResellRequired": {
          "description": "Indicates if do not resell agreement is required. If true, the phone number cannot be acquired unless the customer provides explicit agreement to not resell it.",
          "type": "boolean",
          "readOnly": true
        },
        "error": {
          "$ref": "#/$defs/AvailablePhoneNumberError"
        }
      }
    },
    "AvailablePhoneNumberError": {
      "readOnly": true,
      "type": "object",
      "description": "Contains error details in case of failure when reserving, releasing or purchasing the phone number. Note that this is ignored by the service when present in requests.",
      "properties": {
        "code": {
          "readOnly": true,
          "type": "string",
          "description": "The error code indicating the reason why the operation performed on the phone number failed."
        },
        "message": {
          "readOnly": true,
          "type": "string",
          "description": "The error message describing the failure that occurred."
        }
      }
    },
    "PhoneNumberCapabilities": {
      "description": "Capabilities of a phone number.",
      "required": [
        "calling",
        "sms"
      ],
      "type": "object",
      "properties": {
        "calling": {
          "description": "Capability value for calling.",
          "enum": [
            "none",
            "inbound",
            "outbound",
            "inbound+outbound"
          ],
          "type": "string",
          "x-ms-enum": {
            "name": "PhoneNumberCapabilityType",
            "modelAsString": true
          }
        },
        "sms": {
          "description": "Capability value for SMS.",
          "enum": [
            "none",
            "inbound",
            "outbound",
            "inbound+outbound"
          ],
          "type": "string",
          "x-ms-enum": {
            "name": "PhoneNumberCapabilityType",
            "modelAsString": true
          }
        }
      }
    },
    "PhoneNumberCost": {
      "description": "The incurred cost for a single phone number.",
      "required": [
        "amount",
        "billingFrequency",
        "currencyCode"
      ],
      "type": "object",
      "properties": {
        "amount": {
          "format": "double",
          "description": "The cost amount.",
          "type": "number"
        },
        "currencyCode": {
          "description": "The ISO 4217 currency code for the cost amount, e.g. USD.",
          "type": "string"
        },
        "billingFrequency": {
          "description": "The frequency with which the cost gets billed.",
          "enum": [
            "monthly"
          ],
          "type": "string",
          "x-ms-enum": {
            "name": "BillingFrequency",
            "modelAsString": true
          }
        }
      }
    }
  }
}