Subscribers

Manage subscribers.

List subscribers

GET/subscribers

List all subscribers.

Will return all subscribers the requester has access to.

Query parameters

customerIdsarray of string

Filter by customer. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with rid_ (e.g., rid_crm-customer-12345) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup.

subscriptionIdsarray of string

The unique identifier of the subscription to filter by.

limitinteger>= 1<= 1000default 100

The maximum number of items to return.

cursorstring

Opaque pagination token from a previous response's nextCursor.

Responses

200

A list of subscribers.

application/json

A list of subscribers.

object

itemsarray of SubscriberListItemrequired

Show child attributes

subscriberIdstringrequired

The unique identifier of the subscriber.

namestringrequired

The full name of the subscriber.

emailstringemail

Optional email address of the subscriber.

addressobject

The address of the subscriber. In the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services.

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

Show child attributes

streetstring

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

street1stringdeprecatedrequired

Deprecated. Use street instead.

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

street2string

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

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

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

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

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

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

statestring

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

regionstring

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

attentionstring

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

customerIdstring

The unique identifier of the customer the subscriber belongs to.

subscriptionIdsarray of string

List of subscriptions ids associated with the subscriber.

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

createdAtstringdate-time

Date and time when the subscriber was created.

updatedAtstringdate-time

Date and time when the subscriber was last updated.

paginationobjectrequired

Cursor-based pagination information returned by list endpoints. Pass nextCursor as the cursor query parameter of the next request to fetch the following page.

Show child attributes

nextCursorstring | nullrequired

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

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

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

hintstring

A hint to help resolve the error.

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.

spanIdstring

The span within the trace that failed.

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. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

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

hintstring

A hint to help resolve the error.

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.

spanIdstring

The span within the trace that failed.

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. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

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

hintstring

A hint to help resolve the error.

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.

spanIdstring

The span within the trace that failed.

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. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

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

hintstring

A hint to help resolve the error.

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.

spanIdstring

The span within the trace that failed.

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. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

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

hintstring

A hint to help resolve the error.

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.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

X-Api-Key
Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

GET /subscribers

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

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

requests.get(
    "https://apiv2.example.com/api/v2/subscribers",
    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/subscribers"

	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": [
    {
      "subscriberId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
      "name": "John Doe",
      "email": "john.doe@example.com",
      "address": {
        "street": "500 S Main St",
        "street1": "string",
        "street2": "Apt 1",
        "city": "Natick",
        "zip": "01701",
        "country": "US",
        "state": "CA",
        "region": "Ontario",
        "attention": "John Doe"
      },
      "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
      "subscriptionIds": [
        "d8174435-6378-4be5-a9f5-8b4aaadae5d4"
      ],
      "createdAt": "2024-01-10T08:00: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."
}

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.

subscriberIdstringrequired

The unique identifier of the subscriber.

namestringrequired

The full name of the subscriber.

emailstringemail

Optional email address of the subscriber.

contactNumberstringphone

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

addressobject

The address of the subscriber. In the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services.

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

Show child attributes

streetstring

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

street1stringdeprecatedrequired

Deprecated. Use street instead.

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

street2string

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

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

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

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

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

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

statestring

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

regionstring

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

attentionstring

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

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.

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

subscriptionIdstringrequired

The unique identifier for the subscription.

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.

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

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.

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.

msisdnstringphonerequired

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.

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.

productOfferingobject

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

Show child attributes

productOfferingIdstringrequired

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

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

groupobject

A product group organizes related product offerings.

Show child attributes

imageUrlstringuri

URL to the image representing the product offering.

subscriberobject

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

Show child attributes

subscriberIdstringrequired

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

namestringrequired

The subscriber's full name.

emailstringemail

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

addressobject

The address of the subscriber.

In the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services.

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.

updatedAtstringdate-time

Date and time when the subscriber was last updated.

extensionsobject with string keys

Additional subscription extensions fields provided for custom subscription types.

Show child attributes

*string

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.

imeistring

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

Only applicable for eSIM.

iccidstring

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

pendingMsisdnobject

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

msisdnstringphonerequired

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.

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

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

scheduledAtstringdate

The date when the pending status 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

scheduledAtstringdaterequired

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

productobjectrequired

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

Show child attributes

portingobject

Number porting information for subscriptions, indicating scheduled number transfers.

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

Show child attributes

msisdnstringrequired

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

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

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

scheduledAtstringdaterequired

The date when the number porting is scheduled to occur.

activatedAtstringdate-time

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

cancelledAtstringdate-time

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

createdAtstringdate-timerequired

The date and time when the subscription was created.

updatedAtstringdate-timerequired

The date and time when the subscription was last updated.

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

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. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

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

hintstring

A hint to help resolve the error.

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.

spanIdstring

The span within the trace that failed.

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. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

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

hintstring

A hint to help resolve the error.

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.

spanIdstring

The span within the trace that failed.

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. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

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

hintstring

A hint to help resolve the error.

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.

spanIdstring

The span within the trace that failed.

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. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

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

hintstring

A hint to help resolve the error.

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.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

X-Api-Key
Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

GET /subscribers/{subscriberId}

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

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

requests.get(
    "https://apiv2.example.com/api/v2/subscribers/SUBSCRIBER_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/subscribers/SUBSCRIBER_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))

}

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

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

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

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

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

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

namestring

The full name of the subscriber.

emailstringemail

The email address of the subscriber.

contactNumberstringphone

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

addressobject

The address of the subscriber.

In the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services. Changing it schedules an update with the network operator, so the new address becomes the one emergency services receive.

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

Show child attributes

streetstring

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

street1stringdeprecatedrequired

Deprecated. Use street instead.

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

street2string

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

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

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

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

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

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

statestring

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

regionstring

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

attentionstring

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

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

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.

subscriberIdstringrequired

The unique identifier of the subscriber.

namestringrequired

The full name of the subscriber.

emailstringemail

Optional email address of the subscriber.

contactNumberstringphone

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

addressobject

The address of the subscriber. In the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services.

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

Show child attributes

streetstring

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

street1stringdeprecatedrequired

Deprecated. Use street instead.

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

street2string

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

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

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

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

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

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

statestring

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

regionstring

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

attentionstring

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

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.

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

subscriptionIdstringrequired

The unique identifier for the subscription.

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.

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

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.

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.

msisdnstringphonerequired

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.

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.

productOfferingobject

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

Show child attributes

productOfferingIdstringrequired

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

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

groupobject

A product group organizes related product offerings.

Show child attributes

imageUrlstringuri

URL to the image representing the product offering.

subscriberobject

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

Show child attributes

subscriberIdstringrequired

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

namestringrequired

The subscriber's full name.

emailstringemail

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

addressobject

The address of the subscriber.

In the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services.

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.

updatedAtstringdate-time

Date and time when the subscriber was last updated.

extensionsobject with string keys

Additional subscription extensions fields provided for custom subscription types.

Show child attributes

*string

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.

imeistring

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

Only applicable for eSIM.

iccidstring

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

pendingMsisdnobject

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

msisdnstringphonerequired

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.

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

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

scheduledAtstringdate

The date when the pending status 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

scheduledAtstringdaterequired

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

productobjectrequired

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

Show child attributes

portingobject

Number porting information for subscriptions, indicating scheduled number transfers.

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

Show child attributes

msisdnstringrequired

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

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

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

scheduledAtstringdaterequired

The date when the number porting is scheduled to occur.

activatedAtstringdate-time

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

cancelledAtstringdate-time

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

createdAtstringdate-timerequired

The date and time when the subscription was created.

updatedAtstringdate-timerequired

The date and time when the subscription was last updated.

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

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. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

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

hintstring

A hint to help resolve the error.

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.

spanIdstring

The span within the trace that failed.

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. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

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

hintstring

A hint to help resolve the error.

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.

spanIdstring

The span within the trace that failed.

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. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

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

hintstring

A hint to help resolve the error.

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.

spanIdstring

The span within the trace that failed.

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. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

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

hintstring

A hint to help resolve the error.

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.

spanIdstring

The span within the trace that failed.

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. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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.

internalCodestring

Names the condition that failed, from our own registry. It is independent of which system reported the failure and of the HTTP status, and it is stable across releases. Branch on this field. An unexpected failure on our side can carry no code. Then use the HTTP status.

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

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

hintstring

A hint to help resolve the error.

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.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

X-Api-Key
Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

PUT /subscribers/{subscriberId}

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

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

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

package main

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

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

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

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

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

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

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

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

}

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

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

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

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

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

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

Subscribers

List subscribers

Query parameters

Responses

Get subscriber

Path parameters

Responses

Update subscriber

Path parameters

Headers

Body·UpdateSubscriberRequestrequiredapplication/json

Responses

BodyUpdateSubscriberRequestrequiredapplication/json