Valdyr
View as MarkdownOpen in ClaudeOpen in ChatGPT

Subscriptions

The subscriptions of the user, and the SIM operations on them.

List subscriptions

GET/subscriptions

List all subscriptions.

Will return all subscriptions the requester has access to.

Query parameters

customerIdarray of string

Filter 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 SubscriptionStatus

The status of the subscription to filter by.

typearray of SubscriptionType
limitinteger>= 1<= 1000default 100

The maximum number of items to return.

cursorstring

Opaque pagination token from a previous response's nextCursor.

Responses

200

A list of subscriptions.

application/json

A list of subscriptions.

object

itemsarray of Subscriptionrequired
Show child attributes
activatedAtstringdate-time

The date and time when the subscription was activated. Absent until the subscription has been activated.

barReasonsarray of BarReason

The 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.

cancelledAtstringdate-time

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

createdAtstringdate-timerequired

The date and time when the subscription was created.

customerobjectrequired

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

Show child attributes
customerIdstringrequired

The unique identifier for the customer. Use it with the customer endpoints to fetch full details.

namestringrequired

The customer's display name — the company name for business customers or the person's full name for consumers.

displaystringrequired

Human-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.

extensionsobject with string keys

Additional subscription extensions fields provided for custom subscription types.

Show child attributes
*string
metadataobject with string keys

A 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
*string
msisdnstringphonepersonal datarequired

The 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.

pendingMsisdnobjectpersonal data

A 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 datarequired

The phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.

scheduledAtstringdate

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

pendingProductOfferingobject

A 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
productobjectrequired

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
scheduledAtstringdaterequired

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

pendingStatusobject

A 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
scheduledAtstringdate

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

statusenum<string>required

Current 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

  • PENDING
  • ACTIVATED
  • BLOCKED
  • CANCELLED
  • PAUSED
  • SUSPENDED
portingobject

Number porting information for subscriptions, indicating scheduled number transfers.

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

Show child attributes
directionenum<string>required

The 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

  • INBOUND
  • OUTBOUND
msisdnstringpersonal datarequired

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

scheduledAtstringdaterequired

The date when the number porting is scheduled to occur.

statusenum<string>required

Current 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

  • PENDING
  • IN_PROGRESS
  • SCHEDULED
  • COMPLETED
  • FAILED
productOfferingobject

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
groupobject

A product group organizes related product offerings.

Show child attributes
imageUrlstringuri

URL to the image representing the product offering.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The 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
productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

referenceIdstringmax length 255

A reference identifier provided by API clients to identify this subscription in their own systems. Must be unique per tenant. Use this field to look up subscriptions by your external identifier or to create/retrieve subscriptions during order creation.

serviceAddressobject

The 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
addressobjectrequired

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
sourceenum<string>required

The 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

  • SUBSCRIPTION
  • CUSTOMER_BILLING
simobjectrequired

SIM card information for the subscription. Sensitive details like PUK require separate API calls.

Use dedicated SIM API endpoints with proper authorization to access sensitive information such as PUK.

Show child attributes
esimbooleanrequired

Whether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.

iccidstringpersonal data

Integrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.

imeistringpersonal data

International Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.

Only applicable for eSIM.

statusenum<string>required

Current 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

  • PENDING
  • ACTIVATED
  • BLOCKED
  • CANCELLED
  • PAUSED
  • SUSPENDED
subscriberobject

The person who uses the service on a subscription, as distinct from the customer who pays for it.

Show child attributes
addressobjectdeprecated

Deprecated. 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
createdAtstringdate-time

Date and time when the subscriber was created.

emailstringemailpersonal data

The subscriber's email address, if one has been provided.

namestringrequired

The subscriber's full name.

subscriberIdstringrequired

The unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.

updatedAtstringdate-time

Date and time when the subscriber was last updated.

subscriptionIdstringrequired

The unique identifier for the subscription.

typestringrequired

The 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.

updatedAtstringdate-timerequired

The date and time when the subscription was last updated.

paginationobjectrequired

Cursor-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
nextCursorstring | nullrequired

Opaque token for fetching the next page. Null when no more results.

400

The request was malformed or invalid.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

401

Authentication is required to access this resource.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

403

Access to this resource is forbidden.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

404

The requested resource was not found.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

429

Too 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.

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

500

An unexpected error occurred on the server.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

Auth required

Send

  • X-Api-Key + Bearer JWT
GET /subscriptions
curl https://apiv2.example.com/api/v2/end-user/subscriptions \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
fetch('https://apiv2.example.com/api/v2/end-user/subscriptions', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  }
})
requests.get(
    "https://apiv2.example.com/api/v2/end-user/subscriptions",
    headers={
      "X-Api-Key": "YOUR_API_KEY",
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
)
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/end-user/subscriptions"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
{
  "items": [
    {
      "activatedAt": "2024-01-15T10:30:00Z",
      "createdAt": "2024-01-10T08:00:00Z",
      "customer": {
        "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
        "name": "Acme Corp"
      },
      "display": "(555) 123-4567",
      "metadata": {
        "costCenter": "eng-42"
      },
      "msisdn": "+15551234567",
      "productOffering": {
        "name": "Seamless 10GB",
        "price": {
          "billingCycle": {
            "interval": 1,
            "period": "MONTHLY"
          },
          "bindingContract": {
            "discount": {
              "amountMinor": 200
            },
            "duration": {
              "unit": "MONTHS",
              "value": 12
            }
          },
          "currency": "USD",
          "currencyOptionsMinor": {
            "SEK": 29900,
            "USD": 2999
          },
          "customUpfrontPayment": {
            "billingCycles": 3,
            "discount": {
              "amountMinor": 300
            }
          },
          "netPriceMinor": 2999,
          "priceType": "RECURRING",
          "standardDiscount": {
            "amountMinor": 500
          }
        },
        "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
      },
      "referenceId": "crm-subscription-12345",
      "sim": {
        "esim": true,
        "iccid": "8901240197155182976"
      },
      "status": "ACTIVATED",
      "subscriber": {
        "email": "john.doe@example.com",
        "name": "John Doe",
        "subscriberId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e"
      },
      "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
      "type": "CELL",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "nextCursor": null
  }
}
{
  "code": "bad_request",
  "details": [
    {
      "code": "invalid_email",
      "message": "Email format is invalid.",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields.",
  "message": "The request body is invalid."
}
{
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header.",
  "message": "Authentication is required to access this resource."
}
{
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions.",
  "message": "You do not have permission to perform this action."
}
{
  "code": "not_found",
  "hint": "Verify the customerId and try again.",
  "message": "The requested customer could not be found."
}
{
  "code": "too_many_requests",
  "hint": "Retry after the number of seconds indicated in the Retry-After header.",
  "message": "Too many requests. Please slow down."
}
{
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support.",
  "message": "An unexpected error occurred on the server."
}

Get subscription

GET/subscriptions/{subscriptionId}

Retrieve detailed information about a specific subscription using its unique identifier.

Path parameters

subscriptionIdstringrequired

The 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

200

A subscription object.

application/json

A subscription object.

objectSubscription

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

activatedAtstringdate-time

The date and time when the subscription was activated. Absent until the subscription has been activated.

barReasonsarray of BarReason

The 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.

cancelledAtstringdate-time

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

createdAtstringdate-timerequired

The date and time when the subscription was created.

customerobjectrequired

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

Show child attributes
customerIdstringrequired

The unique identifier for the customer. Use it with the customer endpoints to fetch full details.

namestringrequired

The customer's display name — the company name for business customers or the person's full name for consumers.

displaystringrequired

Human-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.

extensionsobject with string keys

Additional subscription extensions fields provided for custom subscription types.

Show child attributes
*string
metadataobject with string keys

A 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
*string
msisdnstringphonepersonal datarequired

The 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.

pendingMsisdnobjectpersonal data

A 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 datarequired

The phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.

scheduledAtstringdate

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

pendingProductOfferingobject

A 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
productobjectrequired

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
groupobject

A product group organizes related product offerings.

Show child attributes
imageUrlstringuri

URL to the image representing the product offering.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The 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
productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

scheduledAtstringdaterequired

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

pendingStatusobject

A 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
scheduledAtstringdate

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

statusenum<string>required

Current 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

  • PENDING
  • ACTIVATED
  • BLOCKED
  • CANCELLED
  • PAUSED
  • SUSPENDED
portingobject

Number porting information for subscriptions, indicating scheduled number transfers.

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

Show child attributes
directionenum<string>required

The 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

  • INBOUND
  • OUTBOUND
msisdnstringpersonal datarequired

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

scheduledAtstringdaterequired

The date when the number porting is scheduled to occur.

statusenum<string>required

Current 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

  • PENDING
  • IN_PROGRESS
  • SCHEDULED
  • COMPLETED
  • FAILED
productOfferingobject

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
groupobject

A product group organizes related product offerings.

Show child attributes
categoryenum<string>required

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

Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.

Categories are grouped by their product type:

SUBSCRIPTION categories:

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXED - Cellular subscription at a fixed location
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
  • PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming
  • PRODUCT_CATEGORY_VANITY_NUMBER_FORWARD - Vanity number that forwards calls
  • PRODUCT_CATEGORY_VANITY_NUMBER_CELL - Vanity number on a cellular subscription

SUBSCRIPTION_ADDON categories:

  • PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
  • PRODUCT_CATEGORY_ABROAD - International roaming addon
  • PRODUCT_CATEGORY_ABROAD_EXTRA_DATA - Additional data package for roaming
  • PRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EU - Data package for use outside the EU
  • PRODUCT_CATEGORY_NETWORK_EXTENSIONS - Network feature addon
  • PRODUCT_CATEGORY_VANITY_NUMBER - Vanity number addon

EXTERNAL_PRODUCT categories:

  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

SIM_CARD categories:

  • PRODUCT_CATEGORY_SIM_CARD - Physical SIM or eSIM replacement for an existing subscription

LICENSE categories (PBX):

  • PRODUCT_CATEGORY_PBX_USER_LEVEL - Level of a PBX user license
  • PRODUCT_CATEGORY_PBX_NUMBER - PBX phone number
  • PRODUCT_CATEGORY_PBX_MOBILE_NUMBER - PBX mobile number
  • PRODUCT_CATEGORY_PBX_LANDLINE_FORWARD - Forward from a landline number
  • PRODUCT_CATEGORY_PBX_SOFTPHONE - Softphone
  • PRODUCT_CATEGORY_PBX_STATISTICS - Call statistics
  • PRODUCT_CATEGORY_PBX_CALL_RECORDING - Call recording
  • PRODUCT_CATEGORY_PBX_VOICEMAIL - Voicemail
  • PRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERS - Queue capacity
  • PRODUCT_CATEGORY_PBX_ROUTE_IVR, PRODUCT_CATEGORY_PBX_ROUTE_GROUP, PRODUCT_CATEGORY_PBX_ROUTE_QUEUE - Call routes
  • PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVR, PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUP, PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUE, PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAIL - Call route features

Other categories:

  • PRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNER, PRODUCT_CATEGORY_INTERNATIONAL_NUMBER

A caller must tolerate new values.

values

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M
  • PRODUCT_CATEGORY_TRAVEL_ESIM
  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXED
  • PRODUCT_CATEGORY_VANITY_NUMBER_FORWARD
  • PRODUCT_CATEGORY_VANITY_NUMBER_CELL
  • PRODUCT_CATEGORY_EXTRA_DATA
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
  • PRODUCT_CATEGORY_ABROAD
  • PRODUCT_CATEGORY_ABROAD_EXTRA_DATA
  • PRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EU
  • PRODUCT_CATEGORY_NETWORK_EXTENSIONS
  • PRODUCT_CATEGORY_VANITY_NUMBER
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
  • PRODUCT_CATEGORY_SIM_CARD
  • PRODUCT_CATEGORY_PBX_USER_LEVEL
  • PRODUCT_CATEGORY_PBX_NUMBER
  • PRODUCT_CATEGORY_PBX_MOBILE_NUMBER
  • PRODUCT_CATEGORY_PBX_LANDLINE_FORWARD
  • PRODUCT_CATEGORY_PBX_SOFTPHONE
  • PRODUCT_CATEGORY_PBX_STATISTICS
  • PRODUCT_CATEGORY_PBX_CALL_RECORDING
  • PRODUCT_CATEGORY_PBX_VOICEMAIL
  • PRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERS
  • PRODUCT_CATEGORY_PBX_ROUTE_IVR
  • PRODUCT_CATEGORY_PBX_ROUTE_GROUP
  • PRODUCT_CATEGORY_PBX_ROUTE_QUEUE
  • PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVR
  • PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUP
  • PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUE
  • PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAIL
  • PRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNER
  • PRODUCT_CATEGORY_INTERNATIONAL_NUMBER
descriptionstring

Description of the product group in the requested locale.

internalDescriptionstring

Internal description of the product group for operational use only.

namestringrequired

Name of the product group in the requested locale.

productOfferingGroupIdstringrequired

Unique identifier for the product group.

imageUrlstringuri

URL to the image representing the product offering.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The 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
billingCycleobject

How often a recurring price is charged.

Show child attributes
bindingContractobject

A 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
currencystringrequired

The ISO 4217 currency code the price is expressed in (e.g., "USD").

currencyOptionsMinorobject with string keys

Per-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
customUpfrontPaymentobject

Billing 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
includesTaxboolean

True when the configured price includes its tax. The tax is then a part of netPriceMinor rather than an amount on top of it.

netPriceMinorintegerint64

The 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.

priceTypeenum<string>required

How 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_TIME
  • RECURRING
standardDiscountobject

A 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
productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

referenceIdstringmax length 255

A reference identifier provided by API clients to identify this subscription in their own systems. Must be unique per tenant. Use this field to look up subscriptions by your external identifier or to create/retrieve subscriptions during order creation.

serviceAddressobject

The 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
addressobjectrequired

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
attentionstringpersonal data

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

citystringrequired

The city or municipality of the address.

countrystringpattern ^[A-Z]{2}$required

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

regionstring

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

statestring

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

streetstringpersonal data

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

street1stringpersonal datadeprecatedrequired

Deprecated. Use street instead.

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

street2stringpersonal data

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

zipstringpersonal datarequired

The 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.

sourceenum<string>required

The 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

  • SUBSCRIPTION
  • CUSTOMER_BILLING
simobjectrequired

SIM card information for the subscription. Sensitive details like PUK require separate API calls.

Use dedicated SIM API endpoints with proper authorization to access sensitive information such as PUK.

Show child attributes
esimbooleanrequired

Whether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.

iccidstringpersonal data

Integrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.

imeistringpersonal data

International Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.

Only applicable for eSIM.

statusenum<string>required

Current 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

  • PENDING
  • ACTIVATED
  • BLOCKED
  • CANCELLED
  • PAUSED
  • SUSPENDED
subscriberobject

The person who uses the service on a subscription, as distinct from the customer who pays for it.

Show child attributes
addressobjectdeprecated

Deprecated. 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
attentionstringpersonal data

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

citystringrequired

The city or municipality of the address.

countrystringpattern ^[A-Z]{2}$required

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

regionstring

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

statestring

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

streetstringpersonal data

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

street1stringpersonal datadeprecatedrequired

Deprecated. Use street instead.

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

street2stringpersonal data

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

zipstringpersonal datarequired

The 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.

createdAtstringdate-time

Date and time when the subscriber was created.

emailstringemailpersonal data

The subscriber's email address, if one has been provided.

namestringrequired

The subscriber's full name.

subscriberIdstringrequired

The unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.

updatedAtstringdate-time

Date and time when the subscriber was last updated.

subscriptionIdstringrequired

The unique identifier for the subscription.

typestringrequired

The 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.

updatedAtstringdate-timerequired

The date and time when the subscription was last updated.

400

The request was malformed or invalid.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

401

Authentication is required to access this resource.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

404

The requested resource was not found.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

500

An unexpected error occurred on the server.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

Auth required

Send

  • X-Api-Key + Bearer JWT
GET /subscriptions/{subscriptionId}
curl https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
fetch('https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  }
})
requests.get(
    "https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID",
    headers={
      "X-Api-Key": "YOUR_API_KEY",
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
)
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
{
  "activatedAt": "2024-01-15T10:30:00Z",
  "createdAt": "2024-01-10T08:00:00Z",
  "customer": {
    "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "name": "Acme Corp"
  },
  "display": "(555) 123-4567",
  "metadata": {
    "costCenter": "eng-42"
  },
  "msisdn": "+15551234567",
  "productOffering": {
    "name": "Seamless 10GB",
    "price": {
      "billingCycle": {
        "interval": 1,
        "period": "MONTHLY"
      },
      "bindingContract": {
        "discount": {
          "amountMinor": 200
        },
        "duration": {
          "unit": "MONTHS",
          "value": 12
        }
      },
      "currency": "USD",
      "currencyOptionsMinor": {
        "SEK": 29900,
        "USD": 2999
      },
      "customUpfrontPayment": {
        "billingCycles": 3,
        "discount": {
          "amountMinor": 300
        }
      },
      "netPriceMinor": 2999,
      "priceType": "RECURRING",
      "standardDiscount": {
        "amountMinor": 500
      }
    },
    "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  },
  "referenceId": "crm-subscription-12345",
  "serviceAddress": {
    "address": {
      "city": "Natick",
      "country": "US",
      "state": "MA",
      "street": "500 S Main St",
      "street2": "Apt 1",
      "zip": "01701"
    },
    "source": "SUBSCRIPTION"
  },
  "sim": {
    "esim": true,
    "iccid": "8901240197155182976"
  },
  "status": "ACTIVATED",
  "subscriber": {
    "email": "john.doe@example.com",
    "name": "John Doe",
    "subscriberId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e"
  },
  "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
  "type": "CELL",
  "updatedAt": "2024-01-15T10:30:00Z"
}
{
  "code": "bad_request",
  "details": [
    {
      "code": "invalid_email",
      "message": "Email format is invalid.",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields.",
  "message": "The request body is invalid."
}
{
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header.",
  "message": "Authentication is required to access this resource."
}
{
  "code": "not_found",
  "hint": "Verify the customerId and try again.",
  "message": "The requested customer could not be found."
}
{
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support.",
  "message": "An unexpected error occurred on the server."
}

Block subscription SIM

POST/subscriptions/{subscriptionId}/block-sim

Block the SIM card on one subscription of the customer of the user that makes the request, so it can no longer use the network. Use this when the user 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 user their number.

A block is permanent for the user. restoreSubscription does not reverse it, because only a new SIM card brings the subscription back into service. The End-User API does not issue a SIM card, so the user must speak to the operator.

Path parameters

subscriptionIdstringrequired

The 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-Idempotency-Keystringmax length 256

A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request.

Modified requests with the same idempotency keys are rejected with a 409 Conflict status code.

Responses

200

SIM blocked successfully.

application/json

SIM blocked successfully.

objectSubscription

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

activatedAtstringdate-time

The date and time when the subscription was activated. Absent until the subscription has been activated.

barReasonsarray of BarReason

The 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.

cancelledAtstringdate-time

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

createdAtstringdate-timerequired

The date and time when the subscription was created.

customerobjectrequired

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

Show child attributes
customerIdstringrequired

The unique identifier for the customer. Use it with the customer endpoints to fetch full details.

namestringrequired

The customer's display name — the company name for business customers or the person's full name for consumers.

displaystringrequired

Human-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.

extensionsobject with string keys

Additional subscription extensions fields provided for custom subscription types.

Show child attributes
*string
metadataobject with string keys

A 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
*string
msisdnstringphonepersonal datarequired

The 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.

pendingMsisdnobjectpersonal data

A 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 datarequired

The phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.

scheduledAtstringdate

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

pendingProductOfferingobject

A 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
productobjectrequired

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
groupobject

A product group organizes related product offerings.

Show child attributes
imageUrlstringuri

URL to the image representing the product offering.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The 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
productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

scheduledAtstringdaterequired

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

pendingStatusobject

A 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
scheduledAtstringdate

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

statusenum<string>required

Current 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

  • PENDING
  • ACTIVATED
  • BLOCKED
  • CANCELLED
  • PAUSED
  • SUSPENDED
portingobject

Number porting information for subscriptions, indicating scheduled number transfers.

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

Show child attributes
directionenum<string>required

The 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

  • INBOUND
  • OUTBOUND
msisdnstringpersonal datarequired

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

scheduledAtstringdaterequired

The date when the number porting is scheduled to occur.

statusenum<string>required

Current 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

  • PENDING
  • IN_PROGRESS
  • SCHEDULED
  • COMPLETED
  • FAILED
productOfferingobject

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
groupobject

A product group organizes related product offerings.

Show child attributes
categoryenum<string>required

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

Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.

Categories are grouped by their product type:

SUBSCRIPTION categories:

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXED - Cellular subscription at a fixed location
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
  • PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming
  • PRODUCT_CATEGORY_VANITY_NUMBER_FORWARD - Vanity number that forwards calls
  • PRODUCT_CATEGORY_VANITY_NUMBER_CELL - Vanity number on a cellular subscription

SUBSCRIPTION_ADDON categories:

  • PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
  • PRODUCT_CATEGORY_ABROAD - International roaming addon
  • PRODUCT_CATEGORY_ABROAD_EXTRA_DATA - Additional data package for roaming
  • PRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EU - Data package for use outside the EU
  • PRODUCT_CATEGORY_NETWORK_EXTENSIONS - Network feature addon
  • PRODUCT_CATEGORY_VANITY_NUMBER - Vanity number addon

EXTERNAL_PRODUCT categories:

  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

SIM_CARD categories:

  • PRODUCT_CATEGORY_SIM_CARD - Physical SIM or eSIM replacement for an existing subscription

LICENSE categories (PBX):

  • PRODUCT_CATEGORY_PBX_USER_LEVEL - Level of a PBX user license
  • PRODUCT_CATEGORY_PBX_NUMBER - PBX phone number
  • PRODUCT_CATEGORY_PBX_MOBILE_NUMBER - PBX mobile number
  • PRODUCT_CATEGORY_PBX_LANDLINE_FORWARD - Forward from a landline number
  • PRODUCT_CATEGORY_PBX_SOFTPHONE - Softphone
  • PRODUCT_CATEGORY_PBX_STATISTICS - Call statistics
  • PRODUCT_CATEGORY_PBX_CALL_RECORDING - Call recording
  • PRODUCT_CATEGORY_PBX_VOICEMAIL - Voicemail
  • PRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERS - Queue capacity
  • PRODUCT_CATEGORY_PBX_ROUTE_IVR, PRODUCT_CATEGORY_PBX_ROUTE_GROUP, PRODUCT_CATEGORY_PBX_ROUTE_QUEUE - Call routes
  • PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVR, PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUP, PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUE, PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAIL - Call route features

Other categories:

  • PRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNER, PRODUCT_CATEGORY_INTERNATIONAL_NUMBER

A caller must tolerate new values.

values

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M
  • PRODUCT_CATEGORY_TRAVEL_ESIM
  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXED
  • PRODUCT_CATEGORY_VANITY_NUMBER_FORWARD
  • PRODUCT_CATEGORY_VANITY_NUMBER_CELL
  • PRODUCT_CATEGORY_EXTRA_DATA
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
  • PRODUCT_CATEGORY_ABROAD
  • PRODUCT_CATEGORY_ABROAD_EXTRA_DATA
  • PRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EU
  • PRODUCT_CATEGORY_NETWORK_EXTENSIONS
  • PRODUCT_CATEGORY_VANITY_NUMBER
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
  • PRODUCT_CATEGORY_SIM_CARD
  • PRODUCT_CATEGORY_PBX_USER_LEVEL
  • PRODUCT_CATEGORY_PBX_NUMBER
  • PRODUCT_CATEGORY_PBX_MOBILE_NUMBER
  • PRODUCT_CATEGORY_PBX_LANDLINE_FORWARD
  • PRODUCT_CATEGORY_PBX_SOFTPHONE
  • PRODUCT_CATEGORY_PBX_STATISTICS
  • PRODUCT_CATEGORY_PBX_CALL_RECORDING
  • PRODUCT_CATEGORY_PBX_VOICEMAIL
  • PRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERS
  • PRODUCT_CATEGORY_PBX_ROUTE_IVR
  • PRODUCT_CATEGORY_PBX_ROUTE_GROUP
  • PRODUCT_CATEGORY_PBX_ROUTE_QUEUE
  • PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVR
  • PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUP
  • PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUE
  • PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAIL
  • PRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNER
  • PRODUCT_CATEGORY_INTERNATIONAL_NUMBER
descriptionstring

Description of the product group in the requested locale.

internalDescriptionstring

Internal description of the product group for operational use only.

namestringrequired

Name of the product group in the requested locale.

productOfferingGroupIdstringrequired

Unique identifier for the product group.

imageUrlstringuri

URL to the image representing the product offering.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The 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
billingCycleobject

How often a recurring price is charged.

Show child attributes
bindingContractobject

A 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
currencystringrequired

The ISO 4217 currency code the price is expressed in (e.g., "USD").

currencyOptionsMinorobject with string keys

Per-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
customUpfrontPaymentobject

Billing 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
includesTaxboolean

True when the configured price includes its tax. The tax is then a part of netPriceMinor rather than an amount on top of it.

netPriceMinorintegerint64

The 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.

priceTypeenum<string>required

How 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_TIME
  • RECURRING
standardDiscountobject

A 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
productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

referenceIdstringmax length 255

A reference identifier provided by API clients to identify this subscription in their own systems. Must be unique per tenant. Use this field to look up subscriptions by your external identifier or to create/retrieve subscriptions during order creation.

serviceAddressobject

The 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
addressobjectrequired

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
attentionstringpersonal data

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

citystringrequired

The city or municipality of the address.

countrystringpattern ^[A-Z]{2}$required

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

regionstring

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

statestring

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

streetstringpersonal data

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

street1stringpersonal datadeprecatedrequired

Deprecated. Use street instead.

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

street2stringpersonal data

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

zipstringpersonal datarequired

The 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.

sourceenum<string>required

The 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

  • SUBSCRIPTION
  • CUSTOMER_BILLING
simobjectrequired

SIM card information for the subscription. Sensitive details like PUK require separate API calls.

Use dedicated SIM API endpoints with proper authorization to access sensitive information such as PUK.

Show child attributes
esimbooleanrequired

Whether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.

iccidstringpersonal data

Integrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.

imeistringpersonal data

International Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.

Only applicable for eSIM.

statusenum<string>required

Current 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

  • PENDING
  • ACTIVATED
  • BLOCKED
  • CANCELLED
  • PAUSED
  • SUSPENDED
subscriberobject

The person who uses the service on a subscription, as distinct from the customer who pays for it.

Show child attributes
addressobjectdeprecated

Deprecated. 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
attentionstringpersonal data

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

citystringrequired

The city or municipality of the address.

countrystringpattern ^[A-Z]{2}$required

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

regionstring

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

statestring

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

streetstringpersonal data

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

street1stringpersonal datadeprecatedrequired

Deprecated. Use street instead.

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

street2stringpersonal data

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

zipstringpersonal datarequired

The 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.

createdAtstringdate-time

Date and time when the subscriber was created.

emailstringemailpersonal data

The subscriber's email address, if one has been provided.

namestringrequired

The subscriber's full name.

subscriberIdstringrequired

The unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.

updatedAtstringdate-time

Date and time when the subscriber was last updated.

subscriptionIdstringrequired

The unique identifier for the subscription.

typestringrequired

The 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.

updatedAtstringdate-timerequired

The date and time when the subscription was last updated.

400

The request was malformed or invalid.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

401

Authentication is required to access this resource.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

403

Access to this resource is forbidden.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

404

The requested resource was not found.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

412

A precondition for this request was not met.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

500

An unexpected error occurred on the server.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

Auth required

Send

  • X-Api-Key + Bearer JWT
POST /subscriptions/{subscriptionId}/block-sim
curl https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/block-sim \
  --request POST \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
fetch('https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/block-sim', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  }
})
requests.post(
    "https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/block-sim",
    headers={
      "X-Api-Key": "YOUR_API_KEY",
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
)
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/block-sim"

	req, _ := http.NewRequest("POST", requestUrl, nil)

	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
{
  "activatedAt": "2024-01-15T10:30:00Z",
  "barReasons": [
    "MISSING_PAYMENT"
  ],
  "cancelledAt": "2024-06-30T00:00:00Z",
  "createdAt": "2024-01-10T08:00:00Z",
  "customer": {
    "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "name": "John Doe"
  },
  "display": "(555) 123-4567",
  "extensions": {
    "propertyName": "string"
  },
  "metadata": {
    "propertyName": "string"
  },
  "msisdn": "+15551234567",
  "pendingMsisdn": {
    "msisdn": "+15559876543",
    "scheduledAt": "2024-02-01"
  },
  "pendingProductOffering": {
    "product": {
      "group": {
        "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
        "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
        "internalDescription": "Core mobile offerings targeting consumer and business segments",
        "name": "Mobile Plans",
        "productOfferingGroupId": "mobile-plans"
      },
      "imageUrl": "https://cdn.example.com/images/mobile-basic.png",
      "name": "Mobile Unlimited",
      "price": {
        "billingCycle": {
          "interval": 1,
          "period": "MONTHLY"
        },
        "bindingContract": {
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "invoicingDescription": "Campaign discount",
            "source": "STANDARD"
          },
          "duration": {
            "unit": "MONTHS",
            "value": 3
          }
        },
        "currency": "USD",
        "currencyOptionsMinor": {
          "propertyName": 1
        },
        "customUpfrontPayment": {
          "billingCycles": 3,
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "invoicingDescription": "Campaign discount",
            "source": "STANDARD"
          }
        },
        "includesTax": false,
        "netPriceMinor": 2999,
        "priceType": "ONE_TIME",
        "standardDiscount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "invoicingDescription": "Campaign discount",
          "source": "STANDARD"
        }
      },
      "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
    },
    "scheduledAt": "2024-02-01"
  },
  "pendingStatus": {
    "scheduledAt": "2024-02-01",
    "status": "PENDING"
  },
  "porting": {
    "direction": "INBOUND",
    "msisdn": "+15551234567",
    "scheduledAt": "2024-02-01",
    "status": "PENDING"
  },
  "productOffering": {
    "group": {
      "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
      "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
      "internalDescription": "Core mobile offerings targeting consumer and business segments",
      "name": "Mobile Plans",
      "productOfferingGroupId": "mobile-plans"
    },
    "imageUrl": "https://cdn.example.com/images/mobile-basic.png",
    "name": "Mobile Unlimited",
    "price": {
      "billingCycle": {
        "interval": 1,
        "period": "MONTHLY"
      },
      "bindingContract": {
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "invoicingDescription": "Campaign discount",
          "source": "STANDARD"
        },
        "duration": {
          "unit": "MONTHS",
          "value": 3
        }
      },
      "currency": "USD",
      "currencyOptionsMinor": {
        "propertyName": 1
      },
      "customUpfrontPayment": {
        "billingCycles": 3,
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "invoicingDescription": "Campaign discount",
          "source": "STANDARD"
        }
      },
      "includesTax": false,
      "netPriceMinor": 2999,
      "priceType": "ONE_TIME",
      "standardDiscount": {
        "amountMinor": 500,
        "duration": {
          "unit": "MONTHS",
          "value": 3
        },
        "invoicingDescription": "Campaign discount",
        "source": "STANDARD"
      }
    },
    "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  },
  "referenceId": "crm-subscription-12345",
  "serviceAddress": {
    "address": {
      "attention": "John Doe",
      "city": "Natick",
      "country": "US",
      "region": "Ontario",
      "state": "CA",
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "zip": "01701"
    },
    "source": "SUBSCRIPTION"
  },
  "sim": {
    "esim": true,
    "iccid": "8901240197155182976",
    "imei": "356938035643809"
  },
  "status": "PENDING",
  "subscriber": {
    "address": {
      "attention": "John Doe",
      "city": "Natick",
      "country": "US",
      "region": "Ontario",
      "state": "CA",
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "zip": "01701"
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "email": "john.doe@example.com",
    "name": "John Doe",
    "subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
    "updatedAt": "2024-01-20T14:45:00Z"
  },
  "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
  "type": "CELL",
  "updatedAt": "2024-01-15T10:30:00Z"
}
{
  "code": "bad_request",
  "details": [
    {
      "code": "invalid_email",
      "message": "Email format is invalid.",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields.",
  "message": "The request body is invalid."
}
{
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header.",
  "message": "Authentication is required to access this resource."
}
{
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions.",
  "message": "You do not have permission to perform this action."
}
{
  "code": "not_found",
  "hint": "Verify the customerId and try again.",
  "message": "The requested customer could not be found."
}
{
  "code": "precondition_failed",
  "hint": "Fetch the current resource and retry with an up-to-date precondition.",
  "message": "A precondition given in the request headers was not met."
}
{
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support.",
  "message": "An unexpected error occurred on the server."
}

Get eSIM profile status

GET/subscriptions/{subscriptionId}/esim/profile

Retrieve 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

subscriptionIdstringrequired

The 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

200

eSIM profile status retrieved successfully.

application/json

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.

eidstring

The EID (eSIM Identifier) assigned to the device. Empty until the eSIM is activated.

installedCountinteger

The number of times a device installed this profile. Absent when the network operator sets no limit.

lastOperationAtstringdate-time

When the last eUICC operation occurred for this profile.

maxCountinteger

The maximum number of times a device can install this profile. Absent when the network operator sets no limit.

statusenum<string>required

The installation state of an eSIM profile on the network. Reflects the current eUICC profile lifecycle stage as reported by the network operator.

values

  • AVAILABLE
  • ALLOCATED
  • LINKED
  • CONFIRMED
  • RELEASED
  • DOWNLOADED
  • INSTALLED
  • ENABLED
  • DISABLED
  • ERROR
  • UNAVAILABLE
  • DELETED
subscriptionIdstringrequired

The unique identifier of the subscription this eSIM profile belongs to.

400

The request was malformed or invalid.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

401

Authentication is required to access this resource.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

403

Access to this resource is forbidden.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

404

The requested resource was not found.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

409

The request conflicts with the current state of the resource.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

500

An unexpected error occurred on the server.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

503

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.

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.

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

Auth required

Send

  • X-Api-Key + Bearer JWT
GET /subscriptions/{subscriptionId}/esim/profile
curl https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/esim/profile \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
fetch('https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/esim/profile', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  }
})
requests.get(
    "https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/esim/profile",
    headers={
      "X-Api-Key": "YOUR_API_KEY",
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
)
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/esim/profile"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
{
  "eid": "89049032004008882600009B40002780",
  "installedCount": 3,
  "lastOperationAt": "2024-06-15T14:30:00Z",
  "maxCount": 5,
  "status": "AVAILABLE",
  "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4"
}
{
  "code": "bad_request",
  "details": [
    {
      "code": "invalid_email",
      "message": "Email format is invalid.",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields.",
  "message": "The request body is invalid."
}
{
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header.",
  "message": "Authentication is required to access this resource."
}
{
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions.",
  "message": "You do not have permission to perform this action."
}
{
  "code": "not_found",
  "hint": "Verify the customerId and try again.",
  "message": "The requested customer could not be found."
}
{
  "code": "conflict",
  "hint": "Reload the resource to get its latest state before retrying.",
  "message": "The request conflicts with the current state of the resource."
}
{
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support.",
  "message": "An unexpected error occurred on the server."
}
{
  "code": "unavailable",
  "hint": "The network behind this brand did not answer. Try again in a moment.",
  "message": "The service is temporarily unavailable. Please try again."
}

Get eSIM QR code

GET/subscriptions/{subscriptionId}/esim/qrcode

Retrieve 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

subscriptionIdstringrequired

The 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

200

eSIM QR code data and hosted URL retrieved successfully.

application/json

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.

expiresAtstringdate-time

When 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 keys

A 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
*string
qrCodeDatastringrequired

The QR code data string that contains the eSIM profile download information (LPA format).

qrCodeUrlstringuri

Hosted 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.

subscriptionIdstringrequired

The unique identifier of the subscription this QR code belongs to.

400

The request was malformed or invalid.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

401

Authentication is required to access this resource.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

403

Access to this resource is forbidden.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

404

The requested resource was not found.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

409

The request conflicts with the current state of the resource.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

500

An unexpected error occurred on the server.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

Auth required

Send

  • X-Api-Key + Bearer JWT
GET /subscriptions/{subscriptionId}/esim/qrcode
curl https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/esim/qrcode \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
fetch('https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/esim/qrcode', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  }
})
requests.get(
    "https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/esim/qrcode",
    headers={
      "X-Api-Key": "YOUR_API_KEY",
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
)
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/esim/qrcode"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
{
  "expiresAt": "2024-12-31T23:59:59Z",
  "metadata": {
    "propertyName": "string"
  },
  "qrCodeData": "LPA:1$rsp-prod.example.com$12345678-1234-1234-1234-123456789012",
  "qrCodeUrl": "https://esim.your-domain.com/qr/d8174435-6378-4be5-a9f5-8b4aaadae5d4",
  "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4"
}
{
  "code": "bad_request",
  "details": [
    {
      "code": "invalid_email",
      "message": "Email format is invalid.",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields.",
  "message": "The request body is invalid."
}
{
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header.",
  "message": "Authentication is required to access this resource."
}
{
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions.",
  "message": "You do not have permission to perform this action."
}
{
  "code": "not_found",
  "hint": "Verify the customerId and try again.",
  "message": "The requested customer could not be found."
}
{
  "code": "conflict",
  "hint": "Reload the resource to get its latest state before retrying.",
  "message": "The request conflicts with the current state of the resource."
}
{
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support.",
  "message": "An unexpected error occurred on the server."
}

Pause subscription

POST/subscriptions/{subscriptionId}/pause

Pause 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

subscriptionIdstringrequired

The 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-Idempotency-Keystringmax length 256

A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request.

Modified requests with the same idempotency keys are rejected with a 409 Conflict status code.

BodyPauseSubscriptionRequestrequiredapplication/json

Request to pause a subscription. The customer stops paying and service is disabled.

metadataobject with string keys

A 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
*string
scheduledAtstringdate

Earliest date to perform the pause on. If the pause schedule doesn't fit this date, the earliest date after this will be chosen.

Responses

200

Subscription pause scheduled successfully.

application/json

Subscription pause scheduled successfully.

objectSubscription

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

activatedAtstringdate-time

The date and time when the subscription was activated. Absent until the subscription has been activated.

barReasonsarray of BarReason

The 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.

cancelledAtstringdate-time

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

createdAtstringdate-timerequired

The date and time when the subscription was created.

customerobjectrequired

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

Show child attributes
customerIdstringrequired

The unique identifier for the customer. Use it with the customer endpoints to fetch full details.

namestringrequired

The customer's display name — the company name for business customers or the person's full name for consumers.

displaystringrequired

Human-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.

extensionsobject with string keys

Additional subscription extensions fields provided for custom subscription types.

Show child attributes
*string
metadataobject with string keys

A 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
*string
msisdnstringphonepersonal datarequired

The 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.

pendingMsisdnobjectpersonal data

A 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 datarequired

The phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.

scheduledAtstringdate

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

pendingProductOfferingobject

A 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
productobjectrequired

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
groupobject

A product group organizes related product offerings.

Show child attributes
imageUrlstringuri

URL to the image representing the product offering.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The 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
productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

scheduledAtstringdaterequired

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

pendingStatusobject

A 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
scheduledAtstringdate

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

statusenum<string>required

Current 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

  • PENDING
  • ACTIVATED
  • BLOCKED
  • CANCELLED
  • PAUSED
  • SUSPENDED
portingobject

Number porting information for subscriptions, indicating scheduled number transfers.

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

Show child attributes
directionenum<string>required

The 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

  • INBOUND
  • OUTBOUND
msisdnstringpersonal datarequired

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

scheduledAtstringdaterequired

The date when the number porting is scheduled to occur.

statusenum<string>required

Current 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

  • PENDING
  • IN_PROGRESS
  • SCHEDULED
  • COMPLETED
  • FAILED
productOfferingobject

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
groupobject

A product group organizes related product offerings.

Show child attributes
categoryenum<string>required

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

Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.

Categories are grouped by their product type:

SUBSCRIPTION categories:

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXED - Cellular subscription at a fixed location
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
  • PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming
  • PRODUCT_CATEGORY_VANITY_NUMBER_FORWARD - Vanity number that forwards calls
  • PRODUCT_CATEGORY_VANITY_NUMBER_CELL - Vanity number on a cellular subscription

SUBSCRIPTION_ADDON categories:

  • PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
  • PRODUCT_CATEGORY_ABROAD - International roaming addon
  • PRODUCT_CATEGORY_ABROAD_EXTRA_DATA - Additional data package for roaming
  • PRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EU - Data package for use outside the EU
  • PRODUCT_CATEGORY_NETWORK_EXTENSIONS - Network feature addon
  • PRODUCT_CATEGORY_VANITY_NUMBER - Vanity number addon

EXTERNAL_PRODUCT categories:

  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

SIM_CARD categories:

  • PRODUCT_CATEGORY_SIM_CARD - Physical SIM or eSIM replacement for an existing subscription

LICENSE categories (PBX):

  • PRODUCT_CATEGORY_PBX_USER_LEVEL - Level of a PBX user license
  • PRODUCT_CATEGORY_PBX_NUMBER - PBX phone number
  • PRODUCT_CATEGORY_PBX_MOBILE_NUMBER - PBX mobile number
  • PRODUCT_CATEGORY_PBX_LANDLINE_FORWARD - Forward from a landline number
  • PRODUCT_CATEGORY_PBX_SOFTPHONE - Softphone
  • PRODUCT_CATEGORY_PBX_STATISTICS - Call statistics
  • PRODUCT_CATEGORY_PBX_CALL_RECORDING - Call recording
  • PRODUCT_CATEGORY_PBX_VOICEMAIL - Voicemail
  • PRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERS - Queue capacity
  • PRODUCT_CATEGORY_PBX_ROUTE_IVR, PRODUCT_CATEGORY_PBX_ROUTE_GROUP, PRODUCT_CATEGORY_PBX_ROUTE_QUEUE - Call routes
  • PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVR, PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUP, PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUE, PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAIL - Call route features

Other categories:

  • PRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNER, PRODUCT_CATEGORY_INTERNATIONAL_NUMBER

A caller must tolerate new values.

values

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M
  • PRODUCT_CATEGORY_TRAVEL_ESIM
  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXED
  • PRODUCT_CATEGORY_VANITY_NUMBER_FORWARD
  • PRODUCT_CATEGORY_VANITY_NUMBER_CELL
  • PRODUCT_CATEGORY_EXTRA_DATA
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
  • PRODUCT_CATEGORY_ABROAD
  • PRODUCT_CATEGORY_ABROAD_EXTRA_DATA
  • PRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EU
  • PRODUCT_CATEGORY_NETWORK_EXTENSIONS
  • PRODUCT_CATEGORY_VANITY_NUMBER
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
  • PRODUCT_CATEGORY_SIM_CARD
  • PRODUCT_CATEGORY_PBX_USER_LEVEL
  • PRODUCT_CATEGORY_PBX_NUMBER
  • PRODUCT_CATEGORY_PBX_MOBILE_NUMBER
  • PRODUCT_CATEGORY_PBX_LANDLINE_FORWARD
  • PRODUCT_CATEGORY_PBX_SOFTPHONE
  • PRODUCT_CATEGORY_PBX_STATISTICS
  • PRODUCT_CATEGORY_PBX_CALL_RECORDING
  • PRODUCT_CATEGORY_PBX_VOICEMAIL
  • PRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERS
  • PRODUCT_CATEGORY_PBX_ROUTE_IVR
  • PRODUCT_CATEGORY_PBX_ROUTE_GROUP
  • PRODUCT_CATEGORY_PBX_ROUTE_QUEUE
  • PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVR
  • PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUP
  • PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUE
  • PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAIL
  • PRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNER
  • PRODUCT_CATEGORY_INTERNATIONAL_NUMBER
descriptionstring

Description of the product group in the requested locale.

internalDescriptionstring

Internal description of the product group for operational use only.

namestringrequired

Name of the product group in the requested locale.

productOfferingGroupIdstringrequired

Unique identifier for the product group.

imageUrlstringuri

URL to the image representing the product offering.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The 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
billingCycleobject

How often a recurring price is charged.

Show child attributes
bindingContractobject

A 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
currencystringrequired

The ISO 4217 currency code the price is expressed in (e.g., "USD").

currencyOptionsMinorobject with string keys

Per-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
customUpfrontPaymentobject

Billing 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
includesTaxboolean

True when the configured price includes its tax. The tax is then a part of netPriceMinor rather than an amount on top of it.

netPriceMinorintegerint64

The 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.

priceTypeenum<string>required

How 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_TIME
  • RECURRING
standardDiscountobject

A 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
productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

referenceIdstringmax length 255

A reference identifier provided by API clients to identify this subscription in their own systems. Must be unique per tenant. Use this field to look up subscriptions by your external identifier or to create/retrieve subscriptions during order creation.

serviceAddressobject

The 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
addressobjectrequired

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
attentionstringpersonal data

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

citystringrequired

The city or municipality of the address.

countrystringpattern ^[A-Z]{2}$required

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

regionstring

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

statestring

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

streetstringpersonal data

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

street1stringpersonal datadeprecatedrequired

Deprecated. Use street instead.

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

street2stringpersonal data

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

zipstringpersonal datarequired

The 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.

sourceenum<string>required

The 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

  • SUBSCRIPTION
  • CUSTOMER_BILLING
simobjectrequired

SIM card information for the subscription. Sensitive details like PUK require separate API calls.

Use dedicated SIM API endpoints with proper authorization to access sensitive information such as PUK.

Show child attributes
esimbooleanrequired

Whether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.

iccidstringpersonal data

Integrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.

imeistringpersonal data

International Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.

Only applicable for eSIM.

statusenum<string>required

Current 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

  • PENDING
  • ACTIVATED
  • BLOCKED
  • CANCELLED
  • PAUSED
  • SUSPENDED
subscriberobject

The person who uses the service on a subscription, as distinct from the customer who pays for it.

Show child attributes
addressobjectdeprecated

Deprecated. 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
attentionstringpersonal data

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

citystringrequired

The city or municipality of the address.

countrystringpattern ^[A-Z]{2}$required

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

regionstring

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

statestring

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

streetstringpersonal data

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

street1stringpersonal datadeprecatedrequired

Deprecated. Use street instead.

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

street2stringpersonal data

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

zipstringpersonal datarequired

The 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.

createdAtstringdate-time

Date and time when the subscriber was created.

emailstringemailpersonal data

The subscriber's email address, if one has been provided.

namestringrequired

The subscriber's full name.

subscriberIdstringrequired

The unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.

updatedAtstringdate-time

Date and time when the subscriber was last updated.

subscriptionIdstringrequired

The unique identifier for the subscription.

typestringrequired

The 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.

updatedAtstringdate-timerequired

The date and time when the subscription was last updated.

400

The request was malformed or invalid.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

401

Authentication is required to access this resource.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

403

Access to this resource is forbidden.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

404

The requested resource was not found.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

409

The request conflicts with the current state of the resource.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

500

An unexpected error occurred on the server.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

Auth required

Send

  • X-Api-Key + Bearer JWT
POST /subscriptions/{subscriptionId}/pause
curl https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/pause \
  --request POST \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "metadata": {
    "propertyName": "string"
  },
  "scheduledAt": "2024-02-01"
}'
fetch('https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/pause', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    metadata: {
      propertyName: 'string'
    },
    scheduledAt: '2024-02-01'
  })
})
requests.post(
    "https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/pause",
    headers={
      "X-Api-Key": "YOUR_API_KEY",
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json"
    },
    json={
      "metadata": {
        "propertyName": "string"
      },
      "scheduledAt": "2024-02-01"
    }
)
package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/pause"

	payload := strings.NewReader(`{
  "metadata": {
    "propertyName": "string"
  },
  "scheduledAt": "2024-02-01"
}`)

	req, _ := http.NewRequest("POST", requestUrl, payload)

	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	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))

}
{
  "activatedAt": "2024-01-15T10:30:00Z",
  "barReasons": [
    "MISSING_PAYMENT"
  ],
  "cancelledAt": "2024-06-30T00:00:00Z",
  "createdAt": "2024-01-10T08:00:00Z",
  "customer": {
    "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "name": "John Doe"
  },
  "display": "(555) 123-4567",
  "extensions": {
    "propertyName": "string"
  },
  "metadata": {
    "propertyName": "string"
  },
  "msisdn": "+15551234567",
  "pendingMsisdn": {
    "msisdn": "+15559876543",
    "scheduledAt": "2024-02-01"
  },
  "pendingProductOffering": {
    "product": {
      "group": {
        "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
        "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
        "internalDescription": "Core mobile offerings targeting consumer and business segments",
        "name": "Mobile Plans",
        "productOfferingGroupId": "mobile-plans"
      },
      "imageUrl": "https://cdn.example.com/images/mobile-basic.png",
      "name": "Mobile Unlimited",
      "price": {
        "billingCycle": {
          "interval": 1,
          "period": "MONTHLY"
        },
        "bindingContract": {
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "invoicingDescription": "Campaign discount",
            "source": "STANDARD"
          },
          "duration": {
            "unit": "MONTHS",
            "value": 3
          }
        },
        "currency": "USD",
        "currencyOptionsMinor": {
          "propertyName": 1
        },
        "customUpfrontPayment": {
          "billingCycles": 3,
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "invoicingDescription": "Campaign discount",
            "source": "STANDARD"
          }
        },
        "includesTax": false,
        "netPriceMinor": 2999,
        "priceType": "ONE_TIME",
        "standardDiscount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "invoicingDescription": "Campaign discount",
          "source": "STANDARD"
        }
      },
      "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
    },
    "scheduledAt": "2024-02-01"
  },
  "pendingStatus": {
    "scheduledAt": "2024-02-01",
    "status": "PENDING"
  },
  "porting": {
    "direction": "INBOUND",
    "msisdn": "+15551234567",
    "scheduledAt": "2024-02-01",
    "status": "PENDING"
  },
  "productOffering": {
    "group": {
      "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
      "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
      "internalDescription": "Core mobile offerings targeting consumer and business segments",
      "name": "Mobile Plans",
      "productOfferingGroupId": "mobile-plans"
    },
    "imageUrl": "https://cdn.example.com/images/mobile-basic.png",
    "name": "Mobile Unlimited",
    "price": {
      "billingCycle": {
        "interval": 1,
        "period": "MONTHLY"
      },
      "bindingContract": {
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "invoicingDescription": "Campaign discount",
          "source": "STANDARD"
        },
        "duration": {
          "unit": "MONTHS",
          "value": 3
        }
      },
      "currency": "USD",
      "currencyOptionsMinor": {
        "propertyName": 1
      },
      "customUpfrontPayment": {
        "billingCycles": 3,
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "invoicingDescription": "Campaign discount",
          "source": "STANDARD"
        }
      },
      "includesTax": false,
      "netPriceMinor": 2999,
      "priceType": "ONE_TIME",
      "standardDiscount": {
        "amountMinor": 500,
        "duration": {
          "unit": "MONTHS",
          "value": 3
        },
        "invoicingDescription": "Campaign discount",
        "source": "STANDARD"
      }
    },
    "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  },
  "referenceId": "crm-subscription-12345",
  "serviceAddress": {
    "address": {
      "attention": "John Doe",
      "city": "Natick",
      "country": "US",
      "region": "Ontario",
      "state": "CA",
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "zip": "01701"
    },
    "source": "SUBSCRIPTION"
  },
  "sim": {
    "esim": true,
    "iccid": "8901240197155182976",
    "imei": "356938035643809"
  },
  "status": "PENDING",
  "subscriber": {
    "address": {
      "attention": "John Doe",
      "city": "Natick",
      "country": "US",
      "region": "Ontario",
      "state": "CA",
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "zip": "01701"
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "email": "john.doe@example.com",
    "name": "John Doe",
    "subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
    "updatedAt": "2024-01-20T14:45:00Z"
  },
  "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
  "type": "CELL",
  "updatedAt": "2024-01-15T10:30:00Z"
}
{
  "code": "bad_request",
  "details": [
    {
      "code": "invalid_email",
      "message": "Email format is invalid.",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields.",
  "message": "The request body is invalid."
}
{
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header.",
  "message": "Authentication is required to access this resource."
}
{
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions.",
  "message": "You do not have permission to perform this action."
}
{
  "code": "not_found",
  "hint": "Verify the customerId and try again.",
  "message": "The requested customer could not be found."
}
{
  "code": "conflict",
  "hint": "Reload the resource to get its latest state before retrying.",
  "message": "The request conflicts with the current state of the resource."
}
{
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support.",
  "message": "An unexpected error occurred on the server."
}

Get change options for subscription

GET/subscriptions/{subscriptionId}/product-offering-options

Get 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

subscriptionIdstringrequired

The 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

200

Available change options.

application/json

Available change options.

object

itemsarray of ProductOfferingOptionrequired
Show child attributes
changeScheduleenum<string>required

The 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

  • INSTANT
  • FIRST_OF_NEXT_MONTH
  • NEXT_RENEWAL_DAY
  • NEXT_PAYMENT_DAY
  • END_OF_PAID_PERIOD
  • END_OF_BINDING_PERIOD
changeScheduleDatestringdaterequired

The date when the product offering change can take effect.

productOfferingobjectrequired

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
groupobject

A product group organizes related product offerings.

Show child attributes
imageUrlstringuri

URL to the image representing the product offering.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The 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
productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

400

The request was malformed or invalid.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

401

Authentication is required to access this resource.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

403

Access to this resource is forbidden.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

404

The requested resource was not found.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

500

An unexpected error occurred on the server.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

Auth required

Send

  • X-Api-Key + Bearer JWT
GET /subscriptions/{subscriptionId}/product-offering-options
curl https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/product-offering-options \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
fetch('https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/product-offering-options', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  }
})
requests.get(
    "https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/product-offering-options",
    headers={
      "X-Api-Key": "YOUR_API_KEY",
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
)
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/product-offering-options"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
{
  "items": [
    {
      "changeSchedule": "INSTANT",
      "changeScheduleDate": "2024-02-01",
      "productOffering": {
        "group": {
          "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
          "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
          "internalDescription": "Core mobile offerings targeting consumer and business segments",
          "name": "Mobile Plans",
          "productOfferingGroupId": "mobile-plans"
        },
        "imageUrl": "https://cdn.example.com/images/mobile-basic.png",
        "name": "Mobile Unlimited",
        "price": {
          "billingCycle": {
            "interval": 1,
            "period": "MONTHLY"
          },
          "bindingContract": {
            "discount": {
              "amountMinor": 500,
              "duration": {
                "unit": "MONTHS",
                "value": 3
              },
              "invoicingDescription": "Campaign discount",
              "source": "STANDARD"
            },
            "duration": {
              "unit": "MONTHS",
              "value": 3
            }
          },
          "currency": "USD",
          "currencyOptionsMinor": {
            "propertyName": 1
          },
          "customUpfrontPayment": {
            "billingCycles": 3,
            "discount": {
              "amountMinor": 500,
              "duration": {
                "unit": "MONTHS",
                "value": 3
              },
              "invoicingDescription": "Campaign discount",
              "source": "STANDARD"
            }
          },
          "includesTax": false,
          "netPriceMinor": 2999,
          "priceType": "ONE_TIME",
          "standardDiscount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "invoicingDescription": "Campaign discount",
            "source": "STANDARD"
          }
        },
        "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
      }
    }
  ]
}
{
  "code": "bad_request",
  "details": [
    {
      "code": "invalid_email",
      "message": "Email format is invalid.",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields.",
  "message": "The request body is invalid."
}
{
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header.",
  "message": "Authentication is required to access this resource."
}
{
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions.",
  "message": "You do not have permission to perform this action."
}
{
  "code": "not_found",
  "hint": "Verify the customerId and try again.",
  "message": "The requested customer could not be found."
}
{
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support.",
  "message": "An unexpected error occurred on the server."
}

Reset subscription network services

POST/subscriptions/{subscriptionId}/reset-network-services

Start 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

subscriptionIdstringrequired

The 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-Idempotency-Keystringmax length 256

A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request.

Modified requests with the same idempotency keys are rejected with a 409 Conflict status code.

BodyResetNetworkServicesRequestrequiredapplication/json

Confirms that the user approved a temporary interruption while network services are reset.

confirmedbooleanrequired

Must be true after the user explicitly approves the temporary service interruption.

Responses

200

Reset started, already running, or recently completed.

application/json

Reset started, already running, or recently completed.

objectResetNetworkServicesResult

Current state of a subscription network-services reset.

createdAtstringdate-time

When the reset workflow action was created.

finishedAtstringdate-time

When execution finished, if it has finished.

networkProviderstringrequired

Network provider selected for this subscription.

observedAtstringdate-timerequired

When this status was read.

outcomeenum<string>required

Whether a reset was started or an existing recent reset was returned.

values

  • STARTED
  • ALREADY_RUNNING
  • RECENT_SUCCESS
  • RECENT_FAILURE
  • OPERATOR_UNSUPPORTED
startedAtstringdate-time

When execution started, if it has started.

statusenum<string>required

Current workflow state.

values

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • UNSUPPORTED
subscriptionActionIdstring

Identifier of the reset workflow action. Absent when the network provider is unsupported.

subscriptionIdstringrequired

Subscription whose network services are being reset.

400

The request was malformed or invalid.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

401

Authentication is required to access this resource.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

403

Access to this resource is forbidden.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

404

The requested resource was not found.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

409

The request conflicts with the current state of the resource.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

412

A precondition for this request was not met.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

500

An unexpected error occurred on the server.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

501

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.

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.

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

Auth required

Send

  • X-Api-Key + Bearer JWT
POST /subscriptions/{subscriptionId}/reset-network-services
curl https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/reset-network-services \
  --request POST \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "confirmed": true
}'
fetch('https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/reset-network-services', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    confirmed: true
  })
})
requests.post(
    "https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/reset-network-services",
    headers={
      "X-Api-Key": "YOUR_API_KEY",
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json"
    },
    json={
      "confirmed": True
    }
)
package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/reset-network-services"

	payload := strings.NewReader(`{
  "confirmed": true
}`)

	req, _ := http.NewRequest("POST", requestUrl, payload)

	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	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))

}
{
  "createdAt": "2024-01-15T10:30:00Z",
  "finishedAt": "2024-01-15T10:30:00Z",
  "networkProvider": "string",
  "observedAt": "2024-01-15T10:30:00Z",
  "outcome": "STARTED",
  "startedAt": "2024-01-15T10:30:00Z",
  "status": "PENDING",
  "subscriptionActionId": "string",
  "subscriptionId": "string"
}
{
  "code": "bad_request",
  "details": [
    {
      "code": "invalid_email",
      "message": "Email format is invalid.",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields.",
  "message": "The request body is invalid."
}
{
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header.",
  "message": "Authentication is required to access this resource."
}
{
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions.",
  "message": "You do not have permission to perform this action."
}
{
  "code": "not_found",
  "hint": "Verify the customerId and try again.",
  "message": "The requested customer could not be found."
}
{
  "code": "conflict",
  "hint": "Reload the resource to get its latest state before retrying.",
  "message": "The request conflicts with the current state of the resource."
}
{
  "code": "precondition_failed",
  "hint": "Fetch the current resource and retry with an up-to-date precondition.",
  "message": "A precondition given in the request headers was not met."
}
{
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support.",
  "message": "An unexpected error occurred on the server."
}
{
  "code": "not_implemented",
  "hint": "The network behind this brand cannot answer this request.",
  "message": "This endpoint is not available in this environment."
}

Restore subscription

POST/subscriptions/{subscriptionId}/restore

Restore a paused subscription of the customer of the user that makes the request back to the active state.

The user can reverse only a pause that the user made. An operator suspends a subscription for non-payment or for fraud, and this operation does not reverse that suspension.

You can schedule the restoration:

  • Immediate restore
  • Next day restoration
  • Beginning of next month restoration
  • Specific date restoration

Path parameters

subscriptionIdstringrequired

The 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-Idempotency-Keystringmax length 256

A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request.

Modified requests with the same idempotency keys are rejected with a 409 Conflict status code.

BodyRestoreSubscriptionRequestrequiredapplication/json

Request to restore a suspended, paused, or blocked subscription back to active state.

allowedCurrentStatusesarray of SubscriptionStatus

Current statuses from which this request can restore the subscription. If omitted, the request can restore all supported statuses.

barReasonsarray of BarReasonmin items 1

The 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 keys

A 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
*string
scheduledAtstringdate

Restore the subscription on a specific date.

Responses

200

Subscription restoration scheduled successfully.

application/json

Subscription restoration scheduled successfully.

objectSubscription

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

activatedAtstringdate-time

The date and time when the subscription was activated. Absent until the subscription has been activated.

barReasonsarray of BarReason

The 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.

cancelledAtstringdate-time

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

createdAtstringdate-timerequired

The date and time when the subscription was created.

customerobjectrequired

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

Show child attributes
customerIdstringrequired

The unique identifier for the customer. Use it with the customer endpoints to fetch full details.

namestringrequired

The customer's display name — the company name for business customers or the person's full name for consumers.

displaystringrequired

Human-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.

extensionsobject with string keys

Additional subscription extensions fields provided for custom subscription types.

Show child attributes
*string
metadataobject with string keys

A 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
*string
msisdnstringphonepersonal datarequired

The 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.

pendingMsisdnobjectpersonal data

A 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 datarequired

The phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.

scheduledAtstringdate

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

pendingProductOfferingobject

A 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
productobjectrequired

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
groupobject

A product group organizes related product offerings.

Show child attributes
imageUrlstringuri

URL to the image representing the product offering.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The 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
productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

scheduledAtstringdaterequired

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

pendingStatusobject

A 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
scheduledAtstringdate

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

statusenum<string>required

Current 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

  • PENDING
  • ACTIVATED
  • BLOCKED
  • CANCELLED
  • PAUSED
  • SUSPENDED
portingobject

Number porting information for subscriptions, indicating scheduled number transfers.

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

Show child attributes
directionenum<string>required

The 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

  • INBOUND
  • OUTBOUND
msisdnstringpersonal datarequired

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

scheduledAtstringdaterequired

The date when the number porting is scheduled to occur.

statusenum<string>required

Current 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

  • PENDING
  • IN_PROGRESS
  • SCHEDULED
  • COMPLETED
  • FAILED
productOfferingobject

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
groupobject

A product group organizes related product offerings.

Show child attributes
categoryenum<string>required

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

Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.

Categories are grouped by their product type:

SUBSCRIPTION categories:

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXED - Cellular subscription at a fixed location
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
  • PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming
  • PRODUCT_CATEGORY_VANITY_NUMBER_FORWARD - Vanity number that forwards calls
  • PRODUCT_CATEGORY_VANITY_NUMBER_CELL - Vanity number on a cellular subscription

SUBSCRIPTION_ADDON categories:

  • PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
  • PRODUCT_CATEGORY_ABROAD - International roaming addon
  • PRODUCT_CATEGORY_ABROAD_EXTRA_DATA - Additional data package for roaming
  • PRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EU - Data package for use outside the EU
  • PRODUCT_CATEGORY_NETWORK_EXTENSIONS - Network feature addon
  • PRODUCT_CATEGORY_VANITY_NUMBER - Vanity number addon

EXTERNAL_PRODUCT categories:

  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

SIM_CARD categories:

  • PRODUCT_CATEGORY_SIM_CARD - Physical SIM or eSIM replacement for an existing subscription

LICENSE categories (PBX):

  • PRODUCT_CATEGORY_PBX_USER_LEVEL - Level of a PBX user license
  • PRODUCT_CATEGORY_PBX_NUMBER - PBX phone number
  • PRODUCT_CATEGORY_PBX_MOBILE_NUMBER - PBX mobile number
  • PRODUCT_CATEGORY_PBX_LANDLINE_FORWARD - Forward from a landline number
  • PRODUCT_CATEGORY_PBX_SOFTPHONE - Softphone
  • PRODUCT_CATEGORY_PBX_STATISTICS - Call statistics
  • PRODUCT_CATEGORY_PBX_CALL_RECORDING - Call recording
  • PRODUCT_CATEGORY_PBX_VOICEMAIL - Voicemail
  • PRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERS - Queue capacity
  • PRODUCT_CATEGORY_PBX_ROUTE_IVR, PRODUCT_CATEGORY_PBX_ROUTE_GROUP, PRODUCT_CATEGORY_PBX_ROUTE_QUEUE - Call routes
  • PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVR, PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUP, PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUE, PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAIL - Call route features

Other categories:

  • PRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNER, PRODUCT_CATEGORY_INTERNATIONAL_NUMBER

A caller must tolerate new values.

values

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M
  • PRODUCT_CATEGORY_TRAVEL_ESIM
  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXED
  • PRODUCT_CATEGORY_VANITY_NUMBER_FORWARD
  • PRODUCT_CATEGORY_VANITY_NUMBER_CELL
  • PRODUCT_CATEGORY_EXTRA_DATA
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
  • PRODUCT_CATEGORY_ABROAD
  • PRODUCT_CATEGORY_ABROAD_EXTRA_DATA
  • PRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EU
  • PRODUCT_CATEGORY_NETWORK_EXTENSIONS
  • PRODUCT_CATEGORY_VANITY_NUMBER
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
  • PRODUCT_CATEGORY_SIM_CARD
  • PRODUCT_CATEGORY_PBX_USER_LEVEL
  • PRODUCT_CATEGORY_PBX_NUMBER
  • PRODUCT_CATEGORY_PBX_MOBILE_NUMBER
  • PRODUCT_CATEGORY_PBX_LANDLINE_FORWARD
  • PRODUCT_CATEGORY_PBX_SOFTPHONE
  • PRODUCT_CATEGORY_PBX_STATISTICS
  • PRODUCT_CATEGORY_PBX_CALL_RECORDING
  • PRODUCT_CATEGORY_PBX_VOICEMAIL
  • PRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERS
  • PRODUCT_CATEGORY_PBX_ROUTE_IVR
  • PRODUCT_CATEGORY_PBX_ROUTE_GROUP
  • PRODUCT_CATEGORY_PBX_ROUTE_QUEUE
  • PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVR
  • PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUP
  • PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUE
  • PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAIL
  • PRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNER
  • PRODUCT_CATEGORY_INTERNATIONAL_NUMBER
descriptionstring

Description of the product group in the requested locale.

internalDescriptionstring

Internal description of the product group for operational use only.

namestringrequired

Name of the product group in the requested locale.

productOfferingGroupIdstringrequired

Unique identifier for the product group.

imageUrlstringuri

URL to the image representing the product offering.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The 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
billingCycleobject

How often a recurring price is charged.

Show child attributes
bindingContractobject

A 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
currencystringrequired

The ISO 4217 currency code the price is expressed in (e.g., "USD").

currencyOptionsMinorobject with string keys

Per-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
customUpfrontPaymentobject

Billing 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
includesTaxboolean

True when the configured price includes its tax. The tax is then a part of netPriceMinor rather than an amount on top of it.

netPriceMinorintegerint64

The 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.

priceTypeenum<string>required

How 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_TIME
  • RECURRING
standardDiscountobject

A 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
productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

referenceIdstringmax length 255

A reference identifier provided by API clients to identify this subscription in their own systems. Must be unique per tenant. Use this field to look up subscriptions by your external identifier or to create/retrieve subscriptions during order creation.

serviceAddressobject

The 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
addressobjectrequired

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
attentionstringpersonal data

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

citystringrequired

The city or municipality of the address.

countrystringpattern ^[A-Z]{2}$required

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

regionstring

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

statestring

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

streetstringpersonal data

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

street1stringpersonal datadeprecatedrequired

Deprecated. Use street instead.

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

street2stringpersonal data

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

zipstringpersonal datarequired

The 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.

sourceenum<string>required

The 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

  • SUBSCRIPTION
  • CUSTOMER_BILLING
simobjectrequired

SIM card information for the subscription. Sensitive details like PUK require separate API calls.

Use dedicated SIM API endpoints with proper authorization to access sensitive information such as PUK.

Show child attributes
esimbooleanrequired

Whether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.

iccidstringpersonal data

Integrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.

imeistringpersonal data

International Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.

Only applicable for eSIM.

statusenum<string>required

Current 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

  • PENDING
  • ACTIVATED
  • BLOCKED
  • CANCELLED
  • PAUSED
  • SUSPENDED
subscriberobject

The person who uses the service on a subscription, as distinct from the customer who pays for it.

Show child attributes
addressobjectdeprecated

Deprecated. 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
attentionstringpersonal data

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

citystringrequired

The city or municipality of the address.

countrystringpattern ^[A-Z]{2}$required

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

regionstring

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

statestring

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

streetstringpersonal data

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

street1stringpersonal datadeprecatedrequired

Deprecated. Use street instead.

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

street2stringpersonal data

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

zipstringpersonal datarequired

The 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.

createdAtstringdate-time

Date and time when the subscriber was created.

emailstringemailpersonal data

The subscriber's email address, if one has been provided.

namestringrequired

The subscriber's full name.

subscriberIdstringrequired

The unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.

updatedAtstringdate-time

Date and time when the subscriber was last updated.

subscriptionIdstringrequired

The unique identifier for the subscription.

typestringrequired

The 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.

updatedAtstringdate-timerequired

The date and time when the subscription was last updated.

400

The request was malformed or invalid.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

401

Authentication is required to access this resource.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

403

Access to this resource is forbidden.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

404

The requested resource was not found.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

409

The request conflicts with the current state of the resource.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

500

An unexpected error occurred on the server.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

Auth required

Send

  • X-Api-Key + Bearer JWT
POST /subscriptions/{subscriptionId}/restore
curl https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/restore \
  --request POST \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "allowedCurrentStatuses": [
    "PENDING"
  ],
  "barReasons": [
    "MISSING_PAYMENT"
  ],
  "metadata": {
    "propertyName": "string"
  },
  "scheduledAt": "2024-02-01"
}'
fetch('https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/restore', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    allowedCurrentStatuses: ['PENDING'],
    barReasons: ['MISSING_PAYMENT'],
    metadata: {
      propertyName: 'string'
    },
    scheduledAt: '2024-02-01'
  })
})
requests.post(
    "https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/restore",
    headers={
      "X-Api-Key": "YOUR_API_KEY",
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json"
    },
    json={
      "allowedCurrentStatuses": [
        "PENDING"
      ],
      "barReasons": [
        "MISSING_PAYMENT"
      ],
      "metadata": {
        "propertyName": "string"
      },
      "scheduledAt": "2024-02-01"
    }
)
package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/restore"

	payload := strings.NewReader(`{
  "allowedCurrentStatuses": [
    "PENDING"
  ],
  "barReasons": [
    "MISSING_PAYMENT"
  ],
  "metadata": {
    "propertyName": "string"
  },
  "scheduledAt": "2024-02-01"
}`)

	req, _ := http.NewRequest("POST", requestUrl, payload)

	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	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))

}
{
  "activatedAt": "2024-01-15T10:30:00Z",
  "barReasons": [
    "MISSING_PAYMENT"
  ],
  "cancelledAt": "2024-06-30T00:00:00Z",
  "createdAt": "2024-01-10T08:00:00Z",
  "customer": {
    "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "name": "John Doe"
  },
  "display": "(555) 123-4567",
  "extensions": {
    "propertyName": "string"
  },
  "metadata": {
    "propertyName": "string"
  },
  "msisdn": "+15551234567",
  "pendingMsisdn": {
    "msisdn": "+15559876543",
    "scheduledAt": "2024-02-01"
  },
  "pendingProductOffering": {
    "product": {
      "group": {
        "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
        "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
        "internalDescription": "Core mobile offerings targeting consumer and business segments",
        "name": "Mobile Plans",
        "productOfferingGroupId": "mobile-plans"
      },
      "imageUrl": "https://cdn.example.com/images/mobile-basic.png",
      "name": "Mobile Unlimited",
      "price": {
        "billingCycle": {
          "interval": 1,
          "period": "MONTHLY"
        },
        "bindingContract": {
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "invoicingDescription": "Campaign discount",
            "source": "STANDARD"
          },
          "duration": {
            "unit": "MONTHS",
            "value": 3
          }
        },
        "currency": "USD",
        "currencyOptionsMinor": {
          "propertyName": 1
        },
        "customUpfrontPayment": {
          "billingCycles": 3,
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "invoicingDescription": "Campaign discount",
            "source": "STANDARD"
          }
        },
        "includesTax": false,
        "netPriceMinor": 2999,
        "priceType": "ONE_TIME",
        "standardDiscount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "invoicingDescription": "Campaign discount",
          "source": "STANDARD"
        }
      },
      "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
    },
    "scheduledAt": "2024-02-01"
  },
  "pendingStatus": {
    "scheduledAt": "2024-02-01",
    "status": "PENDING"
  },
  "porting": {
    "direction": "INBOUND",
    "msisdn": "+15551234567",
    "scheduledAt": "2024-02-01",
    "status": "PENDING"
  },
  "productOffering": {
    "group": {
      "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
      "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
      "internalDescription": "Core mobile offerings targeting consumer and business segments",
      "name": "Mobile Plans",
      "productOfferingGroupId": "mobile-plans"
    },
    "imageUrl": "https://cdn.example.com/images/mobile-basic.png",
    "name": "Mobile Unlimited",
    "price": {
      "billingCycle": {
        "interval": 1,
        "period": "MONTHLY"
      },
      "bindingContract": {
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "invoicingDescription": "Campaign discount",
          "source": "STANDARD"
        },
        "duration": {
          "unit": "MONTHS",
          "value": 3
        }
      },
      "currency": "USD",
      "currencyOptionsMinor": {
        "propertyName": 1
      },
      "customUpfrontPayment": {
        "billingCycles": 3,
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "invoicingDescription": "Campaign discount",
          "source": "STANDARD"
        }
      },
      "includesTax": false,
      "netPriceMinor": 2999,
      "priceType": "ONE_TIME",
      "standardDiscount": {
        "amountMinor": 500,
        "duration": {
          "unit": "MONTHS",
          "value": 3
        },
        "invoicingDescription": "Campaign discount",
        "source": "STANDARD"
      }
    },
    "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  },
  "referenceId": "crm-subscription-12345",
  "serviceAddress": {
    "address": {
      "attention": "John Doe",
      "city": "Natick",
      "country": "US",
      "region": "Ontario",
      "state": "CA",
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "zip": "01701"
    },
    "source": "SUBSCRIPTION"
  },
  "sim": {
    "esim": true,
    "iccid": "8901240197155182976",
    "imei": "356938035643809"
  },
  "status": "PENDING",
  "subscriber": {
    "address": {
      "attention": "John Doe",
      "city": "Natick",
      "country": "US",
      "region": "Ontario",
      "state": "CA",
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "zip": "01701"
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "email": "john.doe@example.com",
    "name": "John Doe",
    "subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
    "updatedAt": "2024-01-20T14:45:00Z"
  },
  "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
  "type": "CELL",
  "updatedAt": "2024-01-15T10:30:00Z"
}
{
  "code": "bad_request",
  "details": [
    {
      "code": "invalid_email",
      "message": "Email format is invalid.",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields.",
  "message": "The request body is invalid."
}
{
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header.",
  "message": "Authentication is required to access this resource."
}
{
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions.",
  "message": "You do not have permission to perform this action."
}
{
  "code": "not_found",
  "hint": "Verify the customerId and try again.",
  "message": "The requested customer could not be found."
}
{
  "code": "conflict",
  "hint": "Reload the resource to get its latest state before retrying.",
  "message": "The request conflicts with the current state of the resource."
}
{
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support.",
  "message": "An unexpected error occurred on the server."
}

Get roaming cost control

GET/subscriptions/{subscriptionId}/roaming-cost-control

Get 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

subscriptionIdstringrequired

The identifier of the subscription. The value can be an internal UUID or an external reference identifier with the rid_ prefix.

Responses

200

The roaming cost-control setting, including an explicit unsupported state.

application/json

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.

currencystring

The 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.

limitMinorintegerint64>= 0

The configured cost limit in minor currency units. It is present only when state is ACTIVE.

observedAtstringdate-timerequired

The time when the platform read this setting.

providerstringrequired

The network provider that supplies the setting.

stateenum<string>required

The availability and configuration state of roaming cost control.

values

  • ACTIVE
  • NOT_CONFIGURED
  • UNSUPPORTED
  • UNAVAILABLE
subscriptionIdstringrequired

The subscription that owns this roaming cost-control setting.

400

The request was malformed or invalid.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

401

Authentication is required to access this resource.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

403

Access to this resource is forbidden.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

404

The requested resource was not found.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

500

An unexpected error occurred on the server.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

Auth required

Send

  • X-Api-Key + Bearer JWT
GET /subscriptions/{subscriptionId}/roaming-cost-control
curl https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/roaming-cost-control \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
fetch('https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/roaming-cost-control', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  }
})
requests.get(
    "https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/roaming-cost-control",
    headers={
      "X-Api-Key": "YOUR_API_KEY",
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
)
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/roaming-cost-control"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
{
  "currency": "USD",
  "limitMinor": 52000,
  "observedAt": "2024-01-15T10:30:00Z",
  "provider": "telia",
  "state": "ACTIVE",
  "subscriptionId": "a47ac10b-58cc-4372-a567-0e02b2c3d479"
}
{
  "code": "bad_request",
  "details": [
    {
      "code": "invalid_email",
      "message": "Email format is invalid.",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields.",
  "message": "The request body is invalid."
}
{
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header.",
  "message": "Authentication is required to access this resource."
}
{
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions.",
  "message": "You do not have permission to perform this action."
}
{
  "code": "not_found",
  "hint": "Verify the customerId and try again.",
  "message": "The requested customer could not be found."
}
{
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support.",
  "message": "An unexpected error occurred on the server."
}

Change subscription service address

PUT/subscriptions/{subscriptionId}/service-address

Change 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

subscriptionIdstringrequired

The identifier of the subscription. The value can be an internal UUID or an external reference identifier with the rid_ prefix.

Headers

X-Idempotency-Keystringmax length 256

A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request.

Modified requests with the same idempotency keys are rejected with a 409 Conflict status code.

BodyChangeSubscriptionServiceAddressRequestrequiredapplication/json

Request to change the address where a subscription is served.

addressobjectrequired

The 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
attentionstringpersonal data

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

citystringrequired

The city or municipality of the address.

countrystringpattern ^[A-Z]{2}$required

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

regionstring

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

statestring

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

streetstringpersonal data

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

street1stringpersonal datadeprecatedrequired

Deprecated. Use street instead.

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

street2stringpersonal data

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

zipstringpersonal datarequired

The 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.

Responses

200

The 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.

objectSubscription

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

activatedAtstringdate-time

The date and time when the subscription was activated. Absent until the subscription has been activated.

barReasonsarray of BarReason

The 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.

cancelledAtstringdate-time

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

createdAtstringdate-timerequired

The date and time when the subscription was created.

customerobjectrequired

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

Show child attributes
customerIdstringrequired

The unique identifier for the customer. Use it with the customer endpoints to fetch full details.

namestringrequired

The customer's display name — the company name for business customers or the person's full name for consumers.

displaystringrequired

Human-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.

extensionsobject with string keys

Additional subscription extensions fields provided for custom subscription types.

Show child attributes
*string
metadataobject with string keys

A 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
*string
msisdnstringphonepersonal datarequired

The 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.

pendingMsisdnobjectpersonal data

A 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 datarequired

The phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.

scheduledAtstringdate

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

pendingProductOfferingobject

A 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
productobjectrequired

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
groupobject

A product group organizes related product offerings.

Show child attributes
imageUrlstringuri

URL to the image representing the product offering.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The 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
productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

scheduledAtstringdaterequired

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

pendingStatusobject

A 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
scheduledAtstringdate

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

statusenum<string>required

Current 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

  • PENDING
  • ACTIVATED
  • BLOCKED
  • CANCELLED
  • PAUSED
  • SUSPENDED
portingobject

Number porting information for subscriptions, indicating scheduled number transfers.

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

Show child attributes
directionenum<string>required

The 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

  • INBOUND
  • OUTBOUND
msisdnstringpersonal datarequired

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

scheduledAtstringdaterequired

The date when the number porting is scheduled to occur.

statusenum<string>required

Current 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

  • PENDING
  • IN_PROGRESS
  • SCHEDULED
  • COMPLETED
  • FAILED
productOfferingobject

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
groupobject

A product group organizes related product offerings.

Show child attributes
categoryenum<string>required

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

Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.

Categories are grouped by their product type:

SUBSCRIPTION categories:

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXED - Cellular subscription at a fixed location
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
  • PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming
  • PRODUCT_CATEGORY_VANITY_NUMBER_FORWARD - Vanity number that forwards calls
  • PRODUCT_CATEGORY_VANITY_NUMBER_CELL - Vanity number on a cellular subscription

SUBSCRIPTION_ADDON categories:

  • PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
  • PRODUCT_CATEGORY_ABROAD - International roaming addon
  • PRODUCT_CATEGORY_ABROAD_EXTRA_DATA - Additional data package for roaming
  • PRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EU - Data package for use outside the EU
  • PRODUCT_CATEGORY_NETWORK_EXTENSIONS - Network feature addon
  • PRODUCT_CATEGORY_VANITY_NUMBER - Vanity number addon

EXTERNAL_PRODUCT categories:

  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

SIM_CARD categories:

  • PRODUCT_CATEGORY_SIM_CARD - Physical SIM or eSIM replacement for an existing subscription

LICENSE categories (PBX):

  • PRODUCT_CATEGORY_PBX_USER_LEVEL - Level of a PBX user license
  • PRODUCT_CATEGORY_PBX_NUMBER - PBX phone number
  • PRODUCT_CATEGORY_PBX_MOBILE_NUMBER - PBX mobile number
  • PRODUCT_CATEGORY_PBX_LANDLINE_FORWARD - Forward from a landline number
  • PRODUCT_CATEGORY_PBX_SOFTPHONE - Softphone
  • PRODUCT_CATEGORY_PBX_STATISTICS - Call statistics
  • PRODUCT_CATEGORY_PBX_CALL_RECORDING - Call recording
  • PRODUCT_CATEGORY_PBX_VOICEMAIL - Voicemail
  • PRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERS - Queue capacity
  • PRODUCT_CATEGORY_PBX_ROUTE_IVR, PRODUCT_CATEGORY_PBX_ROUTE_GROUP, PRODUCT_CATEGORY_PBX_ROUTE_QUEUE - Call routes
  • PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVR, PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUP, PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUE, PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAIL - Call route features

Other categories:

  • PRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNER, PRODUCT_CATEGORY_INTERNATIONAL_NUMBER

A caller must tolerate new values.

values

  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL
  • PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
  • PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
  • PRODUCT_CATEGORY_SUBSCRIPTION_M2M
  • PRODUCT_CATEGORY_TRAVEL_ESIM
  • PRODUCT_CATEGORY_SUBSCRIPTION_CELL_FIXED
  • PRODUCT_CATEGORY_VANITY_NUMBER_FORWARD
  • PRODUCT_CATEGORY_VANITY_NUMBER_CELL
  • PRODUCT_CATEGORY_EXTRA_DATA
  • PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
  • PRODUCT_CATEGORY_ABROAD
  • PRODUCT_CATEGORY_ABROAD_EXTRA_DATA
  • PRODUCT_CATEGORY_DATA_PACKAGE_OUTSIDE_EU
  • PRODUCT_CATEGORY_NETWORK_EXTENSIONS
  • PRODUCT_CATEGORY_VANITY_NUMBER
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT
  • PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
  • PRODUCT_CATEGORY_SIM_CARD
  • PRODUCT_CATEGORY_PBX_USER_LEVEL
  • PRODUCT_CATEGORY_PBX_NUMBER
  • PRODUCT_CATEGORY_PBX_MOBILE_NUMBER
  • PRODUCT_CATEGORY_PBX_LANDLINE_FORWARD
  • PRODUCT_CATEGORY_PBX_SOFTPHONE
  • PRODUCT_CATEGORY_PBX_STATISTICS
  • PRODUCT_CATEGORY_PBX_CALL_RECORDING
  • PRODUCT_CATEGORY_PBX_VOICEMAIL
  • PRODUCT_CATEGORY_PBX_QUEUE_MAX_WAITING_CALLERS
  • PRODUCT_CATEGORY_PBX_ROUTE_IVR
  • PRODUCT_CATEGORY_PBX_ROUTE_GROUP
  • PRODUCT_CATEGORY_PBX_ROUTE_QUEUE
  • PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_IVR
  • PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_GROUP
  • PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_QUEUE
  • PRODUCT_CATEGORY_PBX_ROUTE_FEATURE_VOICEMAIL
  • PRODUCT_CATEGORY_SUBSCRIPTION_MEX_PARTNER
  • PRODUCT_CATEGORY_INTERNATIONAL_NUMBER
descriptionstring

Description of the product group in the requested locale.

internalDescriptionstring

Internal description of the product group for operational use only.

namestringrequired

Name of the product group in the requested locale.

productOfferingGroupIdstringrequired

Unique identifier for the product group.

imageUrlstringuri

URL to the image representing the product offering.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The 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
billingCycleobject

How often a recurring price is charged.

Show child attributes
bindingContractobject

A 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
currencystringrequired

The ISO 4217 currency code the price is expressed in (e.g., "USD").

currencyOptionsMinorobject with string keys

Per-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
customUpfrontPaymentobject

Billing 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
includesTaxboolean

True when the configured price includes its tax. The tax is then a part of netPriceMinor rather than an amount on top of it.

netPriceMinorintegerint64

The 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.

priceTypeenum<string>required

How 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_TIME
  • RECURRING
standardDiscountobject

A 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
productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

referenceIdstringmax length 255

A reference identifier provided by API clients to identify this subscription in their own systems. Must be unique per tenant. Use this field to look up subscriptions by your external identifier or to create/retrieve subscriptions during order creation.

serviceAddressobject

The 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
addressobjectrequired

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes
attentionstringpersonal data

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

citystringrequired

The city or municipality of the address.

countrystringpattern ^[A-Z]{2}$required

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

regionstring

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

statestring

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

streetstringpersonal data

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

street1stringpersonal datadeprecatedrequired

Deprecated. Use street instead.

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

street2stringpersonal data

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

zipstringpersonal datarequired

The 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.

sourceenum<string>required

The 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

  • SUBSCRIPTION
  • CUSTOMER_BILLING
simobjectrequired

SIM card information for the subscription. Sensitive details like PUK require separate API calls.

Use dedicated SIM API endpoints with proper authorization to access sensitive information such as PUK.

Show child attributes
esimbooleanrequired

Whether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.

iccidstringpersonal data

Integrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.

imeistringpersonal data

International Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.

Only applicable for eSIM.

statusenum<string>required

Current 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

  • PENDING
  • ACTIVATED
  • BLOCKED
  • CANCELLED
  • PAUSED
  • SUSPENDED
subscriberobject

The person who uses the service on a subscription, as distinct from the customer who pays for it.

Show child attributes
addressobjectdeprecated

Deprecated. 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
attentionstringpersonal data

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

citystringrequired

The city or municipality of the address.

countrystringpattern ^[A-Z]{2}$required

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

regionstring

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

statestring

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

streetstringpersonal data

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

street1stringpersonal datadeprecatedrequired

Deprecated. Use street instead.

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

street2stringpersonal data

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

zipstringpersonal datarequired

The 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.

createdAtstringdate-time

Date and time when the subscriber was created.

emailstringemailpersonal data

The subscriber's email address, if one has been provided.

namestringrequired

The subscriber's full name.

subscriberIdstringrequired

The unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.

updatedAtstringdate-time

Date and time when the subscriber was last updated.

subscriptionIdstringrequired

The unique identifier for the subscription.

typestringrequired

The 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.

updatedAtstringdate-timerequired

The date and time when the subscription was last updated.

400

The request was malformed or invalid.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

401

Authentication is required to access this resource.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

403

Access to this resource is forbidden.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

404

The requested resource was not found.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

409

The request conflicts with the current state of the resource.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

412

A precondition for this request was not met.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

500

An unexpected error occurred on the server.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

Auth required

Send

  • X-Api-Key + Bearer JWT
PUT /subscriptions/{subscriptionId}/service-address
curl https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/service-address \
  --request PUT \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "address": {
    "attention": "John Doe",
    "city": "Natick",
    "country": "US",
    "region": "Ontario",
    "state": "CA",
    "street": "500 S Main St",
    "street1": "string",
    "street2": "Apt 1",
    "zip": "01701"
  }
}'
fetch('https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/service-address', {
  method: 'PUT',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    address: {
      attention: 'John Doe',
      city: 'Natick',
      country: 'US',
      region: 'Ontario',
      state: 'CA',
      street: '500 S Main St',
      street1: 'string',
      street2: 'Apt 1',
      zip: '01701'
    }
  })
})
requests.put(
    "https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/service-address",
    headers={
      "X-Api-Key": "YOUR_API_KEY",
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json"
    },
    json={
      "address": {
        "attention": "John Doe",
        "city": "Natick",
        "country": "US",
        "region": "Ontario",
        "state": "CA",
        "street": "500 S Main St",
        "street1": "string",
        "street2": "Apt 1",
        "zip": "01701"
      }
    }
)
package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/service-address"

	payload := strings.NewReader(`{
  "address": {
    "attention": "John Doe",
    "city": "Natick",
    "country": "US",
    "region": "Ontario",
    "state": "CA",
    "street": "500 S Main St",
    "street1": "string",
    "street2": "Apt 1",
    "zip": "01701"
  }
}`)

	req, _ := http.NewRequest("PUT", requestUrl, payload)

	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	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))

}
{
  "activatedAt": "2024-01-15T10:30:00Z",
  "barReasons": [
    "MISSING_PAYMENT"
  ],
  "cancelledAt": "2024-06-30T00:00:00Z",
  "createdAt": "2024-01-10T08:00:00Z",
  "customer": {
    "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "name": "John Doe"
  },
  "display": "(555) 123-4567",
  "extensions": {
    "propertyName": "string"
  },
  "metadata": {
    "propertyName": "string"
  },
  "msisdn": "+15551234567",
  "pendingMsisdn": {
    "msisdn": "+15559876543",
    "scheduledAt": "2024-02-01"
  },
  "pendingProductOffering": {
    "product": {
      "group": {
        "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
        "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
        "internalDescription": "Core mobile offerings targeting consumer and business segments",
        "name": "Mobile Plans",
        "productOfferingGroupId": "mobile-plans"
      },
      "imageUrl": "https://cdn.example.com/images/mobile-basic.png",
      "name": "Mobile Unlimited",
      "price": {
        "billingCycle": {
          "interval": 1,
          "period": "MONTHLY"
        },
        "bindingContract": {
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "invoicingDescription": "Campaign discount",
            "source": "STANDARD"
          },
          "duration": {
            "unit": "MONTHS",
            "value": 3
          }
        },
        "currency": "USD",
        "currencyOptionsMinor": {
          "propertyName": 1
        },
        "customUpfrontPayment": {
          "billingCycles": 3,
          "discount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "invoicingDescription": "Campaign discount",
            "source": "STANDARD"
          }
        },
        "includesTax": false,
        "netPriceMinor": 2999,
        "priceType": "ONE_TIME",
        "standardDiscount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "invoicingDescription": "Campaign discount",
          "source": "STANDARD"
        }
      },
      "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
    },
    "scheduledAt": "2024-02-01"
  },
  "pendingStatus": {
    "scheduledAt": "2024-02-01",
    "status": "PENDING"
  },
  "porting": {
    "direction": "INBOUND",
    "msisdn": "+15551234567",
    "scheduledAt": "2024-02-01",
    "status": "PENDING"
  },
  "productOffering": {
    "group": {
      "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
      "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
      "internalDescription": "Core mobile offerings targeting consumer and business segments",
      "name": "Mobile Plans",
      "productOfferingGroupId": "mobile-plans"
    },
    "imageUrl": "https://cdn.example.com/images/mobile-basic.png",
    "name": "Mobile Unlimited",
    "price": {
      "billingCycle": {
        "interval": 1,
        "period": "MONTHLY"
      },
      "bindingContract": {
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "invoicingDescription": "Campaign discount",
          "source": "STANDARD"
        },
        "duration": {
          "unit": "MONTHS",
          "value": 3
        }
      },
      "currency": "USD",
      "currencyOptionsMinor": {
        "propertyName": 1
      },
      "customUpfrontPayment": {
        "billingCycles": 3,
        "discount": {
          "amountMinor": 500,
          "duration": {
            "unit": "MONTHS",
            "value": 3
          },
          "invoicingDescription": "Campaign discount",
          "source": "STANDARD"
        }
      },
      "includesTax": false,
      "netPriceMinor": 2999,
      "priceType": "ONE_TIME",
      "standardDiscount": {
        "amountMinor": 500,
        "duration": {
          "unit": "MONTHS",
          "value": 3
        },
        "invoicingDescription": "Campaign discount",
        "source": "STANDARD"
      }
    },
    "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  },
  "referenceId": "crm-subscription-12345",
  "serviceAddress": {
    "address": {
      "attention": "John Doe",
      "city": "Natick",
      "country": "US",
      "region": "Ontario",
      "state": "CA",
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "zip": "01701"
    },
    "source": "SUBSCRIPTION"
  },
  "sim": {
    "esim": true,
    "iccid": "8901240197155182976",
    "imei": "356938035643809"
  },
  "status": "PENDING",
  "subscriber": {
    "address": {
      "attention": "John Doe",
      "city": "Natick",
      "country": "US",
      "region": "Ontario",
      "state": "CA",
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "zip": "01701"
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "email": "john.doe@example.com",
    "name": "John Doe",
    "subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
    "updatedAt": "2024-01-20T14:45:00Z"
  },
  "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
  "type": "CELL",
  "updatedAt": "2024-01-15T10:30:00Z"
}
{
  "code": "bad_request",
  "details": [
    {
      "code": "invalid_email",
      "message": "Email format is invalid.",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields.",
  "message": "The request body is invalid."
}
{
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header.",
  "message": "Authentication is required to access this resource."
}
{
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions.",
  "message": "You do not have permission to perform this action."
}
{
  "code": "not_found",
  "hint": "Verify the customerId and try again.",
  "message": "The requested customer could not be found."
}
{
  "code": "conflict",
  "hint": "Reload the resource to get its latest state before retrying.",
  "message": "The request conflicts with the current state of the resource."
}
{
  "code": "precondition_failed",
  "hint": "Fetch the current resource and retry with an up-to-date precondition.",
  "message": "A precondition given in the request headers was not met."
}
{
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support.",
  "message": "An unexpected error occurred on the server."
}

Get the US port-out PIN

GET/subscriptions/{subscriptionId}/us-port-out-pin

Get 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. A new number in its port-out protection period has portOutProtection, which gives the first day that a new carrier can port out the number.

Only US brands support this operation. Other brands return 501 Not Implemented.

Path parameters

subscriptionIdstringrequired

The 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

200

The port-out state of the subscription.

application/json

The port-out state of the subscription.

objectUSPortOutPinState

The US port-out state of a subscription.

activePinobject

The 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
expiresAtstringdate-timerequired

When the PIN stops working.

pinstringpersonal datarequired

The 6-digit port-out PIN. Treat it as a credential.

portOutProtectionobject

Present while the number is in its port-out protection period after activation. The subscription can get a PIN in this period, but a port-out request with the PIN fails.

The port-out protection of a new number. During the protection period, a new carrier cannot port out the number, even with a valid PIN. Support can open the number for port-out before the period ends.

Show child attributes
portableFromstringdate

The first day that a new carrier can port out the number. It is absent when the subscription has no activation date. Then only support can open the number for port-out.

portablebooleanrequired

False when the subscription cannot port out, for example during a binding period. The PIN is then hidden, and no PIN can be generated.

400

The request was malformed or invalid.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

401

Authentication is required to access this resource.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

403

Access to this resource is forbidden.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

404

The requested resource was not found.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

500

An unexpected error occurred on the server.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

501

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.

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.

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

Auth required

Send

  • X-Api-Key + Bearer JWT
GET /subscriptions/{subscriptionId}/us-port-out-pin
curl https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/us-port-out-pin \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
fetch('https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/us-port-out-pin', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  }
})
requests.get(
    "https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/us-port-out-pin",
    headers={
      "X-Api-Key": "YOUR_API_KEY",
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
)
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/us-port-out-pin"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
{
  "activePin": {
    "expiresAt": "2024-01-15T10:30:00Z",
    "pin": "string"
  },
  "portOutProtection": {
    "portableFrom": "2026-10-28"
  },
  "portable": true
}
{
  "code": "bad_request",
  "details": [
    {
      "code": "invalid_email",
      "message": "Email format is invalid.",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields.",
  "message": "The request body is invalid."
}
{
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header.",
  "message": "Authentication is required to access this resource."
}
{
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions.",
  "message": "You do not have permission to perform this action."
}
{
  "code": "not_found",
  "hint": "Verify the customerId and try again.",
  "message": "The requested customer could not be found."
}
{
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support.",
  "message": "An unexpected error occurred on the server."
}
{
  "code": "not_implemented",
  "hint": "The network behind this brand cannot answer this request.",
  "message": "This endpoint is not available in this environment."
}

Generate a US port-out PIN

POST/subscriptions/{subscriptionId}/us-port-out-pin

Generate 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

subscriptionIdstringrequired

The 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

200

The new PIN.

application/json

The new PIN.

objectUSPortOutPin

A PIN that a subscriber gives to a new carrier to move a US number away.

expiresAtstringdate-timerequired

When the PIN stops working.

pinstringpersonal datarequired

The 6-digit port-out PIN. Treat it as a credential.

400

The request was malformed or invalid.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

401

Authentication is required to access this resource.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

403

Access to this resource is forbidden.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

404

The requested resource was not found.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

412

A precondition for this request was not met.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

500

An unexpected error occurred on the server.

application/json

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

501

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.

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.

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.

codestringdeprecatedrequired

Deprecated. 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.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names 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.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The 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.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names 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.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies 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.

Auth required

Send

  • X-Api-Key + Bearer JWT
POST /subscriptions/{subscriptionId}/us-port-out-pin
curl https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/us-port-out-pin \
  --request POST \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
fetch('https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/us-port-out-pin', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  }
})
requests.post(
    "https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/us-port-out-pin",
    headers={
      "X-Api-Key": "YOUR_API_KEY",
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
)
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/end-user/subscriptions/SUBSCRIPTION_ID/us-port-out-pin"

	req, _ := http.NewRequest("POST", requestUrl, nil)

	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
{
  "expiresAt": "2024-01-15T10:30:00Z",
  "pin": "string"
}
{
  "code": "bad_request",
  "details": [
    {
      "code": "invalid_email",
      "message": "Email format is invalid.",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields.",
  "message": "The request body is invalid."
}
{
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header.",
  "message": "Authentication is required to access this resource."
}
{
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions.",
  "message": "You do not have permission to perform this action."
}
{
  "code": "not_found",
  "hint": "Verify the customerId and try again.",
  "message": "The requested customer could not be found."
}
{
  "code": "precondition_failed",
  "hint": "Fetch the current resource and retry with an up-to-date precondition.",
  "message": "A precondition given in the request headers was not met."
}
{
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support.",
  "message": "An unexpected error occurred on the server."
}
{
  "code": "not_implemented",
  "hint": "The network behind this brand cannot answer this request.",
  "message": "This endpoint is not available in this environment."
}