> ## 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. # Create subscription > Create a new subscription for a customer. **Activation Modes:** 1. **Immediate Activation** - Provide complete activation data in the request - Omit scheduleActivationAt or set to today's date - Subscription activates immediately (network availability permitting) 2. **Scheduled Activation** - Provide complete activation data in the request - Set scheduleActivationAt to a future date - Subscription activates on or after the specified date 3. **Deferred Activation (Shell Subscription)** - Omit activation data from the request - Subscription created in PENDING state - Use the activate endpoint later when activation details are available **Common use cases:** - Standard activation: Customer has all details ready (number choice, SIM type, porting info) - Scheduled activation: Activate on a specific date (e.g., start of billing cycle, go-live date) - Shell subscription: Bulk subscription creation, waiting for SIM delivery, phased onboarding **Note**: This endpoint may be disabled when Seamless OS manages billing. In that configuration, subscriptions are created through the orders endpoint instead. ## OpenAPI ````yaml /api-reference/bundled_openapi.json post /subscriptions 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: /subscriptions: post: tags: - Subscriptions summary: Create subscription description: > Create a new subscription for a customer. **Activation Modes:** 1. **Immediate Activation** - Provide complete activation data in the request - Omit scheduleActivationAt or set to today's date - Subscription activates immediately (network availability permitting) 2. **Scheduled Activation** - Provide complete activation data in the request - Set scheduleActivationAt to a future date - Subscription activates on or after the specified date 3. **Deferred Activation (Shell Subscription)** - Omit activation data from the request - Subscription created in PENDING state - Use the activate endpoint later when activation details are available **Common use cases:** - Standard activation: Customer has all details ready (number choice, SIM type, porting info) - Scheduled activation: Activate on a specific date (e.g., start of billing cycle, go-live date) - Shell subscription: Bulk subscription creation, waiting for SIM delivery, phased onboarding **Note**: This endpoint may be disabled when Seamless OS manages billing. In that configuration, subscriptions are created through the orders endpoint instead. operationId: createSubscription parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSubscription' responses: '201': description: The created subscription. content: application/json: schema: $ref: '#/components/schemas/Subscription' '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' '429': $ref: '#/components/responses/TooManyRequests' '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: CreateSubscription: type: object description: > Create a new subscription for a customer. **Activation Options:** 1. **Immediate activation**: Provide activation data without scheduleActivationAt 2. **Scheduled activation**: Provide activation data with scheduleActivationAt for future activation 3. **Shell subscription**: Omit activation data to create a subscription that will be activated later **When to use shell subscriptions:** - When activation details are not yet available (e.g., waiting for SIM card delivery) - When activation requires additional approval or processing - When bulk-creating subscriptions for later activation Note: This endpoint is disabled when Seamless OS manages billing. In that case, subscriptions are created through orders. required: - productOfferingId - customerId - subscriber additionalProperties: false properties: productOfferingId: type: string description: | The unique identifier for the product offering to subscribe to. This controls what type of subscription is being created. customerId: type: string description: > The identifier of the existing customer who will own this subscription. Accepts either an internal UUID or an external referenceId previously assigned to the customer. referenceId: type: string description: > Optional reference ID to assign to the subscription. Must be unique per tenant. Once set, this value can be used in place of the subscriptionId in path parameters and request bodies across the API. example: crm-subscription-12345 maxLength: 255 activation: allOf: - $ref: '#/components/schemas/SubscriptionActivation' - type: object description: > Activation configuration for this subscription. **When to provide:** - Provide activation details to create an active subscription immediately or scheduled for the future - Omit to create a "shell" subscription that must be activated later via the activate endpoint **Use cases:** - **Immediate activation**: Provide activation data without scheduleActivationAt - **Scheduled activation**: Provide activation data with scheduleActivationAt set to a future date - **Deferred activation**: Omit activation data entirely - use the activate endpoint later when ready scheduleActivationAt: type: string format: date x-ogen-type: telnesstech.com/apiv2/apiv2types.Date description: > Date when the subscription should be activated in the network. Only applicable when activation data is provided. If omitted, activation will be immediate or as soon as network resources are available. **Note**: Network availability and porting timelines may affect the exact activation time. This date is a preference, not a guarantee. example: '2024-01-15' extensions: type: object description: >- Additional subscription extensions fields for custom subscription types. additionalProperties: type: string display: type: string description: >- Custom display name for the subscription. If not provided, will be auto-generated from msisdn. subscriber: type: object description: Subscriber details for this subscription. required: - name properties: name: type: string description: The full name of the subscriber. example: John Doe email: type: string format: email description: The email address of the subscriber. example: john.doe@example.com address: $ref: '#/components/schemas/Address' metadata: $ref: '#/components/schemas/Metadata' metadata: $ref: '#/components/schemas/Metadata' Subscription: type: object description: >- A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details. required: - subscriptionId - status - type - display - msisdn - sim - customer - activatedAt - createdAt - updatedAt properties: subscriptionId: type: string description: The unique identifier for the subscription. referenceId: type: string description: > A reference identifier provided by API clients to identify this subscription in their own systems. Must be unique per tenant. Use this field to look up subscriptions by your external identifier or to create/retrieve subscriptions during order creation. example: crm-subscription-12345 maxLength: 255 status: $ref: '#/components/schemas/SubscriptionStatus' type: $ref: '#/components/schemas/SubscriptionType' display: type: string description: >- The display name for the subscription, typically a pretty-print of the msisdn. msisdn: type: string description: The currently active phone number for this subscription. customer: $ref: '#/components/schemas/EmbeddedCustomer' productOffering: $ref: '#/components/schemas/EmbeddedProductOffering' subscriber: $ref: '#/components/schemas/EmbeddedSubscriber' extensions: type: object description: >- Additional subscription extensions fields provided for custom subscription types. additionalProperties: type: string sim: type: object description: > SIM card information for the subscription. Sensitive details like PUK require separate API calls. Use dedicated SIM API endpoints with proper authorization to access sensitive information such as PUK. required: - esim properties: esim: type: boolean description: Indicates whether the subscription uses eSIM technology. imei: type: string description: > International Mobile Equipment Identity, uniquely identifying the mobile device. Only applicable for eSIM. iccid: type: string description: >- Integrated Circuit Card identifier, uniquely identifying the SIM card. pendingMsisdn: type: object description: >- Details about when a pending phone number change is scheduled for this subscription. properties: msisdn: type: string description: >- The pending phone number for this subscription, if a number change is scheduled. scheduledAt: type: string format: date x-ogen-type: telnesstech.com/apiv2/apiv2types.Date description: >- The date when the pending change (e.g., number change) is scheduled to occur. pendingStatus: type: object description: >- Details about when a pending status change is scheduled for this subscription. properties: status: $ref: '#/components/schemas/SubscriptionStatus' scheduledAt: type: string format: date x-ogen-type: telnesstech.com/apiv2/apiv2types.Date description: The date when the pending status change is scheduled to occur. pendingProductOffering: type: object description: Pending product offering change. required: - scheduledAt - product properties: scheduledAt: type: string format: date x-ogen-type: telnesstech.com/apiv2/apiv2types.Date description: >- The date when the pending product offering change is scheduled to occur. product: $ref: '#/components/schemas/EmbeddedProductOffering' porting: $ref: '#/components/schemas/EmbeddedPorting' activatedAt: type: string format: date-time description: The date and time when the subscription was activated. cancelledAt: type: string format: date-time description: >- The date and time when the subscription was cancelled (if applicable). createdAt: type: string format: date-time description: The date and time when the subscription was created. updatedAt: type: string format: date-time description: The date and time when the subscription was last updated. metadata: $ref: '#/components/schemas/Metadata' SubscriptionActivation: type: object description: > Configuration and details required to activate a subscription in the telecommunications network. This includes the phone number (MSISDN), SIM card details, and optional number porting information. All subscriptions require this activation data before they can be used for telecommunications services. additionalProperties: false required: - sim properties: msisdn: type: string description: > The phone number for this subscription. - Leave empty to have a number automatically assigned from the available pool - Provide a specific number when using a leased number from the number pool - Provide the number to be ported when transferring from another carrier example: '+15551234567' leaseToken: type: string description: > Token received when leasing a number from the available number pool. Required only when providing a specific msisdn that was leased from the number pool. Not needed for auto-assigned numbers or ported numbers. porting: type: object description: > Details required to port (transfer) an existing phone number from another carrier. Provide this when the subscriber wants to keep their existing phone number. The porting process may take several days depending on the carrier and regulatory requirements. required: - details properties: details: $ref: '#/components/schemas/PortingDetails' sim: type: object description: SIM card technology and configuration for this subscription. required: - esim additionalProperties: false properties: esim: type: boolean description: | Whether this subscription uses eSIM (embedded SIM) technology. - true: Digital eSIM profile will be provisioned to the device - false: Physical SIM card will be used example: true imei: type: string description: > International Mobile Equipment Identity (IMEI) of the device. Required for eSIM activation on some networks to bind the eSIM profile to a specific device. Not needed for physical SIM cards. example: '356938035643809' iccid: type: string description: > Integrated Circuit Card Identifier (ICCID) of an existing SIM card. Provide this when activating a subscription with a pre-existing physical SIM card. Only applicable to certain networks that support BYO (Bring Your Own) SIM. example: '8931440400000000000' deliveryAddress: $ref: '#/components/schemas/Address' description: | Physical address to ship the SIM card to (for physical SIM only). If not provided, the subscriber's address will be used. Not applicable for eSIM subscriptions. Address: type: object required: - street1 - city - zip - country properties: street1: type: string description: The first line of the address, typically street and house number. example: 500 S Main St street2: type: string description: >- The second line of the address, typically apartment, suite, unit, building, floor, etc. example: Apt 1 city: type: string description: The city or municipality of the address. example: Natick zip: type: string description: > The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). example: '01701' country: type: string description: >- The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). pattern: ^[A-Z]{2}$ example: US state: type: string description: >- For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). example: CA region: type: string description: >- A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). attention: type: string description: >- An optional line for specifying a person, department, or attention to a specific entity within an address. Metadata: type: object additionalProperties: type: string description: > A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. SubscriptionStatus: type: string description: The status of the subscription. enum: - PENDING - ACTIVATED - BLOCKED - CANCELLED - PAUSED - SUSPENDED SubscriptionType: type: string description: > The type of subscription, categorizing the service into various telecommunications service types. EmbeddedCustomer: type: object description: >- Customer information embedded in responses. Sensitive details require separate API calls with appropriate authorization. required: - customerId - name properties: customerId: type: string description: The unique identifier for the customer. name: type: string description: The customer's display name. EmbeddedProductOffering: type: object description: Embedded representation of a product offering. required: - productOfferingId - name - price properties: productOfferingId: type: string description: The unique identifier for the product offering. name: type: string description: The name of the product offering. price: $ref: '#/components/schemas/Price' group: $ref: '#/components/schemas/ProductOfferingGroup' imageUrl: type: string format: uri description: URL to the image representing the product offering. example: https://cdn.example.com/images/mobile-basic.png EmbeddedSubscriber: type: object description: A subscriber is a user that has a subscription. required: - subscriberId - name properties: subscriberId: type: string description: The unique identifier of the subscriber. name: type: string description: The name of the subscriber. email: type: string format: email description: Optional email address of the subscriber. address: $ref: '#/components/schemas/Address' description: > The address of the subscriber. In the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services. createdAt: type: string format: date-time description: Date and time when the subscriber was created. updatedAt: type: string format: date-time description: Date and time when the subscriber was last updated. EmbeddedPorting: type: object description: > Number porting information for subscriptions, indicating scheduled number transfers. To get the detailed porting information, use the porting endpoint. required: - msisdn - status - direction - scheduledAt properties: msisdn: type: string description: >- The pending phone number that the subscription will be ported in with. This will always be a non-active number. status: $ref: '#/components/schemas/PortingStatus' direction: $ref: '#/components/schemas/PortingDirection' scheduledAt: type: string format: date x-ogen-type: telnesstech.com/apiv2/apiv2types.Date description: The date when the number porting is scheduled to occur. 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. PortingDetails: description: > description: Detailed information required for the porting process, varying by country and provider. oneOf: - $ref: '#/components/schemas/PortingDetailsUS' - $ref: '#/components/schemas/PortingDetailsSweden' Price: type: object description: Pricing information with discount details. required: - cost - basePrice - currency - period - priceType properties: discount: type: number format: decimal description: The discount amount from the original price. example: 5 netPrice: type: number format: decimal description: The final cost after all discounts are applied. example: 5 currency: type: string description: The currency code. example: USD priceType: $ref: '#/components/schemas/PriceType' boundMonths: type: integer description: The number of months the price is bound to (for recurring prices). example: 12 billingCycle: $ref: '#/components/schemas/BillingCycle' currencyOptions: type: object additionalProperties: type: number format: decimal description: >- Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency. ProductOfferingGroup: type: object description: A product group organizes related product offerings. required: - productOfferingGroupId - name - category additionalProperties: false properties: productOfferingGroupId: type: string description: Unique identifier for the product group. example: mobile-plans name: type: string description: Name of the product group in the requested locale. example: Mobile Plans description: type: string description: Description of the product group in the requested locale. example: >- Bundled cell subscriptions with unlimited calls and SMS with ILD enabled. category: $ref: '#/components/schemas/ProductCategory' internalDescription: type: string description: Internal description of the product group for operational use only. example: Core mobile offerings targeting consumer and business segments PortingStatus: type: string enum: - PENDING - IN_PROGRESS - SCHEDULED - COMPLETED - FAILED description: Current status of the porting process. PortingDirection: type: string enum: - INBOUND - OUTBOUND description: >- The direction of the number porting, either inbound (to us) or outbound (from us). Any: oneOf: - type: string - type: number - type: boolean - type: object additionalProperties: true - type: array PortingDetailsUS: title: USPortingDetails type: object required: - firstName - lastName - address properties: accountNumber: type: string description: > The account number with the current provider. If not provided here, must be provided in the future for activation on-demand. passcode: type: string description: > The passcode or pin associated with the account at the current provider. If not provided here, must be provided in the future for activation on-demand. firstName: type: string description: The first name of the person requesting the port. lastName: type: string description: The last name of the person requesting the port. address: $ref: '#/components/schemas/Address' PortingDetailsSweden: title: SwedishPortingDetails type: object required: - identity properties: identity: type: string description: >- The identity of the current owner of the phone number, e.g., "personal identity number" or "company registration number". PriceType: type: string description: The type of pricing model applied to the product offering. enum: - ONE_TIME - RECURRING BillingCycle: type: object description: The billing cycle for recurring prices. required: - period - interval properties: period: type: string description: The billing period. enum: - MONTHLY interval: type: integer description: The interval of the billing period. example: 1 ProductCategory: type: string description: > A product category is a sub-type for grouping offerings of the same type. Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though. Categories are grouped by their product type: **SUBSCRIPTION categories:** - `PRODUCT_CATEGORY_SUBSCRIPTION_CELL` - Mobile cellular subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM` - Data-only SIM subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND` - Broadband internet subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_M2M` - Machine-to-machine IoT subscription - `PRODUCT_CATEGORY_TRAVEL_ESIM` - Travel eSIM subscription for international roaming **SUBSCRIPTION_ADDON categories:** - `PRODUCT_CATEGORY_EXTRA_DATA` - Additional data package addon - `PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE` - Travel eSIM data package with country/region coverage - `PRODUCT_CATEGORY_ABROAD` - International roaming addon **EXTERNAL_PRODUCT categories:** - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT` - External purchasable product - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON` - Addon for external product enum: - PRODUCT_CATEGORY_SUBSCRIPTION_CELL - PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - PRODUCT_CATEGORY_SUBSCRIPTION_M2M - PRODUCT_CATEGORY_TRAVEL_ESIM - PRODUCT_CATEGORY_EXTRA_DATA - PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - PRODUCT_CATEGORY_ABROAD - PRODUCT_CATEGORY_EXTERNAL_PRODUCT - PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON example: PRODUCT_CATEGORY_SUBSCRIPTION_CELL 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' TooManyRequests: description: Too many requests have been sent in a given amount of time. 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.