Subscription Actions
Start actions on subscriptions, and follow the progress of each action.
List subscription actions
/subscription-actionsList the actions of the subscriptions that you can access, newest scheduled first. The list does not include a removed plan that never started.
Query parameters
limitinteger>= 1<= 1000default 100The maximum number of items to return.
cursorstringOpaque pagination token from a previous response's nextCursor.
customer Idarray of stringFilter by customer IDs. When omitted, include all customers visible to the caller.
subscription IdstringOptionally restrict results to one subscription of the selected customers.
Responses
200Subscription actions retrieved successfully
application/json
Subscription actions retrieved successfully
Subscription actions retrieved successfully
object
itemsarray of SubscriptionActionrequiredShow child attributes
action IdstringrequiredUnique identifier for this action.
subscription IdstringrequiredSubscription affected by this action.
customer IdstringrequiredCustomer that owns the subscription.
typeenum<string>requiredThe kind of recorded subscription action. The list includes legacy values that can occur in historical records. A caller must tolerate new values.
values
UNKNOWNCREATECREATE_WITH_PORT_INCHANGE_PRODUCTCHANGE_SIM_CARDCHANGE_VANITY_NUMBER_FORWARDCHANGE_MSISDNCHANGE_MSISDN_WITH_PORT_INGET_NEW_MSISDNCHANGE_RATE_PLANPAUSESUSPENDBARRESTORECANCELRESET_NETWORKENABLE_ADDONCANCEL_ADDONCHANGE_ADDON_PRODUCTEXPIRE_ADDONMOVED_FROM_ANOTHER_CUSTOMERCANCEL_DEVICE_LOCATIONRESET_VOICEMAIL_PASSWORDUPDATE_ROAMING_LIMITENABLE_VOWIFIRESEND_ESIM_QR_CODERECONNECTPORT_BACKPORT_OUTCHANGE_E911_ADDRESSTOPUPMOVE_TO_ANOTHER_CUSTOMEROPEN_FOR_OUTPORTINGADD_CONTRACT_PERIODLEGACY_UPDATE
statusenum<string>requiredThe recorded execution state of an action. UNKNOWN means that the state is not known. PENDING waits for execution. RUNNING is in progress. SUCCESS and FAILURE describe the result of execution. A caller must tolerate new values.
values
UNKNOWNPENDINGRUNNINGSUCCESSFAILURE
schedule Modeenum<string>requiredHow the action is scheduled. UNKNOWN means that the schedule mode is not known. IMMEDIATE starts execution at once. AT_SPECIFIED_DATE and AT_SPECIFIED_DATE_TIME target a specified date or time. ON_DEMAND starts execution on demand. A caller must tolerate new values.
values
UNKNOWNIMMEDIATEAT_SPECIFIED_DATEAT_SPECIFIED_DATE_TIMEON_DEMAND
apply Atstringdate-timerequiredWhen the operation is scheduled to take effect.
execution Started Atstringdate-timeWhen execution began, if it has started.
execution Finished Atstringdate-timeWhen execution ended, if it has finished.
failure ReasonstringNames the condition that failed the action, in lower snake_case. The values are the same as
the reason of an error response. For example, invalid_e911_address means that the network
operator refused the service address as an E911 address. Only an action with the status
FAILURE has this field, and such an action can also fail without a reason. Your client must
accept a reason that it does not know.
created Atstringdate-timerequiredWhen the action was created.
updated Atstringdate-timerequiredWhen the action was most recently updated.
paginationobjectrequiredCursor-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
next Cursorstring | nullrequiredOpaque token for fetching the next page. Null when no more results.
400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
external CodestringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
external SourcestringThe third party that reported the failure.
internal CodestringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
trace IdstringIdentifies 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.
span IdstringThe span within the trace that failed.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
external CodestringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
external SourcestringThe third party that reported the failure.
internal CodestringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
trace IdstringIdentifies 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.
span IdstringThe span within the trace that failed.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
external CodestringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
external SourcestringThe third party that reported the failure.
internal CodestringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
trace IdstringIdentifies 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.
span IdstringThe span within the trace that failed.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
external CodestringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
external SourcestringThe third party that reported the failure.
internal CodestringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
trace IdstringIdentifies 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.
span IdstringThe span within the trace that failed.
Auth required
Send one of
X-Api-KeyBearer JWT+X-Api-Key
The API key is always required; the bearer token is optional.
curl https://apiv2.example.com/api/v2/subscription-actions \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'X-Api-Key: YOUR_API_KEY'fetch('https://apiv2.example.com/api/v2/subscription-actions', {
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-Api-Key': 'YOUR_API_KEY'
}
})requests.get(
"https://apiv2.example.com/api/v2/subscription-actions",
headers={
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"X-Api-Key": "YOUR_API_KEY"
}
)package main
import (
"fmt"
"io"
"net/http"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/subscription-actions"
req, _ := http.NewRequest("GET", requestUrl, nil)
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"items": [
{
"actionId": "string",
"subscriptionId": "string",
"customerId": "string",
"type": "ENABLE_VOWIFI",
"status": "PENDING",
"scheduleMode": "ON_DEMAND",
"applyAt": "2024-01-15T10:30:00Z",
"executionStartedAt": "2024-01-15T10:30:00Z",
"executionFinishedAt": "2024-01-15T10:30:00Z",
"failureReason": "invalid_e911_address",
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
}
],
"pagination": {
"nextCursor": "eyJvZmZzZXQiOjEwMH0"
}
}{
"message": "The request body is invalid.",
"code": "bad_request",
"details": [
{
"message": "Email format is invalid.",
"code": "invalid_email",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields."
}{
"message": "Authentication is required to access this resource.",
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header."
}{
"message": "You do not have permission to perform this action.",
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions."
}{
"message": "An unexpected error occurred on the server.",
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support."
}Get subscription action
/subscription-actions/{actionId}Get the execution state of an action. An action of a subscription that you cannot access and a missing action both return not found.
Path parameters
action IdstringrequiredUnique identifier of the action.
Responses
200Subscription action retrieved successfully
application/json
Subscription action retrieved successfully
Subscription action retrieved successfully
objectSubscriptionAction
A subscription operation and its execution state. Action payloads and internal task details are not exposed.
action IdstringrequiredUnique identifier for this action.
subscription IdstringrequiredSubscription affected by this action.
customer IdstringrequiredCustomer that owns the subscription.
typeenum<string>requiredThe kind of recorded subscription action. The list includes legacy values that can occur in historical records. A caller must tolerate new values.
values
UNKNOWNCREATECREATE_WITH_PORT_INCHANGE_PRODUCTCHANGE_SIM_CARDCHANGE_VANITY_NUMBER_FORWARDCHANGE_MSISDNCHANGE_MSISDN_WITH_PORT_INGET_NEW_MSISDNCHANGE_RATE_PLANPAUSESUSPENDBARRESTORECANCELRESET_NETWORKENABLE_ADDONCANCEL_ADDONCHANGE_ADDON_PRODUCTEXPIRE_ADDONMOVED_FROM_ANOTHER_CUSTOMERCANCEL_DEVICE_LOCATIONRESET_VOICEMAIL_PASSWORDUPDATE_ROAMING_LIMITENABLE_VOWIFIRESEND_ESIM_QR_CODERECONNECTPORT_BACKPORT_OUTCHANGE_E911_ADDRESSTOPUPMOVE_TO_ANOTHER_CUSTOMEROPEN_FOR_OUTPORTINGADD_CONTRACT_PERIODLEGACY_UPDATE
statusenum<string>requiredThe recorded execution state of an action. UNKNOWN means that the state is not known. PENDING waits for execution. RUNNING is in progress. SUCCESS and FAILURE describe the result of execution. A caller must tolerate new values.
values
UNKNOWNPENDINGRUNNINGSUCCESSFAILURE
schedule Modeenum<string>requiredHow the action is scheduled. UNKNOWN means that the schedule mode is not known. IMMEDIATE starts execution at once. AT_SPECIFIED_DATE and AT_SPECIFIED_DATE_TIME target a specified date or time. ON_DEMAND starts execution on demand. A caller must tolerate new values.
values
UNKNOWNIMMEDIATEAT_SPECIFIED_DATEAT_SPECIFIED_DATE_TIMEON_DEMAND
apply Atstringdate-timerequiredWhen the operation is scheduled to take effect.
execution Started Atstringdate-timeWhen execution began, if it has started.
execution Finished Atstringdate-timeWhen execution ended, if it has finished.
failure ReasonstringNames the condition that failed the action, in lower snake_case. The values are the same as
the reason of an error response. For example, invalid_e911_address means that the network
operator refused the service address as an E911 address. Only an action with the status
FAILURE has this field, and such an action can also fail without a reason. Your client must
accept a reason that it does not know.
created Atstringdate-timerequiredWhen the action was created.
updated Atstringdate-timerequiredWhen the action was most recently updated.
400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
external CodestringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
external SourcestringThe third party that reported the failure.
internal CodestringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
trace IdstringIdentifies 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.
span IdstringThe span within the trace that failed.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
external CodestringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
external SourcestringThe third party that reported the failure.
internal CodestringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
trace IdstringIdentifies 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.
span IdstringThe span within the trace that failed.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
external CodestringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
external SourcestringThe third party that reported the failure.
internal CodestringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
trace IdstringIdentifies 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.
span IdstringThe span within the trace that failed.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
external CodestringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
external SourcestringThe third party that reported the failure.
internal CodestringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
trace IdstringIdentifies 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.
span IdstringThe span within the trace that failed.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
external CodestringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
external SourcestringThe third party that reported the failure.
internal CodestringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
trace IdstringIdentifies 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.
span IdstringThe span within the trace that failed.
Auth required
Send one of
X-Api-KeyBearer JWT+X-Api-Key
The API key is always required; the bearer token is optional.
curl https://apiv2.example.com/api/v2/subscription-actions/ACTION_ID \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'X-Api-Key: YOUR_API_KEY'fetch('https://apiv2.example.com/api/v2/subscription-actions/ACTION_ID', {
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-Api-Key': 'YOUR_API_KEY'
}
})requests.get(
"https://apiv2.example.com/api/v2/subscription-actions/ACTION_ID",
headers={
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"X-Api-Key": "YOUR_API_KEY"
}
)package main
import (
"fmt"
"io"
"net/http"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/subscription-actions/ACTION_ID"
req, _ := http.NewRequest("GET", requestUrl, nil)
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"actionId": "string",
"subscriptionId": "string",
"customerId": "string",
"type": "ENABLE_VOWIFI",
"status": "PENDING",
"scheduleMode": "ON_DEMAND",
"applyAt": "2024-01-15T10:30:00Z",
"executionStartedAt": "2024-01-15T10:30:00Z",
"executionFinishedAt": "2024-01-15T10:30:00Z",
"failureReason": "invalid_e911_address",
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
}{
"message": "The request body is invalid.",
"code": "bad_request",
"details": [
{
"message": "Email format is invalid.",
"code": "invalid_email",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields."
}{
"message": "Authentication is required to access this resource.",
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header."
}{
"message": "You do not have permission to perform this action.",
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions."
}{
"message": "The requested customer could not be found.",
"code": "not_found",
"hint": "Verify the customerId and try again."
}{
"message": "An unexpected error occurred on the server.",
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support."
}List the action options of a subscription
/subscriptions/{subscriptionId}/action-optionsList the actions that the caller can start on one subscription with startSubscriptionAction.
Read it before you show the buttons for these actions.
- An action is absent when the brand or the network operator does not offer it. Do not show it.
- An action has
availablefalse when the state of the subscription refuses it now. ThenrefusalReasonis thereasonthatstartSubscriptionActiongives. - An available action gives the date that it gets when the request names no date.
The End-User API applies the rules of the manager portal. The Platform API applies the rules of the admin portal.
Path parameters
subscription IdstringrequiredThe identifier of the subscription. May be the entity's internal UUID or an external reference identifier.
Reference identifiers MUST be prefixed with rid_ (e.g., rid_crm-subscription-12345) so the API
can distinguish them from internal UUIDs. The prefix is stripped before lookup.
Responses
200The action options of the subscription.
application/json
The action options of the subscription.
The action options of the subscription.
object
itemsarray of SubscriptionActionOptionrequiredShow child attributes
typeenum<string>requiredThe type to send to startSubscriptionAction. A caller must tolerate new values.
values
PAUSERESTORECANCELBLOCK_SIMRESET_NETWORKACTIVATE
availablebooleanrequiredTrue when startSubscriptionAction accepts the action now. False when the state of the
subscription refuses it now. Then refusalReason gives the cause.
refusal ReasonstringThe reason of the error that startSubscriptionAction gives for the action now. It is
present only when available is false.
schedule Modeenum<string>How the action is scheduled. UNKNOWN means that the schedule mode is not known. IMMEDIATE starts execution at once. AT_SPECIFIED_DATE and AT_SPECIFIED_DATE_TIME target a specified date or time. ON_DEMAND starts execution on demand. A caller must tolerate new values.
values
UNKNOWNIMMEDIATEAT_SPECIFIED_DATEAT_SPECIFIED_DATE_TIMEON_DEMAND
effective DatestringdateThe date that the action gets when the request names no date. It is absent when the action is refused, or when the request must name the date.
400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
external CodestringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
external SourcestringThe third party that reported the failure.
internal CodestringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
trace IdstringIdentifies 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.
span IdstringThe span within the trace that failed.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
external CodestringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
external SourcestringThe third party that reported the failure.
internal CodestringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
trace IdstringIdentifies 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.
span IdstringThe span within the trace that failed.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
external CodestringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
external SourcestringThe third party that reported the failure.
internal CodestringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
trace IdstringIdentifies 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.
span IdstringThe span within the trace that failed.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
external CodestringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
external SourcestringThe third party that reported the failure.
internal CodestringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
trace IdstringIdentifies 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.
span IdstringThe span within the trace that failed.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
external CodestringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
external SourcestringThe third party that reported the failure.
internal CodestringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
trace IdstringIdentifies 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.
span IdstringThe span within the trace that failed.
Auth required
Send one of
X-Api-KeyBearer JWT+X-Api-Key
The API key is always required; the bearer token is optional.
curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/action-options \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'X-Api-Key: YOUR_API_KEY'fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/action-options', {
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-Api-Key': 'YOUR_API_KEY'
}
})requests.get(
"https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/action-options",
headers={
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"X-Api-Key": "YOUR_API_KEY"
}
)package main
import (
"fmt"
"io"
"net/http"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/action-options"
req, _ := http.NewRequest("GET", requestUrl, nil)
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"items": [
{
"type": "CANCEL",
"available": false,
"refusalReason": "subscription_in_binding_period"
},
{
"type": "PAUSE",
"available": true,
"scheduleMode": "AT_SPECIFIED_DATE",
"effectiveDate": "2026-12-01"
},
{
"type": "BLOCK_SIM",
"available": true,
"scheduleMode": "IMMEDIATE",
"effectiveDate": "2026-11-30"
}
]
}{
"message": "The request body is invalid.",
"code": "bad_request",
"details": [
{
"message": "Email format is invalid.",
"code": "invalid_email",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields."
}{
"message": "Authentication is required to access this resource.",
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header."
}{
"message": "You do not have permission to perform this action.",
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions."
}{
"message": "The requested customer could not be found.",
"code": "not_found",
"hint": "Verify the customerId and try again."
}{
"message": "An unexpected error occurred on the server.",
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support."
}List the actions of a subscription
/subscriptions/{subscriptionId}/actionsList the actions of one subscription, with the newest scheduled action first. An action records a change to the subscription and the progress of that change. The list leaves out a removed action that never started.
Path parameters
subscription IdstringrequiredThe 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.
Query parameters
limitinteger>= 1<= 1000default 100The maximum number of items to return.
cursorstringOpaque pagination token from a previous response's nextCursor.
Responses
200The actions of the subscription.
application/json
The actions of the subscription.
The actions of the subscription.
object
itemsarray of SubscriptionActionrequiredShow child attributes
action IdstringrequiredUnique identifier for this action.
subscription IdstringrequiredSubscription affected by this action.
customer IdstringrequiredCustomer that owns the subscription.
typeenum<string>requiredThe kind of recorded subscription action. The list includes legacy values that can occur in historical records. A caller must tolerate new values.
values
UNKNOWNCREATECREATE_WITH_PORT_INCHANGE_PRODUCTCHANGE_SIM_CARDCHANGE_VANITY_NUMBER_FORWARDCHANGE_MSISDNCHANGE_MSISDN_WITH_PORT_INGET_NEW_MSISDNCHANGE_RATE_PLANPAUSESUSPENDBARRESTORECANCELRESET_NETWORKENABLE_ADDONCANCEL_ADDONCHANGE_ADDON_PRODUCTEXPIRE_ADDONMOVED_FROM_ANOTHER_CUSTOMERCANCEL_DEVICE_LOCATIONRESET_VOICEMAIL_PASSWORDUPDATE_ROAMING_LIMITENABLE_VOWIFIRESEND_ESIM_QR_CODERECONNECTPORT_BACKPORT_OUTCHANGE_E911_ADDRESSTOPUPMOVE_TO_ANOTHER_CUSTOMEROPEN_FOR_OUTPORTINGADD_CONTRACT_PERIODLEGACY_UPDATE
statusenum<string>requiredThe recorded execution state of an action. UNKNOWN means that the state is not known. PENDING waits for execution. RUNNING is in progress. SUCCESS and FAILURE describe the result of execution. A caller must tolerate new values.
values
UNKNOWNPENDINGRUNNINGSUCCESSFAILURE
schedule Modeenum<string>requiredHow the action is scheduled. UNKNOWN means that the schedule mode is not known. IMMEDIATE starts execution at once. AT_SPECIFIED_DATE and AT_SPECIFIED_DATE_TIME target a specified date or time. ON_DEMAND starts execution on demand. A caller must tolerate new values.
values
UNKNOWNIMMEDIATEAT_SPECIFIED_DATEAT_SPECIFIED_DATE_TIMEON_DEMAND
apply Atstringdate-timerequiredWhen the operation is scheduled to take effect.
execution Started Atstringdate-timeWhen execution began, if it has started.
execution Finished Atstringdate-timeWhen execution ended, if it has finished.
failure ReasonstringNames the condition that failed the action, in lower snake_case. The values are the same as
the reason of an error response. For example, invalid_e911_address means that the network
operator refused the service address as an E911 address. Only an action with the status
FAILURE has this field, and such an action can also fail without a reason. Your client must
accept a reason that it does not know.
created Atstringdate-timerequiredWhen the action was created.
updated Atstringdate-timerequiredWhen the action was most recently updated.
paginationobjectrequiredCursor-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
next Cursorstring | nullrequiredOpaque token for fetching the next page. Null when no more results.
400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
external CodestringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
external SourcestringThe third party that reported the failure.
internal CodestringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
trace IdstringIdentifies 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.
span IdstringThe span within the trace that failed.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
external CodestringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
external SourcestringThe third party that reported the failure.
internal CodestringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
trace IdstringIdentifies 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.
span IdstringThe span within the trace that failed.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
external CodestringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
external SourcestringThe third party that reported the failure.
internal CodestringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
trace IdstringIdentifies 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.
span IdstringThe span within the trace that failed.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
external CodestringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
external SourcestringThe third party that reported the failure.
internal CodestringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
trace IdstringIdentifies 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.
span IdstringThe span within the trace that failed.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
external CodestringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
external SourcestringThe third party that reported the failure.
internal CodestringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
trace IdstringIdentifies 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.
span IdstringThe span within the trace that failed.
Auth required
Send one of
X-Api-KeyBearer JWT+X-Api-Key
The API key is always required; the bearer token is optional.
curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/actions \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'X-Api-Key: YOUR_API_KEY'fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/actions', {
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-Api-Key': 'YOUR_API_KEY'
}
})requests.get(
"https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/actions",
headers={
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"X-Api-Key": "YOUR_API_KEY"
}
)package main
import (
"fmt"
"io"
"net/http"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/actions"
req, _ := http.NewRequest("GET", requestUrl, nil)
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"items": [
{
"actionId": "string",
"subscriptionId": "string",
"customerId": "string",
"type": "ENABLE_VOWIFI",
"status": "PENDING",
"scheduleMode": "ON_DEMAND",
"applyAt": "2024-01-15T10:30:00Z",
"executionStartedAt": "2024-01-15T10:30:00Z",
"executionFinishedAt": "2024-01-15T10:30:00Z",
"failureReason": "invalid_e911_address",
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
}
],
"pagination": {
"nextCursor": "eyJvZmZzZXQiOjEwMH0"
}
}{
"message": "The request body is invalid.",
"code": "bad_request",
"details": [
{
"message": "Email format is invalid.",
"code": "invalid_email",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields."
}{
"message": "Authentication is required to access this resource.",
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header."
}{
"message": "You do not have permission to perform this action.",
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions."
}{
"message": "The requested customer could not be found.",
"code": "not_found",
"hint": "Verify the customerId and try again."
}{
"message": "An unexpected error occurred on the server.",
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support."
}Start an action on a subscription
/subscriptions/{subscriptionId}/actionsStart an action on one subscription. The type of the body selects the action, and each type has
its own fields.
type | What it does |
|---|---|
PAUSE | Pauses the subscription. |
RESTORE | Restores a paused, suspended or blocked subscription. |
CANCEL | Cancels the subscription. |
BLOCK_SIM | Blocks the SIM card at once. The action has the type BAR. |
RESET_NETWORK | Resets the network services at the network operator. |
The response is the action. Read it again with getActionOfSubscription to follow its status.
A RESET_NETWORK that started or ended in the last 15 minutes is given again, and no second reset
starts. If the brand or the network operator does not offer a network reset, the 409 response
gives the reason subscription_action_not_offered.
Path parameters
subscription IdstringrequiredThe 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 256A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request.
Modified requests with the same idempotency keys are rejected with a 409 Conflict status code.
BodyStartSubscriptionActionRequestrequiredapplication/json
The action to start on the subscription. The type decides the other fields.
Selected by type.
typeenum<string>requiredThe action to start.
values
PAUSE
scheduled AtstringdateThe first date of the pause. If it is absent, the pause starts at once.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringtypeenum<string>requiredThe action to start.
values
RESTORE
scheduled AtstringdateThe date of the restore. If it is absent, the restore occurs today.
allowed Current Statusesarray of SubscriptionStatusThe statuses that the restore can start from. If it is absent, the restore can start from each status that a restore supports.
bar Reasonsarray of BarReasonmin items 1The reasons of the bars to remove from a BLOCKED subscription. If it is absent, the restore
removes each bar. The subscription is activated only when no bar stays.
typeenum<string>requiredThe action to start.
values
CANCEL
cancel Atone ofrequiredThe date of the cancel.
Show child attributes
churnenum<string>The reason for the cancel. We use it for reports and analysis.
If you give OTHER, you must also give a comment.
values
BETTER_DEAL_PRICENOT_HAPPY_MISSING_FUNCTIONSNOT_HAPPY_COVERAGE_SLANOT_HAPPY_COMPLEX_ADMINNOT_HAPPY_SUPPORT_ENGAGEMENTFRAUDFRAUD_ATTEMPTTEST_OR_MARKETINGNO_NEEDWRONG_ORDEROTHER
commentstringA comment about the cancel. It is necessary when churn is OTHER.
typeenum<string>requiredThe action to start.
values
BLOCK_SIM
typeenum<string>requiredThe action to start.
values
RESET_NETWORK
confirmedbooleanrequiredMust be true. It records that the user accepts a short stop of the service.
Responses
201The action started.
application/json
The action started.
The action started.
objectSubscriptionAction
A subscription operation and its execution state. Action payloads and internal task details are not exposed.
action IdstringrequiredUnique identifier for this action.
subscription IdstringrequiredSubscription affected by this action.
customer IdstringrequiredCustomer that owns the subscription.
typeenum<string>requiredThe kind of recorded subscription action. The list includes legacy values that can occur in historical records. A caller must tolerate new values.
values
UNKNOWNCREATECREATE_WITH_PORT_INCHANGE_PRODUCTCHANGE_SIM_CARDCHANGE_VANITY_NUMBER_FORWARDCHANGE_MSISDNCHANGE_MSISDN_WITH_PORT_INGET_NEW_MSISDNCHANGE_RATE_PLANPAUSESUSPENDBARRESTORECANCELRESET_NETWORKENABLE_ADDONCANCEL_ADDONCHANGE_ADDON_PRODUCTEXPIRE_ADDONMOVED_FROM_ANOTHER_CUSTOMERCANCEL_DEVICE_LOCATIONRESET_VOICEMAIL_PASSWORDUPDATE_ROAMING_LIMITENABLE_VOWIFIRESEND_ESIM_QR_CODERECONNECTPORT_BACKPORT_OUTCHANGE_E911_ADDRESSTOPUPMOVE_TO_ANOTHER_CUSTOMEROPEN_FOR_OUTPORTINGADD_CONTRACT_PERIODLEGACY_UPDATE
statusenum<string>requiredThe recorded execution state of an action. UNKNOWN means that the state is not known. PENDING waits for execution. RUNNING is in progress. SUCCESS and FAILURE describe the result of execution. A caller must tolerate new values.
values
UNKNOWNPENDINGRUNNINGSUCCESSFAILURE
schedule Modeenum<string>requiredHow the action is scheduled. UNKNOWN means that the schedule mode is not known. IMMEDIATE starts execution at once. AT_SPECIFIED_DATE and AT_SPECIFIED_DATE_TIME target a specified date or time. ON_DEMAND starts execution on demand. A caller must tolerate new values.
values
UNKNOWNIMMEDIATEAT_SPECIFIED_DATEAT_SPECIFIED_DATE_TIMEON_DEMAND
apply Atstringdate-timerequiredWhen the operation is scheduled to take effect.
execution Started Atstringdate-timeWhen execution began, if it has started.
execution Finished Atstringdate-timeWhen execution ended, if it has finished.
failure ReasonstringNames the condition that failed the action, in lower snake_case. The values are the same as
the reason of an error response. For example, invalid_e911_address means that the network
operator refused the service address as an E911 address. Only an action with the status
FAILURE has this field, and such an action can also fail without a reason. Your client must
accept a reason that it does not know.
created Atstringdate-timerequiredWhen the action was created.
updated Atstringdate-timerequiredWhen the action was most recently updated.
400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
external CodestringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
external SourcestringThe third party that reported the failure.
internal CodestringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
trace IdstringIdentifies 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.
span IdstringThe span within the trace that failed.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
external CodestringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
external SourcestringThe third party that reported the failure.
internal CodestringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
trace IdstringIdentifies 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.
span IdstringThe span within the trace that failed.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
external CodestringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
external SourcestringThe third party that reported the failure.
internal CodestringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
trace IdstringIdentifies 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.
span IdstringThe span within the trace that failed.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
external CodestringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
external SourcestringThe third party that reported the failure.
internal CodestringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
trace IdstringIdentifies 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.
span IdstringThe span within the trace that failed.
409The request conflicts with the current state of the resource.
application/json
The request conflicts with the current state of the resource.
The request conflicts with the current state of the resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
external CodestringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
external SourcestringThe third party that reported the failure.
internal CodestringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
trace IdstringIdentifies 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.
span IdstringThe span within the trace that failed.
412A precondition for this request was not met.
application/json
A precondition for this request was not met.
A precondition for this request was not met.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
external CodestringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
external SourcestringThe third party that reported the failure.
internal CodestringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
trace IdstringIdentifies 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.
span IdstringThe span within the trace that failed.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
external CodestringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
external SourcestringThe third party that reported the failure.
internal CodestringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
trace IdstringIdentifies 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.
span IdstringThe span within the trace that failed.
Auth required
Send one of
X-Api-KeyBearer JWT+X-Api-Key
The API key is always required; the bearer token is optional.
curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/actions \
--request POST \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"type": "PAUSE",
"scheduledAt": "2026-12-01"
}'fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/actions', {
method: 'POST',
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-Api-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
type: 'PAUSE',
scheduledAt: '2026-12-01'
})
})requests.post(
"https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/actions",
headers={
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"X-Api-Key": "YOUR_API_KEY",
"Content-Type": "application/json"
},
json={
"type": "PAUSE",
"scheduledAt": "2026-12-01"
}
)package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/actions"
payload := strings.NewReader(`{
"type": "PAUSE",
"scheduledAt": "2026-12-01"
}`)
req, _ := http.NewRequest("POST", requestUrl, payload)
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"actionId": "string",
"subscriptionId": "string",
"customerId": "string",
"type": "ENABLE_VOWIFI",
"status": "PENDING",
"scheduleMode": "ON_DEMAND",
"applyAt": "2024-01-15T10:30:00Z",
"executionStartedAt": "2024-01-15T10:30:00Z",
"executionFinishedAt": "2024-01-15T10:30:00Z",
"failureReason": "invalid_e911_address",
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
}{
"message": "The request body is invalid.",
"code": "bad_request",
"details": [
{
"message": "Email format is invalid.",
"code": "invalid_email",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields."
}{
"message": "Authentication is required to access this resource.",
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header."
}{
"message": "You do not have permission to perform this action.",
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions."
}{
"message": "The requested customer could not be found.",
"code": "not_found",
"hint": "Verify the customerId and try again."
}{
"message": "The request conflicts with the current state of the resource.",
"code": "conflict",
"hint": "Reload the resource to get its latest state before retrying."
}{
"message": "A precondition given in the request headers was not met.",
"code": "precondition_failed",
"hint": "Fetch the current resource and retry with an up-to-date precondition."
}{
"message": "An unexpected error occurred on the server.",
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support."
}Get an action of a subscription
/subscriptions/{subscriptionId}/actions/{actionId}Get one action of a subscription and its progress. An action of another subscription gets the same 404 response as a missing action.
Path parameters
subscription IdstringrequiredThe 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.
action IdstringrequiredThe identifier of the action.
Responses
200The action.
application/json
The action.
The action.
objectSubscriptionAction
A subscription operation and its execution state. Action payloads and internal task details are not exposed.
action IdstringrequiredUnique identifier for this action.
subscription IdstringrequiredSubscription affected by this action.
customer IdstringrequiredCustomer that owns the subscription.
typeenum<string>requiredThe kind of recorded subscription action. The list includes legacy values that can occur in historical records. A caller must tolerate new values.
values
UNKNOWNCREATECREATE_WITH_PORT_INCHANGE_PRODUCTCHANGE_SIM_CARDCHANGE_VANITY_NUMBER_FORWARDCHANGE_MSISDNCHANGE_MSISDN_WITH_PORT_INGET_NEW_MSISDNCHANGE_RATE_PLANPAUSESUSPENDBARRESTORECANCELRESET_NETWORKENABLE_ADDONCANCEL_ADDONCHANGE_ADDON_PRODUCTEXPIRE_ADDONMOVED_FROM_ANOTHER_CUSTOMERCANCEL_DEVICE_LOCATIONRESET_VOICEMAIL_PASSWORDUPDATE_ROAMING_LIMITENABLE_VOWIFIRESEND_ESIM_QR_CODERECONNECTPORT_BACKPORT_OUTCHANGE_E911_ADDRESSTOPUPMOVE_TO_ANOTHER_CUSTOMEROPEN_FOR_OUTPORTINGADD_CONTRACT_PERIODLEGACY_UPDATE
statusenum<string>requiredThe recorded execution state of an action. UNKNOWN means that the state is not known. PENDING waits for execution. RUNNING is in progress. SUCCESS and FAILURE describe the result of execution. A caller must tolerate new values.
values
UNKNOWNPENDINGRUNNINGSUCCESSFAILURE
schedule Modeenum<string>requiredHow the action is scheduled. UNKNOWN means that the schedule mode is not known. IMMEDIATE starts execution at once. AT_SPECIFIED_DATE and AT_SPECIFIED_DATE_TIME target a specified date or time. ON_DEMAND starts execution on demand. A caller must tolerate new values.
values
UNKNOWNIMMEDIATEAT_SPECIFIED_DATEAT_SPECIFIED_DATE_TIMEON_DEMAND
apply Atstringdate-timerequiredWhen the operation is scheduled to take effect.
execution Started Atstringdate-timeWhen execution began, if it has started.
execution Finished Atstringdate-timeWhen execution ended, if it has finished.
failure ReasonstringNames the condition that failed the action, in lower snake_case. The values are the same as
the reason of an error response. For example, invalid_e911_address means that the network
operator refused the service address as an E911 address. Only an action with the status
FAILURE has this field, and such an action can also fail without a reason. Your client must
accept a reason that it does not know.
created Atstringdate-timerequiredWhen the action was created.
updated Atstringdate-timerequiredWhen the action was most recently updated.
400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
external CodestringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
external SourcestringThe third party that reported the failure.
internal CodestringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
trace IdstringIdentifies 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.
span IdstringThe span within the trace that failed.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
external CodestringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
external SourcestringThe third party that reported the failure.
internal CodestringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
trace IdstringIdentifies 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.
span IdstringThe span within the trace that failed.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
external CodestringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
external SourcestringThe third party that reported the failure.
internal CodestringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
trace IdstringIdentifies 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.
span IdstringThe span within the trace that failed.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
external CodestringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
external SourcestringThe third party that reported the failure.
internal CodestringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
trace IdstringIdentifies 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.
span IdstringThe span within the trace that failed.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
external CodestringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
external SourcestringThe third party that reported the failure.
internal CodestringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
trace IdstringIdentifies 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.
span IdstringThe span within the trace that failed.
Auth required
Send one of
X-Api-KeyBearer JWT+X-Api-Key
The API key is always required; the bearer token is optional.
curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/actions/ACTION_ID \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'X-Api-Key: YOUR_API_KEY'fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/actions/ACTION_ID', {
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-Api-Key': 'YOUR_API_KEY'
}
})requests.get(
"https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/actions/ACTION_ID",
headers={
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"X-Api-Key": "YOUR_API_KEY"
}
)package main
import (
"fmt"
"io"
"net/http"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/actions/ACTION_ID"
req, _ := http.NewRequest("GET", requestUrl, nil)
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"actionId": "string",
"subscriptionId": "string",
"customerId": "string",
"type": "ENABLE_VOWIFI",
"status": "PENDING",
"scheduleMode": "ON_DEMAND",
"applyAt": "2024-01-15T10:30:00Z",
"executionStartedAt": "2024-01-15T10:30:00Z",
"executionFinishedAt": "2024-01-15T10:30:00Z",
"failureReason": "invalid_e911_address",
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
}{
"message": "The request body is invalid.",
"code": "bad_request",
"details": [
{
"message": "Email format is invalid.",
"code": "invalid_email",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields."
}{
"message": "Authentication is required to access this resource.",
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header."
}{
"message": "You do not have permission to perform this action.",
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions."
}{
"message": "The requested customer could not be found.",
"code": "not_found",
"hint": "Verify the customerId and try again."
}{
"message": "An unexpected error occurred on the server.",
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support."
}