Subscribers

The persons that use a subscription.

Get subscriber

GET/subscribers/{subscriberId}

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

Path parameters

subscriberIdstringrequired

The unique identifier of the subscriber.

Responses

200

A subscriber object.

application/json

A subscriber object.

objectSubscriber

The person or entity that uses a subscription's service (the end user), as opposed to the customer, who pays for it. For example, an employee using a company-paid phone plan.

addressobjectdeprecated

Deprecated. Use serviceAddress on each subscription instead.

The service address of the oldest subscription of the subscriber. A subscriber with two subscriptions can hold two service addresses, and this field shows only one.

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

Show child attributes

attentionstringpersonal data

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

citystringrequired

The city or municipality of the address.

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

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

regionstring

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

statestring

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

streetstringpersonal data

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

street1stringpersonal datadeprecatedrequired

Deprecated. Use street instead.

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

street2stringpersonal data

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

zipstringpersonal datarequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.

contactNumberstringphonepersonal data

A phone number for reaching the subscriber, separate from the number their subscription provides.

customerobjectrequired

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

Show child attributes

customerIdstringrequired

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

namestringrequired

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

emailstringemailpersonal data

Optional email address of the subscriber.

namestringrequired

The full name of the subscriber.

subscriberIdstringrequired

The unique identifier of the subscriber.

subscriptionsarray of Subscription

List of subscriptions associated with the subscriber.

Typically a subscriber has exactly one subscription, but in rare cases, a subscriber may have multiple subscriptions.

Show child attributes

activatedAtstringdate-time

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

barReasonsarray of BarReason

The reasons of the bars that keep a BLOCKED subscription blocked. A subscription can have more than one bar, and it stays blocked until every bar is removed. Present only while the status is BLOCKED.

cancelledAtstringdate-time

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

createdAtstringdate-timerequired

The date and time when the subscription was created.

customerobjectrequired

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

Show child attributes

customerIdstringrequired

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

namestringrequired

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

displaystringrequired

Human-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation.

extensionsobject with string keys

Additional subscription extensions fields provided for custom subscription types.

Show child attributes

*string

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

*string

msisdnstringphonepersonal datarequired

The phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number.

pendingMsisdnobjectpersonal data

A phone number change that has been requested but not yet applied. Present only while a number change is scheduled; the current number remains in msisdn until the change takes effect.

Show child attributes

msisdnstringphonepersonal datarequired

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

scheduledAtstringdate

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

pendingProductOfferingobject

A product offering change (upgrade or downgrade) that has been requested but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.

Show child attributes

productobjectrequired

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

Show child attributes

scheduledAtstringdaterequired

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

pendingStatusobject

A status change that has been requested but not yet applied, for example a scheduled cancellation or pause. Present only while a status change is scheduled.

Show child attributes

scheduledAtstringdate

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

statusenum<string>required

Current stage of the subscription lifecycle.

PENDING: Created but not yet activated in the network
ACTIVATED: Active and billable; service is available
BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
CANCELLED: Permanently terminated
PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled

values

PENDING
ACTIVATED
BLOCKED
CANCELLED
PAUSED
SUSPENDED

portingobject

Number porting information for subscriptions, indicating scheduled number transfers.

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

Show child attributes

directionenum<string>required

The direction of the number transfer. INBOUND means the number is being ported into this platform from another carrier; OUTBOUND means the number is leaving this platform for another carrier.

values

INBOUND
OUTBOUND

msisdnstringpersonal datarequired

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

scheduledAtstringdaterequired

The date when the number porting is scheduled to occur.

statusenum<string>required

Current status of the porting process.

PENDING: Porting request created but not yet submitted to the carriers
IN_PROGRESS: Request submitted and awaiting a response from the losing carrier
SCHEDULED: Accepted by the losing carrier; the transfer will execute on the scheduled date
COMPLETED: The number has been transferred and is active
FAILED: The request was rejected, canceled, or could not be completed

values

PENDING
IN_PROGRESS
SCHEDULED
COMPLETED
FAILED

productOfferingobject

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

Show child attributes

groupobject

A product group organizes related product offerings.

Show child attributes

imageUrlstringuri

URL to the image representing the product offering.

namestringrequired

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

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes

productOfferingIdstringrequired

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

referenceIdstringmax length 255

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

serviceAddressobject

The address where this subscription is served. It is the address that the subscription holds, or the billing address of the customer when the subscription holds none.

Absent when no record holds an address.

The address where a subscription is served, and the record that holds it.

In the US, this is the E911 address that emergency services get for the phone number.

Show child attributes

addressobjectrequired

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

Show child attributes

sourceenum<string>required

The record that holds the address.

SUBSCRIPTION: The subscription holds an address of its own.
CUSTOMER_BILLING: The subscription holds no address of its own, so the billing address of the customer applies.

values

SUBSCRIPTION
CUSTOMER_BILLING

simobjectrequired

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

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

Show child attributes

esimbooleanrequired

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

iccidstringpersonal data

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

imeistringpersonal data

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

Only applicable for eSIM.

statusenum<string>required

Current stage of the subscription lifecycle.

PENDING: Created but not yet activated in the network
ACTIVATED: Active and billable; service is available
BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
CANCELLED: Permanently terminated
PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled

values

PENDING
ACTIVATED
BLOCKED
CANCELLED
PAUSED
SUSPENDED

subscriberobject

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

Show child attributes

addressobjectdeprecated

Deprecated. Use serviceAddress on the subscription instead.

The service address of the subscription that embeds this subscriber.

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

Show child attributes

createdAtstringdate-time

Date and time when the subscriber was created.

emailstringemailpersonal data

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

namestringrequired

The subscriber's full name.

subscriberIdstringrequired

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

updatedAtstringdate-time

Date and time when the subscriber was last updated.

subscriptionIdstringrequired

The unique identifier for the subscription.

typestringrequired

The kind of telecommunications service the subscription provides.

Common values include CELL (mobile voice/SMS/data), DATA (data-only SIM), MBB (mobile broadband), M2M (machine-to-machine/IoT), and TRAVEL_ESIM (travel eSIM for international roaming). Determined by the product offering the subscription was created with.

updatedAtstringdate-timerequired

The date and time when the subscription was last updated.

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

domainstring

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

externalCodestring

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

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

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

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

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

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

domainstring

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

externalCodestring

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

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

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

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

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

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

domainstring

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

externalCodestring

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

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

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

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

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

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

domainstring

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

externalCodestring

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

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

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

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

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

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

Auth required

Send

X-Api-Key + Bearer JWT

GET /subscribers/{subscriberId}

curl https://apiv2.example.com/api/v2/end-user/subscribers/SUBSCRIBER_ID \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

fetch('https://apiv2.example.com/api/v2/end-user/subscribers/SUBSCRIBER_ID', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  }
})

requests.get(
    "https://apiv2.example.com/api/v2/end-user/subscribers/SUBSCRIBER_ID",
    headers={
      "X-Api-Key": "YOUR_API_KEY",
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
)

package main

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

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

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

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

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

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

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

}

{
  "address": {
    "attention": "John Doe",
    "city": "Natick",
    "country": "US",
    "region": "Ontario",
    "state": "CA",
    "street": "500 S Main St",
    "street1": "string",
    "street2": "Apt 1",
    "zip": "01701"
  },
  "contactNumber": "+15551234567",
  "customer": {
    "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "name": "John Doe"
  },
  "email": "john.doe@example.com",
  "name": "John Doe",
  "subscriberId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
  "subscriptions": [
    {
      "activatedAt": "2024-01-15T10:30:00Z",
      "barReasons": [
        "MISSING_PAYMENT"
      ],
      "cancelledAt": "2024-06-30T00:00:00Z",
      "createdAt": "2024-01-10T08:00:00Z",
      "customer": {
        "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
        "name": "John Doe"
      },
      "display": "(555) 123-4567",
      "extensions": {
        "propertyName": "string"
      },
      "metadata": {
        "propertyName": "string"
      },
      "msisdn": "+15551234567",
      "pendingMsisdn": {
        "msisdn": "+15559876543",
        "scheduledAt": "2024-02-01"
      },
      "pendingProductOffering": {
        "product": {
          "group": {
            "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
            "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
            "internalDescription": "Core mobile offerings targeting consumer and business segments",
            "name": "Mobile Plans",
            "productOfferingGroupId": "mobile-plans"
          },
          "imageUrl": "https://cdn.example.com/images/mobile-basic.png",
          "name": "Mobile Unlimited",
          "price": {
            "billingCycle": {
              "interval": 1,
              "period": "MONTHLY"
            },
            "bindingContract": {
              "discount": {
                "amountMinor": 500,
                "duration": {
                  "unit": "MONTHS",
                  "value": 3
                },
                "invoicingDescription": "Campaign discount",
                "source": "STANDARD"
              },
              "duration": {
                "unit": "MONTHS",
                "value": 3
              }
            },
            "currency": "USD",
            "currencyOptionsMinor": {
              "propertyName": 1
            },
            "customUpfrontPayment": {
              "billingCycles": 3,
              "discount": {
                "amountMinor": 500,
                "duration": {
                  "unit": "MONTHS",
                  "value": 3
                },
                "invoicingDescription": "Campaign discount",
                "source": "STANDARD"
              }
            },
            "includesTax": false,
            "netPriceMinor": 2999,
            "priceType": "ONE_TIME",
            "standardDiscount": {
              "amountMinor": 500,
              "duration": {
                "unit": "MONTHS",
                "value": 3
              },
              "invoicingDescription": "Campaign discount",
              "source": "STANDARD"
            }
          },
          "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
        },
        "scheduledAt": "2024-02-01"
      },
      "pendingStatus": {
        "scheduledAt": "2024-02-01",
        "status": "PENDING"
      },
      "porting": {
        "direction": "INBOUND",
        "msisdn": "+15551234567",
        "scheduledAt": "2024-02-01",
        "status": "PENDING"
      },
      "productOffering": {
        "group": {
          "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
          "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
          "internalDescription": "Core mobile offerings targeting consumer and business segments",
          "name": "Mobile Plans",
          "productOfferingGroupId": "mobile-plans"
        },
        "imageUrl": "https://cdn.example.com/images/mobile-basic.png",
        "name": "Mobile Unlimited",
        "price": {
          "billingCycle": {
            "interval": 1,
            "period": "MONTHLY"
          },
          "bindingContract": {
            "discount": {
              "amountMinor": 500,
              "duration": {
                "unit": "MONTHS",
                "value": 3
              },
              "invoicingDescription": "Campaign discount",
              "source": "STANDARD"
            },
            "duration": {
              "unit": "MONTHS",
              "value": 3
            }
          },
          "currency": "USD",
          "currencyOptionsMinor": {
            "propertyName": 1
          },
          "customUpfrontPayment": {
            "billingCycles": 3,
            "discount": {
              "amountMinor": 500,
              "duration": {
                "unit": "MONTHS",
                "value": 3
              },
              "invoicingDescription": "Campaign discount",
              "source": "STANDARD"
            }
          },
          "includesTax": false,
          "netPriceMinor": 2999,
          "priceType": "ONE_TIME",
          "standardDiscount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "invoicingDescription": "Campaign discount",
            "source": "STANDARD"
          }
        },
        "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
      },
      "referenceId": "crm-subscription-12345",
      "serviceAddress": {
        "address": {
          "attention": "John Doe",
          "city": "Natick",
          "country": "US",
          "region": "Ontario",
          "state": "CA",
          "street": "500 S Main St",
          "street1": "string",
          "street2": "Apt 1",
          "zip": "01701"
        },
        "source": "SUBSCRIPTION"
      },
      "sim": {
        "esim": true,
        "iccid": "8901240197155182976",
        "imei": "356938035643809"
      },
      "status": "PENDING",
      "subscriber": {
        "address": {
          "attention": "John Doe",
          "city": "Natick",
          "country": "US",
          "region": "Ontario",
          "state": "CA",
          "street": "500 S Main St",
          "street1": "string",
          "street2": "Apt 1",
          "zip": "01701"
        },
        "createdAt": "2024-01-15T10:30:00Z",
        "email": "john.doe@example.com",
        "name": "John Doe",
        "subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
        "updatedAt": "2024-01-20T14:45:00Z"
      },
      "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
      "type": "CELL",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ]
}

{
  "code": "bad_request",
  "details": [
    {
      "code": "invalid_email",
      "message": "Email format is invalid.",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields.",
  "message": "The request body is invalid."
}

{
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header.",
  "message": "Authentication is required to access this resource."
}

{
  "code": "not_found",
  "hint": "Verify the customerId and try again.",
  "message": "The requested customer could not be found."
}

{
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support.",
  "message": "An unexpected error occurred on the server."
}

Update subscriber

PUT/subscribers/{subscriberId}

Update the details of an existing subscriber.

Path parameters

subscriberIdstringrequired

The unique identifier of the subscriber.

Headers

X-Idempotency-Keystringmax length 256

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

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

BodyUpdateSubscriberRequestrequiredapplication/json

Request to update a subscriber's information.

addressobjectdeprecated

Deprecated. Use changeSubscriptionServiceAddress instead.

The service address of the mobile subscription of the subscriber. The request fails when the subscriber does not have exactly one mobile subscription.

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

Show child attributes

attentionstringpersonal data

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

citystringrequired

The city or municipality of the address.

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

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

regionstring

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

statestring

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

streetstringpersonal data

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

street1stringpersonal datadeprecatedrequired

Deprecated. Use street instead.

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

street2stringpersonal data

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

zipstringpersonal datarequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.

contactNumberstringphonepersonal data

A phone number for reaching the subscriber, separate from the number their subscription provides.

emailstringemailpersonal data

The email address of the subscriber.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

*string

namestring

The full name of the subscriber.

Responses

200

Subscriber updated successfully.

application/json

Subscriber updated successfully.

objectSubscriber

The person or entity that uses a subscription's service (the end user), as opposed to the customer, who pays for it. For example, an employee using a company-paid phone plan.

addressobjectdeprecated

Deprecated. Use serviceAddress on each subscription instead.

The service address of the oldest subscription of the subscriber. A subscriber with two subscriptions can hold two service addresses, and this field shows only one.

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

Show child attributes

attentionstringpersonal data

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

citystringrequired

The city or municipality of the address.

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

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

regionstring

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

statestring

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

streetstringpersonal data

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

street1stringpersonal datadeprecatedrequired

Deprecated. Use street instead.

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

street2stringpersonal data

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

zipstringpersonal datarequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.

contactNumberstringphonepersonal data

A phone number for reaching the subscriber, separate from the number their subscription provides.

customerobjectrequired

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

Show child attributes

customerIdstringrequired

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

namestringrequired

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

emailstringemailpersonal data

Optional email address of the subscriber.

namestringrequired

The full name of the subscriber.

subscriberIdstringrequired

The unique identifier of the subscriber.

subscriptionsarray of Subscription

List of subscriptions associated with the subscriber.

Typically a subscriber has exactly one subscription, but in rare cases, a subscriber may have multiple subscriptions.

Show child attributes

activatedAtstringdate-time

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

barReasonsarray of BarReason

The reasons of the bars that keep a BLOCKED subscription blocked. A subscription can have more than one bar, and it stays blocked until every bar is removed. Present only while the status is BLOCKED.

cancelledAtstringdate-time

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

createdAtstringdate-timerequired

The date and time when the subscription was created.

customerobjectrequired

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

Show child attributes

customerIdstringrequired

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

namestringrequired

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

displaystringrequired

Human-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation.

extensionsobject with string keys

Additional subscription extensions fields provided for custom subscription types.

Show child attributes

*string

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes

*string

msisdnstringphonepersonal datarequired

The phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number.

pendingMsisdnobjectpersonal data

A phone number change that has been requested but not yet applied. Present only while a number change is scheduled; the current number remains in msisdn until the change takes effect.

Show child attributes

msisdnstringphonepersonal datarequired

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

scheduledAtstringdate

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

pendingProductOfferingobject

A product offering change (upgrade or downgrade) that has been requested but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.

Show child attributes

productobjectrequired

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

Show child attributes

scheduledAtstringdaterequired

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

pendingStatusobject

A status change that has been requested but not yet applied, for example a scheduled cancellation or pause. Present only while a status change is scheduled.

Show child attributes

scheduledAtstringdate

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

statusenum<string>required

Current stage of the subscription lifecycle.

PENDING: Created but not yet activated in the network
ACTIVATED: Active and billable; service is available
BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
CANCELLED: Permanently terminated
PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled

values

PENDING
ACTIVATED
BLOCKED
CANCELLED
PAUSED
SUSPENDED

portingobject

Number porting information for subscriptions, indicating scheduled number transfers.

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

Show child attributes

directionenum<string>required

The direction of the number transfer. INBOUND means the number is being ported into this platform from another carrier; OUTBOUND means the number is leaving this platform for another carrier.

values

INBOUND
OUTBOUND

msisdnstringpersonal datarequired

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

scheduledAtstringdaterequired

The date when the number porting is scheduled to occur.

statusenum<string>required

Current status of the porting process.

PENDING: Porting request created but not yet submitted to the carriers
IN_PROGRESS: Request submitted and awaiting a response from the losing carrier
SCHEDULED: Accepted by the losing carrier; the transfer will execute on the scheduled date
COMPLETED: The number has been transferred and is active
FAILED: The request was rejected, canceled, or could not be completed

values

PENDING
IN_PROGRESS
SCHEDULED
COMPLETED
FAILED

productOfferingobject

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

Show child attributes

groupobject

A product group organizes related product offerings.

Show child attributes

imageUrlstringuri

URL to the image representing the product offering.

namestringrequired

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

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes

productOfferingIdstringrequired

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

referenceIdstringmax length 255

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

serviceAddressobject

The address where this subscription is served. It is the address that the subscription holds, or the billing address of the customer when the subscription holds none.

Absent when no record holds an address.

The address where a subscription is served, and the record that holds it.

In the US, this is the E911 address that emergency services get for the phone number.

Show child attributes

addressobjectrequired

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

Show child attributes

sourceenum<string>required

The record that holds the address.

SUBSCRIPTION: The subscription holds an address of its own.
CUSTOMER_BILLING: The subscription holds no address of its own, so the billing address of the customer applies.

values

SUBSCRIPTION
CUSTOMER_BILLING

simobjectrequired

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

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

Show child attributes

esimbooleanrequired

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

iccidstringpersonal data

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

imeistringpersonal data

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

Only applicable for eSIM.

statusenum<string>required

Current stage of the subscription lifecycle.

PENDING: Created but not yet activated in the network
ACTIVATED: Active and billable; service is available
BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
CANCELLED: Permanently terminated
PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled

values

PENDING
ACTIVATED
BLOCKED
CANCELLED
PAUSED
SUSPENDED

subscriberobject

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

Show child attributes

addressobjectdeprecated

Deprecated. Use serviceAddress on the subscription instead.

The service address of the subscription that embeds this subscriber.

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

Show child attributes

createdAtstringdate-time

Date and time when the subscriber was created.

emailstringemailpersonal data

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

namestringrequired

The subscriber's full name.

subscriberIdstringrequired

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

updatedAtstringdate-time

Date and time when the subscriber was last updated.

subscriptionIdstringrequired

The unique identifier for the subscription.

typestringrequired

The kind of telecommunications service the subscription provides.

Common values include CELL (mobile voice/SMS/data), DATA (data-only SIM), MBB (mobile broadband), M2M (machine-to-machine/IoT), and TRAVEL_ESIM (travel eSIM for international roaming). Determined by the product offering the subscription was created with.

updatedAtstringdate-timerequired

The date and time when the subscription was last updated.

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

domainstring

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

externalCodestring

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

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

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

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

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

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

domainstring

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

externalCodestring

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

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

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

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

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

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

domainstring

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

externalCodestring

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

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

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

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

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

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

domainstring

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

externalCodestring

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

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

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

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

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

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

domainstring

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

externalCodestring

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

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

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

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

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

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

Auth required

Send

X-Api-Key + Bearer JWT

PUT /subscribers/{subscriberId}

curl https://apiv2.example.com/api/v2/end-user/subscribers/SUBSCRIBER_ID \
  --request PUT \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "address": {
    "attention": "John Doe",
    "city": "Natick",
    "country": "US",
    "region": "Ontario",
    "state": "CA",
    "street": "500 S Main St",
    "street1": "string",
    "street2": "Apt 1",
    "zip": "01701"
  },
  "contactNumber": "+15551234567",
  "email": "john.doe@example.com",
  "metadata": {
    "propertyName": "string"
  },
  "name": "John Doe"
}'

fetch('https://apiv2.example.com/api/v2/end-user/subscribers/SUBSCRIBER_ID', {
  method: 'PUT',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    address: {
      attention: 'John Doe',
      city: 'Natick',
      country: 'US',
      region: 'Ontario',
      state: 'CA',
      street: '500 S Main St',
      street1: 'string',
      street2: 'Apt 1',
      zip: '01701'
    },
    contactNumber: '+15551234567',
    email: 'john.doe@example.com',
    metadata: {
      propertyName: 'string'
    },
    name: 'John Doe'
  })
})

requests.put(
    "https://apiv2.example.com/api/v2/end-user/subscribers/SUBSCRIBER_ID",
    headers={
      "X-Api-Key": "YOUR_API_KEY",
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json"
    },
    json={
      "address": {
        "attention": "John Doe",
        "city": "Natick",
        "country": "US",
        "region": "Ontario",
        "state": "CA",
        "street": "500 S Main St",
        "street1": "string",
        "street2": "Apt 1",
        "zip": "01701"
      },
      "contactNumber": "+15551234567",
      "email": "john.doe@example.com",
      "metadata": {
        "propertyName": "string"
      },
      "name": "John Doe"
    }
)

package main

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

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

	payload := strings.NewReader(`{
  "address": {
    "attention": "John Doe",
    "city": "Natick",
    "country": "US",
    "region": "Ontario",
    "state": "CA",
    "street": "500 S Main St",
    "street1": "string",
    "street2": "Apt 1",
    "zip": "01701"
  },
  "contactNumber": "+15551234567",
  "email": "john.doe@example.com",
  "metadata": {
    "propertyName": "string"
  },
  "name": "John Doe"
}`)

	req, _ := http.NewRequest("PUT", requestUrl, payload)

	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("Content-Type", "application/json")

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

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

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

}

{
  "address": {
    "attention": "John Doe",
    "city": "Natick",
    "country": "US",
    "region": "Ontario",
    "state": "CA",
    "street": "500 S Main St",
    "street1": "string",
    "street2": "Apt 1",
    "zip": "01701"
  },
  "contactNumber": "+15551234567",
  "customer": {
    "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "name": "John Doe"
  },
  "email": "john.doe@example.com",
  "name": "John Doe",
  "subscriberId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
  "subscriptions": [
    {
      "activatedAt": "2024-01-15T10:30:00Z",
      "barReasons": [
        "MISSING_PAYMENT"
      ],
      "cancelledAt": "2024-06-30T00:00:00Z",
      "createdAt": "2024-01-10T08:00:00Z",
      "customer": {
        "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
        "name": "John Doe"
      },
      "display": "(555) 123-4567",
      "extensions": {
        "propertyName": "string"
      },
      "metadata": {
        "propertyName": "string"
      },
      "msisdn": "+15551234567",
      "pendingMsisdn": {
        "msisdn": "+15559876543",
        "scheduledAt": "2024-02-01"
      },
      "pendingProductOffering": {
        "product": {
          "group": {
            "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
            "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
            "internalDescription": "Core mobile offerings targeting consumer and business segments",
            "name": "Mobile Plans",
            "productOfferingGroupId": "mobile-plans"
          },
          "imageUrl": "https://cdn.example.com/images/mobile-basic.png",
          "name": "Mobile Unlimited",
          "price": {
            "billingCycle": {
              "interval": 1,
              "period": "MONTHLY"
            },
            "bindingContract": {
              "discount": {
                "amountMinor": 500,
                "duration": {
                  "unit": "MONTHS",
                  "value": 3
                },
                "invoicingDescription": "Campaign discount",
                "source": "STANDARD"
              },
              "duration": {
                "unit": "MONTHS",
                "value": 3
              }
            },
            "currency": "USD",
            "currencyOptionsMinor": {
              "propertyName": 1
            },
            "customUpfrontPayment": {
              "billingCycles": 3,
              "discount": {
                "amountMinor": 500,
                "duration": {
                  "unit": "MONTHS",
                  "value": 3
                },
                "invoicingDescription": "Campaign discount",
                "source": "STANDARD"
              }
            },
            "includesTax": false,
            "netPriceMinor": 2999,
            "priceType": "ONE_TIME",
            "standardDiscount": {
              "amountMinor": 500,
              "duration": {
                "unit": "MONTHS",
                "value": 3
              },
              "invoicingDescription": "Campaign discount",
              "source": "STANDARD"
            }
          },
          "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
        },
        "scheduledAt": "2024-02-01"
      },
      "pendingStatus": {
        "scheduledAt": "2024-02-01",
        "status": "PENDING"
      },
      "porting": {
        "direction": "INBOUND",
        "msisdn": "+15551234567",
        "scheduledAt": "2024-02-01",
        "status": "PENDING"
      },
      "productOffering": {
        "group": {
          "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
          "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
          "internalDescription": "Core mobile offerings targeting consumer and business segments",
          "name": "Mobile Plans",
          "productOfferingGroupId": "mobile-plans"
        },
        "imageUrl": "https://cdn.example.com/images/mobile-basic.png",
        "name": "Mobile Unlimited",
        "price": {
          "billingCycle": {
            "interval": 1,
            "period": "MONTHLY"
          },
          "bindingContract": {
            "discount": {
              "amountMinor": 500,
              "duration": {
                "unit": "MONTHS",
                "value": 3
              },
              "invoicingDescription": "Campaign discount",
              "source": "STANDARD"
            },
            "duration": {
              "unit": "MONTHS",
              "value": 3
            }
          },
          "currency": "USD",
          "currencyOptionsMinor": {
            "propertyName": 1
          },
          "customUpfrontPayment": {
            "billingCycles": 3,
            "discount": {
              "amountMinor": 500,
              "duration": {
                "unit": "MONTHS",
                "value": 3
              },
              "invoicingDescription": "Campaign discount",
              "source": "STANDARD"
            }
          },
          "includesTax": false,
          "netPriceMinor": 2999,
          "priceType": "ONE_TIME",
          "standardDiscount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "invoicingDescription": "Campaign discount",
            "source": "STANDARD"
          }
        },
        "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
      },
      "referenceId": "crm-subscription-12345",
      "serviceAddress": {
        "address": {
          "attention": "John Doe",
          "city": "Natick",
          "country": "US",
          "region": "Ontario",
          "state": "CA",
          "street": "500 S Main St",
          "street1": "string",
          "street2": "Apt 1",
          "zip": "01701"
        },
        "source": "SUBSCRIPTION"
      },
      "sim": {
        "esim": true,
        "iccid": "8901240197155182976",
        "imei": "356938035643809"
      },
      "status": "PENDING",
      "subscriber": {
        "address": {
          "attention": "John Doe",
          "city": "Natick",
          "country": "US",
          "region": "Ontario",
          "state": "CA",
          "street": "500 S Main St",
          "street1": "string",
          "street2": "Apt 1",
          "zip": "01701"
        },
        "createdAt": "2024-01-15T10:30:00Z",
        "email": "john.doe@example.com",
        "name": "John Doe",
        "subscriberId": "d0e1f2a3-b4c5-6789-0123-456789012345",
        "updatedAt": "2024-01-20T14:45:00Z"
      },
      "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
      "type": "CELL",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ]
}

{
  "code": "bad_request",
  "details": [
    {
      "code": "invalid_email",
      "message": "Email format is invalid.",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields.",
  "message": "The request body is invalid."
}

{
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header.",
  "message": "Authentication is required to access this resource."
}

{
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions.",
  "message": "You do not have permission to perform this action."
}

{
  "code": "not_found",
  "hint": "Verify the customerId and try again.",
  "message": "The requested customer could not be found."
}

{
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support.",
  "message": "An unexpected error occurred on the server."
}

Subscribers

Get subscriber

Path parameters

Responses

Update subscriber

Path parameters

Headers

Body·UpdateSubscriberRequestrequiredapplication/json

Responses

BodyUpdateSubscriberRequestrequiredapplication/json