Subscriptions
Manage subscriptions and subscription.
List subscriptions
/subscriptionsList all subscriptions.
Will return all subscriptions the requester has access to.
Query parameters
customerarray of stringFilter by customer. May be the entity's internal UUID or an external reference identifier.
Reference identifiers MUST be prefixed with rid_ (e.g., rid_crm-customer-12345) so the API
can distinguish them from internal UUIDs. The prefix is stripped before lookup.
statusarray of SubscriptionStatusThe status of the subscription to filter by.
typearray of SubscriptionTypelimitinteger>= 1<= 1000default 100The maximum number of items to return.
cursorstringOpaque pagination token from a previous response's nextCursor.
Responses
200A list of subscriptions.
application/json
A list of subscriptions.
A list of subscriptions.
object
itemsarray of SubscriptionrequiredShow child attributes
subscriptionstringrequiredThe unique identifier for the subscription.
referencestringmax length 255A 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.
statusenum<string>requiredCurrent stage of the subscription lifecycle.
- PENDING: Created but not yet activated in the network
- ACTIVATED: Active and billable; service is available
- BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
- CANCELLED: Permanently terminated
- PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
- SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
typestringrequiredThe kind of telecommunications service the subscription provides.
Common values include CELL (mobile voice/SMS/data), DATA (data-only SIM), MBB (mobile broadband),
M2M (machine-to-machine/IoT), and TRAVEL_ESIM (travel eSIM for international roaming).
Determined by the product offering the subscription was created with.
displaystringrequiredHuman-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation.
msisdnstringphonepersonal datarequiredThe phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number.
customerobjectrequiredCustomer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.
Show child attributes
customerstringrequiredThe unique identifier for the customer. Use it with the customer endpoints to fetch full details.
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers.
productobjectEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
subscriberobjectThe person who uses the service on a subscription, as distinct from the customer who pays for it.
Show child attributes
subscriberstringrequiredThe unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.
namestringrequiredThe subscriber's full name.
emailstringemailpersonal dataThe subscriber's email address, if one has been provided.
addressobjectdeprecatedDeprecated. Use serviceAddress on the subscription instead.
The service address of the subscription that embeds this subscriber.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
createdstringdate-timeDate and time when the subscriber was created.
updatedstringdate-timeDate and time when the subscriber was last updated.
serviceobjectThe address where this subscription is served. It is the address that the subscription holds, or the billing address of the customer when the subscription holds none.
Absent when no record holds an address.
The address where a subscription is served, and the record that holds it.
In the US, this is the E911 address that emergency services get for the phone number.
Show child attributes
addressobjectrequiredA postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
sourceenum<string>requiredThe record that holds the address.
SUBSCRIPTION: The subscription holds an address of its own.CUSTOMER_BILLING: The subscription holds no address of its own, so the billing address of the customer applies.
values
SUBSCRIPTIONCUSTOMER_BILLING
extensionsobject with string keysAdditional subscription extensions fields provided for custom subscription types.
Show child attributes
*stringsimobjectrequiredSIM 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
esimbooleanrequiredWhether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.
imeistringpersonal dataInternational Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.
Only applicable for eSIM.
iccidstringpersonal dataIntegrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.
pendingobjectpersonal dataA phone number change that has been requested but not yet applied. Present only while a number change is scheduled; the current number remains in msisdn until the change takes effect.
Show child attributes
msisdnstringphonepersonal datarequiredThe phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.
scheduledstringdateThe date when the pending number change is scheduled to occur.
bararray of BarReasonThe reasons of the bars that keep a BLOCKED subscription blocked. A subscription can have more than one bar, and it stays
blocked until every bar is removed. Present only while the status is BLOCKED.
pendingobjectA status change that has been requested but not yet applied, for example a scheduled cancellation or pause. Present only while a status change is scheduled.
Show child attributes
statusenum<string>requiredCurrent stage of the subscription lifecycle.
- PENDING: Created but not yet activated in the network
- ACTIVATED: Active and billable; service is available
- BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
- CANCELLED: Permanently terminated
- PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
- SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
scheduledstringdateThe date when the pending status change is scheduled to occur.
pendingobjectA product offering change (upgrade or downgrade) that has been requested but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.
Show child attributes
scheduledstringdaterequiredThe date when the pending product offering change is scheduled to occur.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
portingobjectNumber porting information for subscriptions, indicating scheduled number transfers.
To get the detailed porting information, use the porting endpoint.
Show child attributes
msisdnstringpersonal datarequiredThe pending phone number that the subscription will be ported in with. This will always be a non-active number.
statusenum<string>requiredCurrent status of the porting process.
- PENDING: Porting request created but not yet submitted to the carriers
- IN_PROGRESS: Request submitted and awaiting a response from the losing carrier
- SCHEDULED: Accepted by the losing carrier; the transfer will execute on the scheduled date
- COMPLETED: The number has been transferred and is active
- FAILED: The request was rejected, canceled, or could not be completed
values
PENDINGIN_PROGRESSSCHEDULEDCOMPLETEDFAILED
directionenum<string>requiredThe direction of the number transfer. INBOUND means the number is being ported into this platform from another carrier; OUTBOUND means the number is leaving this platform for another carrier.
values
INBOUNDOUTBOUND
scheduledstringdaterequiredThe date when the number porting is scheduled to occur.
activatedstringdate-timeThe date and time when the subscription was activated. Absent until the subscription has been activated.
cancelledstringdate-timeThe date and time when the subscription was cancelled (if applicable).
createdstringdate-timerequiredThe date and time when the subscription was created.
updatedstringdate-timerequiredThe date and time when the subscription was last updated.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringpaginationobjectrequiredCursor-based pagination information returned by list endpoints.
Pass nextCursor as the cursor query parameter of the next request to fetch the following page.
Show child attributes
nextstring | nullrequiredOpaque token for fetching the next page. Null when no more results.
400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
429Too many requests have been sent in a given amount of time.
application/json
Too many requests have been sent in a given amount of time.
Too many requests have been sent in a given amount of time.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
Auth required
Send one of
X-Api-KeyBearer JWT+X-Api-Key
The API key is always required; the bearer token is optional.
curl https://apiv2.example.com/api/v2/subscriptions \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'X-Api-Key: YOUR_API_KEY'fetch('https://apiv2.example.com/api/v2/subscriptions', {
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-Api-Key': 'YOUR_API_KEY'
}
})requests.get(
"https://apiv2.example.com/api/v2/subscriptions",
headers={
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"X-Api-Key": "YOUR_API_KEY"
}
)package main
import (
"fmt"
"io"
"net/http"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/subscriptions"
req, _ := http.NewRequest("GET", requestUrl, nil)
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"items": [
{
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"referenceId": "crm-subscription-12345",
"status": "ACTIVATED",
"type": "CELL",
"display": "(555) 123-4567",
"msisdn": "+15551234567",
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "Acme Corp"
},
"productOffering": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Seamless 10GB",
"price": {
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "RECURRING",
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"standardDiscount": {
"amountMinor": 500
},
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 12
},
"discount": {
"amountMinor": 200
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 300
}
},
"currencyOptionsMinor": {
"USD": 2999,
"SEK": 29900
}
}
},
"subscriber": {
"subscriberId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
"name": "John Doe",
"email": "john.doe@example.com"
},
"sim": {
"esim": true,
"iccid": "8901240197155182976"
},
"activatedAt": "2024-01-15T10:30:00Z",
"createdAt": "2024-01-10T08:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"metadata": {
"costCenter": "eng-42"
}
}
],
"pagination": {
"nextCursor": null
}
}{
"message": "The request body is invalid.",
"code": "bad_request",
"details": [
{
"message": "Email format is invalid.",
"code": "invalid_email",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields."
}{
"message": "Authentication is required to access this resource.",
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header."
}{
"message": "You do not have permission to perform this action.",
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions."
}{
"message": "The requested customer could not be found.",
"code": "not_found",
"hint": "Verify the customerId and try again."
}{
"message": "Too many requests. Please slow down.",
"code": "too_many_requests",
"hint": "Retry after the number of seconds indicated in the Retry-After header."
}{
"message": "An unexpected error occurred on the server.",
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support."
}Create subscription
/subscriptionsCreate a new subscription for a customer.
Activation Modes:
-
Immediate Activation
- Provide complete activation data in the request
- Omit scheduleActivationAt or set to today's date
- Subscription activates immediately (network availability permitting)
-
Scheduled Activation
- Provide complete activation data in the request
- Set scheduleActivationAt to a future date
- Subscription activates on or after the specified date
-
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
The product offering must be an initial product offering of the product catalog of the customer.
initialProductOfferingIds of the customer product catalog names these product offerings. If the product offering
is not one of them, the
request gets status 400 with the internalCode 4334.
Note: This endpoint may be disabled when Seamless OS manages billing. In that configuration, subscriptions are created through the orders endpoint instead.
Headers
X-stringmax length 256A 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.
BodyCreateSubscriptionRequestrequiredapplication/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.
productstringrequiredThe unique identifier for the product offering to subscribe to.
This controls what type of subscription is being created.
customerstringrequiredThe identifier of the existing customer who will own this subscription. Accepts either an internal UUID or an external referenceId previously assigned to the customer.
referencestringmax length 255Optional 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.
activationobjectEverything needed to bring the subscription online in the mobile network: the phone number (a specific number, a leased number, or empty for automatic assignment), the SIM configuration (eSIM or physical SIM), and optional porting details when the subscriber keeps their existing number from another carrier.
When to provide:
- Provide activation details to have the subscription provisioned in the network — immediately,
or on the date given in
scheduleActivationAt - Omit to create a "shell" subscription that stays in PENDING status until you activate it later via POST /subscriptions/{subscriptionId}/activate, for example when SIM or porting details are not yet known
Show child attributes
msisdnstringpersonal dataThe 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
leasestringToken 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.
portingobjectDetails 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
detailsone ofrequiredOwnership and account information the carriers need to approve a number transfer. The required information varies by country: provide US details for US numbers and Swedish details for Swedish numbers.
Show child attributes
simobjectrequiredSIM card technology and configuration for this subscription.
Show child attributes
esimbooleanrequiredWhether this subscription uses eSIM (embedded SIM) technology.
- true: Digital eSIM profile will be provisioned to the device
- false: Physical SIM card will be used
iccidstringpersonal dataIntegrated 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.
deliveryobjectThe address a physical SIM card is posted to.
An eSIM subscription needs no delivery address. The address the subscription is served at is separate, and a delivery address does not change it.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
schedulestringdateDate 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.
extensionsobject with string keysAdditional subscription extensions fields for custom subscription types.
Show child attributes
*stringdisplaystringCustom display name for the subscription. If not provided, will be auto-generated from msisdn.
subscriberobjectrequiredSubscriber details for this subscription.
Show child attributes
namestringrequiredThe full name of the subscriber.
emailstringemailpersonal dataThe email address of the subscriber.
addressobjectThe address where the subscriber uses this subscription. In the US, this is the E911 address.
Give it only when it is different from the billing address of the customer. The subscription then holds it as its service address. A subscription with no address of its own is served at the billing address.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringmetadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringResponses
201The created subscription.
application/json
The created subscription.
The created subscription.
objectSubscription
A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details.
subscriptionstringrequiredThe unique identifier for the subscription.
referencestringmax length 255A 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.
statusenum<string>requiredCurrent stage of the subscription lifecycle.
- PENDING: Created but not yet activated in the network
- ACTIVATED: Active and billable; service is available
- BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
- CANCELLED: Permanently terminated
- PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
- SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
typestringrequiredThe kind of telecommunications service the subscription provides.
Common values include CELL (mobile voice/SMS/data), DATA (data-only SIM), MBB (mobile broadband),
M2M (machine-to-machine/IoT), and TRAVEL_ESIM (travel eSIM for international roaming).
Determined by the product offering the subscription was created with.
displaystringrequiredHuman-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation.
msisdnstringphonepersonal datarequiredThe phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number.
customerobjectrequiredCustomer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.
Show child attributes
customerstringrequiredThe unique identifier for the customer. Use it with the customer endpoints to fetch full details.
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers.
productobjectEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.
Show child attributes
netintegerint64The configured price of the offering, in minor currency units. When includesTax is
true, this amount is the total the customer pays, and the tax is a part of it.
includesbooleanTrue when the configured price includes its tax. The tax is then a part of
netPriceMinor rather than an amount on top of it.
currencystringrequiredThe ISO 4217 currency code the price is expressed in (e.g., "USD").
priceenum<string>requiredHow the price is charged.
- ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).
- RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).
values
ONE_TIMERECURRING
bindingobjectA commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.
Show child attributes
standardobjectA recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.
Show child attributes
customobjectBilling cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out.
Show child attributes
billingobjectHow often a recurring price is charged.
Show child attributes
currencyobject with string keysPer-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
productstringrequiredUnique identifier for the product group.
namestringrequiredName of the product group in the requested locale.
descriptionstringDescription of the product group in the requested locale.
categoryenum<string>requiredA 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 subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM- Data-only SIM subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND- Broadband internet subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_M2M- Machine-to-machine IoT subscriptionPRODUCT_CATEGORY_TRAVEL_ESIM- Travel eSIM subscription for international roaming
SUBSCRIPTION_ADDON categories:
PRODUCT_CATEGORY_EXTRA_DATA- Additional data package addonPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE- Travel eSIM data package with country/region coveragePRODUCT_CATEGORY_ABROAD- International roaming addon
EXTERNAL_PRODUCT categories:
PRODUCT_CATEGORY_EXTERNAL_PRODUCT- External purchasable productPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON- Addon for external product
SIM_CARD categories:
PRODUCT_CATEGORY_SIM_CARD- Physical SIM or eSIM replacement for an existing subscription
values
PRODUCT_CATEGORY_SUBSCRIPTION_CELLPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIMPRODUCT_CATEGORY_SUBSCRIPTION_BROADBANDPRODUCT_CATEGORY_SUBSCRIPTION_M2MPRODUCT_CATEGORY_TRAVEL_ESIMPRODUCT_CATEGORY_EXTRA_DATAPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGEPRODUCT_CATEGORY_ABROADPRODUCT_CATEGORY_EXTERNAL_PRODUCTPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDONPRODUCT_CATEGORY_SIM_CARD
internalstringInternal description of the product group for operational use only.
imagestringuriURL to the image representing the product offering.
subscriberobjectThe person who uses the service on a subscription, as distinct from the customer who pays for it.
Show child attributes
subscriberstringrequiredThe unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.
namestringrequiredThe subscriber's full name.
emailstringemailpersonal dataThe subscriber's email address, if one has been provided.
addressobjectdeprecatedDeprecated. Use serviceAddress on the subscription instead.
The service address of the subscription that embeds this subscriber.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
createdstringdate-timeDate and time when the subscriber was created.
updatedstringdate-timeDate and time when the subscriber was last updated.
serviceobjectThe address where this subscription is served. It is the address that the subscription holds, or the billing address of the customer when the subscription holds none.
Absent when no record holds an address.
The address where a subscription is served, and the record that holds it.
In the US, this is the E911 address that emergency services get for the phone number.
Show child attributes
addressobjectrequiredA postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
sourceenum<string>requiredThe record that holds the address.
SUBSCRIPTION: The subscription holds an address of its own.CUSTOMER_BILLING: The subscription holds no address of its own, so the billing address of the customer applies.
values
SUBSCRIPTIONCUSTOMER_BILLING
extensionsobject with string keysAdditional subscription extensions fields provided for custom subscription types.
Show child attributes
*stringsimobjectrequiredSIM 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
esimbooleanrequiredWhether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.
imeistringpersonal dataInternational Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.
Only applicable for eSIM.
iccidstringpersonal dataIntegrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.
pendingobjectpersonal dataA phone number change that has been requested but not yet applied. Present only while a number change is scheduled; the current number remains in msisdn until the change takes effect.
Show child attributes
msisdnstringphonepersonal datarequiredThe phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.
scheduledstringdateThe date when the pending number change is scheduled to occur.
bararray of BarReasonThe reasons of the bars that keep a BLOCKED subscription blocked. A subscription can have more than one bar, and it stays
blocked until every bar is removed. Present only while the status is BLOCKED.
pendingobjectA status change that has been requested but not yet applied, for example a scheduled cancellation or pause. Present only while a status change is scheduled.
Show child attributes
statusenum<string>requiredCurrent stage of the subscription lifecycle.
- PENDING: Created but not yet activated in the network
- ACTIVATED: Active and billable; service is available
- BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
- CANCELLED: Permanently terminated
- PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
- SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
scheduledstringdateThe date when the pending status change is scheduled to occur.
pendingobjectA product offering change (upgrade or downgrade) that has been requested but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.
Show child attributes
scheduledstringdaterequiredThe date when the pending product offering change is scheduled to occur.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
portingobjectNumber porting information for subscriptions, indicating scheduled number transfers.
To get the detailed porting information, use the porting endpoint.
Show child attributes
msisdnstringpersonal datarequiredThe pending phone number that the subscription will be ported in with. This will always be a non-active number.
statusenum<string>requiredCurrent status of the porting process.
- PENDING: Porting request created but not yet submitted to the carriers
- IN_PROGRESS: Request submitted and awaiting a response from the losing carrier
- SCHEDULED: Accepted by the losing carrier; the transfer will execute on the scheduled date
- COMPLETED: The number has been transferred and is active
- FAILED: The request was rejected, canceled, or could not be completed
values
PENDINGIN_PROGRESSSCHEDULEDCOMPLETEDFAILED
directionenum<string>requiredThe direction of the number transfer. INBOUND means the number is being ported into this platform from another carrier; OUTBOUND means the number is leaving this platform for another carrier.
values
INBOUNDOUTBOUND
scheduledstringdaterequiredThe date when the number porting is scheduled to occur.
activatedstringdate-timeThe date and time when the subscription was activated. Absent until the subscription has been activated.
cancelledstringdate-timeThe date and time when the subscription was cancelled (if applicable).
createdstringdate-timerequiredThe date and time when the subscription was created.
updatedstringdate-timerequiredThe date and time when the subscription was last updated.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*string400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
409The request conflicts with the current state of the resource.
application/json
The request conflicts with the current state of the resource.
The request conflicts with the current state of the resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
429Too many requests have been sent in a given amount of time.
application/json
Too many requests have been sent in a given amount of time.
Too many requests have been sent in a given amount of time.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
Auth required
Send one of
X-Api-KeyBearer JWT+X-Api-Key
The API key is always required; the bearer token is optional.
curl https://apiv2.example.com/api/v2/subscriptions \
--request POST \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"referenceId": "crm-subscription-12345",
"activation": {
"msisdn": "+15551234567",
"leaseToken": "lease_abc123def456",
"porting": {
"details": {
"accountNumber": "987654321",
"passcode": "123456",
"firstName": "John",
"lastName": "Doe",
"address": {
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
}
}
},
"sim": {
"esim": true,
"iccid": "8931440400000000000"
},
"deliveryAddress": {
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
}
},
"scheduleActivationAt": "2024-01-15",
"extensions": {
"propertyName": "string"
},
"display": "John'\''s work phone",
"subscriber": {
"name": "John Doe",
"email": "john.doe@example.com",
"address": {
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"metadata": {
"propertyName": "string"
}
},
"metadata": {
"propertyName": "string"
}
}'fetch('https://apiv2.example.com/api/v2/subscriptions', {
method: 'POST',
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-Api-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
productOfferingId: 'f47ac10b-58cc-4372-a567-0e02b2c3d479',
customerId: 'a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d',
referenceId: 'crm-subscription-12345',
activation: {
msisdn: '+15551234567',
leaseToken: 'lease_abc123def456',
porting: {
details: {
accountNumber: '987654321',
passcode: '123456',
firstName: 'John',
lastName: 'Doe',
address: {
street: '500 S Main St',
street1: 'string',
street2: 'Apt 1',
city: 'Natick',
zip: '01701',
country: 'US',
state: 'CA',
region: 'Ontario',
attention: 'John Doe'
}
}
},
sim: {
esim: true,
iccid: '8931440400000000000'
},
deliveryAddress: {
street: '500 S Main St',
street1: 'string',
street2: 'Apt 1',
city: 'Natick',
zip: '01701',
country: 'US',
state: 'CA',
region: 'Ontario',
attention: 'John Doe'
}
},
scheduleActivationAt: '2024-01-15',
extensions: {
propertyName: 'string'
},
display: 'John\'s work phone',
subscriber: {
name: 'John Doe',
email: 'john.doe@example.com',
address: {
street: '500 S Main St',
street1: 'string',
street2: 'Apt 1',
city: 'Natick',
zip: '01701',
country: 'US',
state: 'CA',
region: 'Ontario',
attention: 'John Doe'
},
metadata: {
propertyName: 'string'
}
},
metadata: {
propertyName: 'string'
}
})
})requests.post(
"https://apiv2.example.com/api/v2/subscriptions",
headers={
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"X-Api-Key": "YOUR_API_KEY",
"Content-Type": "application/json"
},
json={
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"referenceId": "crm-subscription-12345",
"activation": {
"msisdn": "+15551234567",
"leaseToken": "lease_abc123def456",
"porting": {
"details": {
"accountNumber": "987654321",
"passcode": "123456",
"firstName": "John",
"lastName": "Doe",
"address": {
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
}
}
},
"sim": {
"esim": True,
"iccid": "8931440400000000000"
},
"deliveryAddress": {
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
}
},
"scheduleActivationAt": "2024-01-15",
"extensions": {
"propertyName": "string"
},
"display": "John's work phone",
"subscriber": {
"name": "John Doe",
"email": "john.doe@example.com",
"address": {
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"metadata": {
"propertyName": "string"
}
},
"metadata": {
"propertyName": "string"
}
}
)package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/subscriptions"
payload := strings.NewReader(`{
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"referenceId": "crm-subscription-12345",
"activation": {
"msisdn": "+15551234567",
"leaseToken": "lease_abc123def456",
"porting": {
"details": {
"accountNumber": "987654321",
"passcode": "123456",
"firstName": "John",
"lastName": "Doe",
"address": {
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
}
}
},
"sim": {
"esim": true,
"iccid": "8931440400000000000"
},
"deliveryAddress": {
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
}
},
"scheduleActivationAt": "2024-01-15",
"extensions": {
"propertyName": "string"
},
"display": "John's work phone",
"subscriber": {
"name": "John Doe",
"email": "john.doe@example.com",
"address": {
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"metadata": {
"propertyName": "string"
}
},
"metadata": {
"propertyName": "string"
}
}`)
req, _ := http.NewRequest("POST", requestUrl, payload)
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"referenceId": "crm-subscription-12345",
"status": "PENDING",
"type": "CELL",
"display": "(555) 123-4567",
"msisdn": "+15551234567",
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
},
"productOffering": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"netPriceMinor": 2999,
"includesTax": false,
"currency": "USD",
"priceType": "ONE_TIME",
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
},
"subscriber": {
"subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
"name": "John Doe",
"email": "john.doe@example.com",
"address": {
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-20T14:45:00Z"
},
"serviceAddress": {
"address": {
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"source": "SUBSCRIPTION"
},
"extensions": {
"propertyName": "string"
},
"sim": {
"esim": true,
"imei": "356938035643809",
"iccid": "8901240197155182976"
},
"pendingMsisdn": {
"msisdn": "+15559876543",
"scheduledAt": "2024-02-01"
},
"barReasons": [
"MISSING_PAYMENT"
],
"pendingStatus": {
"status": "PENDING",
"scheduledAt": "2024-02-01"
},
"pendingProductOffering": {
"scheduledAt": "2024-02-01",
"product": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"netPriceMinor": 2999,
"includesTax": false,
"currency": "USD",
"priceType": "ONE_TIME",
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
}
},
"porting": {
"msisdn": "+15551234567",
"status": "PENDING",
"direction": "INBOUND",
"scheduledAt": "2024-02-01"
},
"activatedAt": "2024-01-15T10:30:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"createdAt": "2024-01-10T08:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"metadata": {
"propertyName": "string"
}
}{
"message": "The request body is invalid.",
"code": "bad_request",
"details": [
{
"message": "Email format is invalid.",
"code": "invalid_email",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields."
}{
"message": "Authentication is required to access this resource.",
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header."
}{
"message": "You do not have permission to perform this action.",
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions."
}{
"message": "The requested customer could not be found.",
"code": "not_found",
"hint": "Verify the customerId and try again."
}{
"message": "The request conflicts with the current state of the resource.",
"code": "conflict",
"hint": "Reload the resource to get its latest state before retrying."
}{
"message": "Too many requests. Please slow down.",
"code": "too_many_requests",
"hint": "Retry after the number of seconds indicated in the Retry-After header."
}{
"message": "An unexpected error occurred on the server.",
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support."
}Get subscription
/subscriptions/{subscriptionId}Retrieve detailed information about a specific subscription using its unique identifier.
Path parameters
subscriptionstringrequiredThe identifier of the subscription. May be the entity's internal UUID or an external reference identifier.
Reference identifiers MUST be prefixed with rid_ (e.g., rid_crm-subscription-12345) so the API
can distinguish them from internal UUIDs. The prefix is stripped before lookup.
Responses
200A subscription object.
application/json
A subscription object.
A subscription object.
objectSubscription
A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details.
subscriptionstringrequiredThe unique identifier for the subscription.
referencestringmax length 255A 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.
statusenum<string>requiredCurrent stage of the subscription lifecycle.
- PENDING: Created but not yet activated in the network
- ACTIVATED: Active and billable; service is available
- BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
- CANCELLED: Permanently terminated
- PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
- SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
typestringrequiredThe kind of telecommunications service the subscription provides.
Common values include CELL (mobile voice/SMS/data), DATA (data-only SIM), MBB (mobile broadband),
M2M (machine-to-machine/IoT), and TRAVEL_ESIM (travel eSIM for international roaming).
Determined by the product offering the subscription was created with.
displaystringrequiredHuman-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation.
msisdnstringphonepersonal datarequiredThe phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number.
customerobjectrequiredCustomer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.
Show child attributes
customerstringrequiredThe unique identifier for the customer. Use it with the customer endpoints to fetch full details.
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers.
productobjectEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.
Show child attributes
netintegerint64The configured price of the offering, in minor currency units. When includesTax is
true, this amount is the total the customer pays, and the tax is a part of it.
includesbooleanTrue when the configured price includes its tax. The tax is then a part of
netPriceMinor rather than an amount on top of it.
currencystringrequiredThe ISO 4217 currency code the price is expressed in (e.g., "USD").
priceenum<string>requiredHow the price is charged.
- ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).
- RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).
values
ONE_TIMERECURRING
bindingobjectA commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.
Show child attributes
standardobjectA recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.
Show child attributes
customobjectBilling cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out.
Show child attributes
billingobjectHow often a recurring price is charged.
Show child attributes
currencyobject with string keysPer-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
productstringrequiredUnique identifier for the product group.
namestringrequiredName of the product group in the requested locale.
descriptionstringDescription of the product group in the requested locale.
categoryenum<string>requiredA 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 subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM- Data-only SIM subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND- Broadband internet subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_M2M- Machine-to-machine IoT subscriptionPRODUCT_CATEGORY_TRAVEL_ESIM- Travel eSIM subscription for international roaming
SUBSCRIPTION_ADDON categories:
PRODUCT_CATEGORY_EXTRA_DATA- Additional data package addonPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE- Travel eSIM data package with country/region coveragePRODUCT_CATEGORY_ABROAD- International roaming addon
EXTERNAL_PRODUCT categories:
PRODUCT_CATEGORY_EXTERNAL_PRODUCT- External purchasable productPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON- Addon for external product
SIM_CARD categories:
PRODUCT_CATEGORY_SIM_CARD- Physical SIM or eSIM replacement for an existing subscription
values
PRODUCT_CATEGORY_SUBSCRIPTION_CELLPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIMPRODUCT_CATEGORY_SUBSCRIPTION_BROADBANDPRODUCT_CATEGORY_SUBSCRIPTION_M2MPRODUCT_CATEGORY_TRAVEL_ESIMPRODUCT_CATEGORY_EXTRA_DATAPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGEPRODUCT_CATEGORY_ABROADPRODUCT_CATEGORY_EXTERNAL_PRODUCTPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDONPRODUCT_CATEGORY_SIM_CARD
internalstringInternal description of the product group for operational use only.
imagestringuriURL to the image representing the product offering.
subscriberobjectThe person who uses the service on a subscription, as distinct from the customer who pays for it.
Show child attributes
subscriberstringrequiredThe unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.
namestringrequiredThe subscriber's full name.
emailstringemailpersonal dataThe subscriber's email address, if one has been provided.
addressobjectdeprecatedDeprecated. Use serviceAddress on the subscription instead.
The service address of the subscription that embeds this subscriber.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
createdstringdate-timeDate and time when the subscriber was created.
updatedstringdate-timeDate and time when the subscriber was last updated.
serviceobjectThe address where this subscription is served. It is the address that the subscription holds, or the billing address of the customer when the subscription holds none.
Absent when no record holds an address.
The address where a subscription is served, and the record that holds it.
In the US, this is the E911 address that emergency services get for the phone number.
Show child attributes
addressobjectrequiredA postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
sourceenum<string>requiredThe record that holds the address.
SUBSCRIPTION: The subscription holds an address of its own.CUSTOMER_BILLING: The subscription holds no address of its own, so the billing address of the customer applies.
values
SUBSCRIPTIONCUSTOMER_BILLING
extensionsobject with string keysAdditional subscription extensions fields provided for custom subscription types.
Show child attributes
*stringsimobjectrequiredSIM 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
esimbooleanrequiredWhether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.
imeistringpersonal dataInternational Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.
Only applicable for eSIM.
iccidstringpersonal dataIntegrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.
pendingobjectpersonal dataA phone number change that has been requested but not yet applied. Present only while a number change is scheduled; the current number remains in msisdn until the change takes effect.
Show child attributes
msisdnstringphonepersonal datarequiredThe phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.
scheduledstringdateThe date when the pending number change is scheduled to occur.
bararray of BarReasonThe reasons of the bars that keep a BLOCKED subscription blocked. A subscription can have more than one bar, and it stays
blocked until every bar is removed. Present only while the status is BLOCKED.
pendingobjectA status change that has been requested but not yet applied, for example a scheduled cancellation or pause. Present only while a status change is scheduled.
Show child attributes
statusenum<string>requiredCurrent stage of the subscription lifecycle.
- PENDING: Created but not yet activated in the network
- ACTIVATED: Active and billable; service is available
- BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
- CANCELLED: Permanently terminated
- PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
- SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
scheduledstringdateThe date when the pending status change is scheduled to occur.
pendingobjectA product offering change (upgrade or downgrade) that has been requested but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.
Show child attributes
scheduledstringdaterequiredThe date when the pending product offering change is scheduled to occur.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
portingobjectNumber porting information for subscriptions, indicating scheduled number transfers.
To get the detailed porting information, use the porting endpoint.
Show child attributes
msisdnstringpersonal datarequiredThe pending phone number that the subscription will be ported in with. This will always be a non-active number.
statusenum<string>requiredCurrent status of the porting process.
- PENDING: Porting request created but not yet submitted to the carriers
- IN_PROGRESS: Request submitted and awaiting a response from the losing carrier
- SCHEDULED: Accepted by the losing carrier; the transfer will execute on the scheduled date
- COMPLETED: The number has been transferred and is active
- FAILED: The request was rejected, canceled, or could not be completed
values
PENDINGIN_PROGRESSSCHEDULEDCOMPLETEDFAILED
directionenum<string>requiredThe direction of the number transfer. INBOUND means the number is being ported into this platform from another carrier; OUTBOUND means the number is leaving this platform for another carrier.
values
INBOUNDOUTBOUND
scheduledstringdaterequiredThe date when the number porting is scheduled to occur.
activatedstringdate-timeThe date and time when the subscription was activated. Absent until the subscription has been activated.
cancelledstringdate-timeThe date and time when the subscription was cancelled (if applicable).
createdstringdate-timerequiredThe date and time when the subscription was created.
updatedstringdate-timerequiredThe date and time when the subscription was last updated.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*string400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
Auth required
Send one of
X-Api-KeyBearer JWT+X-Api-Key
The API key is always required; the bearer token is optional.
curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'X-Api-Key: YOUR_API_KEY'fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID', {
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-Api-Key': 'YOUR_API_KEY'
}
})requests.get(
"https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID",
headers={
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"X-Api-Key": "YOUR_API_KEY"
}
)package main
import (
"fmt"
"io"
"net/http"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID"
req, _ := http.NewRequest("GET", requestUrl, nil)
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"referenceId": "crm-subscription-12345",
"status": "ACTIVATED",
"type": "CELL",
"display": "(555) 123-4567",
"msisdn": "+15551234567",
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "Acme Corp"
},
"productOffering": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Seamless 10GB",
"price": {
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "RECURRING",
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"standardDiscount": {
"amountMinor": 500
},
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 12
},
"discount": {
"amountMinor": 200
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 300
}
},
"currencyOptionsMinor": {
"USD": 2999,
"SEK": 29900
}
}
},
"subscriber": {
"subscriberId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
"name": "John Doe",
"email": "john.doe@example.com"
},
"serviceAddress": {
"address": {
"street": "500 S Main St",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"state": "MA",
"country": "US"
},
"source": "SUBSCRIPTION"
},
"sim": {
"esim": true,
"iccid": "8901240197155182976"
},
"activatedAt": "2024-01-15T10:30:00Z",
"createdAt": "2024-01-10T08:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"metadata": {
"costCenter": "eng-42"
}
}{
"message": "The request body is invalid.",
"code": "bad_request",
"details": [
{
"message": "Email format is invalid.",
"code": "invalid_email",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields."
}{
"message": "Authentication is required to access this resource.",
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header."
}{
"message": "The requested customer could not be found.",
"code": "not_found",
"hint": "Verify the customerId and try again."
}{
"message": "An unexpected error occurred on the server.",
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support."
}Activate subscription
/subscriptions/{subscriptionId}/activateActivate a pending subscription by providing the necessary network activation details.
Use this endpoint when a subscription was created as a "shell" without activation data.
If the subscription is not pending, an error will be returned.
Path parameters
subscriptionstringrequiredThe identifier of the subscription. May be the entity's internal UUID or an external reference identifier.
Reference identifiers MUST be prefixed with rid_ (e.g., rid_crm-subscription-12345) so the API
can distinguish them from internal UUIDs. The prefix is stripped before lookup.
Headers
X-stringmax length 256A 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.
BodyActivateSubscriptionRequestrequiredapplication/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
activationobjectrequiredComplete 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.
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.
Show child attributes
msisdnstringpersonal dataThe 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
leasestringToken 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.
portingobjectDetails 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
detailsone ofrequiredOwnership and account information the carriers need to approve a number transfer. The required information varies by country: provide US details for US numbers and Swedish details for Swedish numbers.
Show child attributes
simobjectrequiredSIM card technology and configuration for this subscription.
Show child attributes
esimbooleanrequiredWhether this subscription uses eSIM (embedded SIM) technology.
- true: Digital eSIM profile will be provisioned to the device
- false: Physical SIM card will be used
iccidstringpersonal dataIntegrated 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.
deliveryobjectThe address a physical SIM card is posted to.
An eSIM subscription needs no delivery address. The address the subscription is served at is separate, and a delivery address does not change it.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
schedulestringdateDate 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.
Responses
200Subscription activation scheduled or completed successfully.
application/json
Subscription activation scheduled or completed successfully.
Subscription activation scheduled or completed successfully.
objectSubscription
A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details.
subscriptionstringrequiredThe unique identifier for the subscription.
referencestringmax length 255A 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.
statusenum<string>requiredCurrent stage of the subscription lifecycle.
- PENDING: Created but not yet activated in the network
- ACTIVATED: Active and billable; service is available
- BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
- CANCELLED: Permanently terminated
- PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
- SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
typestringrequiredThe kind of telecommunications service the subscription provides.
Common values include CELL (mobile voice/SMS/data), DATA (data-only SIM), MBB (mobile broadband),
M2M (machine-to-machine/IoT), and TRAVEL_ESIM (travel eSIM for international roaming).
Determined by the product offering the subscription was created with.
displaystringrequiredHuman-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation.
msisdnstringphonepersonal datarequiredThe phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number.
customerobjectrequiredCustomer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.
Show child attributes
customerstringrequiredThe unique identifier for the customer. Use it with the customer endpoints to fetch full details.
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers.
productobjectEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.
Show child attributes
netintegerint64The configured price of the offering, in minor currency units. When includesTax is
true, this amount is the total the customer pays, and the tax is a part of it.
includesbooleanTrue when the configured price includes its tax. The tax is then a part of
netPriceMinor rather than an amount on top of it.
currencystringrequiredThe ISO 4217 currency code the price is expressed in (e.g., "USD").
priceenum<string>requiredHow the price is charged.
- ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).
- RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).
values
ONE_TIMERECURRING
bindingobjectA commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.
Show child attributes
standardobjectA recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.
Show child attributes
customobjectBilling cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out.
Show child attributes
billingobjectHow often a recurring price is charged.
Show child attributes
currencyobject with string keysPer-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
productstringrequiredUnique identifier for the product group.
namestringrequiredName of the product group in the requested locale.
descriptionstringDescription of the product group in the requested locale.
categoryenum<string>requiredA 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 subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM- Data-only SIM subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND- Broadband internet subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_M2M- Machine-to-machine IoT subscriptionPRODUCT_CATEGORY_TRAVEL_ESIM- Travel eSIM subscription for international roaming
SUBSCRIPTION_ADDON categories:
PRODUCT_CATEGORY_EXTRA_DATA- Additional data package addonPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE- Travel eSIM data package with country/region coveragePRODUCT_CATEGORY_ABROAD- International roaming addon
EXTERNAL_PRODUCT categories:
PRODUCT_CATEGORY_EXTERNAL_PRODUCT- External purchasable productPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON- Addon for external product
SIM_CARD categories:
PRODUCT_CATEGORY_SIM_CARD- Physical SIM or eSIM replacement for an existing subscription
values
PRODUCT_CATEGORY_SUBSCRIPTION_CELLPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIMPRODUCT_CATEGORY_SUBSCRIPTION_BROADBANDPRODUCT_CATEGORY_SUBSCRIPTION_M2MPRODUCT_CATEGORY_TRAVEL_ESIMPRODUCT_CATEGORY_EXTRA_DATAPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGEPRODUCT_CATEGORY_ABROADPRODUCT_CATEGORY_EXTERNAL_PRODUCTPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDONPRODUCT_CATEGORY_SIM_CARD
internalstringInternal description of the product group for operational use only.
imagestringuriURL to the image representing the product offering.
subscriberobjectThe person who uses the service on a subscription, as distinct from the customer who pays for it.
Show child attributes
subscriberstringrequiredThe unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.
namestringrequiredThe subscriber's full name.
emailstringemailpersonal dataThe subscriber's email address, if one has been provided.
addressobjectdeprecatedDeprecated. Use serviceAddress on the subscription instead.
The service address of the subscription that embeds this subscriber.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
createdstringdate-timeDate and time when the subscriber was created.
updatedstringdate-timeDate and time when the subscriber was last updated.
serviceobjectThe address where this subscription is served. It is the address that the subscription holds, or the billing address of the customer when the subscription holds none.
Absent when no record holds an address.
The address where a subscription is served, and the record that holds it.
In the US, this is the E911 address that emergency services get for the phone number.
Show child attributes
addressobjectrequiredA postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
sourceenum<string>requiredThe record that holds the address.
SUBSCRIPTION: The subscription holds an address of its own.CUSTOMER_BILLING: The subscription holds no address of its own, so the billing address of the customer applies.
values
SUBSCRIPTIONCUSTOMER_BILLING
extensionsobject with string keysAdditional subscription extensions fields provided for custom subscription types.
Show child attributes
*stringsimobjectrequiredSIM 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
esimbooleanrequiredWhether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.
imeistringpersonal dataInternational Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.
Only applicable for eSIM.
iccidstringpersonal dataIntegrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.
pendingobjectpersonal dataA phone number change that has been requested but not yet applied. Present only while a number change is scheduled; the current number remains in msisdn until the change takes effect.
Show child attributes
msisdnstringphonepersonal datarequiredThe phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.
scheduledstringdateThe date when the pending number change is scheduled to occur.
bararray of BarReasonThe reasons of the bars that keep a BLOCKED subscription blocked. A subscription can have more than one bar, and it stays
blocked until every bar is removed. Present only while the status is BLOCKED.
pendingobjectA status change that has been requested but not yet applied, for example a scheduled cancellation or pause. Present only while a status change is scheduled.
Show child attributes
statusenum<string>requiredCurrent stage of the subscription lifecycle.
- PENDING: Created but not yet activated in the network
- ACTIVATED: Active and billable; service is available
- BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
- CANCELLED: Permanently terminated
- PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
- SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
scheduledstringdateThe date when the pending status change is scheduled to occur.
pendingobjectA product offering change (upgrade or downgrade) that has been requested but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.
Show child attributes
scheduledstringdaterequiredThe date when the pending product offering change is scheduled to occur.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
portingobjectNumber porting information for subscriptions, indicating scheduled number transfers.
To get the detailed porting information, use the porting endpoint.
Show child attributes
msisdnstringpersonal datarequiredThe pending phone number that the subscription will be ported in with. This will always be a non-active number.
statusenum<string>requiredCurrent status of the porting process.
- PENDING: Porting request created but not yet submitted to the carriers
- IN_PROGRESS: Request submitted and awaiting a response from the losing carrier
- SCHEDULED: Accepted by the losing carrier; the transfer will execute on the scheduled date
- COMPLETED: The number has been transferred and is active
- FAILED: The request was rejected, canceled, or could not be completed
values
PENDINGIN_PROGRESSSCHEDULEDCOMPLETEDFAILED
directionenum<string>requiredThe direction of the number transfer. INBOUND means the number is being ported into this platform from another carrier; OUTBOUND means the number is leaving this platform for another carrier.
values
INBOUNDOUTBOUND
scheduledstringdaterequiredThe date when the number porting is scheduled to occur.
activatedstringdate-timeThe date and time when the subscription was activated. Absent until the subscription has been activated.
cancelledstringdate-timeThe date and time when the subscription was cancelled (if applicable).
createdstringdate-timerequiredThe date and time when the subscription was created.
updatedstringdate-timerequiredThe date and time when the subscription was last updated.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*string400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
409The request conflicts with the current state of the resource.
application/json
The request conflicts with the current state of the resource.
The request conflicts with the current state of the resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
429Too many requests have been sent in a given amount of time.
application/json
Too many requests have been sent in a given amount of time.
Too many requests have been sent in a given amount of time.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
Auth required
Send one of
X-Api-KeyBearer JWT+X-Api-Key
The API key is always required; the bearer token is optional.
curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/activate \
--request POST \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"activation": {
"msisdn": "+15551234567",
"leaseToken": "lease_abc123def456",
"sim": {
"esim": true
}
}
}'fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/activate', {
method: 'POST',
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-Api-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
activation: {
msisdn: '+15551234567',
leaseToken: 'lease_abc123def456',
sim: {
esim: true
}
}
})
})requests.post(
"https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/activate",
headers={
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"X-Api-Key": "YOUR_API_KEY",
"Content-Type": "application/json"
},
json={
"activation": {
"msisdn": "+15551234567",
"leaseToken": "lease_abc123def456",
"sim": {
"esim": True
}
}
}
)package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/activate"
payload := strings.NewReader(`{
"activation": {
"msisdn": "+15551234567",
"leaseToken": "lease_abc123def456",
"sim": {
"esim": true
}
}
}`)
req, _ := http.NewRequest("POST", requestUrl, payload)
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"referenceId": "crm-subscription-12345",
"status": "ACTIVATED",
"type": "CELL",
"display": "(555) 123-4567",
"msisdn": "+15551234567",
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "Acme Corp"
},
"productOffering": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Seamless 10GB",
"price": {
"netPriceMinor": 2999,
"currency": "USD",
"priceType": "RECURRING",
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"standardDiscount": {
"amountMinor": 500
},
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 12
},
"discount": {
"amountMinor": 200
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 300
}
},
"currencyOptionsMinor": {
"USD": 2999,
"SEK": 29900
}
}
},
"subscriber": {
"subscriberId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
"name": "John Doe",
"email": "john.doe@example.com"
},
"sim": {
"esim": true,
"iccid": "8901240197155182976"
},
"activatedAt": "2024-01-15T10:30:00Z",
"createdAt": "2024-01-10T08:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
}{
"message": "The request body is invalid.",
"code": "bad_request",
"details": [
{
"message": "Email format is invalid.",
"code": "invalid_email",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields."
}{
"message": "Authentication is required to access this resource.",
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header."
}{
"message": "You do not have permission to perform this action.",
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions."
}{
"message": "The requested customer could not be found.",
"code": "not_found",
"hint": "Verify the customerId and try again."
}{
"message": "The request conflicts with the current state of the resource.",
"code": "conflict",
"hint": "Reload the resource to get its latest state before retrying."
}{
"message": "Too many requests. Please slow down.",
"code": "too_many_requests",
"hint": "Retry after the number of seconds indicated in the Retry-After header."
}{
"message": "An unexpected error occurred on the server.",
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support."
}Get subscription in-porting
/subscriptions/{subscriptionId}/in-portingRetrieve the current porting information for a subscription that is in the process of porting in a number.
Path parameters
subscriptionstringrequiredThe identifier of the subscription. May be the entity's internal UUID or an external reference identifier.
Reference identifiers MUST be prefixed with rid_ (e.g., rid_crm-subscription-12345) so the API
can distinguish them from internal UUIDs. The prefix is stripped before lookup.
Responses
200Porting information retrieved successfully.
application/json
Porting information retrieved successfully.
Porting information retrieved successfully.
objectPorting
A request to transfer (port) a phone number between carriers, either into this platform from the subscriber's previous carrier or out to another carrier. Tracks the number, the transfer's progress, and the ownership details required by the carriers involved.
msisdnstringpersonal datarequiredThe phone number to be ported, in E.164 format.
statusenum<string>requiredCurrent status of the porting process.
- PENDING: Porting request created but not yet submitted to the carriers
- IN_PROGRESS: Request submitted and awaiting a response from the losing carrier
- SCHEDULED: Accepted by the losing carrier; the transfer will execute on the scheduled date
- COMPLETED: The number has been transferred and is active
- FAILED: The request was rejected, canceled, or could not be completed
values
PENDINGIN_PROGRESSSCHEDULEDCOMPLETEDFAILED
directionenum<string>requiredThe direction of the number transfer. INBOUND means the number is being ported into this platform from another carrier; OUTBOUND means the number is leaving this platform for another carrier.
values
INBOUNDOUTBOUND
scheduledstringdateThe date when the porting is scheduled to occur.
detailsone ofrequiredOwnership and account information the carriers need to approve a number transfer. The required information varies by country: provide US details for US numbers and Swedish details for Swedish numbers.
Show child attributes
accountstringThe account number with the current provider.
If not provided here, must be provided in the future for activation on-demand.
passcodestringThe passcode or PIN associated with the account at the current provider, often called a Number Transfer PIN or port-out PIN. Most US carriers require the account holder to generate this in their account settings before the number can be released.
If not provided here, must be provided in the future for activation on-demand.
firststringpersonal datarequiredThe first name of the account holder at the current provider.
laststringpersonal datarequiredThe last name of the account holder at the current provider.
addressobjectrequiredThe address that the current provider holds for the account holder. The provider compares it with its own record before it releases the number.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
identitystringpersonal datarequiredThe identity of the number's current owner as registered with the losing carrier: a Swedish personal identity number (personnummer) for individuals, or a company registration number (organisationsnummer) for businesses. The transfer is rejected if this does not match the losing carrier's records.
updatedstringdate-timeThe timestamp of the last update to the porting request.
createdstringdate-timerequiredThe timestamp when the porting request was created.
400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
Auth required
Send one of
X-Api-KeyBearer JWT+X-Api-Key
The API key is always required; the bearer token is optional.
curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/in-porting \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'X-Api-Key: YOUR_API_KEY'fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/in-porting', {
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-Api-Key': 'YOUR_API_KEY'
}
})requests.get(
"https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/in-porting",
headers={
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"X-Api-Key": "YOUR_API_KEY"
}
)package main
import (
"fmt"
"io"
"net/http"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/in-porting"
req, _ := http.NewRequest("GET", requestUrl, nil)
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"msisdn": "+15551234567",
"status": "PENDING",
"direction": "INBOUND",
"scheduledAt": "2024-02-01",
"details": {
"accountNumber": "987654321",
"passcode": "123456",
"firstName": "John",
"lastName": "Doe",
"address": {
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
}
},
"updatedAt": "2024-01-20T09:00:00Z",
"createdAt": "2024-01-15T10:30:00Z"
}{
"message": "The request body is invalid.",
"code": "bad_request",
"details": [
{
"message": "Email format is invalid.",
"code": "invalid_email",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields."
}{
"message": "Authentication is required to access this resource.",
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header."
}{
"message": "You do not have permission to perform this action.",
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions."
}{
"message": "The requested customer could not be found.",
"code": "not_found",
"hint": "Verify the customerId and try again."
}{
"message": "An unexpected error occurred on the server.",
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support."
}Update subscription porting details
/subscriptions/{subscriptionId}/in-portingUpdate the porting details for a subscription that is in the process of porting in a number. This endpoint allows you to modify porting information while the port is still pending or in progress.
Path parameters
subscriptionstringrequiredThe identifier of the subscription. May be the entity's internal UUID or an external reference identifier.
Reference identifiers MUST be prefixed with rid_ (e.g., rid_crm-subscription-12345) so the API
can distinguish them from internal UUIDs. The prefix is stripped before lookup.
Headers
X-stringmax length 256A 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.
BodyUpdatePortingRequestrequiredapplication/json
Request to correct or complete the porting details of a subscription's in-progress port-in, for example after the losing carrier rejected the transfer because the owner details did not match.
detailsone ofrequiredOwnership and account information the carriers need to approve a number transfer. The required information varies by country: provide US details for US numbers and Swedish details for Swedish numbers.
Show child attributes
accountstringThe account number with the current provider.
If not provided here, must be provided in the future for activation on-demand.
passcodestringThe passcode or PIN associated with the account at the current provider, often called a Number Transfer PIN or port-out PIN. Most US carriers require the account holder to generate this in their account settings before the number can be released.
If not provided here, must be provided in the future for activation on-demand.
firststringpersonal datarequiredThe first name of the account holder at the current provider.
laststringpersonal datarequiredThe last name of the account holder at the current provider.
addressobjectrequiredThe address that the current provider holds for the account holder. The provider compares it with its own record before it releases the number.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
identitystringpersonal datarequiredThe identity of the number's current owner as registered with the losing carrier: a Swedish personal identity number (personnummer) for individuals, or a company registration number (organisationsnummer) for businesses. The transfer is rejected if this does not match the losing carrier's records.
Responses
200Porting details updated successfully.
application/json
Porting details updated successfully.
Porting details updated successfully.
object
subscriptionobjectA subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details.
Show child attributes
subscriptionstringrequiredThe unique identifier for the subscription.
referencestringmax length 255A 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.
statusenum<string>requiredCurrent stage of the subscription lifecycle.
- PENDING: Created but not yet activated in the network
- ACTIVATED: Active and billable; service is available
- BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
- CANCELLED: Permanently terminated
- PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
- SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
typestringrequiredThe kind of telecommunications service the subscription provides.
Common values include CELL (mobile voice/SMS/data), DATA (data-only SIM), MBB (mobile broadband),
M2M (machine-to-machine/IoT), and TRAVEL_ESIM (travel eSIM for international roaming).
Determined by the product offering the subscription was created with.
displaystringrequiredHuman-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation.
msisdnstringphonepersonal datarequiredThe phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number.
customerobjectrequiredCustomer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.
Show child attributes
customerstringrequiredThe unique identifier for the customer. Use it with the customer endpoints to fetch full details.
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers.
productobjectEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
subscriberobjectThe person who uses the service on a subscription, as distinct from the customer who pays for it.
Show child attributes
subscriberstringrequiredThe unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.
namestringrequiredThe subscriber's full name.
emailstringemailpersonal dataThe subscriber's email address, if one has been provided.
addressobjectdeprecatedDeprecated. Use serviceAddress on the subscription instead.
The service address of the subscription that embeds this subscriber.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
createdstringdate-timeDate and time when the subscriber was created.
updatedstringdate-timeDate and time when the subscriber was last updated.
serviceobjectThe address where this subscription is served. It is the address that the subscription holds, or the billing address of the customer when the subscription holds none.
Absent when no record holds an address.
The address where a subscription is served, and the record that holds it.
In the US, this is the E911 address that emergency services get for the phone number.
Show child attributes
addressobjectrequiredA postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
sourceenum<string>requiredThe record that holds the address.
SUBSCRIPTION: The subscription holds an address of its own.CUSTOMER_BILLING: The subscription holds no address of its own, so the billing address of the customer applies.
values
SUBSCRIPTIONCUSTOMER_BILLING
extensionsobject with string keysAdditional subscription extensions fields provided for custom subscription types.
Show child attributes
*stringsimobjectrequiredSIM 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
esimbooleanrequiredWhether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.
imeistringpersonal dataInternational Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.
Only applicable for eSIM.
iccidstringpersonal dataIntegrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.
pendingobjectpersonal dataA phone number change that has been requested but not yet applied. Present only while a number change is scheduled; the current number remains in msisdn until the change takes effect.
Show child attributes
msisdnstringphonepersonal datarequiredThe phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.
scheduledstringdateThe date when the pending number change is scheduled to occur.
bararray of BarReasonThe reasons of the bars that keep a BLOCKED subscription blocked. A subscription can have more than one bar, and it stays
blocked until every bar is removed. Present only while the status is BLOCKED.
pendingobjectA status change that has been requested but not yet applied, for example a scheduled cancellation or pause. Present only while a status change is scheduled.
Show child attributes
statusenum<string>requiredCurrent stage of the subscription lifecycle.
- PENDING: Created but not yet activated in the network
- ACTIVATED: Active and billable; service is available
- BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
- CANCELLED: Permanently terminated
- PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
- SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
scheduledstringdateThe date when the pending status change is scheduled to occur.
pendingobjectA product offering change (upgrade or downgrade) that has been requested but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.
Show child attributes
scheduledstringdaterequiredThe date when the pending product offering change is scheduled to occur.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
portingobjectNumber porting information for subscriptions, indicating scheduled number transfers.
To get the detailed porting information, use the porting endpoint.
Show child attributes
msisdnstringpersonal datarequiredThe pending phone number that the subscription will be ported in with. This will always be a non-active number.
statusenum<string>requiredCurrent status of the porting process.
- PENDING: Porting request created but not yet submitted to the carriers
- IN_PROGRESS: Request submitted and awaiting a response from the losing carrier
- SCHEDULED: Accepted by the losing carrier; the transfer will execute on the scheduled date
- COMPLETED: The number has been transferred and is active
- FAILED: The request was rejected, canceled, or could not be completed
values
PENDINGIN_PROGRESSSCHEDULEDCOMPLETEDFAILED
directionenum<string>requiredThe direction of the number transfer. INBOUND means the number is being ported into this platform from another carrier; OUTBOUND means the number is leaving this platform for another carrier.
values
INBOUNDOUTBOUND
scheduledstringdaterequiredThe date when the number porting is scheduled to occur.
activatedstringdate-timeThe date and time when the subscription was activated. Absent until the subscription has been activated.
cancelledstringdate-timeThe date and time when the subscription was cancelled (if applicable).
createdstringdate-timerequiredThe date and time when the subscription was created.
updatedstringdate-timerequiredThe date and time when the subscription was last updated.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringportingobjectUpdated porting information and status.
Show child attributes
portingstringThe unique identifier for this porting request.
statusenum<string>Current status of the porting process.
values
pendingin_progressscheduledcompletedfailed
estimatedstringdate-timeEstimated completion time for the port.
nextarray of stringNext steps required to complete the porting process.
400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
409The request conflicts with the current state of the resource.
application/json
The request conflicts with the current state of the resource.
The request conflicts with the current state of the resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
Auth required
Send one of
X-Api-KeyBearer JWT+X-Api-Key
The API key is always required; the bearer token is optional.
curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/in-porting \
--request POST \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"details": {
"identity": "199001011234"
}
}'fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/in-porting', {
method: 'POST',
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-Api-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
details: {
identity: '199001011234'
}
})
})requests.post(
"https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/in-porting",
headers={
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"X-Api-Key": "YOUR_API_KEY",
"Content-Type": "application/json"
},
json={
"details": {
"identity": "199001011234"
}
}
)package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/in-porting"
payload := strings.NewReader(`{
"details": {
"identity": "199001011234"
}
}`)
req, _ := http.NewRequest("POST", requestUrl, payload)
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"subscription": {
"subscriptionId": "7a1b9c3d-2e4f-4a6b-8c0d-9e8f7a6b5c4d",
"status": "ACTIVATED",
"type": "CELL",
"display": "073-111 00 00",
"msisdn": "+46731110000",
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "Volt AB"
},
"productOffering": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobil 10GB",
"price": {
"netPriceMinor": 24900,
"currency": "SEK",
"priceType": "RECURRING",
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"standardDiscount": {
"amountMinor": 5000
},
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 12
},
"discount": {
"amountMinor": 2000
}
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 3000
}
},
"currencyOptionsMinor": {
"SEK": 24900,
"USD": 2499
}
}
},
"subscriber": {
"subscriberId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
"name": "Anna Andersson",
"email": "anna.andersson@example.com"
},
"sim": {
"esim": false,
"iccid": "8946071234567890123"
},
"pendingMsisdn": {
"msisdn": "+46701234567",
"scheduledAt": "2025-02-01"
},
"porting": {
"msisdn": "+46701234567",
"status": "IN_PROGRESS",
"direction": "INBOUND",
"scheduledAt": "2025-02-01"
},
"activatedAt": "2025-01-10T09:00:00Z",
"createdAt": "2025-01-08T08:00:00Z",
"updatedAt": "2025-01-15T10:30:00Z"
},
"portingInfo": {
"portingId": "e5f6a7b8-c9d0-4123-8456-789abcdef012",
"status": "in_progress",
"estimatedCompletion": "2025-02-01T00:00:00Z",
"nextSteps": [
"Waiting for the current provider to respond to the porting request",
"No action required at this time"
]
}
}{
"message": "The request body is invalid.",
"code": "bad_request",
"details": [
{
"message": "Email format is invalid.",
"code": "invalid_email",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields."
}{
"message": "Authentication is required to access this resource.",
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header."
}{
"message": "You do not have permission to perform this action.",
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions."
}{
"message": "The requested customer could not be found.",
"code": "not_found",
"hint": "Verify the customerId and try again."
}{
"message": "The request conflicts with the current state of the resource.",
"code": "conflict",
"hint": "Reload the resource to get its latest state before retrying."
}{
"message": "An unexpected error occurred on the server.",
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support."
}Change subscription product offering
/subscriptions/{subscriptionId}/product-offering-changeChange the product offering of a subscription (upgrade or downgrade).
To get a list of to what and when the subscription can be changed, get change options for the subscription.
When the change takes effect is dictated by what product offering is chosen, which in its place depends on the network setup, billing cycle.
A product catalog can limit the product offerings that an offering change can move to. If a catalog of the customer does that
and the list does not hold the product offering, the request gets status 400 with the internalCode 4336.
Path parameters
subscriptionstringrequiredThe identifier of the subscription. May be the entity's internal UUID or an external reference identifier.
Reference identifiers MUST be prefixed with rid_ (e.g., rid_crm-subscription-12345) so the API
can distinguish them from internal UUIDs. The prefix is stripped before lookup.
Headers
X-stringmax length 256A 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.
BodyChangeSubscriptionProductOfferingRequestrequiredapplication/json
Request to change the product offering of a subscription.
productstringrequiredThe unique identifier of the new product offering. Use the product-offering-options endpoint to discover which offerings the subscription can be changed to.
scheduledstringdateEarliest date to perform the change on. If the change schedule doesn't fit this date, the earliest date after this will be chosen.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringResponses
200Product offering change scheduled.
application/json
Product offering change scheduled.
Product offering change scheduled.
objectSubscription
A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details.
subscriptionstringrequiredThe unique identifier for the subscription.
referencestringmax length 255A 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.
statusenum<string>requiredCurrent stage of the subscription lifecycle.
- PENDING: Created but not yet activated in the network
- ACTIVATED: Active and billable; service is available
- BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
- CANCELLED: Permanently terminated
- PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
- SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
typestringrequiredThe kind of telecommunications service the subscription provides.
Common values include CELL (mobile voice/SMS/data), DATA (data-only SIM), MBB (mobile broadband),
M2M (machine-to-machine/IoT), and TRAVEL_ESIM (travel eSIM for international roaming).
Determined by the product offering the subscription was created with.
displaystringrequiredHuman-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation.
msisdnstringphonepersonal datarequiredThe phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number.
customerobjectrequiredCustomer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.
Show child attributes
customerstringrequiredThe unique identifier for the customer. Use it with the customer endpoints to fetch full details.
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers.
productobjectEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.
Show child attributes
netintegerint64The configured price of the offering, in minor currency units. When includesTax is
true, this amount is the total the customer pays, and the tax is a part of it.
includesbooleanTrue when the configured price includes its tax. The tax is then a part of
netPriceMinor rather than an amount on top of it.
currencystringrequiredThe ISO 4217 currency code the price is expressed in (e.g., "USD").
priceenum<string>requiredHow the price is charged.
- ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).
- RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).
values
ONE_TIMERECURRING
bindingobjectA commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.
Show child attributes
standardobjectA recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.
Show child attributes
customobjectBilling cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out.
Show child attributes
billingobjectHow often a recurring price is charged.
Show child attributes
currencyobject with string keysPer-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
productstringrequiredUnique identifier for the product group.
namestringrequiredName of the product group in the requested locale.
descriptionstringDescription of the product group in the requested locale.
categoryenum<string>requiredA 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 subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM- Data-only SIM subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND- Broadband internet subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_M2M- Machine-to-machine IoT subscriptionPRODUCT_CATEGORY_TRAVEL_ESIM- Travel eSIM subscription for international roaming
SUBSCRIPTION_ADDON categories:
PRODUCT_CATEGORY_EXTRA_DATA- Additional data package addonPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE- Travel eSIM data package with country/region coveragePRODUCT_CATEGORY_ABROAD- International roaming addon
EXTERNAL_PRODUCT categories:
PRODUCT_CATEGORY_EXTERNAL_PRODUCT- External purchasable productPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON- Addon for external product
SIM_CARD categories:
PRODUCT_CATEGORY_SIM_CARD- Physical SIM or eSIM replacement for an existing subscription
values
PRODUCT_CATEGORY_SUBSCRIPTION_CELLPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIMPRODUCT_CATEGORY_SUBSCRIPTION_BROADBANDPRODUCT_CATEGORY_SUBSCRIPTION_M2MPRODUCT_CATEGORY_TRAVEL_ESIMPRODUCT_CATEGORY_EXTRA_DATAPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGEPRODUCT_CATEGORY_ABROADPRODUCT_CATEGORY_EXTERNAL_PRODUCTPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDONPRODUCT_CATEGORY_SIM_CARD
internalstringInternal description of the product group for operational use only.
imagestringuriURL to the image representing the product offering.
subscriberobjectThe person who uses the service on a subscription, as distinct from the customer who pays for it.
Show child attributes
subscriberstringrequiredThe unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.
namestringrequiredThe subscriber's full name.
emailstringemailpersonal dataThe subscriber's email address, if one has been provided.
addressobjectdeprecatedDeprecated. Use serviceAddress on the subscription instead.
The service address of the subscription that embeds this subscriber.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
createdstringdate-timeDate and time when the subscriber was created.
updatedstringdate-timeDate and time when the subscriber was last updated.
serviceobjectThe address where this subscription is served. It is the address that the subscription holds, or the billing address of the customer when the subscription holds none.
Absent when no record holds an address.
The address where a subscription is served, and the record that holds it.
In the US, this is the E911 address that emergency services get for the phone number.
Show child attributes
addressobjectrequiredA postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
sourceenum<string>requiredThe record that holds the address.
SUBSCRIPTION: The subscription holds an address of its own.CUSTOMER_BILLING: The subscription holds no address of its own, so the billing address of the customer applies.
values
SUBSCRIPTIONCUSTOMER_BILLING
extensionsobject with string keysAdditional subscription extensions fields provided for custom subscription types.
Show child attributes
*stringsimobjectrequiredSIM 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
esimbooleanrequiredWhether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.
imeistringpersonal dataInternational Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.
Only applicable for eSIM.
iccidstringpersonal dataIntegrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.
pendingobjectpersonal dataA phone number change that has been requested but not yet applied. Present only while a number change is scheduled; the current number remains in msisdn until the change takes effect.
Show child attributes
msisdnstringphonepersonal datarequiredThe phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.
scheduledstringdateThe date when the pending number change is scheduled to occur.
bararray of BarReasonThe reasons of the bars that keep a BLOCKED subscription blocked. A subscription can have more than one bar, and it stays
blocked until every bar is removed. Present only while the status is BLOCKED.
pendingobjectA status change that has been requested but not yet applied, for example a scheduled cancellation or pause. Present only while a status change is scheduled.
Show child attributes
statusenum<string>requiredCurrent stage of the subscription lifecycle.
- PENDING: Created but not yet activated in the network
- ACTIVATED: Active and billable; service is available
- BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
- CANCELLED: Permanently terminated
- PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
- SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
scheduledstringdateThe date when the pending status change is scheduled to occur.
pendingobjectA product offering change (upgrade or downgrade) that has been requested but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.
Show child attributes
scheduledstringdaterequiredThe date when the pending product offering change is scheduled to occur.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
portingobjectNumber porting information for subscriptions, indicating scheduled number transfers.
To get the detailed porting information, use the porting endpoint.
Show child attributes
msisdnstringpersonal datarequiredThe pending phone number that the subscription will be ported in with. This will always be a non-active number.
statusenum<string>requiredCurrent status of the porting process.
- PENDING: Porting request created but not yet submitted to the carriers
- IN_PROGRESS: Request submitted and awaiting a response from the losing carrier
- SCHEDULED: Accepted by the losing carrier; the transfer will execute on the scheduled date
- COMPLETED: The number has been transferred and is active
- FAILED: The request was rejected, canceled, or could not be completed
values
PENDINGIN_PROGRESSSCHEDULEDCOMPLETEDFAILED
directionenum<string>requiredThe direction of the number transfer. INBOUND means the number is being ported into this platform from another carrier; OUTBOUND means the number is leaving this platform for another carrier.
values
INBOUNDOUTBOUND
scheduledstringdaterequiredThe date when the number porting is scheduled to occur.
activatedstringdate-timeThe date and time when the subscription was activated. Absent until the subscription has been activated.
cancelledstringdate-timeThe date and time when the subscription was cancelled (if applicable).
createdstringdate-timerequiredThe date and time when the subscription was created.
updatedstringdate-timerequiredThe date and time when the subscription was last updated.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*string400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
409The request conflicts with the current state of the resource.
application/json
The request conflicts with the current state of the resource.
The request conflicts with the current state of the resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
Auth required
Send one of
X-Api-KeyBearer JWT+X-Api-Key
The API key is always required; the bearer token is optional.
curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/product-offering-change \
--request PUT \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"scheduledAt": "2024-02-01",
"metadata": {
"propertyName": "string"
}
}'fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/product-offering-change', {
method: 'PUT',
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-Api-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
productOfferingId: 'f47ac10b-58cc-4372-a567-0e02b2c3d479',
scheduledAt: '2024-02-01',
metadata: {
propertyName: 'string'
}
})
})requests.put(
"https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/product-offering-change",
headers={
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"X-Api-Key": "YOUR_API_KEY",
"Content-Type": "application/json"
},
json={
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"scheduledAt": "2024-02-01",
"metadata": {
"propertyName": "string"
}
}
)package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/product-offering-change"
payload := strings.NewReader(`{
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"scheduledAt": "2024-02-01",
"metadata": {
"propertyName": "string"
}
}`)
req, _ := http.NewRequest("PUT", requestUrl, payload)
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"referenceId": "crm-subscription-12345",
"status": "PENDING",
"type": "CELL",
"display": "(555) 123-4567",
"msisdn": "+15551234567",
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
},
"productOffering": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"netPriceMinor": 2999,
"includesTax": false,
"currency": "USD",
"priceType": "ONE_TIME",
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
},
"subscriber": {
"subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
"name": "John Doe",
"email": "john.doe@example.com",
"address": {
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-20T14:45:00Z"
},
"serviceAddress": {
"address": {
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"source": "SUBSCRIPTION"
},
"extensions": {
"propertyName": "string"
},
"sim": {
"esim": true,
"imei": "356938035643809",
"iccid": "8901240197155182976"
},
"pendingMsisdn": {
"msisdn": "+15559876543",
"scheduledAt": "2024-02-01"
},
"barReasons": [
"MISSING_PAYMENT"
],
"pendingStatus": {
"status": "PENDING",
"scheduledAt": "2024-02-01"
},
"pendingProductOffering": {
"scheduledAt": "2024-02-01",
"product": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"netPriceMinor": 2999,
"includesTax": false,
"currency": "USD",
"priceType": "ONE_TIME",
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
}
},
"porting": {
"msisdn": "+15551234567",
"status": "PENDING",
"direction": "INBOUND",
"scheduledAt": "2024-02-01"
},
"activatedAt": "2024-01-15T10:30:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"createdAt": "2024-01-10T08:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"metadata": {
"propertyName": "string"
}
}{
"message": "The request body is invalid.",
"code": "bad_request",
"details": [
{
"message": "Email format is invalid.",
"code": "invalid_email",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields."
}{
"message": "Authentication is required to access this resource.",
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header."
}{
"message": "You do not have permission to perform this action.",
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions."
}{
"message": "The requested customer could not be found.",
"code": "not_found",
"hint": "Verify the customerId and try again."
}{
"message": "The request conflicts with the current state of the resource.",
"code": "conflict",
"hint": "Reload the resource to get its latest state before retrying."
}{
"message": "An unexpected error occurred on the server.",
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support."
}Get change options for subscription
/subscriptions/{subscriptionId}/product-offering-optionsGet all available product offerings a subscription can be changed to and when the change can take effect.
When the subscription can be changed typically depends on the network setup, billing cycle, and current product offering. As a rule of thumb (though not always), upgrades and lateral moves are immediate, while downgrades take effect at the next renewal date.
A product catalog can limit the product offerings that an offering change can move to. If a catalog of the customer does that, the options hold only product offerings of that list.
Path parameters
subscriptionstringrequiredThe identifier of the subscription. May be the entity's internal UUID or an external reference identifier.
Reference identifiers MUST be prefixed with rid_ (e.g., rid_crm-subscription-12345) so the API
can distinguish them from internal UUIDs. The prefix is stripped before lookup.
Responses
200Available change options.
application/json
Available change options.
Available change options.
object
itemsarray of ProductOfferingOptionrequiredShow child attributes
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
changeenum<string>requiredThe schedule type for when a product offering change can take effect.
- INSTANT: The change takes effect at once
- FIRST_OF_NEXT_MONTH: The change takes effect on the first day of the next calendar month
- NEXT_RENEWAL_DAY: The change takes effect on the next renewal date
- NEXT_PAYMENT_DAY: The change takes effect on the next payment day, when the days already paid for run out
- END_OF_PAID_PERIOD: The change takes effect the day after the current paid period ends
- END_OF_BINDING_PERIOD: The change takes effect the day after the binding period ends
values
INSTANTFIRST_OF_NEXT_MONTHNEXT_RENEWAL_DAYNEXT_PAYMENT_DAYEND_OF_PAID_PERIODEND_OF_BINDING_PERIOD
changestringdaterequiredThe date when the product offering change can take effect.
400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
Auth required
Send one of
X-Api-KeyBearer JWT+X-Api-Key
The API key is always required; the bearer token is optional.
curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/product-offering-options \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'X-Api-Key: YOUR_API_KEY'fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/product-offering-options', {
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-Api-Key': 'YOUR_API_KEY'
}
})requests.get(
"https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/product-offering-options",
headers={
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"X-Api-Key": "YOUR_API_KEY"
}
)package main
import (
"fmt"
"io"
"net/http"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/product-offering-options"
req, _ := http.NewRequest("GET", requestUrl, nil)
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"items": [
{
"productOffering": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"netPriceMinor": 2999,
"includesTax": false,
"currency": "USD",
"priceType": "ONE_TIME",
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
},
"changeSchedule": "INSTANT",
"changeScheduleDate": "2024-02-01"
}
]
}{
"message": "The request body is invalid.",
"code": "bad_request",
"details": [
{
"message": "Email format is invalid.",
"code": "invalid_email",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields."
}{
"message": "Authentication is required to access this resource.",
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header."
}{
"message": "You do not have permission to perform this action.",
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions."
}{
"message": "The requested customer could not be found.",
"code": "not_found",
"hint": "Verify the customerId and try again."
}{
"message": "An unexpected error occurred on the server.",
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support."
}Cancel subscription
/subscriptions/{subscriptionId}/cancelThis endpoint allows cancelling a subscription with various timing options:
- Next day cancellation
- Beginning of next month cancellation
- Specific date cancellation
Standardized churn reasons help with reporting and analysis.
Path parameters
subscriptionstringrequiredThe identifier of the subscription. May be the entity's internal UUID or an external reference identifier.
Reference identifiers MUST be prefixed with rid_ (e.g., rid_crm-subscription-12345) so the API
can distinguish them from internal UUIDs. The prefix is stripped before lookup.
Headers
X-stringmax length 256A 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.
BodyCancelSubscriptionRequestrequiredapplication/json
Request to cancel a subscription.
cancelone ofrequiredWhen the subscription should be cancelled.
Show child attributes
nextbooleanrequiredCancel the subscription the next day.
nextbooleanrequiredCancel the subscription at the beginning of next month.
datestringdaterequiredCancel the subscription on a specific date.
churnenum<string>Standardized reason for the cancellation used for reporting and analysis.
If OTHER is provided, please also provide a comment.
values
BETTER_DEAL_PRICENOT_HAPPY_MISSING_FUNCTIONSNOT_HAPPY_COVERAGE_SLANOT_HAPPY_COMPLEX_ADMINNOT_HAPPY_SUPPORT_ENGAGEMENTFRAUDFRAUD_ATTEMPTTEST_OR_MARKETINGNO_NEEDWRONG_ORDEROTHER
commentstringOptional comment about the cancellation.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringResponses
200Subscription cancellation scheduled successfully.
application/json
Subscription cancellation scheduled successfully.
Subscription cancellation scheduled successfully.
objectSubscription
A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details.
subscriptionstringrequiredThe unique identifier for the subscription.
referencestringmax length 255A 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.
statusenum<string>requiredCurrent stage of the subscription lifecycle.
- PENDING: Created but not yet activated in the network
- ACTIVATED: Active and billable; service is available
- BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
- CANCELLED: Permanently terminated
- PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
- SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
typestringrequiredThe kind of telecommunications service the subscription provides.
Common values include CELL (mobile voice/SMS/data), DATA (data-only SIM), MBB (mobile broadband),
M2M (machine-to-machine/IoT), and TRAVEL_ESIM (travel eSIM for international roaming).
Determined by the product offering the subscription was created with.
displaystringrequiredHuman-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation.
msisdnstringphonepersonal datarequiredThe phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number.
customerobjectrequiredCustomer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.
Show child attributes
customerstringrequiredThe unique identifier for the customer. Use it with the customer endpoints to fetch full details.
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers.
productobjectEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.
Show child attributes
netintegerint64The configured price of the offering, in minor currency units. When includesTax is
true, this amount is the total the customer pays, and the tax is a part of it.
includesbooleanTrue when the configured price includes its tax. The tax is then a part of
netPriceMinor rather than an amount on top of it.
currencystringrequiredThe ISO 4217 currency code the price is expressed in (e.g., "USD").
priceenum<string>requiredHow the price is charged.
- ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).
- RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).
values
ONE_TIMERECURRING
bindingobjectA commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.
Show child attributes
standardobjectA recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.
Show child attributes
customobjectBilling cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out.
Show child attributes
billingobjectHow often a recurring price is charged.
Show child attributes
currencyobject with string keysPer-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
productstringrequiredUnique identifier for the product group.
namestringrequiredName of the product group in the requested locale.
descriptionstringDescription of the product group in the requested locale.
categoryenum<string>requiredA 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 subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM- Data-only SIM subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND- Broadband internet subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_M2M- Machine-to-machine IoT subscriptionPRODUCT_CATEGORY_TRAVEL_ESIM- Travel eSIM subscription for international roaming
SUBSCRIPTION_ADDON categories:
PRODUCT_CATEGORY_EXTRA_DATA- Additional data package addonPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE- Travel eSIM data package with country/region coveragePRODUCT_CATEGORY_ABROAD- International roaming addon
EXTERNAL_PRODUCT categories:
PRODUCT_CATEGORY_EXTERNAL_PRODUCT- External purchasable productPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON- Addon for external product
SIM_CARD categories:
PRODUCT_CATEGORY_SIM_CARD- Physical SIM or eSIM replacement for an existing subscription
values
PRODUCT_CATEGORY_SUBSCRIPTION_CELLPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIMPRODUCT_CATEGORY_SUBSCRIPTION_BROADBANDPRODUCT_CATEGORY_SUBSCRIPTION_M2MPRODUCT_CATEGORY_TRAVEL_ESIMPRODUCT_CATEGORY_EXTRA_DATAPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGEPRODUCT_CATEGORY_ABROADPRODUCT_CATEGORY_EXTERNAL_PRODUCTPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDONPRODUCT_CATEGORY_SIM_CARD
internalstringInternal description of the product group for operational use only.
imagestringuriURL to the image representing the product offering.
subscriberobjectThe person who uses the service on a subscription, as distinct from the customer who pays for it.
Show child attributes
subscriberstringrequiredThe unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.
namestringrequiredThe subscriber's full name.
emailstringemailpersonal dataThe subscriber's email address, if one has been provided.
addressobjectdeprecatedDeprecated. Use serviceAddress on the subscription instead.
The service address of the subscription that embeds this subscriber.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
createdstringdate-timeDate and time when the subscriber was created.
updatedstringdate-timeDate and time when the subscriber was last updated.
serviceobjectThe address where this subscription is served. It is the address that the subscription holds, or the billing address of the customer when the subscription holds none.
Absent when no record holds an address.
The address where a subscription is served, and the record that holds it.
In the US, this is the E911 address that emergency services get for the phone number.
Show child attributes
addressobjectrequiredA postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
sourceenum<string>requiredThe record that holds the address.
SUBSCRIPTION: The subscription holds an address of its own.CUSTOMER_BILLING: The subscription holds no address of its own, so the billing address of the customer applies.
values
SUBSCRIPTIONCUSTOMER_BILLING
extensionsobject with string keysAdditional subscription extensions fields provided for custom subscription types.
Show child attributes
*stringsimobjectrequiredSIM 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
esimbooleanrequiredWhether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.
imeistringpersonal dataInternational Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.
Only applicable for eSIM.
iccidstringpersonal dataIntegrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.
pendingobjectpersonal dataA phone number change that has been requested but not yet applied. Present only while a number change is scheduled; the current number remains in msisdn until the change takes effect.
Show child attributes
msisdnstringphonepersonal datarequiredThe phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.
scheduledstringdateThe date when the pending number change is scheduled to occur.
bararray of BarReasonThe reasons of the bars that keep a BLOCKED subscription blocked. A subscription can have more than one bar, and it stays
blocked until every bar is removed. Present only while the status is BLOCKED.
pendingobjectA status change that has been requested but not yet applied, for example a scheduled cancellation or pause. Present only while a status change is scheduled.
Show child attributes
statusenum<string>requiredCurrent stage of the subscription lifecycle.
- PENDING: Created but not yet activated in the network
- ACTIVATED: Active and billable; service is available
- BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
- CANCELLED: Permanently terminated
- PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
- SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
scheduledstringdateThe date when the pending status change is scheduled to occur.
pendingobjectA product offering change (upgrade or downgrade) that has been requested but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.
Show child attributes
scheduledstringdaterequiredThe date when the pending product offering change is scheduled to occur.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
portingobjectNumber porting information for subscriptions, indicating scheduled number transfers.
To get the detailed porting information, use the porting endpoint.
Show child attributes
msisdnstringpersonal datarequiredThe pending phone number that the subscription will be ported in with. This will always be a non-active number.
statusenum<string>requiredCurrent status of the porting process.
- PENDING: Porting request created but not yet submitted to the carriers
- IN_PROGRESS: Request submitted and awaiting a response from the losing carrier
- SCHEDULED: Accepted by the losing carrier; the transfer will execute on the scheduled date
- COMPLETED: The number has been transferred and is active
- FAILED: The request was rejected, canceled, or could not be completed
values
PENDINGIN_PROGRESSSCHEDULEDCOMPLETEDFAILED
directionenum<string>requiredThe direction of the number transfer. INBOUND means the number is being ported into this platform from another carrier; OUTBOUND means the number is leaving this platform for another carrier.
values
INBOUNDOUTBOUND
scheduledstringdaterequiredThe date when the number porting is scheduled to occur.
activatedstringdate-timeThe date and time when the subscription was activated. Absent until the subscription has been activated.
cancelledstringdate-timeThe date and time when the subscription was cancelled (if applicable).
createdstringdate-timerequiredThe date and time when the subscription was created.
updatedstringdate-timerequiredThe date and time when the subscription was last updated.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*string400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
409The request conflicts with the current state of the resource.
application/json
The request conflicts with the current state of the resource.
The request conflicts with the current state of the resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
Auth required
Send one of
X-Api-KeyBearer JWT+X-Api-Key
The API key is always required; the bearer token is optional.
curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/cancel \
--request POST \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"cancelAt": {
"nextDay": true
},
"churn": "BETTER_DEAL_PRICE",
"comment": "Switching to a different provider",
"metadata": {
"propertyName": "string"
}
}'fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/cancel', {
method: 'POST',
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-Api-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
cancelAt: {
nextDay: true
},
churn: 'BETTER_DEAL_PRICE',
comment: 'Switching to a different provider',
metadata: {
propertyName: 'string'
}
})
})requests.post(
"https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/cancel",
headers={
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"X-Api-Key": "YOUR_API_KEY",
"Content-Type": "application/json"
},
json={
"cancelAt": {
"nextDay": True
},
"churn": "BETTER_DEAL_PRICE",
"comment": "Switching to a different provider",
"metadata": {
"propertyName": "string"
}
}
)package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/cancel"
payload := strings.NewReader(`{
"cancelAt": {
"nextDay": true
},
"churn": "BETTER_DEAL_PRICE",
"comment": "Switching to a different provider",
"metadata": {
"propertyName": "string"
}
}`)
req, _ := http.NewRequest("POST", requestUrl, payload)
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"referenceId": "crm-subscription-12345",
"status": "PENDING",
"type": "CELL",
"display": "(555) 123-4567",
"msisdn": "+15551234567",
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
},
"productOffering": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"netPriceMinor": 2999,
"includesTax": false,
"currency": "USD",
"priceType": "ONE_TIME",
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
},
"subscriber": {
"subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
"name": "John Doe",
"email": "john.doe@example.com",
"address": {
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-20T14:45:00Z"
},
"serviceAddress": {
"address": {
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"source": "SUBSCRIPTION"
},
"extensions": {
"propertyName": "string"
},
"sim": {
"esim": true,
"imei": "356938035643809",
"iccid": "8901240197155182976"
},
"pendingMsisdn": {
"msisdn": "+15559876543",
"scheduledAt": "2024-02-01"
},
"barReasons": [
"MISSING_PAYMENT"
],
"pendingStatus": {
"status": "PENDING",
"scheduledAt": "2024-02-01"
},
"pendingProductOffering": {
"scheduledAt": "2024-02-01",
"product": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"netPriceMinor": 2999,
"includesTax": false,
"currency": "USD",
"priceType": "ONE_TIME",
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
}
},
"porting": {
"msisdn": "+15551234567",
"status": "PENDING",
"direction": "INBOUND",
"scheduledAt": "2024-02-01"
},
"activatedAt": "2024-01-15T10:30:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"createdAt": "2024-01-10T08:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"metadata": {
"propertyName": "string"
}
}{
"message": "The request body is invalid.",
"code": "bad_request",
"details": [
{
"message": "Email format is invalid.",
"code": "invalid_email",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields."
}{
"message": "Authentication is required to access this resource.",
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header."
}{
"message": "You do not have permission to perform this action.",
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions."
}{
"message": "The requested customer could not be found.",
"code": "not_found",
"hint": "Verify the customerId and try again."
}{
"message": "The request conflicts with the current state of the resource.",
"code": "conflict",
"hint": "Reload the resource to get its latest state before retrying."
}{
"message": "An unexpected error occurred on the server.",
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support."
}Suspend subscription
/subscriptions/{subscriptionId}/suspendTemporarily suspend a subscription. The customer continues to pay but service is disabled. This is typically used for payment issues or fraud prevention.
Supports flexible scheduling:
- Immediate suspension
- Next day suspension
- Beginning of next month suspension
- Specific date suspension
Path parameters
subscriptionstringrequiredThe identifier of the subscription. May be the entity's internal UUID or an external reference identifier.
Reference identifiers MUST be prefixed with rid_ (e.g., rid_crm-subscription-12345) so the API
can distinguish them from internal UUIDs. The prefix is stripped before lookup.
Headers
X-stringmax length 256A 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.
BodySuspendSubscriptionRequestrequiredapplication/json
Request to temporarily suspend a subscription. The customer continues to pay but service is disabled.
scheduledstringdateSuspend the subscription on a specific date.
reasonstringOptional reason for the suspension.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringResponses
200Subscription suspension scheduled successfully.
application/json
Subscription suspension scheduled successfully.
Subscription suspension scheduled successfully.
objectSubscription
A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details.
subscriptionstringrequiredThe unique identifier for the subscription.
referencestringmax length 255A 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.
statusenum<string>requiredCurrent stage of the subscription lifecycle.
- PENDING: Created but not yet activated in the network
- ACTIVATED: Active and billable; service is available
- BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
- CANCELLED: Permanently terminated
- PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
- SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
typestringrequiredThe kind of telecommunications service the subscription provides.
Common values include CELL (mobile voice/SMS/data), DATA (data-only SIM), MBB (mobile broadband),
M2M (machine-to-machine/IoT), and TRAVEL_ESIM (travel eSIM for international roaming).
Determined by the product offering the subscription was created with.
displaystringrequiredHuman-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation.
msisdnstringphonepersonal datarequiredThe phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number.
customerobjectrequiredCustomer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.
Show child attributes
customerstringrequiredThe unique identifier for the customer. Use it with the customer endpoints to fetch full details.
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers.
productobjectEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.
Show child attributes
netintegerint64The configured price of the offering, in minor currency units. When includesTax is
true, this amount is the total the customer pays, and the tax is a part of it.
includesbooleanTrue when the configured price includes its tax. The tax is then a part of
netPriceMinor rather than an amount on top of it.
currencystringrequiredThe ISO 4217 currency code the price is expressed in (e.g., "USD").
priceenum<string>requiredHow the price is charged.
- ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).
- RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).
values
ONE_TIMERECURRING
bindingobjectA commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.
Show child attributes
standardobjectA recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.
Show child attributes
customobjectBilling cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out.
Show child attributes
billingobjectHow often a recurring price is charged.
Show child attributes
currencyobject with string keysPer-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
productstringrequiredUnique identifier for the product group.
namestringrequiredName of the product group in the requested locale.
descriptionstringDescription of the product group in the requested locale.
categoryenum<string>requiredA 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 subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM- Data-only SIM subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND- Broadband internet subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_M2M- Machine-to-machine IoT subscriptionPRODUCT_CATEGORY_TRAVEL_ESIM- Travel eSIM subscription for international roaming
SUBSCRIPTION_ADDON categories:
PRODUCT_CATEGORY_EXTRA_DATA- Additional data package addonPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE- Travel eSIM data package with country/region coveragePRODUCT_CATEGORY_ABROAD- International roaming addon
EXTERNAL_PRODUCT categories:
PRODUCT_CATEGORY_EXTERNAL_PRODUCT- External purchasable productPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON- Addon for external product
SIM_CARD categories:
PRODUCT_CATEGORY_SIM_CARD- Physical SIM or eSIM replacement for an existing subscription
values
PRODUCT_CATEGORY_SUBSCRIPTION_CELLPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIMPRODUCT_CATEGORY_SUBSCRIPTION_BROADBANDPRODUCT_CATEGORY_SUBSCRIPTION_M2MPRODUCT_CATEGORY_TRAVEL_ESIMPRODUCT_CATEGORY_EXTRA_DATAPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGEPRODUCT_CATEGORY_ABROADPRODUCT_CATEGORY_EXTERNAL_PRODUCTPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDONPRODUCT_CATEGORY_SIM_CARD
internalstringInternal description of the product group for operational use only.
imagestringuriURL to the image representing the product offering.
subscriberobjectThe person who uses the service on a subscription, as distinct from the customer who pays for it.
Show child attributes
subscriberstringrequiredThe unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.
namestringrequiredThe subscriber's full name.
emailstringemailpersonal dataThe subscriber's email address, if one has been provided.
addressobjectdeprecatedDeprecated. Use serviceAddress on the subscription instead.
The service address of the subscription that embeds this subscriber.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
createdstringdate-timeDate and time when the subscriber was created.
updatedstringdate-timeDate and time when the subscriber was last updated.
serviceobjectThe address where this subscription is served. It is the address that the subscription holds, or the billing address of the customer when the subscription holds none.
Absent when no record holds an address.
The address where a subscription is served, and the record that holds it.
In the US, this is the E911 address that emergency services get for the phone number.
Show child attributes
addressobjectrequiredA postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
sourceenum<string>requiredThe record that holds the address.
SUBSCRIPTION: The subscription holds an address of its own.CUSTOMER_BILLING: The subscription holds no address of its own, so the billing address of the customer applies.
values
SUBSCRIPTIONCUSTOMER_BILLING
extensionsobject with string keysAdditional subscription extensions fields provided for custom subscription types.
Show child attributes
*stringsimobjectrequiredSIM 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
esimbooleanrequiredWhether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.
imeistringpersonal dataInternational Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.
Only applicable for eSIM.
iccidstringpersonal dataIntegrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.
pendingobjectpersonal dataA phone number change that has been requested but not yet applied. Present only while a number change is scheduled; the current number remains in msisdn until the change takes effect.
Show child attributes
msisdnstringphonepersonal datarequiredThe phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.
scheduledstringdateThe date when the pending number change is scheduled to occur.
bararray of BarReasonThe reasons of the bars that keep a BLOCKED subscription blocked. A subscription can have more than one bar, and it stays
blocked until every bar is removed. Present only while the status is BLOCKED.
pendingobjectA status change that has been requested but not yet applied, for example a scheduled cancellation or pause. Present only while a status change is scheduled.
Show child attributes
statusenum<string>requiredCurrent stage of the subscription lifecycle.
- PENDING: Created but not yet activated in the network
- ACTIVATED: Active and billable; service is available
- BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
- CANCELLED: Permanently terminated
- PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
- SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
scheduledstringdateThe date when the pending status change is scheduled to occur.
pendingobjectA product offering change (upgrade or downgrade) that has been requested but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.
Show child attributes
scheduledstringdaterequiredThe date when the pending product offering change is scheduled to occur.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
portingobjectNumber porting information for subscriptions, indicating scheduled number transfers.
To get the detailed porting information, use the porting endpoint.
Show child attributes
msisdnstringpersonal datarequiredThe pending phone number that the subscription will be ported in with. This will always be a non-active number.
statusenum<string>requiredCurrent status of the porting process.
- PENDING: Porting request created but not yet submitted to the carriers
- IN_PROGRESS: Request submitted and awaiting a response from the losing carrier
- SCHEDULED: Accepted by the losing carrier; the transfer will execute on the scheduled date
- COMPLETED: The number has been transferred and is active
- FAILED: The request was rejected, canceled, or could not be completed
values
PENDINGIN_PROGRESSSCHEDULEDCOMPLETEDFAILED
directionenum<string>requiredThe direction of the number transfer. INBOUND means the number is being ported into this platform from another carrier; OUTBOUND means the number is leaving this platform for another carrier.
values
INBOUNDOUTBOUND
scheduledstringdaterequiredThe date when the number porting is scheduled to occur.
activatedstringdate-timeThe date and time when the subscription was activated. Absent until the subscription has been activated.
cancelledstringdate-timeThe date and time when the subscription was cancelled (if applicable).
createdstringdate-timerequiredThe date and time when the subscription was created.
updatedstringdate-timerequiredThe date and time when the subscription was last updated.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*string400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
409The request conflicts with the current state of the resource.
application/json
The request conflicts with the current state of the resource.
The request conflicts with the current state of the resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
Auth required
Send one of
X-Api-KeyBearer JWT+X-Api-Key
The API key is always required; the bearer token is optional.
curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/suspend \
--request POST \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"scheduledAt": "2024-02-01",
"reason": "Payment overdue",
"metadata": {
"propertyName": "string"
}
}'fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/suspend', {
method: 'POST',
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-Api-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
scheduledAt: '2024-02-01',
reason: 'Payment overdue',
metadata: {
propertyName: 'string'
}
})
})requests.post(
"https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/suspend",
headers={
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"X-Api-Key": "YOUR_API_KEY",
"Content-Type": "application/json"
},
json={
"scheduledAt": "2024-02-01",
"reason": "Payment overdue",
"metadata": {
"propertyName": "string"
}
}
)package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/suspend"
payload := strings.NewReader(`{
"scheduledAt": "2024-02-01",
"reason": "Payment overdue",
"metadata": {
"propertyName": "string"
}
}`)
req, _ := http.NewRequest("POST", requestUrl, payload)
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"referenceId": "crm-subscription-12345",
"status": "PENDING",
"type": "CELL",
"display": "(555) 123-4567",
"msisdn": "+15551234567",
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
},
"productOffering": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"netPriceMinor": 2999,
"includesTax": false,
"currency": "USD",
"priceType": "ONE_TIME",
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
},
"subscriber": {
"subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
"name": "John Doe",
"email": "john.doe@example.com",
"address": {
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-20T14:45:00Z"
},
"serviceAddress": {
"address": {
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"source": "SUBSCRIPTION"
},
"extensions": {
"propertyName": "string"
},
"sim": {
"esim": true,
"imei": "356938035643809",
"iccid": "8901240197155182976"
},
"pendingMsisdn": {
"msisdn": "+15559876543",
"scheduledAt": "2024-02-01"
},
"barReasons": [
"MISSING_PAYMENT"
],
"pendingStatus": {
"status": "PENDING",
"scheduledAt": "2024-02-01"
},
"pendingProductOffering": {
"scheduledAt": "2024-02-01",
"product": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"netPriceMinor": 2999,
"includesTax": false,
"currency": "USD",
"priceType": "ONE_TIME",
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
}
},
"porting": {
"msisdn": "+15551234567",
"status": "PENDING",
"direction": "INBOUND",
"scheduledAt": "2024-02-01"
},
"activatedAt": "2024-01-15T10:30:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"createdAt": "2024-01-10T08:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"metadata": {
"propertyName": "string"
}
}{
"message": "The request body is invalid.",
"code": "bad_request",
"details": [
{
"message": "Email format is invalid.",
"code": "invalid_email",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields."
}{
"message": "Authentication is required to access this resource.",
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header."
}{
"message": "You do not have permission to perform this action.",
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions."
}{
"message": "The requested customer could not be found.",
"code": "not_found",
"hint": "Verify the customerId and try again."
}{
"message": "The request conflicts with the current state of the resource.",
"code": "conflict",
"hint": "Reload the resource to get its latest state before retrying."
}{
"message": "An unexpected error occurred on the server.",
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support."
}Pause subscription
/subscriptions/{subscriptionId}/pausePause a subscription. The customer stops paying and service is disabled. This is typically used when a customer wants to temporarily stop service.
Supports flexible scheduling:
- Immediate pause
- Next day pause
- Beginning of next month pause
- Specific date pause
Path parameters
subscriptionstringrequiredThe identifier of the subscription. May be the entity's internal UUID or an external reference identifier.
Reference identifiers MUST be prefixed with rid_ (e.g., rid_crm-subscription-12345) so the API
can distinguish them from internal UUIDs. The prefix is stripped before lookup.
Headers
X-stringmax length 256A 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.
BodyPauseSubscriptionRequestrequiredapplication/json
Request to pause a subscription. The customer stops paying and service is disabled.
scheduledstringdateEarliest date to perform the pause on. If the pause schedule doesn't fit this date, the earliest date after this will be chosen.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringResponses
200Subscription pause scheduled successfully.
application/json
Subscription pause scheduled successfully.
Subscription pause scheduled successfully.
objectSubscription
A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details.
subscriptionstringrequiredThe unique identifier for the subscription.
referencestringmax length 255A 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.
statusenum<string>requiredCurrent stage of the subscription lifecycle.
- PENDING: Created but not yet activated in the network
- ACTIVATED: Active and billable; service is available
- BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
- CANCELLED: Permanently terminated
- PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
- SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
typestringrequiredThe kind of telecommunications service the subscription provides.
Common values include CELL (mobile voice/SMS/data), DATA (data-only SIM), MBB (mobile broadband),
M2M (machine-to-machine/IoT), and TRAVEL_ESIM (travel eSIM for international roaming).
Determined by the product offering the subscription was created with.
displaystringrequiredHuman-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation.
msisdnstringphonepersonal datarequiredThe phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number.
customerobjectrequiredCustomer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.
Show child attributes
customerstringrequiredThe unique identifier for the customer. Use it with the customer endpoints to fetch full details.
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers.
productobjectEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.
Show child attributes
netintegerint64The configured price of the offering, in minor currency units. When includesTax is
true, this amount is the total the customer pays, and the tax is a part of it.
includesbooleanTrue when the configured price includes its tax. The tax is then a part of
netPriceMinor rather than an amount on top of it.
currencystringrequiredThe ISO 4217 currency code the price is expressed in (e.g., "USD").
priceenum<string>requiredHow the price is charged.
- ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).
- RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).
values
ONE_TIMERECURRING
bindingobjectA commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.
Show child attributes
standardobjectA recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.
Show child attributes
customobjectBilling cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out.
Show child attributes
billingobjectHow often a recurring price is charged.
Show child attributes
currencyobject with string keysPer-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
productstringrequiredUnique identifier for the product group.
namestringrequiredName of the product group in the requested locale.
descriptionstringDescription of the product group in the requested locale.
categoryenum<string>requiredA 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 subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM- Data-only SIM subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND- Broadband internet subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_M2M- Machine-to-machine IoT subscriptionPRODUCT_CATEGORY_TRAVEL_ESIM- Travel eSIM subscription for international roaming
SUBSCRIPTION_ADDON categories:
PRODUCT_CATEGORY_EXTRA_DATA- Additional data package addonPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE- Travel eSIM data package with country/region coveragePRODUCT_CATEGORY_ABROAD- International roaming addon
EXTERNAL_PRODUCT categories:
PRODUCT_CATEGORY_EXTERNAL_PRODUCT- External purchasable productPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON- Addon for external product
SIM_CARD categories:
PRODUCT_CATEGORY_SIM_CARD- Physical SIM or eSIM replacement for an existing subscription
values
PRODUCT_CATEGORY_SUBSCRIPTION_CELLPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIMPRODUCT_CATEGORY_SUBSCRIPTION_BROADBANDPRODUCT_CATEGORY_SUBSCRIPTION_M2MPRODUCT_CATEGORY_TRAVEL_ESIMPRODUCT_CATEGORY_EXTRA_DATAPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGEPRODUCT_CATEGORY_ABROADPRODUCT_CATEGORY_EXTERNAL_PRODUCTPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDONPRODUCT_CATEGORY_SIM_CARD
internalstringInternal description of the product group for operational use only.
imagestringuriURL to the image representing the product offering.
subscriberobjectThe person who uses the service on a subscription, as distinct from the customer who pays for it.
Show child attributes
subscriberstringrequiredThe unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.
namestringrequiredThe subscriber's full name.
emailstringemailpersonal dataThe subscriber's email address, if one has been provided.
addressobjectdeprecatedDeprecated. Use serviceAddress on the subscription instead.
The service address of the subscription that embeds this subscriber.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
createdstringdate-timeDate and time when the subscriber was created.
updatedstringdate-timeDate and time when the subscriber was last updated.
serviceobjectThe address where this subscription is served. It is the address that the subscription holds, or the billing address of the customer when the subscription holds none.
Absent when no record holds an address.
The address where a subscription is served, and the record that holds it.
In the US, this is the E911 address that emergency services get for the phone number.
Show child attributes
addressobjectrequiredA postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
sourceenum<string>requiredThe record that holds the address.
SUBSCRIPTION: The subscription holds an address of its own.CUSTOMER_BILLING: The subscription holds no address of its own, so the billing address of the customer applies.
values
SUBSCRIPTIONCUSTOMER_BILLING
extensionsobject with string keysAdditional subscription extensions fields provided for custom subscription types.
Show child attributes
*stringsimobjectrequiredSIM 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
esimbooleanrequiredWhether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.
imeistringpersonal dataInternational Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.
Only applicable for eSIM.
iccidstringpersonal dataIntegrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.
pendingobjectpersonal dataA phone number change that has been requested but not yet applied. Present only while a number change is scheduled; the current number remains in msisdn until the change takes effect.
Show child attributes
msisdnstringphonepersonal datarequiredThe phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.
scheduledstringdateThe date when the pending number change is scheduled to occur.
bararray of BarReasonThe reasons of the bars that keep a BLOCKED subscription blocked. A subscription can have more than one bar, and it stays
blocked until every bar is removed. Present only while the status is BLOCKED.
pendingobjectA status change that has been requested but not yet applied, for example a scheduled cancellation or pause. Present only while a status change is scheduled.
Show child attributes
statusenum<string>requiredCurrent stage of the subscription lifecycle.
- PENDING: Created but not yet activated in the network
- ACTIVATED: Active and billable; service is available
- BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
- CANCELLED: Permanently terminated
- PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
- SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
scheduledstringdateThe date when the pending status change is scheduled to occur.
pendingobjectA product offering change (upgrade or downgrade) that has been requested but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.
Show child attributes
scheduledstringdaterequiredThe date when the pending product offering change is scheduled to occur.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
portingobjectNumber porting information for subscriptions, indicating scheduled number transfers.
To get the detailed porting information, use the porting endpoint.
Show child attributes
msisdnstringpersonal datarequiredThe pending phone number that the subscription will be ported in with. This will always be a non-active number.
statusenum<string>requiredCurrent status of the porting process.
- PENDING: Porting request created but not yet submitted to the carriers
- IN_PROGRESS: Request submitted and awaiting a response from the losing carrier
- SCHEDULED: Accepted by the losing carrier; the transfer will execute on the scheduled date
- COMPLETED: The number has been transferred and is active
- FAILED: The request was rejected, canceled, or could not be completed
values
PENDINGIN_PROGRESSSCHEDULEDCOMPLETEDFAILED
directionenum<string>requiredThe direction of the number transfer. INBOUND means the number is being ported into this platform from another carrier; OUTBOUND means the number is leaving this platform for another carrier.
values
INBOUNDOUTBOUND
scheduledstringdaterequiredThe date when the number porting is scheduled to occur.
activatedstringdate-timeThe date and time when the subscription was activated. Absent until the subscription has been activated.
cancelledstringdate-timeThe date and time when the subscription was cancelled (if applicable).
createdstringdate-timerequiredThe date and time when the subscription was created.
updatedstringdate-timerequiredThe date and time when the subscription was last updated.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*string400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
409The request conflicts with the current state of the resource.
application/json
The request conflicts with the current state of the resource.
The request conflicts with the current state of the resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
Auth required
Send one of
X-Api-KeyBearer JWT+X-Api-Key
The API key is always required; the bearer token is optional.
curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/pause \
--request POST \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"scheduledAt": "2024-02-01",
"metadata": {
"propertyName": "string"
}
}'fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/pause', {
method: 'POST',
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-Api-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
scheduledAt: '2024-02-01',
metadata: {
propertyName: 'string'
}
})
})requests.post(
"https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/pause",
headers={
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"X-Api-Key": "YOUR_API_KEY",
"Content-Type": "application/json"
},
json={
"scheduledAt": "2024-02-01",
"metadata": {
"propertyName": "string"
}
}
)package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/pause"
payload := strings.NewReader(`{
"scheduledAt": "2024-02-01",
"metadata": {
"propertyName": "string"
}
}`)
req, _ := http.NewRequest("POST", requestUrl, payload)
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"referenceId": "crm-subscription-12345",
"status": "PENDING",
"type": "CELL",
"display": "(555) 123-4567",
"msisdn": "+15551234567",
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
},
"productOffering": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"netPriceMinor": 2999,
"includesTax": false,
"currency": "USD",
"priceType": "ONE_TIME",
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
},
"subscriber": {
"subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
"name": "John Doe",
"email": "john.doe@example.com",
"address": {
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-20T14:45:00Z"
},
"serviceAddress": {
"address": {
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"source": "SUBSCRIPTION"
},
"extensions": {
"propertyName": "string"
},
"sim": {
"esim": true,
"imei": "356938035643809",
"iccid": "8901240197155182976"
},
"pendingMsisdn": {
"msisdn": "+15559876543",
"scheduledAt": "2024-02-01"
},
"barReasons": [
"MISSING_PAYMENT"
],
"pendingStatus": {
"status": "PENDING",
"scheduledAt": "2024-02-01"
},
"pendingProductOffering": {
"scheduledAt": "2024-02-01",
"product": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"netPriceMinor": 2999,
"includesTax": false,
"currency": "USD",
"priceType": "ONE_TIME",
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
}
},
"porting": {
"msisdn": "+15551234567",
"status": "PENDING",
"direction": "INBOUND",
"scheduledAt": "2024-02-01"
},
"activatedAt": "2024-01-15T10:30:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"createdAt": "2024-01-10T08:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"metadata": {
"propertyName": "string"
}
}{
"message": "The request body is invalid.",
"code": "bad_request",
"details": [
{
"message": "Email format is invalid.",
"code": "invalid_email",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields."
}{
"message": "Authentication is required to access this resource.",
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header."
}{
"message": "You do not have permission to perform this action.",
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions."
}{
"message": "The requested customer could not be found.",
"code": "not_found",
"hint": "Verify the customerId and try again."
}{
"message": "The request conflicts with the current state of the resource.",
"code": "conflict",
"hint": "Reload the resource to get its latest state before retrying."
}{
"message": "An unexpected error occurred on the server.",
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support."
}Restore subscription
/subscriptions/{subscriptionId}/restoreRestore a suspended, paused, or blocked subscription back to active state.
A blocked subscription can have more than one bar. To remove only some of them, name their reasons in barReasons.
The subscription then stays blocked until the last bar is removed.
Supports flexible scheduling:
- Immediate restore
- Next day restoration
- Beginning of next month restoration
- Specific date restoration
Path parameters
subscriptionstringrequiredThe identifier of the subscription. May be the entity's internal UUID or an external reference identifier.
Reference identifiers MUST be prefixed with rid_ (e.g., rid_crm-subscription-12345) so the API
can distinguish them from internal UUIDs. The prefix is stripped before lookup.
Headers
X-stringmax length 256A 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.
BodyRestoreSubscriptionRequestrequiredapplication/json
Request to restore a suspended, paused, or blocked subscription back to active state.
scheduledstringdateRestore the subscription on a specific date.
allowedarray of SubscriptionStatusCurrent statuses from which this request can restore the subscription. If omitted, the request can restore all supported statuses.
bararray of BarReasonmin items 1The reasons of the bars to remove from a BLOCKED subscription. The barReasons field of the subscription lists them.
The subscription is activated only when no other bar stays. Otherwise it stays BLOCKED with the bars that stay.
If omitted, the request removes every bar. If the subscription has no bar with one of these reasons, the request fails with 412.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringResponses
200Subscription restoration scheduled successfully.
application/json
Subscription restoration scheduled successfully.
Subscription restoration scheduled successfully.
objectSubscription
A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details.
subscriptionstringrequiredThe unique identifier for the subscription.
referencestringmax length 255A 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.
statusenum<string>requiredCurrent stage of the subscription lifecycle.
- PENDING: Created but not yet activated in the network
- ACTIVATED: Active and billable; service is available
- BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
- CANCELLED: Permanently terminated
- PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
- SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
typestringrequiredThe kind of telecommunications service the subscription provides.
Common values include CELL (mobile voice/SMS/data), DATA (data-only SIM), MBB (mobile broadband),
M2M (machine-to-machine/IoT), and TRAVEL_ESIM (travel eSIM for international roaming).
Determined by the product offering the subscription was created with.
displaystringrequiredHuman-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation.
msisdnstringphonepersonal datarequiredThe phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number.
customerobjectrequiredCustomer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.
Show child attributes
customerstringrequiredThe unique identifier for the customer. Use it with the customer endpoints to fetch full details.
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers.
productobjectEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.
Show child attributes
netintegerint64The configured price of the offering, in minor currency units. When includesTax is
true, this amount is the total the customer pays, and the tax is a part of it.
includesbooleanTrue when the configured price includes its tax. The tax is then a part of
netPriceMinor rather than an amount on top of it.
currencystringrequiredThe ISO 4217 currency code the price is expressed in (e.g., "USD").
priceenum<string>requiredHow the price is charged.
- ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).
- RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).
values
ONE_TIMERECURRING
bindingobjectA commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.
Show child attributes
standardobjectA recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.
Show child attributes
customobjectBilling cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out.
Show child attributes
billingobjectHow often a recurring price is charged.
Show child attributes
currencyobject with string keysPer-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
productstringrequiredUnique identifier for the product group.
namestringrequiredName of the product group in the requested locale.
descriptionstringDescription of the product group in the requested locale.
categoryenum<string>requiredA 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 subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM- Data-only SIM subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND- Broadband internet subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_M2M- Machine-to-machine IoT subscriptionPRODUCT_CATEGORY_TRAVEL_ESIM- Travel eSIM subscription for international roaming
SUBSCRIPTION_ADDON categories:
PRODUCT_CATEGORY_EXTRA_DATA- Additional data package addonPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE- Travel eSIM data package with country/region coveragePRODUCT_CATEGORY_ABROAD- International roaming addon
EXTERNAL_PRODUCT categories:
PRODUCT_CATEGORY_EXTERNAL_PRODUCT- External purchasable productPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON- Addon for external product
SIM_CARD categories:
PRODUCT_CATEGORY_SIM_CARD- Physical SIM or eSIM replacement for an existing subscription
values
PRODUCT_CATEGORY_SUBSCRIPTION_CELLPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIMPRODUCT_CATEGORY_SUBSCRIPTION_BROADBANDPRODUCT_CATEGORY_SUBSCRIPTION_M2MPRODUCT_CATEGORY_TRAVEL_ESIMPRODUCT_CATEGORY_EXTRA_DATAPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGEPRODUCT_CATEGORY_ABROADPRODUCT_CATEGORY_EXTERNAL_PRODUCTPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDONPRODUCT_CATEGORY_SIM_CARD
internalstringInternal description of the product group for operational use only.
imagestringuriURL to the image representing the product offering.
subscriberobjectThe person who uses the service on a subscription, as distinct from the customer who pays for it.
Show child attributes
subscriberstringrequiredThe unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.
namestringrequiredThe subscriber's full name.
emailstringemailpersonal dataThe subscriber's email address, if one has been provided.
addressobjectdeprecatedDeprecated. Use serviceAddress on the subscription instead.
The service address of the subscription that embeds this subscriber.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
createdstringdate-timeDate and time when the subscriber was created.
updatedstringdate-timeDate and time when the subscriber was last updated.
serviceobjectThe address where this subscription is served. It is the address that the subscription holds, or the billing address of the customer when the subscription holds none.
Absent when no record holds an address.
The address where a subscription is served, and the record that holds it.
In the US, this is the E911 address that emergency services get for the phone number.
Show child attributes
addressobjectrequiredA postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
sourceenum<string>requiredThe record that holds the address.
SUBSCRIPTION: The subscription holds an address of its own.CUSTOMER_BILLING: The subscription holds no address of its own, so the billing address of the customer applies.
values
SUBSCRIPTIONCUSTOMER_BILLING
extensionsobject with string keysAdditional subscription extensions fields provided for custom subscription types.
Show child attributes
*stringsimobjectrequiredSIM 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
esimbooleanrequiredWhether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.
imeistringpersonal dataInternational Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.
Only applicable for eSIM.
iccidstringpersonal dataIntegrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.
pendingobjectpersonal dataA phone number change that has been requested but not yet applied. Present only while a number change is scheduled; the current number remains in msisdn until the change takes effect.
Show child attributes
msisdnstringphonepersonal datarequiredThe phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.
scheduledstringdateThe date when the pending number change is scheduled to occur.
bararray of BarReasonThe reasons of the bars that keep a BLOCKED subscription blocked. A subscription can have more than one bar, and it stays
blocked until every bar is removed. Present only while the status is BLOCKED.
pendingobjectA status change that has been requested but not yet applied, for example a scheduled cancellation or pause. Present only while a status change is scheduled.
Show child attributes
statusenum<string>requiredCurrent stage of the subscription lifecycle.
- PENDING: Created but not yet activated in the network
- ACTIVATED: Active and billable; service is available
- BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
- CANCELLED: Permanently terminated
- PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
- SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
scheduledstringdateThe date when the pending status change is scheduled to occur.
pendingobjectA product offering change (upgrade or downgrade) that has been requested but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.
Show child attributes
scheduledstringdaterequiredThe date when the pending product offering change is scheduled to occur.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
portingobjectNumber porting information for subscriptions, indicating scheduled number transfers.
To get the detailed porting information, use the porting endpoint.
Show child attributes
msisdnstringpersonal datarequiredThe pending phone number that the subscription will be ported in with. This will always be a non-active number.
statusenum<string>requiredCurrent status of the porting process.
- PENDING: Porting request created but not yet submitted to the carriers
- IN_PROGRESS: Request submitted and awaiting a response from the losing carrier
- SCHEDULED: Accepted by the losing carrier; the transfer will execute on the scheduled date
- COMPLETED: The number has been transferred and is active
- FAILED: The request was rejected, canceled, or could not be completed
values
PENDINGIN_PROGRESSSCHEDULEDCOMPLETEDFAILED
directionenum<string>requiredThe direction of the number transfer. INBOUND means the number is being ported into this platform from another carrier; OUTBOUND means the number is leaving this platform for another carrier.
values
INBOUNDOUTBOUND
scheduledstringdaterequiredThe date when the number porting is scheduled to occur.
activatedstringdate-timeThe date and time when the subscription was activated. Absent until the subscription has been activated.
cancelledstringdate-timeThe date and time when the subscription was cancelled (if applicable).
createdstringdate-timerequiredThe date and time when the subscription was created.
updatedstringdate-timerequiredThe date and time when the subscription was last updated.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*string400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
409The request conflicts with the current state of the resource.
application/json
The request conflicts with the current state of the resource.
The request conflicts with the current state of the resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
412A precondition for this request was not met.
application/json
A precondition for this request was not met.
A precondition for this request was not met.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
Auth required
Send one of
X-Api-KeyBearer JWT+X-Api-Key
The API key is always required; the bearer token is optional.
curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/restore \
--request POST \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"scheduledAt": "2024-02-01",
"allowedCurrentStatuses": [
"PENDING"
],
"barReasons": [
"MISSING_PAYMENT"
],
"metadata": {
"propertyName": "string"
}
}'fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/restore', {
method: 'POST',
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-Api-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
scheduledAt: '2024-02-01',
allowedCurrentStatuses: ['PENDING'],
barReasons: ['MISSING_PAYMENT'],
metadata: {
propertyName: 'string'
}
})
})requests.post(
"https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/restore",
headers={
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"X-Api-Key": "YOUR_API_KEY",
"Content-Type": "application/json"
},
json={
"scheduledAt": "2024-02-01",
"allowedCurrentStatuses": [
"PENDING"
],
"barReasons": [
"MISSING_PAYMENT"
],
"metadata": {
"propertyName": "string"
}
}
)package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/restore"
payload := strings.NewReader(`{
"scheduledAt": "2024-02-01",
"allowedCurrentStatuses": [
"PENDING"
],
"barReasons": [
"MISSING_PAYMENT"
],
"metadata": {
"propertyName": "string"
}
}`)
req, _ := http.NewRequest("POST", requestUrl, payload)
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"referenceId": "crm-subscription-12345",
"status": "PENDING",
"type": "CELL",
"display": "(555) 123-4567",
"msisdn": "+15551234567",
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
},
"productOffering": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"netPriceMinor": 2999,
"includesTax": false,
"currency": "USD",
"priceType": "ONE_TIME",
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
},
"subscriber": {
"subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
"name": "John Doe",
"email": "john.doe@example.com",
"address": {
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-20T14:45:00Z"
},
"serviceAddress": {
"address": {
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"source": "SUBSCRIPTION"
},
"extensions": {
"propertyName": "string"
},
"sim": {
"esim": true,
"imei": "356938035643809",
"iccid": "8901240197155182976"
},
"pendingMsisdn": {
"msisdn": "+15559876543",
"scheduledAt": "2024-02-01"
},
"barReasons": [
"MISSING_PAYMENT"
],
"pendingStatus": {
"status": "PENDING",
"scheduledAt": "2024-02-01"
},
"pendingProductOffering": {
"scheduledAt": "2024-02-01",
"product": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"netPriceMinor": 2999,
"includesTax": false,
"currency": "USD",
"priceType": "ONE_TIME",
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
}
},
"porting": {
"msisdn": "+15551234567",
"status": "PENDING",
"direction": "INBOUND",
"scheduledAt": "2024-02-01"
},
"activatedAt": "2024-01-15T10:30:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"createdAt": "2024-01-10T08:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"metadata": {
"propertyName": "string"
}
}{
"message": "The request body is invalid.",
"code": "bad_request",
"details": [
{
"message": "Email format is invalid.",
"code": "invalid_email",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields."
}{
"message": "Authentication is required to access this resource.",
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header."
}{
"message": "You do not have permission to perform this action.",
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions."
}{
"message": "The requested customer could not be found.",
"code": "not_found",
"hint": "Verify the customerId and try again."
}{
"message": "The request conflicts with the current state of the resource.",
"code": "conflict",
"hint": "Reload the resource to get its latest state before retrying."
}{
"message": "A precondition given in the request headers was not met.",
"code": "precondition_failed",
"hint": "Fetch the current resource and retry with an up-to-date precondition."
}{
"message": "An unexpected error occurred on the server.",
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support."
}Get the US port-out PIN
/subscriptions/{subscriptionId}/us-port-out-pinGet the active port-out PIN of a subscription and whether the subscription can port out. A
subscription that cannot port out, for example during a binding period or with a leased custom
number, has portable false and no PIN.
Only US brands support this operation. Other brands return 501 Not Implemented.
Path parameters
subscriptionstringrequiredThe identifier of the subscription. May be the entity's internal UUID or an external reference identifier.
Reference identifiers MUST be prefixed with rid_ (e.g., rid_crm-subscription-12345) so the API
can distinguish them from internal UUIDs. The prefix is stripped before lookup.
Responses
200The port-out state of the subscription.
application/json
The port-out state of the subscription.
The port-out state of the subscription.
objectUSPortOutPinState
The US port-out state of a subscription.
portablebooleanrequiredFalse when the subscription cannot port out, for example during a binding period. The PIN is then hidden, and no PIN can be generated.
activeobjectThe active PIN. It is absent when the subscription has no active PIN.
A PIN that a subscriber gives to a new carrier to move a US number away.
Show child attributes
pinstringpersonal datarequiredThe 6-digit port-out PIN. Treat it as a credential.
expiresstringdate-timerequiredWhen the PIN stops working.
400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
501This endpoint is not available for this brand. The network it asks cannot
answer the question, so no request will succeed until the brand is configured
with a network that can.
application/json
This endpoint is not available for this brand. The network it asks cannot answer the question, so no request will succeed until the brand is configured with a network that can.
This endpoint is not available for this brand. The network it asks cannot answer the question, so no request will succeed until the brand is configured with a network that can.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
Auth required
Send one of
X-Api-KeyBearer JWT+X-Api-Key
The API key is always required; the bearer token is optional.
curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/us-port-out-pin \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'X-Api-Key: YOUR_API_KEY'fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/us-port-out-pin', {
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-Api-Key': 'YOUR_API_KEY'
}
})requests.get(
"https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/us-port-out-pin",
headers={
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"X-Api-Key": "YOUR_API_KEY"
}
)package main
import (
"fmt"
"io"
"net/http"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/us-port-out-pin"
req, _ := http.NewRequest("GET", requestUrl, nil)
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"portable": true,
"activePin": {
"pin": "string",
"expiresAt": "2024-01-15T10:30:00Z"
}
}{
"message": "The request body is invalid.",
"code": "bad_request",
"details": [
{
"message": "Email format is invalid.",
"code": "invalid_email",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields."
}{
"message": "Authentication is required to access this resource.",
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header."
}{
"message": "You do not have permission to perform this action.",
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions."
}{
"message": "The requested customer could not be found.",
"code": "not_found",
"hint": "Verify the customerId and try again."
}{
"message": "An unexpected error occurred on the server.",
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support."
}{
"message": "This endpoint is not available in this environment.",
"code": "not_implemented",
"hint": "The network behind this brand cannot answer this request."
}Generate a US port-out PIN
/subscriptions/{subscriptionId}/us-port-out-pinGenerate a new PIN that the subscriber gives to a new carrier to move the number away from this subscription. The PIN is valid for 7 days. The previous PIN of the subscription stops working when you generate a new one.
A subscription that cannot port out, for example during a binding period or with a leased
custom number, returns 412 Precondition Failed. Only US brands support this operation. Other
brands return 501 Not Implemented.
Path parameters
subscriptionstringrequiredThe identifier of the subscription. May be the entity's internal UUID or an external reference identifier.
Reference identifiers MUST be prefixed with rid_ (e.g., rid_crm-subscription-12345) so the API
can distinguish them from internal UUIDs. The prefix is stripped before lookup.
Responses
200The new PIN.
application/json
The new PIN.
The new PIN.
objectUSPortOutPin
A PIN that a subscriber gives to a new carrier to move a US number away.
pinstringpersonal datarequiredThe 6-digit port-out PIN. Treat it as a credential.
expiresstringdate-timerequiredWhen the PIN stops working.
400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
412A precondition for this request was not met.
application/json
A precondition for this request was not met.
A precondition for this request was not met.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
501This endpoint is not available for this brand. The network it asks cannot
answer the question, so no request will succeed until the brand is configured
with a network that can.
application/json
This endpoint is not available for this brand. The network it asks cannot answer the question, so no request will succeed until the brand is configured with a network that can.
This endpoint is not available for this brand. The network it asks cannot answer the question, so no request will succeed until the brand is configured with a network that can.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
Auth required
Send one of
X-Api-KeyBearer JWT+X-Api-Key
The API key is always required; the bearer token is optional.
curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/us-port-out-pin \
--request POST \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'X-Api-Key: YOUR_API_KEY'fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/us-port-out-pin', {
method: 'POST',
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-Api-Key': 'YOUR_API_KEY'
}
})requests.post(
"https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/us-port-out-pin",
headers={
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"X-Api-Key": "YOUR_API_KEY"
}
)package main
import (
"fmt"
"io"
"net/http"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/us-port-out-pin"
req, _ := http.NewRequest("POST", requestUrl, nil)
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"pin": "string",
"expiresAt": "2024-01-15T10:30:00Z"
}{
"message": "The request body is invalid.",
"code": "bad_request",
"details": [
{
"message": "Email format is invalid.",
"code": "invalid_email",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields."
}{
"message": "Authentication is required to access this resource.",
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header."
}{
"message": "You do not have permission to perform this action.",
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions."
}{
"message": "The requested customer could not be found.",
"code": "not_found",
"hint": "Verify the customerId and try again."
}{
"message": "A precondition given in the request headers was not met.",
"code": "precondition_failed",
"hint": "Fetch the current resource and retry with an up-to-date precondition."
}{
"message": "An unexpected error occurred on the server.",
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support."
}{
"message": "This endpoint is not available in this environment.",
"code": "not_implemented",
"hint": "The network behind this brand cannot answer this request."
}Reset subscription network services
/subscriptions/{subscriptionId}/reset-network-servicesStart the platform's provider-specific network-services reset for an activated subscription.
The operation may briefly interrupt service, so confirmed must be true.
A pending or running reset is returned instead of starting another one. A successful or failed reset completed during the previous 15 minutes is also returned, so an immediate retry is safe. Two requests that arrive at the same time usually return the same reset. In rare cases, each request returns a new reset. Then only the first reset changes the network, and the other reset fails without a change to the network. The reset does not change Seamless OS barring, add-ons, data buckets, or other commercial configuration. The provider workflow can suspend, reconnect, or recreate network-side state. On some networks, this can change the network-side data balance or shared data group.
This operation is disabled by default. A deployment must set
FEATURE_END_USER_RESET_NETWORK_SERVICES=true to make it available. A disabled deployment
returns 501 Not Implemented and starts no reset. Enable the operation only when the customer
accepts the provider-specific risks.
Path parameters
subscriptionstringrequiredThe identifier of the subscription. May be the entity's internal UUID or an external reference identifier.
Reference identifiers MUST be prefixed with rid_ (e.g., rid_crm-subscription-12345) so the API
can distinguish them from internal UUIDs. The prefix is stripped before lookup.
Headers
X-stringmax length 256A 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.
BodyResetNetworkServicesRequestrequiredapplication/json
Confirms that the user approved a temporary interruption while network services are reset.
confirmedbooleanrequiredMust be true after the user explicitly approves the temporary service interruption.
Responses
200Reset started, already running, or recently completed.
application/json
Reset started, already running, or recently completed.
Reset started, already running, or recently completed.
objectResetNetworkServicesResult
Current state of a subscription network-services reset.
subscriptionstringrequiredSubscription whose network services are being reset.
subscriptionstringIdentifier of the reset workflow action. Absent when the network provider is unsupported.
networkstringrequiredNetwork provider selected for this subscription.
statusenum<string>requiredCurrent workflow state.
values
PENDINGRUNNINGSUCCEEDEDFAILEDUNSUPPORTED
outcomeenum<string>requiredWhether a reset was started or an existing recent reset was returned.
values
STARTEDALREADY_RUNNINGRECENT_SUCCESSRECENT_FAILUREOPERATOR_UNSUPPORTED
createdstringdate-timeWhen the reset workflow action was created.
startedstringdate-timeWhen execution started, if it has started.
finishedstringdate-timeWhen execution finished, if it has finished.
observedstringdate-timerequiredWhen this status was read.
400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
409The request conflicts with the current state of the resource.
application/json
The request conflicts with the current state of the resource.
The request conflicts with the current state of the resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
412A precondition for this request was not met.
application/json
A precondition for this request was not met.
A precondition for this request was not met.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
501This endpoint is not available for this brand. The network it asks cannot
answer the question, so no request will succeed until the brand is configured
with a network that can.
application/json
This endpoint is not available for this brand. The network it asks cannot answer the question, so no request will succeed until the brand is configured with a network that can.
This endpoint is not available for this brand. The network it asks cannot answer the question, so no request will succeed until the brand is configured with a network that can.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
Auth required
Send one of
X-Api-KeyBearer JWT+X-Api-Key
The API key is always required; the bearer token is optional.
curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/reset-network-services \
--request POST \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"confirmed": true
}'fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/reset-network-services', {
method: 'POST',
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-Api-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
confirmed: true
})
})requests.post(
"https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/reset-network-services",
headers={
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"X-Api-Key": "YOUR_API_KEY",
"Content-Type": "application/json"
},
json={
"confirmed": True
}
)package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/reset-network-services"
payload := strings.NewReader(`{
"confirmed": true
}`)
req, _ := http.NewRequest("POST", requestUrl, payload)
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"subscriptionId": "string",
"subscriptionActionId": "string",
"networkProvider": "string",
"status": "PENDING",
"outcome": "STARTED",
"createdAt": "2024-01-15T10:30:00Z",
"startedAt": "2024-01-15T10:30:00Z",
"finishedAt": "2024-01-15T10:30:00Z",
"observedAt": "2024-01-15T10:30:00Z"
}{
"message": "The request body is invalid.",
"code": "bad_request",
"details": [
{
"message": "Email format is invalid.",
"code": "invalid_email",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields."
}{
"message": "Authentication is required to access this resource.",
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header."
}{
"message": "You do not have permission to perform this action.",
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions."
}{
"message": "The requested customer could not be found.",
"code": "not_found",
"hint": "Verify the customerId and try again."
}{
"message": "The request conflicts with the current state of the resource.",
"code": "conflict",
"hint": "Reload the resource to get its latest state before retrying."
}{
"message": "A precondition given in the request headers was not met.",
"code": "precondition_failed",
"hint": "Fetch the current resource and retry with an up-to-date precondition."
}{
"message": "An unexpected error occurred on the server.",
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support."
}{
"message": "This endpoint is not available in this environment.",
"code": "not_implemented",
"hint": "The network behind this brand cannot answer this request."
}Block SIM
/subscriptions/{subscriptionId}/block-simBlock the SIM card on a subscription, so it can no longer use the network. Use this when a subscriber reports their SIM lost or stolen.
The block takes effect immediately and cannot be scheduled. Any changes already scheduled on the subscription are cancelled, except an in-progress number port or a scheduled SIM card change, which both continue — a cancelled port would lose the subscriber their number.
Blocking is not reversible through this endpoint: issue a new SIM card to bring the subscription back into service.
Path parameters
subscriptionstringrequiredThe identifier of the subscription. May be the entity's internal UUID or an external reference identifier.
Reference identifiers MUST be prefixed with rid_ (e.g., rid_crm-subscription-12345) so the API
can distinguish them from internal UUIDs. The prefix is stripped before lookup.
Headers
X-stringmax length 256A 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.
Responses
200SIM blocked successfully.
application/json
SIM blocked successfully.
SIM blocked successfully.
objectSubscription
A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details.
subscriptionstringrequiredThe unique identifier for the subscription.
referencestringmax length 255A 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.
statusenum<string>requiredCurrent stage of the subscription lifecycle.
- PENDING: Created but not yet activated in the network
- ACTIVATED: Active and billable; service is available
- BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
- CANCELLED: Permanently terminated
- PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
- SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
typestringrequiredThe kind of telecommunications service the subscription provides.
Common values include CELL (mobile voice/SMS/data), DATA (data-only SIM), MBB (mobile broadband),
M2M (machine-to-machine/IoT), and TRAVEL_ESIM (travel eSIM for international roaming).
Determined by the product offering the subscription was created with.
displaystringrequiredHuman-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation.
msisdnstringphonepersonal datarequiredThe phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number.
customerobjectrequiredCustomer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.
Show child attributes
customerstringrequiredThe unique identifier for the customer. Use it with the customer endpoints to fetch full details.
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers.
productobjectEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.
Show child attributes
netintegerint64The configured price of the offering, in minor currency units. When includesTax is
true, this amount is the total the customer pays, and the tax is a part of it.
includesbooleanTrue when the configured price includes its tax. The tax is then a part of
netPriceMinor rather than an amount on top of it.
currencystringrequiredThe ISO 4217 currency code the price is expressed in (e.g., "USD").
priceenum<string>requiredHow the price is charged.
- ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).
- RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).
values
ONE_TIMERECURRING
bindingobjectA commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.
Show child attributes
standardobjectA recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.
Show child attributes
customobjectBilling cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out.
Show child attributes
billingobjectHow often a recurring price is charged.
Show child attributes
currencyobject with string keysPer-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
productstringrequiredUnique identifier for the product group.
namestringrequiredName of the product group in the requested locale.
descriptionstringDescription of the product group in the requested locale.
categoryenum<string>requiredA 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 subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM- Data-only SIM subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND- Broadband internet subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_M2M- Machine-to-machine IoT subscriptionPRODUCT_CATEGORY_TRAVEL_ESIM- Travel eSIM subscription for international roaming
SUBSCRIPTION_ADDON categories:
PRODUCT_CATEGORY_EXTRA_DATA- Additional data package addonPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE- Travel eSIM data package with country/region coveragePRODUCT_CATEGORY_ABROAD- International roaming addon
EXTERNAL_PRODUCT categories:
PRODUCT_CATEGORY_EXTERNAL_PRODUCT- External purchasable productPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON- Addon for external product
SIM_CARD categories:
PRODUCT_CATEGORY_SIM_CARD- Physical SIM or eSIM replacement for an existing subscription
values
PRODUCT_CATEGORY_SUBSCRIPTION_CELLPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIMPRODUCT_CATEGORY_SUBSCRIPTION_BROADBANDPRODUCT_CATEGORY_SUBSCRIPTION_M2MPRODUCT_CATEGORY_TRAVEL_ESIMPRODUCT_CATEGORY_EXTRA_DATAPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGEPRODUCT_CATEGORY_ABROADPRODUCT_CATEGORY_EXTERNAL_PRODUCTPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDONPRODUCT_CATEGORY_SIM_CARD
internalstringInternal description of the product group for operational use only.
imagestringuriURL to the image representing the product offering.
subscriberobjectThe person who uses the service on a subscription, as distinct from the customer who pays for it.
Show child attributes
subscriberstringrequiredThe unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.
namestringrequiredThe subscriber's full name.
emailstringemailpersonal dataThe subscriber's email address, if one has been provided.
addressobjectdeprecatedDeprecated. Use serviceAddress on the subscription instead.
The service address of the subscription that embeds this subscriber.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
createdstringdate-timeDate and time when the subscriber was created.
updatedstringdate-timeDate and time when the subscriber was last updated.
serviceobjectThe address where this subscription is served. It is the address that the subscription holds, or the billing address of the customer when the subscription holds none.
Absent when no record holds an address.
The address where a subscription is served, and the record that holds it.
In the US, this is the E911 address that emergency services get for the phone number.
Show child attributes
addressobjectrequiredA postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
sourceenum<string>requiredThe record that holds the address.
SUBSCRIPTION: The subscription holds an address of its own.CUSTOMER_BILLING: The subscription holds no address of its own, so the billing address of the customer applies.
values
SUBSCRIPTIONCUSTOMER_BILLING
extensionsobject with string keysAdditional subscription extensions fields provided for custom subscription types.
Show child attributes
*stringsimobjectrequiredSIM 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
esimbooleanrequiredWhether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.
imeistringpersonal dataInternational Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.
Only applicable for eSIM.
iccidstringpersonal dataIntegrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.
pendingobjectpersonal dataA phone number change that has been requested but not yet applied. Present only while a number change is scheduled; the current number remains in msisdn until the change takes effect.
Show child attributes
msisdnstringphonepersonal datarequiredThe phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.
scheduledstringdateThe date when the pending number change is scheduled to occur.
bararray of BarReasonThe reasons of the bars that keep a BLOCKED subscription blocked. A subscription can have more than one bar, and it stays
blocked until every bar is removed. Present only while the status is BLOCKED.
pendingobjectA status change that has been requested but not yet applied, for example a scheduled cancellation or pause. Present only while a status change is scheduled.
Show child attributes
statusenum<string>requiredCurrent stage of the subscription lifecycle.
- PENDING: Created but not yet activated in the network
- ACTIVATED: Active and billable; service is available
- BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
- CANCELLED: Permanently terminated
- PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
- SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
scheduledstringdateThe date when the pending status change is scheduled to occur.
pendingobjectA product offering change (upgrade or downgrade) that has been requested but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.
Show child attributes
scheduledstringdaterequiredThe date when the pending product offering change is scheduled to occur.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
portingobjectNumber porting information for subscriptions, indicating scheduled number transfers.
To get the detailed porting information, use the porting endpoint.
Show child attributes
msisdnstringpersonal datarequiredThe pending phone number that the subscription will be ported in with. This will always be a non-active number.
statusenum<string>requiredCurrent status of the porting process.
- PENDING: Porting request created but not yet submitted to the carriers
- IN_PROGRESS: Request submitted and awaiting a response from the losing carrier
- SCHEDULED: Accepted by the losing carrier; the transfer will execute on the scheduled date
- COMPLETED: The number has been transferred and is active
- FAILED: The request was rejected, canceled, or could not be completed
values
PENDINGIN_PROGRESSSCHEDULEDCOMPLETEDFAILED
directionenum<string>requiredThe direction of the number transfer. INBOUND means the number is being ported into this platform from another carrier; OUTBOUND means the number is leaving this platform for another carrier.
values
INBOUNDOUTBOUND
scheduledstringdaterequiredThe date when the number porting is scheduled to occur.
activatedstringdate-timeThe date and time when the subscription was activated. Absent until the subscription has been activated.
cancelledstringdate-timeThe date and time when the subscription was cancelled (if applicable).
createdstringdate-timerequiredThe date and time when the subscription was created.
updatedstringdate-timerequiredThe date and time when the subscription was last updated.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*string400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
412A precondition for this request was not met.
application/json
A precondition for this request was not met.
A precondition for this request was not met.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
Auth required
Send one of
X-Api-KeyBearer JWT+X-Api-Key
The API key is always required; the bearer token is optional.
curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/block-sim \
--request POST \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'X-Api-Key: YOUR_API_KEY'fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/block-sim', {
method: 'POST',
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-Api-Key': 'YOUR_API_KEY'
}
})requests.post(
"https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/block-sim",
headers={
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"X-Api-Key": "YOUR_API_KEY"
}
)package main
import (
"fmt"
"io"
"net/http"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/block-sim"
req, _ := http.NewRequest("POST", requestUrl, nil)
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"referenceId": "crm-subscription-12345",
"status": "PENDING",
"type": "CELL",
"display": "(555) 123-4567",
"msisdn": "+15551234567",
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
},
"productOffering": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"netPriceMinor": 2999,
"includesTax": false,
"currency": "USD",
"priceType": "ONE_TIME",
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
},
"subscriber": {
"subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
"name": "John Doe",
"email": "john.doe@example.com",
"address": {
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-20T14:45:00Z"
},
"serviceAddress": {
"address": {
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"source": "SUBSCRIPTION"
},
"extensions": {
"propertyName": "string"
},
"sim": {
"esim": true,
"imei": "356938035643809",
"iccid": "8901240197155182976"
},
"pendingMsisdn": {
"msisdn": "+15559876543",
"scheduledAt": "2024-02-01"
},
"barReasons": [
"MISSING_PAYMENT"
],
"pendingStatus": {
"status": "PENDING",
"scheduledAt": "2024-02-01"
},
"pendingProductOffering": {
"scheduledAt": "2024-02-01",
"product": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"netPriceMinor": 2999,
"includesTax": false,
"currency": "USD",
"priceType": "ONE_TIME",
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
}
},
"porting": {
"msisdn": "+15551234567",
"status": "PENDING",
"direction": "INBOUND",
"scheduledAt": "2024-02-01"
},
"activatedAt": "2024-01-15T10:30:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"createdAt": "2024-01-10T08:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"metadata": {
"propertyName": "string"
}
}{
"message": "The request body is invalid.",
"code": "bad_request",
"details": [
{
"message": "Email format is invalid.",
"code": "invalid_email",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields."
}{
"message": "Authentication is required to access this resource.",
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header."
}{
"message": "You do not have permission to perform this action.",
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions."
}{
"message": "The requested customer could not be found.",
"code": "not_found",
"hint": "Verify the customerId and try again."
}{
"message": "A precondition given in the request headers was not met.",
"code": "precondition_failed",
"hint": "Fetch the current resource and retry with an up-to-date precondition."
}{
"message": "An unexpected error occurred on the server.",
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support."
}Change subscription SIM card
/subscriptions/{subscriptionId}/change-simChange the SIM card (ICC/ICCID) for a subscription. This is used when replacing a lost, damaged, or upgraded SIM card.
Supports flexible scheduling:
- Immediate SIM card change
- Next day SIM card change
- Beginning of next month SIM card change
- Specific date SIM card change
Path parameters
subscriptionstringrequiredThe identifier of the subscription. May be the entity's internal UUID or an external reference identifier.
Reference identifiers MUST be prefixed with rid_ (e.g., rid_crm-subscription-12345) so the API
can distinguish them from internal UUIDs. The prefix is stripped before lookup.
Headers
X-stringmax length 256A 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.
BodyChangeSubscriptionSimRequestrequiredapplication/json
Request to change the SIM card (ICC/ICCID) for a subscription.
scheduledstringdateChange the SIM card on a specific date.
iccstringpersonal datarequiredThe ICCID (Integrated Circuit Card Identifier) of the new SIM card — the 19-20 digit serial number printed on the SIM or embedded in the eSIM profile.
simenum<string>requiredThe type of SIM card being installed.
values
PHYSICALESIM
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringResponses
200SIM card change scheduled successfully.
application/json
SIM card change scheduled successfully.
SIM card change scheduled successfully.
objectSubscription
A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details.
subscriptionstringrequiredThe unique identifier for the subscription.
referencestringmax length 255A 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.
statusenum<string>requiredCurrent stage of the subscription lifecycle.
- PENDING: Created but not yet activated in the network
- ACTIVATED: Active and billable; service is available
- BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
- CANCELLED: Permanently terminated
- PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
- SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
typestringrequiredThe kind of telecommunications service the subscription provides.
Common values include CELL (mobile voice/SMS/data), DATA (data-only SIM), MBB (mobile broadband),
M2M (machine-to-machine/IoT), and TRAVEL_ESIM (travel eSIM for international roaming).
Determined by the product offering the subscription was created with.
displaystringrequiredHuman-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation.
msisdnstringphonepersonal datarequiredThe phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number.
customerobjectrequiredCustomer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.
Show child attributes
customerstringrequiredThe unique identifier for the customer. Use it with the customer endpoints to fetch full details.
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers.
productobjectEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.
Show child attributes
netintegerint64The configured price of the offering, in minor currency units. When includesTax is
true, this amount is the total the customer pays, and the tax is a part of it.
includesbooleanTrue when the configured price includes its tax. The tax is then a part of
netPriceMinor rather than an amount on top of it.
currencystringrequiredThe ISO 4217 currency code the price is expressed in (e.g., "USD").
priceenum<string>requiredHow the price is charged.
- ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).
- RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).
values
ONE_TIMERECURRING
bindingobjectA commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.
Show child attributes
standardobjectA recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.
Show child attributes
customobjectBilling cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out.
Show child attributes
billingobjectHow often a recurring price is charged.
Show child attributes
currencyobject with string keysPer-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
productstringrequiredUnique identifier for the product group.
namestringrequiredName of the product group in the requested locale.
descriptionstringDescription of the product group in the requested locale.
categoryenum<string>requiredA 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 subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM- Data-only SIM subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND- Broadband internet subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_M2M- Machine-to-machine IoT subscriptionPRODUCT_CATEGORY_TRAVEL_ESIM- Travel eSIM subscription for international roaming
SUBSCRIPTION_ADDON categories:
PRODUCT_CATEGORY_EXTRA_DATA- Additional data package addonPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE- Travel eSIM data package with country/region coveragePRODUCT_CATEGORY_ABROAD- International roaming addon
EXTERNAL_PRODUCT categories:
PRODUCT_CATEGORY_EXTERNAL_PRODUCT- External purchasable productPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON- Addon for external product
SIM_CARD categories:
PRODUCT_CATEGORY_SIM_CARD- Physical SIM or eSIM replacement for an existing subscription
values
PRODUCT_CATEGORY_SUBSCRIPTION_CELLPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIMPRODUCT_CATEGORY_SUBSCRIPTION_BROADBANDPRODUCT_CATEGORY_SUBSCRIPTION_M2MPRODUCT_CATEGORY_TRAVEL_ESIMPRODUCT_CATEGORY_EXTRA_DATAPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGEPRODUCT_CATEGORY_ABROADPRODUCT_CATEGORY_EXTERNAL_PRODUCTPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDONPRODUCT_CATEGORY_SIM_CARD
internalstringInternal description of the product group for operational use only.
imagestringuriURL to the image representing the product offering.
subscriberobjectThe person who uses the service on a subscription, as distinct from the customer who pays for it.
Show child attributes
subscriberstringrequiredThe unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.
namestringrequiredThe subscriber's full name.
emailstringemailpersonal dataThe subscriber's email address, if one has been provided.
addressobjectdeprecatedDeprecated. Use serviceAddress on the subscription instead.
The service address of the subscription that embeds this subscriber.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
createdstringdate-timeDate and time when the subscriber was created.
updatedstringdate-timeDate and time when the subscriber was last updated.
serviceobjectThe address where this subscription is served. It is the address that the subscription holds, or the billing address of the customer when the subscription holds none.
Absent when no record holds an address.
The address where a subscription is served, and the record that holds it.
In the US, this is the E911 address that emergency services get for the phone number.
Show child attributes
addressobjectrequiredA postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
sourceenum<string>requiredThe record that holds the address.
SUBSCRIPTION: The subscription holds an address of its own.CUSTOMER_BILLING: The subscription holds no address of its own, so the billing address of the customer applies.
values
SUBSCRIPTIONCUSTOMER_BILLING
extensionsobject with string keysAdditional subscription extensions fields provided for custom subscription types.
Show child attributes
*stringsimobjectrequiredSIM 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
esimbooleanrequiredWhether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.
imeistringpersonal dataInternational Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.
Only applicable for eSIM.
iccidstringpersonal dataIntegrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.
pendingobjectpersonal dataA phone number change that has been requested but not yet applied. Present only while a number change is scheduled; the current number remains in msisdn until the change takes effect.
Show child attributes
msisdnstringphonepersonal datarequiredThe phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.
scheduledstringdateThe date when the pending number change is scheduled to occur.
bararray of BarReasonThe reasons of the bars that keep a BLOCKED subscription blocked. A subscription can have more than one bar, and it stays
blocked until every bar is removed. Present only while the status is BLOCKED.
pendingobjectA status change that has been requested but not yet applied, for example a scheduled cancellation or pause. Present only while a status change is scheduled.
Show child attributes
statusenum<string>requiredCurrent stage of the subscription lifecycle.
- PENDING: Created but not yet activated in the network
- ACTIVATED: Active and billable; service is available
- BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
- CANCELLED: Permanently terminated
- PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
- SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
scheduledstringdateThe date when the pending status change is scheduled to occur.
pendingobjectA product offering change (upgrade or downgrade) that has been requested but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.
Show child attributes
scheduledstringdaterequiredThe date when the pending product offering change is scheduled to occur.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
portingobjectNumber porting information for subscriptions, indicating scheduled number transfers.
To get the detailed porting information, use the porting endpoint.
Show child attributes
msisdnstringpersonal datarequiredThe pending phone number that the subscription will be ported in with. This will always be a non-active number.
statusenum<string>requiredCurrent status of the porting process.
- PENDING: Porting request created but not yet submitted to the carriers
- IN_PROGRESS: Request submitted and awaiting a response from the losing carrier
- SCHEDULED: Accepted by the losing carrier; the transfer will execute on the scheduled date
- COMPLETED: The number has been transferred and is active
- FAILED: The request was rejected, canceled, or could not be completed
values
PENDINGIN_PROGRESSSCHEDULEDCOMPLETEDFAILED
directionenum<string>requiredThe direction of the number transfer. INBOUND means the number is being ported into this platform from another carrier; OUTBOUND means the number is leaving this platform for another carrier.
values
INBOUNDOUTBOUND
scheduledstringdaterequiredThe date when the number porting is scheduled to occur.
activatedstringdate-timeThe date and time when the subscription was activated. Absent until the subscription has been activated.
cancelledstringdate-timeThe date and time when the subscription was cancelled (if applicable).
createdstringdate-timerequiredThe date and time when the subscription was created.
updatedstringdate-timerequiredThe date and time when the subscription was last updated.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*string400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
409The request conflicts with the current state of the resource.
application/json
The request conflicts with the current state of the resource.
The request conflicts with the current state of the resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
Auth required
Send one of
X-Api-KeyBearer JWT+X-Api-Key
The API key is always required; the bearer token is optional.
curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/change-sim \
--request POST \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"scheduledAt": "2024-02-01",
"icc": "89012345678901234567",
"simCardType": "PHYSICAL",
"metadata": {
"propertyName": "string"
}
}'fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/change-sim', {
method: 'POST',
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-Api-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
scheduledAt: '2024-02-01',
icc: '89012345678901234567',
simCardType: 'PHYSICAL',
metadata: {
propertyName: 'string'
}
})
})requests.post(
"https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/change-sim",
headers={
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"X-Api-Key": "YOUR_API_KEY",
"Content-Type": "application/json"
},
json={
"scheduledAt": "2024-02-01",
"icc": "89012345678901234567",
"simCardType": "PHYSICAL",
"metadata": {
"propertyName": "string"
}
}
)package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/change-sim"
payload := strings.NewReader(`{
"scheduledAt": "2024-02-01",
"icc": "89012345678901234567",
"simCardType": "PHYSICAL",
"metadata": {
"propertyName": "string"
}
}`)
req, _ := http.NewRequest("POST", requestUrl, payload)
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"referenceId": "crm-subscription-12345",
"status": "PENDING",
"type": "CELL",
"display": "(555) 123-4567",
"msisdn": "+15551234567",
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
},
"productOffering": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"netPriceMinor": 2999,
"includesTax": false,
"currency": "USD",
"priceType": "ONE_TIME",
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
},
"subscriber": {
"subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
"name": "John Doe",
"email": "john.doe@example.com",
"address": {
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-20T14:45:00Z"
},
"serviceAddress": {
"address": {
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"source": "SUBSCRIPTION"
},
"extensions": {
"propertyName": "string"
},
"sim": {
"esim": true,
"imei": "356938035643809",
"iccid": "8901240197155182976"
},
"pendingMsisdn": {
"msisdn": "+15559876543",
"scheduledAt": "2024-02-01"
},
"barReasons": [
"MISSING_PAYMENT"
],
"pendingStatus": {
"status": "PENDING",
"scheduledAt": "2024-02-01"
},
"pendingProductOffering": {
"scheduledAt": "2024-02-01",
"product": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"netPriceMinor": 2999,
"includesTax": false,
"currency": "USD",
"priceType": "ONE_TIME",
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
}
},
"porting": {
"msisdn": "+15551234567",
"status": "PENDING",
"direction": "INBOUND",
"scheduledAt": "2024-02-01"
},
"activatedAt": "2024-01-15T10:30:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"createdAt": "2024-01-10T08:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"metadata": {
"propertyName": "string"
}
}{
"message": "The request body is invalid.",
"code": "bad_request",
"details": [
{
"message": "Email format is invalid.",
"code": "invalid_email",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields."
}{
"message": "Authentication is required to access this resource.",
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header."
}{
"message": "You do not have permission to perform this action.",
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions."
}{
"message": "The requested customer could not be found.",
"code": "not_found",
"hint": "Verify the customerId and try again."
}{
"message": "The request conflicts with the current state of the resource.",
"code": "conflict",
"hint": "Reload the resource to get its latest state before retrying."
}{
"message": "An unexpected error occurred on the server.",
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support."
}Get roaming cost control
/subscriptions/{subscriptionId}/roaming-cost-controlGet the roaming cost-control setting and current cost limit for a subscription. This operation does not return roaming allowances or top-up balances.
Path parameters
subscriptionstringrequiredThe identifier of the subscription. The value can be an internal UUID or an external reference identifier with the rid_ prefix.
Responses
200The roaming cost-control setting, including an explicit unsupported state.
application/json
The roaming cost-control setting, including an explicit unsupported state.
The roaming cost-control setting, including an explicit unsupported state.
objectRoamingCostControl
The roaming cost-control setting for one subscription. This cost limit is separate from roaming data allowances and top-up balances.
subscriptionstringrequiredThe subscription that owns this roaming cost-control setting.
providerstringrequiredThe network provider that supplies the setting.
stateenum<string>requiredThe availability and configuration state of roaming cost control.
values
ACTIVENOT_CONFIGUREDUNSUPPORTEDUNAVAILABLE
limitintegerint64>= 0The configured cost limit in minor currency units. It is present only when state is ACTIVE.
currencystringThe currency of limitMinor. It is present only when state is ACTIVE.
The three-letter ISO 4217 code of the currency used for prices, billing, and payments.
observedstringdate-timerequiredThe time when the platform read this setting.
400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
Auth required
Send one of
X-Api-KeyBearer JWT+X-Api-Key
The API key is always required; the bearer token is optional.
curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/roaming-cost-control \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'X-Api-Key: YOUR_API_KEY'fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/roaming-cost-control', {
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-Api-Key': 'YOUR_API_KEY'
}
})requests.get(
"https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/roaming-cost-control",
headers={
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"X-Api-Key": "YOUR_API_KEY"
}
)package main
import (
"fmt"
"io"
"net/http"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/roaming-cost-control"
req, _ := http.NewRequest("GET", requestUrl, nil)
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"subscriptionId": "a47ac10b-58cc-4372-a567-0e02b2c3d479",
"provider": "telia",
"state": "ACTIVE",
"limitMinor": 52000,
"currency": "USD",
"observedAt": "2024-01-15T10:30:00Z"
}{
"message": "The request body is invalid.",
"code": "bad_request",
"details": [
{
"message": "Email format is invalid.",
"code": "invalid_email",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields."
}{
"message": "Authentication is required to access this resource.",
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header."
}{
"message": "You do not have permission to perform this action.",
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions."
}{
"message": "The requested customer could not be found.",
"code": "not_found",
"hint": "Verify the customerId and try again."
}{
"message": "An unexpected error occurred on the server.",
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support."
}Change subscription service address
/subscriptions/{subscriptionId}/service-addressChange the address where a subscription is served. In the US, this is the E911 address that emergency services get for the phone number.
The subscription holds an address only when it is different from the billing address of the customer. An address that is equal to the billing address removes the address that the subscription holds.
For an activated subscription, the platform sends the address to the network operator first. serviceAddress on the subscription shows the new address after the operator accepts it.
Path parameters
subscriptionstringrequiredThe identifier of the subscription. The value can be an internal UUID or an external reference identifier with the rid_ prefix.
Headers
X-stringmax length 256A 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.
BodyChangeSubscriptionServiceAddressRequestrequiredapplication/json
Request to change the address where a subscription is served.
addressobjectrequiredThe address where the subscriber uses this subscription.
An address that is equal to the billing address of the customer removes the address that the subscription holds. The subscription then takes the billing address.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
Responses
200The subscription. An activated subscription shows the new address after the network operator accepts it.
application/json
The subscription. An activated subscription shows the new address after the network operator accepts it.
The subscription. An activated subscription shows the new address after the network operator accepts it.
objectSubscription
A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details.
subscriptionstringrequiredThe unique identifier for the subscription.
referencestringmax length 255A 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.
statusenum<string>requiredCurrent stage of the subscription lifecycle.
- PENDING: Created but not yet activated in the network
- ACTIVATED: Active and billable; service is available
- BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
- CANCELLED: Permanently terminated
- PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
- SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
typestringrequiredThe kind of telecommunications service the subscription provides.
Common values include CELL (mobile voice/SMS/data), DATA (data-only SIM), MBB (mobile broadband),
M2M (machine-to-machine/IoT), and TRAVEL_ESIM (travel eSIM for international roaming).
Determined by the product offering the subscription was created with.
displaystringrequiredHuman-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation.
msisdnstringphonepersonal datarequiredThe phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number.
customerobjectrequiredCustomer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.
Show child attributes
customerstringrequiredThe unique identifier for the customer. Use it with the customer endpoints to fetch full details.
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers.
productobjectEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.
Show child attributes
netintegerint64The configured price of the offering, in minor currency units. When includesTax is
true, this amount is the total the customer pays, and the tax is a part of it.
includesbooleanTrue when the configured price includes its tax. The tax is then a part of
netPriceMinor rather than an amount on top of it.
currencystringrequiredThe ISO 4217 currency code the price is expressed in (e.g., "USD").
priceenum<string>requiredHow the price is charged.
- ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).
- RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).
values
ONE_TIMERECURRING
bindingobjectA commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.
Show child attributes
standardobjectA recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.
Show child attributes
customobjectBilling cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out.
Show child attributes
billingobjectHow often a recurring price is charged.
Show child attributes
currencyobject with string keysPer-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
productstringrequiredUnique identifier for the product group.
namestringrequiredName of the product group in the requested locale.
descriptionstringDescription of the product group in the requested locale.
categoryenum<string>requiredA 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 subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM- Data-only SIM subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND- Broadband internet subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_M2M- Machine-to-machine IoT subscriptionPRODUCT_CATEGORY_TRAVEL_ESIM- Travel eSIM subscription for international roaming
SUBSCRIPTION_ADDON categories:
PRODUCT_CATEGORY_EXTRA_DATA- Additional data package addonPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE- Travel eSIM data package with country/region coveragePRODUCT_CATEGORY_ABROAD- International roaming addon
EXTERNAL_PRODUCT categories:
PRODUCT_CATEGORY_EXTERNAL_PRODUCT- External purchasable productPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON- Addon for external product
SIM_CARD categories:
PRODUCT_CATEGORY_SIM_CARD- Physical SIM or eSIM replacement for an existing subscription
values
PRODUCT_CATEGORY_SUBSCRIPTION_CELLPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIMPRODUCT_CATEGORY_SUBSCRIPTION_BROADBANDPRODUCT_CATEGORY_SUBSCRIPTION_M2MPRODUCT_CATEGORY_TRAVEL_ESIMPRODUCT_CATEGORY_EXTRA_DATAPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGEPRODUCT_CATEGORY_ABROADPRODUCT_CATEGORY_EXTERNAL_PRODUCTPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDONPRODUCT_CATEGORY_SIM_CARD
internalstringInternal description of the product group for operational use only.
imagestringuriURL to the image representing the product offering.
subscriberobjectThe person who uses the service on a subscription, as distinct from the customer who pays for it.
Show child attributes
subscriberstringrequiredThe unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.
namestringrequiredThe subscriber's full name.
emailstringemailpersonal dataThe subscriber's email address, if one has been provided.
addressobjectdeprecatedDeprecated. Use serviceAddress on the subscription instead.
The service address of the subscription that embeds this subscriber.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
createdstringdate-timeDate and time when the subscriber was created.
updatedstringdate-timeDate and time when the subscriber was last updated.
serviceobjectThe address where this subscription is served. It is the address that the subscription holds, or the billing address of the customer when the subscription holds none.
Absent when no record holds an address.
The address where a subscription is served, and the record that holds it.
In the US, this is the E911 address that emergency services get for the phone number.
Show child attributes
addressobjectrequiredA postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
sourceenum<string>requiredThe record that holds the address.
SUBSCRIPTION: The subscription holds an address of its own.CUSTOMER_BILLING: The subscription holds no address of its own, so the billing address of the customer applies.
values
SUBSCRIPTIONCUSTOMER_BILLING
extensionsobject with string keysAdditional subscription extensions fields provided for custom subscription types.
Show child attributes
*stringsimobjectrequiredSIM 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
esimbooleanrequiredWhether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.
imeistringpersonal dataInternational Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.
Only applicable for eSIM.
iccidstringpersonal dataIntegrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.
pendingobjectpersonal dataA phone number change that has been requested but not yet applied. Present only while a number change is scheduled; the current number remains in msisdn until the change takes effect.
Show child attributes
msisdnstringphonepersonal datarequiredThe phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.
scheduledstringdateThe date when the pending number change is scheduled to occur.
bararray of BarReasonThe reasons of the bars that keep a BLOCKED subscription blocked. A subscription can have more than one bar, and it stays
blocked until every bar is removed. Present only while the status is BLOCKED.
pendingobjectA status change that has been requested but not yet applied, for example a scheduled cancellation or pause. Present only while a status change is scheduled.
Show child attributes
statusenum<string>requiredCurrent stage of the subscription lifecycle.
- PENDING: Created but not yet activated in the network
- ACTIVATED: Active and billable; service is available
- BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
- CANCELLED: Permanently terminated
- PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
- SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled
values
PENDINGACTIVATEDBLOCKEDCANCELLEDPAUSEDSUSPENDED
scheduledstringdateThe date when the pending status change is scheduled to occur.
pendingobjectA product offering change (upgrade or downgrade) that has been requested but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.
Show child attributes
scheduledstringdaterequiredThe date when the pending product offering change is scheduled to occur.
productobjectrequiredEssential information about a product offering — what is being sold and at what price — without the full catalog details.
Show child attributes
productstringrequiredThe unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.
namestringrequiredThe customer-facing name of the product offering, suitable for display in checkout and account views.
priceobjectrequiredThe cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
imagestringuriURL to the image representing the product offering.
portingobjectNumber porting information for subscriptions, indicating scheduled number transfers.
To get the detailed porting information, use the porting endpoint.
Show child attributes
msisdnstringpersonal datarequiredThe pending phone number that the subscription will be ported in with. This will always be a non-active number.
statusenum<string>requiredCurrent status of the porting process.
- PENDING: Porting request created but not yet submitted to the carriers
- IN_PROGRESS: Request submitted and awaiting a response from the losing carrier
- SCHEDULED: Accepted by the losing carrier; the transfer will execute on the scheduled date
- COMPLETED: The number has been transferred and is active
- FAILED: The request was rejected, canceled, or could not be completed
values
PENDINGIN_PROGRESSSCHEDULEDCOMPLETEDFAILED
directionenum<string>requiredThe direction of the number transfer. INBOUND means the number is being ported into this platform from another carrier; OUTBOUND means the number is leaving this platform for another carrier.
values
INBOUNDOUTBOUND
scheduledstringdaterequiredThe date when the number porting is scheduled to occur.
activatedstringdate-timeThe date and time when the subscription was activated. Absent until the subscription has been activated.
cancelledstringdate-timeThe date and time when the subscription was cancelled (if applicable).
createdstringdate-timerequiredThe date and time when the subscription was created.
updatedstringdate-timerequiredThe date and time when the subscription was last updated.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*string400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
409The request conflicts with the current state of the resource.
application/json
The request conflicts with the current state of the resource.
The request conflicts with the current state of the resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
412A precondition for this request was not met.
application/json
A precondition for this request was not met.
A precondition for this request was not met.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
Auth required
Send one of
X-Api-KeyBearer JWT+X-Api-Key
The API key is always required; the bearer token is optional.
curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/service-address \
--request PUT \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"address": {
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
}
}'fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/service-address', {
method: 'PUT',
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-Api-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
address: {
street: '500 S Main St',
street1: 'string',
street2: 'Apt 1',
city: 'Natick',
zip: '01701',
country: 'US',
state: 'CA',
region: 'Ontario',
attention: 'John Doe'
}
})
})requests.put(
"https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/service-address",
headers={
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"X-Api-Key": "YOUR_API_KEY",
"Content-Type": "application/json"
},
json={
"address": {
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
}
}
)package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/service-address"
payload := strings.NewReader(`{
"address": {
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
}
}`)
req, _ := http.NewRequest("PUT", requestUrl, payload)
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"referenceId": "crm-subscription-12345",
"status": "PENDING",
"type": "CELL",
"display": "(555) 123-4567",
"msisdn": "+15551234567",
"customer": {
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"name": "John Doe"
},
"productOffering": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"netPriceMinor": 2999,
"includesTax": false,
"currency": "USD",
"priceType": "ONE_TIME",
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
},
"subscriber": {
"subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
"name": "John Doe",
"email": "john.doe@example.com",
"address": {
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-20T14:45:00Z"
},
"serviceAddress": {
"address": {
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"source": "SUBSCRIPTION"
},
"extensions": {
"propertyName": "string"
},
"sim": {
"esim": true,
"imei": "356938035643809",
"iccid": "8901240197155182976"
},
"pendingMsisdn": {
"msisdn": "+15559876543",
"scheduledAt": "2024-02-01"
},
"barReasons": [
"MISSING_PAYMENT"
],
"pendingStatus": {
"status": "PENDING",
"scheduledAt": "2024-02-01"
},
"pendingProductOffering": {
"scheduledAt": "2024-02-01",
"product": {
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "Mobile Unlimited",
"price": {
"netPriceMinor": 2999,
"includesTax": false,
"currency": "USD",
"priceType": "ONE_TIME",
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"imageUrl": "https://cdn.example.com/images/mobile-basic.png"
}
},
"porting": {
"msisdn": "+15551234567",
"status": "PENDING",
"direction": "INBOUND",
"scheduledAt": "2024-02-01"
},
"activatedAt": "2024-01-15T10:30:00Z",
"cancelledAt": "2024-06-30T00:00:00Z",
"createdAt": "2024-01-10T08:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"metadata": {
"propertyName": "string"
}
}{
"message": "The request body is invalid.",
"code": "bad_request",
"details": [
{
"message": "Email format is invalid.",
"code": "invalid_email",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields."
}{
"message": "Authentication is required to access this resource.",
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header."
}{
"message": "You do not have permission to perform this action.",
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions."
}{
"message": "The requested customer could not be found.",
"code": "not_found",
"hint": "Verify the customerId and try again."
}{
"message": "The request conflicts with the current state of the resource.",
"code": "conflict",
"hint": "Reload the resource to get its latest state before retrying."
}{
"message": "A precondition given in the request headers was not met.",
"code": "precondition_failed",
"hint": "Fetch the current resource and retry with an up-to-date precondition."
}{
"message": "An unexpected error occurred on the server.",
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support."
}Get eSIM QR code
/subscriptions/{subscriptionId}/esim/qrcodeRetrieve QR code data and hosted URL for eSIM profile download.
Returns both the raw QR code data (LPA format) and a hosted URL for the QR code image. Only available for eSIM subscriptions (sim.esim: true). QR codes expire for security and should be treated as sensitive data.
Path parameters
subscriptionstringrequiredThe identifier of the subscription. May be the entity's internal UUID or an external reference identifier.
Reference identifiers MUST be prefixed with rid_ (e.g., rid_crm-subscription-12345) so the API
can distinguish them from internal UUIDs. The prefix is stripped before lookup.
Responses
200eSIM QR code data and hosted URL retrieved successfully.
application/json
eSIM QR code data and hosted URL retrieved successfully.
eSIM QR code data and hosted URL retrieved successfully.
objectEsimQrCode
eSIM QR code data for a subscription's eSIM profile, with an optional hosted image URL.
subscriptionstringrequiredThe unique identifier of the subscription this QR code belongs to.
qrstringrequiredThe QR code data string that contains the eSIM profile download information (LPA format).
qrstringuriHosted URL where the QR code image can be accessed for display or download. Omitted when no hosted image is available; render the qrCodeData string as a QR code instead.
expiresstringdate-timeWhen the QR code and any hosted URL expire. After this time, a new QR code should be requested. Omitted when no expiry applies.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*string400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
409The request conflicts with the current state of the resource.
application/json
The request conflicts with the current state of the resource.
The request conflicts with the current state of the resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
Auth required
Send one of
X-Api-KeyBearer JWT+X-Api-Key
The API key is always required; the bearer token is optional.
curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/esim/qrcode \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'X-Api-Key: YOUR_API_KEY'fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/esim/qrcode', {
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-Api-Key': 'YOUR_API_KEY'
}
})requests.get(
"https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/esim/qrcode",
headers={
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"X-Api-Key": "YOUR_API_KEY"
}
)package main
import (
"fmt"
"io"
"net/http"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/esim/qrcode"
req, _ := http.NewRequest("GET", requestUrl, nil)
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"qrCodeData": "LPA:1$rsp-prod.example.com$12345678-1234-1234-1234-123456789012",
"qrCodeUrl": "https://esim.your-domain.com/qr/d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"expiresAt": "2024-12-31T23:59:59Z",
"metadata": {
"propertyName": "string"
}
}{
"message": "The request body is invalid.",
"code": "bad_request",
"details": [
{
"message": "Email format is invalid.",
"code": "invalid_email",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields."
}{
"message": "Authentication is required to access this resource.",
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header."
}{
"message": "You do not have permission to perform this action.",
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions."
}{
"message": "The requested customer could not be found.",
"code": "not_found",
"hint": "Verify the customerId and try again."
}{
"message": "The request conflicts with the current state of the resource.",
"code": "conflict",
"hint": "Reload the resource to get its latest state before retrying."
}{
"message": "An unexpected error occurred on the server.",
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support."
}Get eSIM profile status
/subscriptions/{subscriptionId}/esim/profileRetrieve the live eSIM profile status for a subscription's SIM, reported by the network
operator. Only available for eSIM subscriptions (sim.esim: true) that already have a SIM
assigned.
When the network operator reports no live status, the response still carries a profile
object with status: UNAVAILABLE rather than an error, so a caller can tell "the operator
gave nothing" apart from "there is no eSIM to ask about". When the network operator does not
answer, the response is 503, and the same request can succeed later.
Path parameters
subscriptionstringrequiredThe identifier of the subscription. May be the entity's internal UUID or an external reference identifier.
Reference identifiers MUST be prefixed with rid_ (e.g., rid_crm-subscription-12345) so the API
can distinguish them from internal UUIDs. The prefix is stripped before lookup.
Responses
200eSIM profile status retrieved successfully.
application/json
eSIM profile status retrieved successfully.
eSIM profile status retrieved successfully.
objectSubscriptionEsimProfile
The live eSIM profile status of a subscription's SIM, reported by the network operator. Shows whether the eSIM has been downloaded, installed, or enabled on a device.
subscriptionstringrequiredThe unique identifier of the subscription this eSIM profile belongs to.
statusenum<string>requiredThe installation state of an eSIM profile on the network. Reflects the current eUICC profile lifecycle stage as reported by the network operator.
values
AVAILABLEALLOCATEDLINKEDCONFIRMEDRELEASEDDOWNLOADEDINSTALLEDENABLEDDISABLEDERRORUNAVAILABLEDELETED
eidstringThe EID (eSIM Identifier) assigned to the device. Empty until the eSIM is activated.
laststringdate-timeWhen the last eUICC operation occurred for this profile.
installedintegerThe number of times a device installed this profile. Absent when the network operator sets no limit.
maxintegerThe maximum number of times a device can install this profile. Absent when the network operator sets no limit.
400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
409The request conflicts with the current state of the resource.
application/json
The request conflicts with the current state of the resource.
The request conflicts with the current state of the resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
503The network this endpoint asks could not answer. The request was correct and
the endpoint is available for this brand, so the same request can succeed
later. Retry after a short delay.
application/json
The network this endpoint asks could not answer. The request was correct and the endpoint is available for this brand, so the same request can succeed later. Retry after a short delay.
The network this endpoint asks could not answer. The request was correct and the endpoint is available for this brand, so the same request can succeed later. Retry after a short delay.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA 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.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
Auth required
Send one of
X-Api-KeyBearer JWT+X-Api-Key
The API key is always required; the bearer token is optional.
curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/esim/profile \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'X-Api-Key: YOUR_API_KEY'fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/esim/profile', {
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-Api-Key': 'YOUR_API_KEY'
}
})requests.get(
"https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/esim/profile",
headers={
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"X-Api-Key": "YOUR_API_KEY"
}
)package main
import (
"fmt"
"io"
"net/http"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/esim/profile"
req, _ := http.NewRequest("GET", requestUrl, nil)
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
"status": "AVAILABLE",
"eid": "89049032004008882600009B40002780",
"lastOperationAt": "2024-06-15T14:30:00Z",
"installedCount": 3,
"maxCount": 5
}{
"message": "The request body is invalid.",
"code": "bad_request",
"details": [
{
"message": "Email format is invalid.",
"code": "invalid_email",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields."
}{
"message": "Authentication is required to access this resource.",
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header."
}{
"message": "You do not have permission to perform this action.",
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions."
}{
"message": "The requested customer could not be found.",
"code": "not_found",
"hint": "Verify the customerId and try again."
}{
"message": "The request conflicts with the current state of the resource.",
"code": "conflict",
"hint": "Reload the resource to get its latest state before retrying."
}{
"message": "An unexpected error occurred on the server.",
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support."
}{
"message": "The service is temporarily unavailable. Please try again.",
"code": "unavailable",
"hint": "The network behind this brand did not answer. Try again in a moment."
}