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

# rent a number

> rent a number from the inventory. the first month's rent is taken from the wallet up front, then the KYC goes to the carrier; the rental then moves through `kyc_submitted` → `kyc_accepted` → `purchasing` → `active` (poll `GET /v1/phone-numbers/{number_id}`, its `timeline` says where it is). a short wallet parks the rental in `funding` until auto-pay tops it up.

**with documents** — `multipart/form-data`: a `data` field holding the JSON below and the document `files` in `documents` order (`pdf`, `jpeg` or `png`, 5 MB each). **KYC already verified** (see `verifiedKyc` on the requirements) — a plain JSON body with just `requestedNumber`.



## OpenAPI

````yaml /openapi.json post /v1/phone-numbers
openapi: 3.1.0
info:
  title: silk api
  version: 1.0.0
  description: >-
    rumik ai's speech api. synthesize speech with the expressive `muga` model,
    the faster `mulberry` model or the multilingual `mulberry-1.6` model over
    http or a streaming websocket session, run conversational voice agents over
    webrtc, a realtime pcm socket or the phone, and manage everything the agents
    playground does — agents, voices, variables, tools, phone numbers, sip
    trunks and outbound calls — with the same api key.
  contact:
    name: rumik ai
    url: https://rumik.ai
servers:
  - url: https://silk-api.rumik.ai
    description: production
security:
  - bearerAuth: []
tags:
  - name: speech
    description: text-to-speech over HTTP and WebSocket.
  - name: voice agents
    description: start calls with a deployed agent from your own app.
  - name: agents
    description: build, configure, deploy and inspect your agents.
  - name: calls
    description: place outbound phone calls and read call history.
  - name: voices
    description: the voices, languages and styles an agent may use.
  - name: variables
    description: account-wide `{name}` prompt variables and their defaults.
  - name: tools
    description: HTTP tools agents call before or during a call.
  - name: phone numbers
    description: 'numbers rented through rumik: search, rent, connect, release.'
  - name: sip trunks
    description: bring your own numbers over SIP.
paths:
  /v1/phone-numbers:
    post:
      tags:
        - phone numbers
      summary: rent a number
      description: >-
        rent a number from the inventory. the first month's rent is taken from
        the wallet up front, then the KYC goes to the carrier; the rental then
        moves through `kyc_submitted` → `kyc_accepted` → `purchasing` → `active`
        (poll `GET /v1/phone-numbers/{number_id}`, its `timeline` says where it
        is). a short wallet parks the rental in `funding` until auto-pay tops it
        up.


        **with documents** — `multipart/form-data`: a `data` field holding the
        JSON below and the document `files` in `documents` order (`pdf`, `jpeg`
        or `png`, 5 MB each). **KYC already verified** (see `verifiedKyc` on the
        requirements) — a plain JSON body with just `requestedNumber`.
      operationId: rentPhoneNumber
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RentalRequest'
            examples:
              kyc already verified:
                value:
                  requestedNumber: '918046800123'
                  searchFilters:
                    pattern: '8046'
          multipart/form-data:
            schema:
              type: object
              required:
                - data
              properties:
                data:
                  type: string
                  description: >-
                    the rental as a JSON string — see the `RentalRequest`
                    schema. `endUser` and `documents` are required when files
                    are sent.
                files:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: one file per entry of `documents`, in the same order.
            examples:
              with documents:
                value:
                  data: >-
                    {"requestedNumber": "918046800123", "searchFilters":
                    {"pattern": "8046"}, "endUser": {"name": "Acme Technologies
                    Pvt Ltd", "email": "ops@acme.example", "address_line1": "12
                    MG Road", "city": "Bengaluru", "state": "Karnataka",
                    "postal_code": "560001", "country": "IN"}, "documents":
                    [{"documentTypeId": "certificate_of_incorporation",
                    "dataFields": {"registration_number":
                    "U72900KA2020PTC123456"}}, {"documentTypeId":
                    "gst_certificate", "dataFields": {"gstin":
                    "29ABCDE1234F1Z5"}}]}
                  files:
                    - <certificate.pdf>
                    - <gst.pdf>
      responses:
        '201':
          description: created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RentedNumber'
              examples:
                default:
                  value:
                    id: 019f7d21-3c5f-7e60-9b7c-8d9e0f1a2b3c
                    status: kyc_submitted
                    requestedNumber: '918046800123'
                    number: null
                    e164: null
                    alias: null
                    numberType: local
                    countryIso: IN
                    region: Karnataka
                    city: Bangalore
                    monthlyRentalRateUsd: '2.50000'
                    setupRateUsd: '0.00000'
                    voiceRateUsd: '0.00787'
                    monthlyRentNanos: 236250000000
                    setupNanos: 0
                    voiceRateNanos: 743715000
                    outboundRateUsd: '0.01000'
                    outboundRateNanos: 945000000
                    outboundUnitSeconds: 30
                    prepaidNanos: 236250000000
                    currency: INR
                    rentedAt: null
                    nextRenewalAt: null
                    lastRenewalChargedFor: '2026-09-11T10:30:00Z'
                    renewalAttempts: 0
                    renewalLastError: null
                    releaseReason: null
                    releasedAt: null
                    lastError: null
                    userAgentId: null
                    agentName: null
                    compliance: null
                    timeline:
                      - key: prepaid
                        label: first month's rent deducted
                        state: done
                        at: '2026-09-11T10:00:05Z'
                        detail: null
                      - key: submitted
                        label: documents submitted
                        state: done
                        at: '2026-09-11T10:00:06Z'
                        detail: null
                      - key: verification
                        label: verification
                        state: active
                        at: null
                        detail: null
                      - key: purchase
                        label: number purchase
                        state: pending
                        at: null
                        detail: null
                      - key: active
                        label: number active
                        state: pending
                        at: null
                        detail: null
                    events: []
                    createdAt: '2026-09-11T10:00:00Z'
                    updatedAt: '2026-09-11T10:30:00Z'
        '401':
          description: >-
            `unauthorized` — key missing, malformed, unknown, revoked or
            expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unauthorized:
                  value:
                    error: Invalid API key
                    code: unauthorized
        '402':
          description: >-
            `telephony_autopay_required` — a pay-as-you-go account needs an
            auto-pay mandate before renting.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                telephony_autopay_required:
                  value:
                    error: >-
                      Set up auto-pay for at least the required amount before
                      renting a number
                    code: telephony_autopay_required
        '403':
          description: >-
            `forbidden_scope` — the key was created without the `agent` scope.
            `telephony_account_ineligible` — the account cannot rent: see
            `eligibility.reason` on the requirements.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                forbidden_scope:
                  value:
                    error: This API key lacks the 'agent' scope
                    code: forbidden_scope
                telephony_account_ineligible:
                  value:
                    error: >-
                      Number rental needs a pay-as-you-go or subscription
                      account
                    code: telephony_account_ineligible
        '422':
          description: >-
            `telephony_document_invalid` — a required document type is missing,
            or a file is the wrong type or too large. `invalid_request` — a
            field is missing or malformed. `details` lists every failing field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                telephony_document_invalid:
                  value:
                    error: A document is missing or invalid
                    code: telephony_document_invalid
                invalid_request:
                  value:
                    error: >-
                      body.toNumber: must be an E.164 phone number, e.g.
                      +14155551234
                    code: invalid_request
                    details:
                      - loc: body.toNumber
                        message: must be an E.164 phone number, e.g. +14155551234
        '429':
          description: >-
            `rate_limited` — the key's per-minute budget is spent. `Retry-After`
            says how long to wait; the body carries `limit` and `current`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                rate_limited:
                  value:
                    error: Rate limit exceeded
                    code: rate_limited
                    limit: 100
                    current: 101
          headers:
            Retry-After:
              description: seconds to wait before retrying (per-key rate limit only).
              schema:
                type: integer
        '502':
          description: >-
            `telephony_plivo_error` — the carrier refused the request. safe to
            retry later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                telephony_plivo_error:
                  value:
                    error: The telephony provider rejected the request
                    code: telephony_plivo_error
        '503':
          description: >-
            `telephony_not_configured` — rented numbers are unavailable on this
            deployment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                telephony_not_configured:
                  value:
                    error: Phone number rental is not available right now
                    code: telephony_not_configured
components:
  schemas:
    RentalRequest:
      type: object
      required:
        - requestedNumber
      properties:
        requestedNumber:
          type: string
          example: '918046800123'
          description: >-
            the number to rent, as returned by the search (`number`, bare
            digits, or `e164`).
        searchFilters:
          type: object
          properties:
            pattern:
              type: string
            city:
              type: string
          description: >-
            the filters the number was found with (`pattern`, `city`), so a
            substitute can be picked from the same search if the number is taken
            meanwhile.
        endUser:
          type: object
          properties:
            name:
              type: string
            email:
              type: string
            address_line1:
              type: string
            address_line2:
              type: string
            city:
              type: string
            state:
              type: string
            postal_code:
              type: string
            country:
              type: string
            registration_number:
              type: string
          description: >-
            the business renting the number: `name` (required, the legal name),
            `email`, `address_line1`, `address_line2`, `city`, `state`,
            `postal_code`, `country`, `registration_number`. required when
            documents are sent.
        documents:
          type: array
          items:
            type: object
            required:
              - documentTypeId
            properties:
              documentTypeId:
                type: string
              dataFields:
                type: object
                additionalProperties:
                  type: string
          description: >-
            one entry per required document type from the requirements:
            `documentTypeId` and its `dataFields`. the files go in the multipart
            `files` field, in this order.
      description: >-
        the rental payload — the JSON body, or the `data` field of the multipart
        form.
    RentedNumber:
      properties:
        id:
          type: string
          format: uuid
          description: the rental's id.
        status:
          type: string
          description: >-
            `funding` → `kyc_submitted` → `kyc_accepted` → `purchasing` →
            `awaiting_funds` → `active`; `kyc_rejected`, `past_due`,
            `releasing`, `released`, `failed`.
        requestedNumber:
          anyOf:
            - type: string
            - type: 'null'
          description: what was asked for.
        number:
          anyOf:
            - type: string
            - type: 'null'
          description: the number owned (bare digits), once purchased.
        e164:
          anyOf:
            - type: string
            - type: 'null'
          description: the same in E.164 — what `fromNumber` on `POST /v1/calls` takes.
        alias:
          anyOf:
            - type: string
            - type: 'null'
        numberType:
          type: string
        countryIso:
          type: string
        region:
          anyOf:
            - type: string
            - type: 'null'
        city:
          anyOf:
            - type: string
            - type: 'null'
        monthlyRentalRateUsd:
          anyOf:
            - type: string
            - type: 'null'
        setupRateUsd:
          anyOf:
            - type: string
            - type: 'null'
        voiceRateUsd:
          anyOf:
            - type: string
            - type: 'null'
        monthlyRentNanos:
          anyOf:
            - type: integer
            - type: 'null'
          description: the monthly rent in the wallet's currency, in nanos (billionths).
        setupNanos:
          anyOf:
            - type: integer
            - type: 'null'
          description: one-off setup fee, nanos.
        voiceRateNanos:
          anyOf:
            - type: integer
            - type: 'null'
          description: inbound per-minute carrier rate, nanos.
        outboundRateUsd:
          anyOf:
            - type: string
            - type: 'null'
        outboundRateNanos:
          anyOf:
            - type: integer
            - type: 'null'
          description: >-
            outbound per-minute carrier rate, nanos, billed per
            `outboundUnitSeconds`.
        outboundUnitSeconds:
          anyOf:
            - type: integer
            - type: 'null'
          description: the outbound billing pulse (30 s for India).
        prepaidNanos:
          type: integer
          default: 0
          description: the first charge collected before the KYC went out.
        currency:
          type: string
          description: the wallet's currency (`INR`).
        rentedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          description: when the number was purchased.
        nextRenewalAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          description: when the next month's rent is due.
        lastRenewalChargedFor:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
        renewalAttempts:
          type: integer
          default: 0
        renewalLastError:
          anyOf:
            - type: string
            - type: 'null'
        releaseReason:
          anyOf:
            - type: string
            - type: 'null'
          description: why it was released (`user`, `non_payment`, …).
        releasedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
        lastError:
          anyOf:
            - type: string
            - type: 'null'
          description: the last carrier or billing error, if any.
        userAgentId:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          description: the agent connected to the number, or null.
        agentName:
          anyOf:
            - type: string
            - type: 'null'
          description: that agent's name.
        compliance:
          anyOf:
            - $ref: '#/components/schemas/ComplianceApplication'
            - type: 'null'
          description: >-
            the KYC application: `status`, `rejectionReason`, `attempts`,
            history.
        timeline:
          items:
            $ref: '#/components/schemas/TimelineStep'
          type: array
          description: >-
            the rental's progress, step by step: `key`, `label`, `state` (`done`
            | `active` | `pending` | `failed`), `at`, `detail`.
        events:
          items:
            additionalProperties: true
            type: object
          type: array
          description: the raw event log.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      type: object
      required:
        - id
        - status
        - numberType
        - countryIso
        - currency
        - timeline
        - events
        - createdAt
        - updatedAt
      title: RentedNumber
      description: a number rented through rumik, with its lifecycle.
    Error:
      type: object
      properties:
        error:
          type: string
          description: human-readable error message.
        code:
          type: string
          description: machine-readable error code.
    ComplianceApplication:
      properties:
        id:
          type: string
          format: uuid
        plivoComplianceId:
          anyOf:
            - type: string
            - type: 'null'
        status:
          type: string
        rejectionReason:
          anyOf:
            - type: string
            - type: 'null'
        alias:
          type: string
        endUser:
          additionalProperties: true
          type: object
        documents:
          items:
            additionalProperties: true
            type: object
          type: array
        attempts:
          type: integer
        submittedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
        decidedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
        history:
          items:
            additionalProperties: true
            type: object
          type: array
      type: object
      required:
        - id
        - status
        - alias
        - endUser
        - documents
        - attempts
        - history
      title: ComplianceApplication
    TimelineStep:
      properties:
        key:
          type: string
        label:
          type: string
        state:
          type: string
          enum:
            - done
            - active
            - pending
            - failed
        at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
        detail:
          anyOf:
            - type: string
            - type: 'null'
      type: object
      required:
        - key
        - label
        - state
      title: TimelineStep
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        your rumik api key, e.g. `rk_live_...`. create one in the rumik
        dashboard.

````