{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"7f5f6235-b91d-430f-8cce-454ba18aa45c","name":"Telzen Partner","description":"# Telzen Partner API\n\nThe **Telzen Partner API** provides a comprehensive suite of endpoints for managing eSIM and physical SIM products, orders, and account operations. This API is designed for authorized partners to integrate Telzen's connectivity solutions into their own platforms.\n\n---\n\n## Base URL\n\nAll requests are made relative to the base URL stored in the `{{base_url}}` environment variable.\n\n---\n\n## Authentication\n\nEvery request to the Telzen Partner API **requires authentication** via an API key. The API key must be included in the request header as follows:\n\n| Header | Value |\n| --- | --- |\n| `x-api-key` | `{{api_key}}` |\n\nThe `{{api_key}}` variable is stored in the active environment. Requests made without a valid API key will be rejected with a `401 Unauthorized` response.\n\n---\n\n## Response Format\n\nAll API responses follow a consistent JSON structure:\n\n``` json\n{\n  \"status_code\": 200,\n  \"success\": true,\n  \"message\": \"Operation completed successfully.\",\n  \"meta\": { ... },\n  \"data\": { ... }\n}\n\n ```\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `status_code` | integer | The HTTP status code of the response. |\n| `success` | boolean | `true` if the operation succeeded, `false` otherwise. |\n| `message` | string | A human-readable description of the result. |\n| `meta` | object | null | Pagination metadata for list endpoints; `null` for single-resource endpoints. |\n| `data` | object | array | null | The response payload. |\n\n---\n\n## Pagination\n\nList endpoints support pagination via query parameters:\n\n| Parameter | Type | Default | Description |\n| --- | --- | --- | --- |\n| `page` | integer | `1` | The page number to retrieve. |\n| `limit` | integer | `10` | The number of records to return per page. |\n\nPaginated responses include a `meta` object:\n\n``` json\n\"meta\": {\n  \"total_items\": 100,\n  \"total_pages\": 10,\n  \"current_page\": 1,\n  \"page_size\": 10,\n  \"has_next_page\": true,\n  \"has_previous_page\": false\n}\n\n ```\n\n---\n\n## Endpoints Overview\n\n### Account\n\n| Method | Endpoint | Description |\n| --- | --- | --- |\n| `GET` | `/balance` | Retrieve the current account balance for the authenticated partner. |\n\n### Geography\n\n| Method | Endpoint | Description |\n| --- | --- | --- |\n| `GET` | `/country` | Retrieve a paginated list of supported countries. Supports optional `search` filtering. |\n| `GET` | `/region` | Retrieve a paginated list of supported regions. |\n\n### Packages\n\n| Method | Endpoint | Description |\n| --- | --- | --- |\n| `GET` | `/package/esim` | Retrieve a list of available eSIM packages. Filter by `coverage_type` (e.g., `country`). |\n| `GET` | `/package/esim/single/:uid` | Retrieve details of a specific eSIM package by its unique identifier. |\n| `GET` | `/package/esim/topup/:iccid` | Retrieve available top-up packages for an existing eSIM by ICCID. |\n| `GET` | `/package/physical` | Retrieve a paginated list of available physical SIM packages. |\n| `GET` | `/package/physical/single/:uid` | Retrieve details of a specific physical SIM package by its unique identifier. |\n| `GET` | `/package/physical/topup/:iccid` | Retrieve available top-up packages for an existing physical SIM by ICCID. |\n\n### Orders\n\n| Method | Endpoint | Description |\n| --- | --- | --- |\n| `POST` | `/order/create` | Create a new order for an eSIM or physical SIM. Supports `new` and `top-up` order types. |\n\n### SIM Management\n\n| Method | Endpoint | Description |\n| --- | --- | --- |\n| `GET` | `/sim/esim/profile/:iccid` | Retrieve the profile details of a specific eSIM by ICCID. |\n| `GET` | `/sim/esim/usage/:iccid` | Retrieve the data usage details of a specific eSIM by ICCID. |\n| `GET` | `/sim/physical/profile/:iccid` | Retrieve the profile details of a specific physical SIM by ICCID. |\n\n---\n\n## HTTP Status Codes\n\nThe Telzen Partner API uses standard HTTP status codes to indicate the outcome of every request.\n\n### Success Codes\n\n| Code | Status | Description |\n| --- | --- | --- |\n| `200` | OK | The request was successful. The response body contains the requested data or confirmation of the operation. |\n| `201` | Created | A new resource was successfully created (e.g., a new order). |\n\n### Client Error Codes\n\n| Code | Status | Description |\n| --- | --- | --- |\n| `400` | Bad Request | The request was malformed or contained invalid parameters. Check the request body, query parameters, or path variables. |\n| `401` | Unauthorized | Authentication failed. The `x-api-key` header is missing, invalid, or expired. |\n| `403` | Forbidden | The authenticated partner does not have permission to perform this action. |\n| `404` | Not Found | The requested resource does not exist. This may occur when an invalid `iccid`, package `uid`, or endpoint path is provided. |\n| `409` | Conflict | The request conflicts with the current state of the resource (e.g., attempting to create a duplicate order). |\n| `422` | Unprocessable Entity | The request was well-formed but contained semantic errors. The server understands the content type but cannot process the instructions. |\n| `429` | Too Many Requests | The rate limit has been exceeded. Slow down the request frequency and retry after the indicated period. |\n\n### Server Error Codes\n\n| Code | Status | Description |\n| --- | --- | --- |\n| `500` | Internal Server Error | An unexpected error occurred on the server. If this persists, contact Telzen support. |\n| `502` | Bad Gateway | The server received an invalid response from an upstream service. |\n| `503` | Service Unavailable | The server is temporarily unavailable, likely due to maintenance or overload. Retry after a short delay. |\n\n---\n\n## Error Response Format\n\nWhen an error occurs, the API returns a structured error response:\n\n``` json\n{\n  \"status_code\": 400,\n  \"success\": false,\n  \"message\": \"Invalid request parameters.\",\n  \"meta\": null,\n  \"data\": null\n}\n\n ```\n\n---\n\n## Path Parameters\n\nSeveral endpoints use path parameters to identify specific resources:\n\n| Parameter | Format | Example | Description |\n| --- | --- | --- | --- |\n| `:iccid` | Numeric string | `8948010010013836761` | The Integrated Circuit Card Identifier of a SIM card. |\n| `:uid` | Alphanumeric string | `TZPK_20260010` | The unique identifier of a package or order. |\n\n---\n\n## Environment Variables\n\nThis collection uses the following environment variables. Configure them in the active Postman environment before sending requests.\n\n| Variable | Description |\n| --- | --- |\n| `base_url` | The base URL of the Telzen Partner API (e.g., `https://api.telzen.com/v1/`). |\n| `api_key` | Your Telzen Partner API key, sent as the `x-api-key` header on every request. |\n\n---\n\n## Getting Started\n\n1. Set the `base_url` and `api_key` variables in your active environment.\n    \n2. Send a `GET /balance` request to verify your credentials and check your account balance.\n    \n3. Use `GET /country` or `GET /region` to explore available coverage areas.\n    \n4. Browse packages using the `/package/esim` or `/package/physical` endpoints.\n    \n5. Place an order using `POST /order/create` with the appropriate payload.\n    \n6. Monitor your SIM cards using the `/sim/esim/profile/:iccid` and `/sim/esim/usage/:iccid` endpoints.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"29709389","team":5558656,"collectionId":"7f5f6235-b91d-430f-8cce-454ba18aa45c","publishedId":"2sBXwyGSMM","public":true,"publicUrl":"https://documenter-api.postman.tech/view/29709389/2sBXwyGSMM","privateUrl":"https://go.postman.co/documentation/29709389-7f5f6235-b91d-430f-8cce-454ba18aa45c","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":"Create a custom sales experience with our API."},{"name":"title","value":""}],"appearance":{"default":"dark","themes":[{"name":"dark","logo":"https://content.pstmn.io/abb1a10f-8fcc-411c-9b40-48006cc23a02/c2hhcGUucG5n","colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"FF6C37"}},{"name":"light","logo":"https://content.pstmn.io/abb1a10f-8fcc-411c-9b40-48006cc23a02/c2hhcGUucG5n","colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"}}]}},"version":"8.12.3","publishDate":"2026-06-28T06:04:40.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":"Create a custom sales experience with our API."},"logos":{"logoLight":"https://content.pstmn.io/abb1a10f-8fcc-411c-9b40-48006cc23a02/c2hhcGUucG5n","logoDark":"https://content.pstmn.io/abb1a10f-8fcc-411c-9b40-48006cc23a02/c2hhcGUucG5n"}},"statusCode":200},"environments":[{"name":"Telzen Partner","id":"280c73f6-f72f-4f56-895b-e355ebca53e5","owner":"29709389","values":[{"key":"api_key","value":"","enabled":true,"type":"default"}],"published":true}],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/8b40d5e23f434014c574a1e19ab2196c1c225b90130895d03a2930aedd0d699e","favicon":""},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"},{"label":"Telzen Partner","value":"29709389-280c73f6-f72f-4f56-895b-e355ebca53e5"}],"canonicalUrl":"https://documenter.gw.postman.com/view/metadata/2sBXwyGSMM"}