Create subscription

Authorizations

X-Api-Key

string

header

required

An API key that grants access to the Connect API. You can create and manage API keys in the portal.

Headers

X-Idempotency-Key

string

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.

Maximum string length: 256

Body

application/json

Create a new subscription for a customer.

Activation Options:

Immediate activation: Provide activation data without scheduleActivationAt
Scheduled activation: Provide activation data with scheduleActivationAt for future activation
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.

productOfferingId

string

required

The unique identifier for the product offering to subscribe to.

This controls what type of subscription is being created.

customerId

string

required

The unique identifier for the existing customer who will own this subscription.

subscriber

object

required

Subscriber details for this subscription.

Show child attributes

subscriber.name

string

required

The full name of the subscriber.

Example:

"John Doe"

subscriber.email

string<email>

The email address of the subscriber.

Example:

"[email protected]"

subscriber.address

object

Show child attributes

subscriber.address.street1

string

required

The first line of the address, typically street and house number.

Example:

"500 S Main St"

subscriber.address.city

string

required

The city or municipality of the address.

Example:

"Natick"

subscriber.address.zip

string

required

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"

subscriber.address.country

string

required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

Example:

"US"

subscriber.address.street2

string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

Example:

"Apt 1"

subscriber.address.state

string

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

Example:

"CA"

subscriber.address.region

string

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

subscriber.address.attention

string

An optional line for specifying a person, department, or attention to a specific entity within an address.

subscriber.metadata

object

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format.

Show child attributes

subscriber.metadata.{key}

string

activation

object

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.

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

Show child attributes

activation.sim

object

required

SIM card technology and configuration for this subscription.

Show child attributes

activation.sim.esim

boolean

required

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

activation.sim.imei

string

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"

activation.sim.iccid

string

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"

activation.msisdn

string

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"

activation.leaseToken

string

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.

activation.porting

object

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.

Show child attributes

activation.porting.details

USPortingDetails · object

required

description: Detailed information required for the porting process, varying by country and provider.

USPortingDetails
SwedishPortingDetails

Show child attributes

activation.porting.details.firstName

string

required

The first name of the person requesting the port.

activation.porting.details.lastName

string

required

The last name of the person requesting the port.

activation.porting.details.address

object

required

Show child attributes

activation.porting.details.address.street1

string

required

The first line of the address, typically street and house number.

Example:

"500 S Main St"

activation.porting.details.address.city

string

required

The city or municipality of the address.

Example:

"Natick"

activation.porting.details.address.zip

string

required

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"

activation.porting.details.address.country

string

required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

Example:

"US"

activation.porting.details.address.street2

string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

Example:

"Apt 1"

activation.porting.details.address.state

string

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

Example:

"CA"

activation.porting.details.address.region

string

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

activation.porting.details.address.attention

string

An optional line for specifying a person, department, or attention to a specific entity within an address.

activation.porting.details.accountNumber

string

The account number with the current provider.

If not provided here, must be provided in the future for activation on-demand.

activation.porting.details.passcode

string

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.

activation.deliveryAddress

object

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.

Show child attributes

activation.deliveryAddress.street1

string

required

The first line of the address, typically street and house number.

Example:

"500 S Main St"

activation.deliveryAddress.city

string

required

The city or municipality of the address.

Example:

"Natick"

activation.deliveryAddress.zip

string

required

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"

activation.deliveryAddress.country

string

required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

Example:

"US"

activation.deliveryAddress.street2

string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

Example:

"Apt 1"

activation.deliveryAddress.state

string

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

Example:

"CA"

activation.deliveryAddress.region

string

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

activation.deliveryAddress.attention

string

An optional line for specifying a person, department, or attention to a specific entity within an address.

scheduleActivationAt

string<date>

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

object

Additional subscription extensions fields for custom subscription types.

Show child attributes

extensions.{key}

string

display

string

Custom display name for the subscription. If not provided, will be auto-generated from msisdn.

metadata

object

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format.

Show child attributes

metadata.{key}

string

Response

The created subscription.

A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details.

subscriptionId

string

required

The unique identifier for the subscription.

status

enum<string>

required

The status of the subscription.

Available options:

PENDING,

ACTIVATED,

BLOCKED,

CANCELLED,

PAUSED

type

string

required

The type of subscription, categorizing the service into various telecommunications service types.

display

string

required

The display name for the subscription, typically a pretty-print of the msisdn.

msisdn

string

required

The currently active phone number for this subscription.

customer

object

required

Customer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.

Show child attributes

customer.customerId

string

required

The unique identifier for the customer.

customer.name

string

required

The customer's display name.

productOffering

object

required

Embedded representation of a product offering.

Show child attributes

productOffering.productOfferingId

string

required

The unique identifier for the product offering.

productOffering.name

string

required

The name of the product offering.

productOffering.price

object

required

Pricing information with discount details.

Show child attributes

productOffering.price.currency

string

required

The currency code.

Example:

"USD"

productOffering.price.discount

number<decimal>

default:5

The discount amount from the original price.

productOffering.price.netPrice

number<decimal>

The final cost after all discounts are applied.

Example:

5

productOffering.price.priceType

enum<string>

The type of pricing model applied to the product offering.

Available options:

ONE_TIME,

RECURRING

productOffering.price.boundMonths

integer

The number of months the price is bound to (for recurring prices).

Example:

12

productOffering.price.billingCycle

object

The billing cycle for recurring prices.

Show child attributes

productOffering.price.billingCycle.period

enum<string>

The billing period.

Available options:

MONTHLY

productOffering.price.billingCycle.interval

integer

The interval of the billing period.

Example:

1

productOffering.productOfferingGroupId

string

The unique identifier for the product offering group.

productOffering.group

object

Product offering group information embedded in responses.

Show child attributes

productOffering.group.productOfferingGroupId

string

required

The unique identifier for the product offering group.

productOffering.group.name

string

required

The name of the product offering group.

productOffering.group.category

string

required

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.

Example:

"SUBSCRIPTION_CELL"

sim

object

required

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.

Show child attributes

sim.esim

boolean

required

Indicates whether the subscription uses eSIM technology.

sim.imei

string

International Mobile Equipment Identity, uniquely identifying the mobile device.

Only applicable for eSIM.

sim.iccid

string

Integrated Circuit Card identifier, uniquely identifying the SIM card.

activatedAt

string<date-time>

required

The date and time when the subscription was activated.

createdAt

string<date-time>

required

The date and time when the subscription was created.

updatedAt

string<date-time>

required

The date and time when the subscription was last updated.

subscriber

object

A subscriber is a user that has a subscription.

Show child attributes

subscriber.subscriberId

string

required

The unique identifier of the subscriber.

subscriber.name

string

required

The name of the subscriber.

subscriber.email

string<email>

Optional email address of the subscriber.

subscriber.address

object

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.

Show child attributes

subscriber.address.street1

string

required

The first line of the address, typically street and house number.

Example:

"500 S Main St"

subscriber.address.city

string

required

The city or municipality of the address.

Example:

"Natick"

subscriber.address.zip

string

required

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"

subscriber.address.country

string

required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

Example:

"US"

subscriber.address.street2

string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

Example:

"Apt 1"

subscriber.address.state

string

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

Example:

"CA"

subscriber.address.region

string

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

subscriber.address.attention

string

An optional line for specifying a person, department, or attention to a specific entity within an address.

subscriber.createdAt

string<date-time>

Date and time when the subscriber was created.

subscriber.updatedAt

string<date-time>

Date and time when the subscriber was last updated.

extensions

object

Additional subscription extensions fields provided for custom subscription types.

Show child attributes

extensions.{key}

string

pendingMsisdn

object

Details about when a pending phone number change is scheduled for this subscription.

Show child attributes

pendingMsisdn.msisdn

string

The pending phone number for this subscription, if a number change is scheduled.

pendingMsisdn.scheduledAt

string<date>

The date when the pending change (e.g., number change) is scheduled to occur.

pendingStatus

object

Details about when a pending status change is scheduled for this subscription.

Show child attributes

pendingStatus.status

enum<string>

The status of the subscription.

Available options:

PENDING,

ACTIVATED,

BLOCKED,

CANCELLED,

PAUSED

pendingStatus.scheduledAt

string<date>

The date when the pending status change is scheduled to occur.

pendingProductOffering

object

Pending product offering change.

Show child attributes

pendingProductOffering.scheduledAt

string<date>

required

The date when the pending product offering change is scheduled to occur.

pendingProductOffering.product

object

required

Embedded representation of a product offering.

Show child attributes

pendingProductOffering.product.productOfferingId

string

required

The unique identifier for the product offering.

pendingProductOffering.product.name

string

required

The name of the product offering.

pendingProductOffering.product.price

object

required

Pricing information with discount details.

Show child attributes

pendingProductOffering.product.price.currency

string

required

The currency code.

Example:

"USD"

pendingProductOffering.product.price.discount

number<decimal>

default:5

The discount amount from the original price.

pendingProductOffering.product.price.netPrice

number<decimal>

The final cost after all discounts are applied.

Example:

5

pendingProductOffering.product.price.priceType

enum<string>

The type of pricing model applied to the product offering.

Available options:

ONE_TIME,

RECURRING

pendingProductOffering.product.price.boundMonths

integer

The number of months the price is bound to (for recurring prices).

Example:

12

pendingProductOffering.product.price.billingCycle

object

The billing cycle for recurring prices.

Show child attributes

pendingProductOffering.product.price.billingCycle.period

enum<string>

The billing period.

Available options:

MONTHLY

pendingProductOffering.product.price.billingCycle.interval

integer

The interval of the billing period.

Example:

1

pendingProductOffering.product.productOfferingGroupId

string

The unique identifier for the product offering group.

pendingProductOffering.product.group

object

Product offering group information embedded in responses.

Show child attributes

pendingProductOffering.product.group.productOfferingGroupId

string

required

The unique identifier for the product offering group.

pendingProductOffering.product.group.name

string

required

The name of the product offering group.

pendingProductOffering.product.group.category

string

required

A product category is a sub-type for grouping offerings of the same type.

Example:

"SUBSCRIPTION_CELL"

porting

object

Number porting information for subscriptions, indicating scheduled number transfers.

To get the detailed porting information, use the porting endpoint.

Show child attributes

porting.msisdn

string

required

The pending phone number that the subscription will be ported in with. This will always be a non-active number.

porting.status

enum<string>

required

Current status of the porting process.

Available options:

PENDING,

IN_PROGRESS,

SCHEDULED,

COMPLETED,

FAILED

porting.direction

enum<string>

required

The direction of the number porting, either inbound (to us) or outbound (from us).

Available options:

INBOUND,

OUTBOUND

porting.scheduledAt

string<date>

required

The date when the number porting is scheduled to occur.

cancelledAt

string<date-time>

The date and time when the subscription was cancelled (if applicable).

metadata

object

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format.

Show child attributes

metadata.{key}

string

Getting started

Overview

API reference

Authorizations

Headers

Body

Response