Activate 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

Path Parameters

subscriptionId

string

required

The unique identifier of the subscription.

Body

application/json

Request to activate a pending subscription in the telecommunications network.

Use this endpoint to activate subscriptions that were created as "shells" without initial activation data, or to activate subscriptions that are in a state where network activation is needed.

Activation timing:

Omit scheduleActivationAt for immediate activation (or as soon as network resources are available)
Provide scheduleActivationAt to schedule activation for a future date

activation

object

required

Complete activation configuration required to bring the subscription online in the network.

This includes the phone number assignment, SIM card details, and any number porting information.

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 scheduled for activation.

If not provided, activation will be immediate or as soon as possible based on network availability.

Note: Network availability and porting timelines may affect exact timing. This date is considered a preference, not a guarantee. The actual activation may occur on or after this date.

Example:

"2025-01-01"

Response

Subscription activation scheduled or completed successfully.

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

Path Parameters

Body

Response