> ## Documentation Index > Fetch the complete documentation index at: https://docs.mobilerun.ai/llms.txt > Use this file to discover all available pages before exploring further. # Import a BYO (tenant-supplied) physical eSIM activation code > Registers a bring-your-own (BYO) eSIM activation code as owned inventory. Provide either `{ smdpAddress, matchingId?, confirmationCode? }` or `{ lpaCode }` — supplying both, or neither, returns 400. An optional `name` sets a display label on the created eSIM (up to 15 characters). Subject to per-owner and daily import limits, and disabled entirely unless BYO imports are enabled for this deployment (409 `byo_disabled`). Idempotent via `idempotencyKey`: replaying the same key with an identical request returns the original response; the same key with a different request returns 409 `idempotency_conflict`. When rent-first billing is off (default), the import is free — 201 with the eSIM. Setting `autoInstall: true` additionally dispatches an install immediately after import (`deviceId` may only be set together with `autoInstall`): this returns 202 with `{esim, operationId, statusUrl}` when the install claim succeeds (poll `GET /esims/{id}/install-status`), or 201 with the eSIM plus `installDispatch: {ok: false, reason}` when the install could not be dispatched — the import itself still succeeds either way. When rent-first billing is on, import additionally requires available device capacity (409 `device_pool_empty`) and is subject to a per-owner awaiting-payment cap (409 `byo_awaiting_payment_cap`). On success the eSIM is created `awaiting_payment` and a checkout is started: 201 with `{esim, rentStatus, checkoutUrl}` when the checkout URL is ready immediately, or 202 with `checkoutUrl: null` otherwise — poll `GET /esims/{id}` until it's populated. Once payment is confirmed, install is triggered automatically. ## OpenAPI ````yaml /api-reference/mobilerun-numbers.yaml post /numbers/esims/import openapi: 3.1.0 info: title: Mobilerun Numbers version: v1 servers: - description: Droidrun Cloud API url: https://api.mobilerun.ai/v1 security: - bearerAuth: [] paths: /numbers/esims/import: post: tags: - Esims summary: Import a BYO (tenant-supplied) physical eSIM activation code description: >- Registers a bring-your-own (BYO) eSIM activation code as owned inventory. Provide either `{ smdpAddress, matchingId?, confirmationCode? }` or `{ lpaCode }` — supplying both, or neither, returns 400. An optional `name` sets a display label on the created eSIM (up to 15 characters). Subject to per-owner and daily import limits, and disabled entirely unless BYO imports are enabled for this deployment (409 `byo_disabled`). Idempotent via `idempotencyKey`: replaying the same key with an identical request returns the original response; the same key with a different request returns 409 `idempotency_conflict`. When rent-first billing is off (default), the import is free — 201 with the eSIM. Setting `autoInstall: true` additionally dispatches an install immediately after import (`deviceId` may only be set together with `autoInstall`): this returns 202 with `{esim, operationId, statusUrl}` when the install claim succeeds (poll `GET /esims/{id}/install-status`), or 201 with the eSIM plus `installDispatch: {ok: false, reason}` when the install could not be dispatched — the import itself still succeeds either way. When rent-first billing is on, import additionally requires available device capacity (409 `device_pool_empty`) and is subject to a per-owner awaiting-payment cap (409 `byo_awaiting_payment_cap`). On success the eSIM is created `awaiting_payment` and a checkout is started: 201 with `{esim, rentStatus, checkoutUrl}` when the checkout URL is ready immediately, or 202 with `checkoutUrl: null` otherwise — poll `GET /esims/{id}` until it's populated. Once payment is confirmed, install is triggered automatically. operationId: importEsim requestBody: content: application/json: schema: $ref: '#/components/schemas/ImportEsimInput' responses: '201': content: application/json: schema: properties: data: anyOf: - $ref: '#/components/schemas/PublicEsim' - $ref: '#/components/schemas/EsimAwaitingPaymentResponse' - $ref: >- #/components/schemas/EsimImportInstallDispatchFailedResponse required: - data type: object description: >- eSIM imported — plain eSIM, an inline-resolved rent checkout, or an eSIM with a failed autoInstall dispatch '202': content: application/json: schema: properties: data: anyOf: - $ref: '#/components/schemas/EsimAwaitingPaymentResponse' - $ref: '#/components/schemas/EsimInstallPendingResponse' required: - data type: object description: >- Import accepted but not yet resolved. With rent-first billing on, the checkout URL isn't ready yet — poll `GET /esims/{id}` (no `Retry-After`). With `autoInstall: true`, the install was dispatched — poll `GET /esims/{id}/install-status` (`Retry-After: 5`). Distinguish by shape: `rentStatus`+`checkoutUrl` (rent checkout) vs. `operationId`+`statusUrl` (install pending). headers: Retry-After: description: >- Present only on the install-pending response (autoInstall dispatched); absent on the rent-checkout response. required: false schema: description: >- Present only on the install-pending response (autoInstall dispatched); absent on the rent-checkout response. example: '5' type: string '400': description: Bad Request '401': description: Unauthorized '409': content: application/json: schema: $ref: '#/components/schemas/EsimErrorResponse' description: Conflict — see `reason` for the stable, machine-readable cause '500': description: Internal Server Error '503': content: application/json: schema: $ref: '#/components/schemas/EsimErrorResponse' description: >- Service Unavailable — esims are disabled for this deployment (see `reason`) x-codeSamples: - lang: JavaScript source: |- import Mobilerun from '@mobilerun/sdk'; const client = new Mobilerun({ apiKey: process.env['MOBILERUN_CLOUD_API_KEY'], // This is the default and can be omitted }); const response = await client.esims.import(); console.log(response.data); - lang: Python source: |- import os from mobilerun_sdk import Mobilerun client = Mobilerun( api_key=os.environ.get("MOBILERUN_CLOUD_API_KEY"), # This is the default and can be omitted ) response = client.esims.import_() print(response.data) components: schemas: ImportEsimInput: properties: autoInstall: description: >- Rent OFF only: dispatch install-on-device immediately after a successful import. No-op when ESIM_BYO_RENT_ENABLED=true. type: boolean carrierName: maxLength: 100 type: string confirmationCode: maxLength: 128 type: string countryCode: maxLength: 8 type: string deviceId: description: >- physedge device id to auto-install onto; requires autoInstall:true and rent OFF. Omit for a random pool device. example: physedge-dev-8f3a2c minLength: 1 type: string idempotencyKey: description: >- Client-supplied key; replaying the same key+request returns the original import instead of importing again maxLength: 128 minLength: 1 type: string lpaCode: description: Full LPA activation code example: LPA:1$smdp.example.com$QR-MATCH-1 maxLength: 512 type: string matchingId: maxLength: 128 type: string msisdn: description: >- Self-reported E.164 MSISDN for this eSIM's line — an unverified label, never used for routing example: '+33612345678' maxLength: 20 minLength: 1 type: string name: description: >- User-defined display label — NFC-normalized, up to 15 GRAPHEMES (not UTF-16 code units; an emoji/flag may span several). Omit/null/empty/whitespace-only leaves it unset. example: Mom's phone type: - string - 'null' notes: maxLength: 500 type: string smdpAddress: description: SM-DP+ activation host — bare hostname ONLY, no port/scheme/path. example: smdp.example.com maxLength: 255 type: string type: object PublicEsim: properties: cancellationScheduled: type: boolean carrierName: type: - string - 'null' checkoutUrl: type: - string - 'null' countryCode: type: - string - 'null' createdAt: format: date-time type: - string - 'null' createdBy: type: - string - 'null' currentPeriodEnd: format: date-time type: - string - 'null' deviceId: format: uuid type: - string - 'null' deviceUuid: type: - string - 'null' exempt: type: boolean iccid: type: - string - 'null' id: format: uuid type: string msisdn: type: - string - 'null' name: type: - string - 'null' networkStatus: enum: - degraded - null type: - string - 'null' rentStatus: enum: - not_applicable - exempt - inactive - awaiting_payment - active - cancel_pending - refund_pending - retiring - billing_error type: string source: enum: - stocked - byo type: string status: enum: - in_stock - owned - installing - installed - install_failed - retired type: string subscriptionId: type: - integer - 'null' updatedAt: format: date-time type: - string - 'null' required: - id - status - source - carrierName - countryCode - iccid - subscriptionId - deviceId - deviceUuid - msisdn - name - createdBy - networkStatus - createdAt - updatedAt type: object EsimAwaitingPaymentResponse: properties: checkoutUrl: type: - string - 'null' esim: $ref: '#/components/schemas/PublicEsim' rentStatus: enum: - awaiting_payment type: string required: - esim - rentStatus - checkoutUrl type: object EsimImportInstallDispatchFailedResponse: allOf: - $ref: '#/components/schemas/PublicEsim' - properties: installDispatch: properties: ok: enum: - false type: boolean reason: type: string required: - ok - reason type: object required: - installDispatch type: object EsimInstallPendingResponse: properties: esim: $ref: '#/components/schemas/PublicEsim' operationId: type: - string - 'null' statusUrl: type: string required: - esim - operationId - statusUrl type: object EsimErrorResponse: properties: message: type: string reason: enum: - out_of_stock - owner_esim_cap - byo_disabled - byo_esim_cap - byo_daily_import_limit - byo_failed_limit - esim_not_owned - device_pool_empty - device_claim_cap - operator_resolution_required - idempotency_conflict - byo_awaiting_payment_cap - operator_review_required - byo_not_reassignable - product_disabled type: string success: enum: - false type: boolean required: - success - reason - message type: object securitySchemes: bearerAuth: bearerFormat: Opaque description: Bearer token via Authorization header scheme: bearer type: http ````