> ## Documentation Index > Fetch the complete documentation index at: https://telnesstech-a0a16404.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Lease phone numbers > Reserve phone numbers from inventory for use in orders. This allows customers to choose specific numbers before completing their order. **Availability**: This feature is part of our premium number selection offering and may not be available for all product offerings. Check the response for availability information. **Usage Flow**: 1. Lease numbers to get a lease token 2. Use the lease token and chosen msisdn in subscription line items 3. Numbers are automatically released if not used before expiry **Important**: Leased numbers expire after a short time (typically 1 hour) to prevent inventory hoarding. ## OpenAPI ````yaml /api-reference/bundled_openapi.json post /inventory/lease-numbers openapi: 3.1.0 info: title: Telness Tech Connect version: 2.0.0-alpha description: > Telness Tech Connect API provides all you need to own your user's connectivity experience. Go back to [Telnesstech.com](https://telnesstech.com) servers: - url: https://apiv2.example.com description: Connect API URL for your domain security: - apiKey: [] - bearerAuth: [] apiKey: [] tags: - name: Auth description: Authenticate users and obtain access tokens. - name: Users description: Manage users. - name: Customers description: Manage customers. - name: Subscriptions description: Manage subscriptions and subscription. - name: Subscription Addons description: Manage subscription addons. - name: Subscription Usage description: Get subscription usage. - name: Subscribers description: Manage subscribers. - name: Licenses description: Manage licenses. - name: Product Offerings description: Browse product offerings. - name: Product Catalogs description: Browse product catalogs. - name: Product Discounts description: Discounts and promotions. - name: Orders description: Manage orders and line items. - name: Payment Intents description: >- Inspect payment intents, the money collected over card rails for orders and renewals. - name: Payment Links description: Create and manage payment links for orders and invoices. - name: Payment Sessions description: Create and manage payment sessions for orders. - name: Payment Profiles description: Manage customer payment profiles and methods. - name: Payment Profile Sessions description: Create sessions for setting up payment profiles. - name: Signing sessions description: Handle contract signing sessions for postpaid orders. - name: Porting description: Manage number porting for subscriptions. - name: Taxes description: Calculate taxes for products and line items. - name: Invoices description: Manage invoices and invoice items. - name: Tools description: >- Tools for address validation, number porting, device info, and network coverage. - name: Inventory description: Manage phone number inventory, SIM cards, and reservations. - name: Workflows description: Dynamic processing of customer journeys and events. paths: /inventory/lease-numbers: post: tags: - Inventory summary: Lease phone numbers description: > Reserve phone numbers from inventory for use in orders. This allows customers to choose specific numbers before completing their order. **Availability**: This feature is part of our premium number selection offering and may not be available for all product offerings. Check the response for availability information. **Usage Flow**: 1. Lease numbers to get a lease token 2. Use the lease token and chosen msisdn in subscription line items 3. Numbers are automatically released if not used before expiry **Important**: Leased numbers expire after a short time (typically 1 hour) to prevent inventory hoarding. operationId: leaseNumbers parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LeaseNumbersRequest' responses: '200': description: Numbers leased successfully. content: application/json: schema: $ref: '#/components/schemas/NumberLeaseResult' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' description: >- Not enough numbers available or number leasing not available for this product offering. '500': $ref: '#/components/responses/InternalServerError' components: parameters: IdempotencyKey: in: header name: X-Idempotency-Key required: false description: > A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. schema: type: string maxLength: 256 schemas: LeaseNumbersRequest: type: object description: Request to lease phone numbers for use in orders. required: - types - count additionalProperties: false properties: types: type: array description: Types of numbers to lease. items: $ref: '#/components/schemas/NumberType' example: - CELL count: type: integer minimum: 1 maximum: 10 description: Number of phone numbers to lease. example: 2 NumberLeaseResult: type: object description: Result of a number leasing request. required: - numbers - leaseToken - expiresAt additionalProperties: false properties: numbers: type: array description: The leased phone numbers. items: $ref: '#/components/schemas/LeasedNumber' leaseToken: type: string description: > Token to use when creating subscription line items with these numbers. Provide this token in the `leaseToken` field when ordering or creating a subscription along with the chosen `msisdn` from the leased numbers. example: lease_abc123def456 expiresAt: type: string format: date-time description: When this lease expires if not used in an order. example: '2024-01-15T11:30:00Z' NumberType: type: string enum: - CELL - FIXED - DATA - M2M description: The type of phone number for different use cases. example: CELL LeasedNumber: type: object description: A phone number that has been leased for use in orders. required: - msisdn - type - grade - expiresAt additionalProperties: false properties: msisdn: type: string format: phone description: The leased phone number. example: '+15551234567' type: $ref: '#/components/schemas/NumberType' grade: type: integer minimum: 1 maximum: 10 description: Quality grade of the number (1=premium, 10=standard). example: 5 availableAt: type: string format: date-time description: When this number became available for leasing. example: '2024-01-15T10:00:00Z' leasedAt: type: string format: date-time description: When this number was leased. example: '2024-01-15T10:30:00Z' expiresAt: type: string format: date-time description: When this lease expires if not used in an order. example: '2024-01-15T11:30:00Z' metadata: type: object description: Additional number metadata. additionalProperties: type: string example: region: New York areaCode: '555' Error: type: object required: - message - code properties: message: type: string description: A human-readable message providing more details about the error. code: type: string description: A machine-readable code for the error. details: type: array description: Additional details about the error. items: type: object required: - message - code properties: message: type: string description: >- A human-readable message providing more details about the error. code: type: string description: A machine-readable code for the specific detail. property: type: string description: The property or field related to the error. suggestion: $ref: '#/components/schemas/Any' description: > A suggested value for the particular property. For example, this may be set when validating an address with an alias, suggesting the expected value by the operator. hint: type: string description: A hint to help resolve the error. Any: oneOf: - type: string - type: number - type: boolean - type: object additionalProperties: true - type: array responses: BadRequest: description: The request was malformed or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Authentication is required to access this resource. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: Access to this resource is forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: The requested resource was not found. content: application/json: schema: $ref: '#/components/schemas/Error' Conflict: description: Conflict content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: An unexpected error occurred on the server. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: apiKey: type: apiKey in: header name: X-Api-Key description: > An API key that grants access to the Connect API. You can create and manage API keys in the portal. bearerAuth: type: http scheme: bearer bearerFormat: JWT description: > Bearer authentication with JWT tokens is used to authenticate users. Do note that a valid API keys is also required to access the Connect API to prove that requests are made by a trusted party. Requests with a JWT token is scoped to the permissions of the user the token belongs to, regardless of the API key used. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.