Customers
Manage customers.
List customers
/customersList all customers.
Will return all customers the requester has access to.
Query parameters
filterstringA free text search string to filter customers.
limitinteger>= 1<= 1000default 100The maximum number of items to return.
cursorstringOpaque pagination token from a previous response's nextCursor.
Responses
200A list of customers.
application/json
A list of customers.
A list of customers.
object
itemsarray of CustomerrequiredShow child attributes
customerstringrequiredUnique identifier for the customer.
customerenum<string>requiredWhether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.
values
CONSUMERBUSINESS
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers. Shown on invoices and throughout the API.
identitystringpersonal dataA government or company registration identifier for the entity, such as a personal identification number for consumers or an organization number for businesses. The expected format depends on the country and customer type; for example, Swedish customers use a 12-digit personal number or a 10-digit organization number.
preferredstringdefault en-USThe preferred locale for the customer, in IETF BCP 47 format (e.g., "en-US", "sv-SE").
humanstringA human-readable identifier for the customer that customers can state in support requests.
referencestringmax length 255A reference identifier provided by API clients to identify this customer in their own systems. Must be unique per tenant. Use this field to look up customers or to create/retrieve customers during order creation.
contactobjectrequiredContact details for the customer.
Show child attributes
emailstringemailpersonal dataThe primary contact email for the customer.
msisdnstringphonepersonal dataThe primary contact phone number for the customer.
billingobjectBilling configuration and payment preferences for the customer.
Show child attributes
methodenum<string>requiredHow invoices should be delivered to the customer.
How invoices are delivered to the customer: electronically (E_INVOICE), by email (EMAIL_INVOICE), or by postal mail (PAPER_INVOICE). EMAIL_INVOICE requires a billing email and PAPER_INVOICE requires a billing address.
values
E_INVOICEEMAIL_INVOICEPAPER_INVOICE
emailstringemailpersonal dataThe email address to send invoices to. Required if billing method is EMAIL_INVOICE.
addressobjectThe billing address of the customer. A paper invoice goes to this address, and it decides the tax of each charge.
A subscription with no service address of its own is served at this address. A delivery goes to this address when the customer holds no shipping address.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
currencystringrequiredThe currency for customer billing and payments.
The three-letter ISO 4217 code of the currency used for prices, billing, and payments.
defaultstringDefault payment profile to use for automatic payments and new orders. If specified, enables automatic payment collection for invoices and bills.
autobooleandefault falseWhether the customer authorized automatic charges to their default payment profile. An automatic charge also needs an active default payment profile that works off-session.
usersarray of EmbeddedCustomerUserThe users associated with this customer, each with the role that governs what they can manage on the customer's account.
Show child attributes
userstringrequiredUnique identifier for the user. Use it with the user endpoints to fetch full details.
namestringrequiredThe user's full name.
roleenum<string>The user's level of access when managing the customer's account. ADMIN grants full administrative control, MANAGER grants day-to-day management access, and MEMBER grants limited access.
values
MEMBERMANAGERADMIN
contactobjectThe primary contact person for the customer.
A user associated with a customer, including the role that governs what they can manage on the customer's account. Contains essential details only — use the user endpoints for the full profile.
Show child attributes
userstringrequiredUnique identifier for the user. Use it with the user endpoints to fetch full details.
namestringrequiredThe user's full name.
roleenum<string>The user's level of access when managing the customer's account. ADMIN grants full administrative control, MANAGER grants day-to-day management access, and MEMBER grants limited access.
values
MEMBERMANAGERADMIN
shippingobjectdeprecatedDeprecated. Use shippingAddress instead.
The shipping address for the customer. Only address holds a value.
Shipping information for order fulfillment. Only required if the order contains shippable items.
Show child attributes
namestringrequiredFull name of the person or department receiving the delivery, printed on the shipping label.
msisdnstringphonepersonal dataPhone number the carrier can use to reach the recipient about the delivery.
addressobjectrequiredThe address that the physical items of this order go to. It is a record of the order, and it does not change the shipping address of the customer.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
instructionsstringFree-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.
shippingobjectThe address where the customer gets physical goods, such as SIM cards or devices.
Absent when the customer gave no shipping address. A delivery then goes to the billing address.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
deliveryobjectThe address that a delivery to this customer uses. It is shippingAddress when the customer holds one, and billing.address when the customer holds none.
The platform resolves this field. To change it, change one of the two addresses.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringpaginationobjectrequiredCursor-based pagination information returned by list endpoints.
Pass nextCursor as the cursor query parameter of the next request to fetch the following page.
Show child attributes
nextstring | nullrequiredOpaque token for fetching the next page. Null when no more results.
400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
429Too many requests have been sent in a given amount of time.
application/json
Too many requests have been sent in a given amount of time.
Too many requests have been sent in a given amount of time.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
Auth required
Send one of
X-Api-KeyBearer JWT+X-Api-Key
The API key is always required; the bearer token is optional.
curl https://apiv2.example.com/api/v2/customers \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'X-Api-Key: YOUR_API_KEY'fetch('https://apiv2.example.com/api/v2/customers', {
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-Api-Key': 'YOUR_API_KEY'
}
})requests.get(
"https://apiv2.example.com/api/v2/customers",
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/customers"
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": [
{
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"customerType": "BUSINESS",
"name": "Acme Corp",
"humanReadableId": "29A-BY3Z-X78",
"referenceId": "crm-customer-12345",
"preferredLocale": "en-US",
"contact": {
"email": "john.doe@example.com",
"msisdn": "+15551234567"
},
"billing": {
"method": "EMAIL_INVOICE",
"email": "billing@example.com",
"currency": "USD",
"autoPay": false
},
"users": [
{
"userId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
"name": "John Doe",
"role": "ADMIN"
}
],
"contactPerson": {
"userId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
"name": "John Doe",
"role": "ADMIN"
},
"shippingAddress": {
"street": "123 Main Street",
"city": "New York",
"zip": "10001",
"state": "NY",
"country": "US"
},
"deliveryAddress": {
"street": "123 Main Street",
"city": "New York",
"zip": "10001",
"state": "NY",
"country": "US"
}
}
],
"pagination": {
"nextCursor": null
}
}{
"message": "The request body is invalid.",
"code": "bad_request",
"details": [
{
"message": "Email format is invalid.",
"code": "invalid_email",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields."
}{
"message": "Authentication is required to access this resource.",
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header."
}{
"message": "You do not have permission to perform this action.",
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions."
}{
"message": "The requested customer could not be found.",
"code": "not_found",
"hint": "Verify the customerId and try again."
}{
"message": "Too many requests. Please slow down.",
"code": "too_many_requests",
"hint": "Retry after the number of seconds indicated in the Retry-After header."
}{
"message": "An unexpected error occurred on the server.",
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support."
}Create customer
/customersCreate a new customer.
Headers
X-stringmax length 256A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request.
Modified requests with the same idempotency keys are rejected with a 409 Conflict status code.
BodyCreateCustomerRequestrequiredapplication/json
The details needed to create a customer: who they are, how to reach them, how they should be billed, and which users can manage the account.
customerenum<string>requiredWhether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.
values
CONSUMERBUSINESS
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers. Shown on invoices and throughout the API.
identitystringpersonal dataA government or company registration identifier for the entity, such as a personal identification number for consumers or an organization number for businesses. The expected format depends on the country and customer type; for example, Swedish customers use a 12-digit personal number or a 10-digit organization number.
referencestringmax length 255Optional reference ID to assign to the customer. Must be unique per tenant.
preferredstringdefault en-USThe preferred locale for the customer, in IETF BCP 47 format (e.g., "en-US", "sv-SE").
contactobjectrequiredContact details for the customer.
Show child attributes
emailstringemailpersonal datarequiredThe primary contact email for the customer.
msisdnstringphonepersonal dataThe primary contact phone number for the customer.
billingobjectrequiredBilling configuration and payment preferences for the customer.
Show child attributes
methodenum<string>requiredHow invoices should be delivered to the customer.
How invoices are delivered to the customer: electronically (E_INVOICE), by email (EMAIL_INVOICE), or by postal mail (PAPER_INVOICE). EMAIL_INVOICE requires a billing email and PAPER_INVOICE requires a billing address.
values
E_INVOICEEMAIL_INVOICEPAPER_INVOICE
emailstringemailpersonal dataThe email address to send invoices to. Required if billing method is EMAIL_INVOICE.
addressobjectThe billing address of the customer. A paper invoice goes to this address, and it decides the tax of each charge.
A subscription with no service address of its own is served at this address. A delivery goes to this address when the customer holds no shipping address.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
currencystringrequiredThe currency for customer billing and payments.
The three-letter ISO 4217 code of the currency used for prices, billing, and payments.
defaultstringDefault payment profile to use for automatic payments and new orders. Must be a payment profile that will be accessible to this customer.
autobooleandefault falseWhether to automatically charge the default payment profile for invoices and bills. Requires defaultPaymentProfileId to be set.
userarray of stringrequiredList of user IDs to associate with this customer.
Depending on the user's role they will either be a member of the customer or given access to manage it.
contactstringrequiredThe user ID of the contact person for this customer.
This user will be set as the primary contact for the customer and will receive important notifications.
shippingobjectdeprecatedDeprecated. Use shippingAddress instead.
The shipping address for the customer. The platform stores only address.
Shipping information for order fulfillment. Only required if the order contains shippable items.
Show child attributes
namestringrequiredFull name of the person or department receiving the delivery, printed on the shipping label.
msisdnstringphonepersonal dataPhone number the carrier can use to reach the recipient about the delivery.
addressobjectrequiredThe address that the physical items of this order go to. It is a record of the order, and it does not change the shipping address of the customer.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
instructionsstringFree-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.
shippingobjectThe address where the customer gets physical goods, such as SIM cards or devices.
Give it only when it is different from the billing address. A customer with no shipping address gets a delivery at the billing address.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringResponses
201Customer created successfully.
application/json
Customer created successfully.
Customer created successfully.
objectCustomer
A customer is a billable entity, the person or organization responsible for paying for services.
The customer is the owner of subscribers and subscriptions. Users are associated with a customer, but are not owned by the customer.
customerstringrequiredUnique identifier for the customer.
customerenum<string>requiredWhether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.
values
CONSUMERBUSINESS
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers. Shown on invoices and throughout the API.
identitystringpersonal dataA government or company registration identifier for the entity, such as a personal identification number for consumers or an organization number for businesses. The expected format depends on the country and customer type; for example, Swedish customers use a 12-digit personal number or a 10-digit organization number.
preferredstringdefault en-USThe preferred locale for the customer, in IETF BCP 47 format (e.g., "en-US", "sv-SE").
humanstringA human-readable identifier for the customer that customers can state in support requests.
referencestringmax length 255A reference identifier provided by API clients to identify this customer in their own systems. Must be unique per tenant. Use this field to look up customers or to create/retrieve customers during order creation.
contactobjectrequiredContact details for the customer.
Show child attributes
emailstringemailpersonal dataThe primary contact email for the customer.
msisdnstringphonepersonal dataThe primary contact phone number for the customer.
billingobjectBilling configuration and payment preferences for the customer.
Show child attributes
methodenum<string>requiredHow invoices should be delivered to the customer.
How invoices are delivered to the customer: electronically (E_INVOICE), by email (EMAIL_INVOICE), or by postal mail (PAPER_INVOICE). EMAIL_INVOICE requires a billing email and PAPER_INVOICE requires a billing address.
values
E_INVOICEEMAIL_INVOICEPAPER_INVOICE
emailstringemailpersonal dataThe email address to send invoices to. Required if billing method is EMAIL_INVOICE.
addressobjectThe billing address of the customer. A paper invoice goes to this address, and it decides the tax of each charge.
A subscription with no service address of its own is served at this address. A delivery goes to this address when the customer holds no shipping address.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
currencystringrequiredThe currency for customer billing and payments.
The three-letter ISO 4217 code of the currency used for prices, billing, and payments.
defaultstringDefault payment profile to use for automatic payments and new orders. If specified, enables automatic payment collection for invoices and bills.
autobooleandefault falseWhether the customer authorized automatic charges to their default payment profile. An automatic charge also needs an active default payment profile that works off-session.
usersarray of EmbeddedCustomerUserThe users associated with this customer, each with the role that governs what they can manage on the customer's account.
Show child attributes
userstringrequiredUnique identifier for the user. Use it with the user endpoints to fetch full details.
namestringrequiredThe user's full name.
roleenum<string>The user's level of access when managing the customer's account. ADMIN grants full administrative control, MANAGER grants day-to-day management access, and MEMBER grants limited access.
values
MEMBERMANAGERADMIN
contactobjectThe primary contact person for the customer.
A user associated with a customer, including the role that governs what they can manage on the customer's account. Contains essential details only — use the user endpoints for the full profile.
Show child attributes
userstringrequiredUnique identifier for the user. Use it with the user endpoints to fetch full details.
namestringrequiredThe user's full name.
roleenum<string>The user's level of access when managing the customer's account. ADMIN grants full administrative control, MANAGER grants day-to-day management access, and MEMBER grants limited access.
values
MEMBERMANAGERADMIN
shippingobjectdeprecatedDeprecated. Use shippingAddress instead.
The shipping address for the customer. Only address holds a value.
Shipping information for order fulfillment. Only required if the order contains shippable items.
Show child attributes
namestringrequiredFull name of the person or department receiving the delivery, printed on the shipping label.
msisdnstringphonepersonal dataPhone number the carrier can use to reach the recipient about the delivery.
addressobjectrequiredThe address that the physical items of this order go to. It is a record of the order, and it does not change the shipping address of the customer.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
instructionsstringFree-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.
shippingobjectThe address where the customer gets physical goods, such as SIM cards or devices.
Absent when the customer gave no shipping address. A delivery then goes to the billing address.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
deliveryobjectThe address that a delivery to this customer uses. It is shippingAddress when the customer holds one, and billing.address when the customer holds none.
The platform resolves this field. To change it, change one of the two addresses.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*string400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
409The request conflicts with the current state of the resource.
application/json
The request conflicts with the current state of the resource.
The request conflicts with the current state of the resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
429Too many requests have been sent in a given amount of time.
application/json
Too many requests have been sent in a given amount of time.
Too many requests have been sent in a given amount of time.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
Auth required
Send one of
X-Api-KeyBearer JWT+X-Api-Key
The API key is always required; the bearer token is optional.
curl https://apiv2.example.com/api/v2/customers \
--request POST \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"customerType": "BUSINESS",
"name": "Acme Corp",
"referenceId": "crm-customer-12345",
"preferredLocale": "en-US",
"contact": {
"email": "john.doe@example.com",
"msisdn": "+15551234567"
},
"billing": {
"method": "EMAIL_INVOICE",
"email": "billing@example.com",
"currency": "USD"
},
"userIds": [
"b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e"
],
"contactPersonUserId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
"shippingAddress": {
"street": "123 Main Street",
"city": "New York",
"zip": "10001",
"state": "NY",
"country": "US"
}
}'fetch('https://apiv2.example.com/api/v2/customers', {
method: 'POST',
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-Api-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
customerType: 'BUSINESS',
name: 'Acme Corp',
referenceId: 'crm-customer-12345',
preferredLocale: 'en-US',
contact: {
email: 'john.doe@example.com',
msisdn: '+15551234567'
},
billing: {
method: 'EMAIL_INVOICE',
email: 'billing@example.com',
currency: 'USD'
},
userIds: ['b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e'],
contactPersonUserId: 'b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e',
shippingAddress: {
street: '123 Main Street',
city: 'New York',
zip: '10001',
state: 'NY',
country: 'US'
}
})
})requests.post(
"https://apiv2.example.com/api/v2/customers",
headers={
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"X-Api-Key": "YOUR_API_KEY",
"Content-Type": "application/json"
},
json={
"customerType": "BUSINESS",
"name": "Acme Corp",
"referenceId": "crm-customer-12345",
"preferredLocale": "en-US",
"contact": {
"email": "john.doe@example.com",
"msisdn": "+15551234567"
},
"billing": {
"method": "EMAIL_INVOICE",
"email": "billing@example.com",
"currency": "USD"
},
"userIds": [
"b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e"
],
"contactPersonUserId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
"shippingAddress": {
"street": "123 Main Street",
"city": "New York",
"zip": "10001",
"state": "NY",
"country": "US"
}
}
)package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/customers"
payload := strings.NewReader(`{
"customerType": "BUSINESS",
"name": "Acme Corp",
"referenceId": "crm-customer-12345",
"preferredLocale": "en-US",
"contact": {
"email": "john.doe@example.com",
"msisdn": "+15551234567"
},
"billing": {
"method": "EMAIL_INVOICE",
"email": "billing@example.com",
"currency": "USD"
},
"userIds": [
"b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e"
],
"contactPersonUserId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
"shippingAddress": {
"street": "123 Main Street",
"city": "New York",
"zip": "10001",
"state": "NY",
"country": "US"
}
}`)
req, _ := http.NewRequest("POST", requestUrl, payload)
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"customerType": "BUSINESS",
"name": "Acme Corp",
"humanReadableId": "29A-BY3Z-X78",
"referenceId": "crm-customer-12345",
"preferredLocale": "en-US",
"contact": {
"email": "john.doe@example.com",
"msisdn": "+15551234567"
},
"billing": {
"method": "EMAIL_INVOICE",
"email": "billing@example.com",
"currency": "USD",
"autoPay": false
},
"users": [
{
"userId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
"name": "John Doe",
"role": "ADMIN"
}
],
"contactPerson": {
"userId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
"name": "John Doe",
"role": "ADMIN"
},
"shippingAddress": {
"street": "123 Main Street",
"city": "New York",
"zip": "10001",
"state": "NY",
"country": "US"
},
"deliveryAddress": {
"street": "123 Main Street",
"city": "New York",
"zip": "10001",
"state": "NY",
"country": "US"
}
}{
"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 request conflicts with the current state of the resource.",
"code": "conflict",
"hint": "Reload the resource to get its latest state before retrying."
}{
"message": "Too many requests. Please slow down.",
"code": "too_many_requests",
"hint": "Retry after the number of seconds indicated in the Retry-After header."
}{
"message": "An unexpected error occurred on the server.",
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support."
}Get customer
/customers/{customerId}Get a customer by ID or referenceId.
Path parameters
customerstringrequiredThe unique identifier of the 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.
Responses
200Customer details.
application/json
Customer details.
Customer details.
objectCustomer
A customer is a billable entity, the person or organization responsible for paying for services.
The customer is the owner of subscribers and subscriptions. Users are associated with a customer, but are not owned by the customer.
customerstringrequiredUnique identifier for the customer.
customerenum<string>requiredWhether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.
values
CONSUMERBUSINESS
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers. Shown on invoices and throughout the API.
identitystringpersonal dataA government or company registration identifier for the entity, such as a personal identification number for consumers or an organization number for businesses. The expected format depends on the country and customer type; for example, Swedish customers use a 12-digit personal number or a 10-digit organization number.
preferredstringdefault en-USThe preferred locale for the customer, in IETF BCP 47 format (e.g., "en-US", "sv-SE").
humanstringA human-readable identifier for the customer that customers can state in support requests.
referencestringmax length 255A reference identifier provided by API clients to identify this customer in their own systems. Must be unique per tenant. Use this field to look up customers or to create/retrieve customers during order creation.
contactobjectrequiredContact details for the customer.
Show child attributes
emailstringemailpersonal dataThe primary contact email for the customer.
msisdnstringphonepersonal dataThe primary contact phone number for the customer.
billingobjectBilling configuration and payment preferences for the customer.
Show child attributes
methodenum<string>requiredHow invoices should be delivered to the customer.
How invoices are delivered to the customer: electronically (E_INVOICE), by email (EMAIL_INVOICE), or by postal mail (PAPER_INVOICE). EMAIL_INVOICE requires a billing email and PAPER_INVOICE requires a billing address.
values
E_INVOICEEMAIL_INVOICEPAPER_INVOICE
emailstringemailpersonal dataThe email address to send invoices to. Required if billing method is EMAIL_INVOICE.
addressobjectThe billing address of the customer. A paper invoice goes to this address, and it decides the tax of each charge.
A subscription with no service address of its own is served at this address. A delivery goes to this address when the customer holds no shipping address.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
currencystringrequiredThe currency for customer billing and payments.
The three-letter ISO 4217 code of the currency used for prices, billing, and payments.
defaultstringDefault payment profile to use for automatic payments and new orders. If specified, enables automatic payment collection for invoices and bills.
autobooleandefault falseWhether the customer authorized automatic charges to their default payment profile. An automatic charge also needs an active default payment profile that works off-session.
usersarray of EmbeddedCustomerUserThe users associated with this customer, each with the role that governs what they can manage on the customer's account.
Show child attributes
userstringrequiredUnique identifier for the user. Use it with the user endpoints to fetch full details.
namestringrequiredThe user's full name.
roleenum<string>The user's level of access when managing the customer's account. ADMIN grants full administrative control, MANAGER grants day-to-day management access, and MEMBER grants limited access.
values
MEMBERMANAGERADMIN
contactobjectThe primary contact person for the customer.
A user associated with a customer, including the role that governs what they can manage on the customer's account. Contains essential details only — use the user endpoints for the full profile.
Show child attributes
userstringrequiredUnique identifier for the user. Use it with the user endpoints to fetch full details.
namestringrequiredThe user's full name.
roleenum<string>The user's level of access when managing the customer's account. ADMIN grants full administrative control, MANAGER grants day-to-day management access, and MEMBER grants limited access.
values
MEMBERMANAGERADMIN
shippingobjectdeprecatedDeprecated. Use shippingAddress instead.
The shipping address for the customer. Only address holds a value.
Shipping information for order fulfillment. Only required if the order contains shippable items.
Show child attributes
namestringrequiredFull name of the person or department receiving the delivery, printed on the shipping label.
msisdnstringphonepersonal dataPhone number the carrier can use to reach the recipient about the delivery.
addressobjectrequiredThe address that the physical items of this order go to. It is a record of the order, and it does not change the shipping address of the customer.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
instructionsstringFree-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.
shippingobjectThe address where the customer gets physical goods, such as SIM cards or devices.
Absent when the customer gave no shipping address. A delivery then goes to the billing address.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
deliveryobjectThe address that a delivery to this customer uses. It is shippingAddress when the customer holds one, and billing.address when the customer holds none.
The platform resolves this field. To change it, change one of the two addresses.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*string400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
Auth required
Send one of
X-Api-KeyBearer JWT+X-Api-Key
The API key is always required; the bearer token is optional.
curl https://apiv2.example.com/api/v2/customers/CUSTOMER_ID \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'X-Api-Key: YOUR_API_KEY'fetch('https://apiv2.example.com/api/v2/customers/CUSTOMER_ID', {
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-Api-Key': 'YOUR_API_KEY'
}
})requests.get(
"https://apiv2.example.com/api/v2/customers/CUSTOMER_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/customers/CUSTOMER_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))
}{
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"customerType": "BUSINESS",
"name": "Acme Corp",
"humanReadableId": "29A-BY3Z-X78",
"referenceId": "crm-customer-12345",
"preferredLocale": "en-US",
"contact": {
"email": "john.doe@example.com",
"msisdn": "+15551234567"
},
"billing": {
"method": "EMAIL_INVOICE",
"email": "billing@example.com",
"currency": "USD",
"autoPay": false
},
"users": [
{
"userId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
"name": "John Doe",
"role": "ADMIN"
}
],
"contactPerson": {
"userId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
"name": "John Doe",
"role": "ADMIN"
},
"shippingAddress": {
"street": "123 Main Street",
"city": "New York",
"zip": "10001",
"state": "NY",
"country": "US"
},
"deliveryAddress": {
"street": "123 Main Street",
"city": "New York",
"zip": "10001",
"state": "NY",
"country": "US"
}
}{
"message": "The request body is invalid.",
"code": "bad_request",
"details": [
{
"message": "Email format is invalid.",
"code": "invalid_email",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields."
}{
"message": "Authentication is required to access this resource.",
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header."
}{
"message": "You do not have permission to perform this action.",
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions."
}{
"message": "The requested customer could not be found.",
"code": "not_found",
"hint": "Verify the customerId and try again."
}{
"message": "An unexpected error occurred on the server.",
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support."
}Update customer
/customers/{customerId}Update an existing customer.
Path parameters
customerstringrequiredThe unique identifier of the 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.
Headers
X-stringmax length 256A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request.
Modified requests with the same idempotency keys are rejected with a 409 Conflict status code.
BodyUpdateCustomerRequestrequiredapplication/json
The customer fields to change. Only provided fields are updated; omitted fields keep their current values.
namestringThe customer's display name — the company name for business customers or the person's full name for consumers. Shown on invoices and throughout the API.
identitystringpersonal dataA government or company registration identifier for the entity, such as a personal identification number for consumers or an organization number for businesses. The expected format depends on the country and customer type; for example, Swedish customers use a 12-digit personal number or a 10-digit organization number.
preferredstringThe preferred locale for the customer, in IETF BCP 47 format (e.g., "en-US", "sv-SE").
contactobjectContact details for the customer.
Show child attributes
emailstringemailpersonal dataThe primary contact email for the customer.
msisdnstringphonepersonal dataThe primary contact phone number for the customer.
billingobjectBilling details for the customer.
Show child attributes
methodenum<string>How invoices are delivered to the customer: electronically (E_INVOICE), by email (EMAIL_INVOICE), or by postal mail (PAPER_INVOICE). EMAIL_INVOICE requires a billing email and PAPER_INVOICE requires a billing address.
values
E_INVOICEEMAIL_INVOICEPAPER_INVOICE
emailstringemailpersonal dataThe email address to send invoices to.
Required if billing method is EMAIL_INVOICE.
addressobjectThe billing address of the customer. A paper invoice goes to this address, and it decides the tax of each charge.
A subscription with no service address of its own is served at this address. A delivery goes to this address when the customer holds no shipping address.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
currencystringThe currency for the customer billing.
The three-letter ISO 4217 code of the currency used for prices, billing, and payments.
defaultstringDefault payment profile to use for automatic payments and new orders. Must be a valid payment profile owned by this customer. Set to null to disable automatic payments.
autobooleanWhether to automatically pay invoices for this customer if a valid payment method is available.
userarray of stringUser IDs to associate with this customer, in addition to those already associated.
Depending on the user's role they will either be a member of the customer or given access to manage it. To remove a user, use the remove-user endpoint instead.
shippingobjectThe address where the customer gets physical goods, such as SIM cards or devices.
Give it only when it is different from the billing address. A customer with no shipping address gets a delivery at the billing address.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringResponses
200Customer updated successfully.
application/json
Customer updated successfully.
Customer updated successfully.
objectCustomer
A customer is a billable entity, the person or organization responsible for paying for services.
The customer is the owner of subscribers and subscriptions. Users are associated with a customer, but are not owned by the customer.
customerstringrequiredUnique identifier for the customer.
customerenum<string>requiredWhether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.
values
CONSUMERBUSINESS
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers. Shown on invoices and throughout the API.
identitystringpersonal dataA government or company registration identifier for the entity, such as a personal identification number for consumers or an organization number for businesses. The expected format depends on the country and customer type; for example, Swedish customers use a 12-digit personal number or a 10-digit organization number.
preferredstringdefault en-USThe preferred locale for the customer, in IETF BCP 47 format (e.g., "en-US", "sv-SE").
humanstringA human-readable identifier for the customer that customers can state in support requests.
referencestringmax length 255A reference identifier provided by API clients to identify this customer in their own systems. Must be unique per tenant. Use this field to look up customers or to create/retrieve customers during order creation.
contactobjectrequiredContact details for the customer.
Show child attributes
emailstringemailpersonal dataThe primary contact email for the customer.
msisdnstringphonepersonal dataThe primary contact phone number for the customer.
billingobjectBilling configuration and payment preferences for the customer.
Show child attributes
methodenum<string>requiredHow invoices should be delivered to the customer.
How invoices are delivered to the customer: electronically (E_INVOICE), by email (EMAIL_INVOICE), or by postal mail (PAPER_INVOICE). EMAIL_INVOICE requires a billing email and PAPER_INVOICE requires a billing address.
values
E_INVOICEEMAIL_INVOICEPAPER_INVOICE
emailstringemailpersonal dataThe email address to send invoices to. Required if billing method is EMAIL_INVOICE.
addressobjectThe billing address of the customer. A paper invoice goes to this address, and it decides the tax of each charge.
A subscription with no service address of its own is served at this address. A delivery goes to this address when the customer holds no shipping address.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
currencystringrequiredThe currency for customer billing and payments.
The three-letter ISO 4217 code of the currency used for prices, billing, and payments.
defaultstringDefault payment profile to use for automatic payments and new orders. If specified, enables automatic payment collection for invoices and bills.
autobooleandefault falseWhether the customer authorized automatic charges to their default payment profile. An automatic charge also needs an active default payment profile that works off-session.
usersarray of EmbeddedCustomerUserThe users associated with this customer, each with the role that governs what they can manage on the customer's account.
Show child attributes
userstringrequiredUnique identifier for the user. Use it with the user endpoints to fetch full details.
namestringrequiredThe user's full name.
roleenum<string>The user's level of access when managing the customer's account. ADMIN grants full administrative control, MANAGER grants day-to-day management access, and MEMBER grants limited access.
values
MEMBERMANAGERADMIN
contactobjectThe primary contact person for the customer.
A user associated with a customer, including the role that governs what they can manage on the customer's account. Contains essential details only — use the user endpoints for the full profile.
Show child attributes
userstringrequiredUnique identifier for the user. Use it with the user endpoints to fetch full details.
namestringrequiredThe user's full name.
roleenum<string>The user's level of access when managing the customer's account. ADMIN grants full administrative control, MANAGER grants day-to-day management access, and MEMBER grants limited access.
values
MEMBERMANAGERADMIN
shippingobjectdeprecatedDeprecated. Use shippingAddress instead.
The shipping address for the customer. Only address holds a value.
Shipping information for order fulfillment. Only required if the order contains shippable items.
Show child attributes
namestringrequiredFull name of the person or department receiving the delivery, printed on the shipping label.
msisdnstringphonepersonal dataPhone number the carrier can use to reach the recipient about the delivery.
addressobjectrequiredThe address that the physical items of this order go to. It is a record of the order, and it does not change the shipping address of the customer.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
instructionsstringFree-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.
shippingobjectThe address where the customer gets physical goods, such as SIM cards or devices.
Absent when the customer gave no shipping address. A delivery then goes to the billing address.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
deliveryobjectThe address that a delivery to this customer uses. It is shippingAddress when the customer holds one, and billing.address when the customer holds none.
The platform resolves this field. To change it, change one of the two addresses.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*string400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
409The request conflicts with the current state of the resource.
application/json
The request conflicts with the current state of the resource.
The request conflicts with the current state of the resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
Auth required
Send one of
X-Api-KeyBearer JWT+X-Api-Key
The API key is always required; the bearer token is optional.
curl https://apiv2.example.com/api/v2/customers/CUSTOMER_ID \
--request PUT \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"contact": {
"email": "newemail@example.com",
"msisdn": "+15559876543"
}
}'fetch('https://apiv2.example.com/api/v2/customers/CUSTOMER_ID', {
method: 'PUT',
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-Api-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
contact: {
email: 'newemail@example.com',
msisdn: '+15559876543'
}
})
})requests.put(
"https://apiv2.example.com/api/v2/customers/CUSTOMER_ID",
headers={
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"X-Api-Key": "YOUR_API_KEY",
"Content-Type": "application/json"
},
json={
"contact": {
"email": "newemail@example.com",
"msisdn": "+15559876543"
}
}
)package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/customers/CUSTOMER_ID"
payload := strings.NewReader(`{
"contact": {
"email": "newemail@example.com",
"msisdn": "+15559876543"
}
}`)
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))
}{
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"customerType": "CONSUMER",
"name": "John Doe",
"identity": "12-3456789",
"preferredLocale": "en-US",
"humanReadableId": "29A-BY3Z-X78",
"referenceId": "crm-customer-12345",
"contact": {
"email": "john.doe@example.com",
"msisdn": "+15551234567"
},
"billing": {
"method": "E_INVOICE",
"email": "billing@company.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"
},
"currency": "USD",
"defaultPaymentProfileId": "c1d2e3f4-a5b6-7890-1234-901234567890",
"autoPay": true
},
"users": [
{
"userId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
"name": "John Doe",
"role": "MEMBER"
}
],
"contactPerson": {
"userId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
"name": "John Doe",
"role": "MEMBER"
},
"shipping": {
"name": "John Doe",
"msisdn": "+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"
},
"instructions": "Leave at front door"
},
"shippingAddress": {
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"deliveryAddress": {
"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"
}
}{
"message": "The request body is invalid.",
"code": "bad_request",
"details": [
{
"message": "Email format is invalid.",
"code": "invalid_email",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields."
}{
"message": "Authentication is required to access this resource.",
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header."
}{
"message": "You do not have permission to perform this action.",
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions."
}{
"message": "The requested customer could not be found.",
"code": "not_found",
"hint": "Verify the customerId and try again."
}{
"message": "The request conflicts with the current state of the resource.",
"code": "conflict",
"hint": "Reload the resource to get its latest state before retrying."
}{
"message": "An unexpected error occurred on the server.",
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support."
}Remove user from customer
/customers/{customerId}/usersRemove a user from a customer. The user keeps their account, so they can still be added to another customer later, but loses the roles and permissions this customer granted them.
A customer's contact person cannot be removed — assign another contact person first.
Path parameters
customerstringrequiredThe unique identifier of the 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.
Query parameters
userstringrequiredThe unique identifier of the user to remove from the customer. May be the entity's internal UUID or an external reference identifier.
Reference identifiers MUST be prefixed with rid_ (e.g., rid_hr-employee-98765) so the API
can distinguish them from internal UUIDs. The prefix is stripped before lookup.
Headers
X-stringmax length 256A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request.
Modified requests with the same idempotency keys are rejected with a 409 Conflict status code.
Responses
200User removed from customer successfully.
application/json
User removed from customer successfully.
User removed from customer successfully.
objectCustomer
A customer is a billable entity, the person or organization responsible for paying for services.
The customer is the owner of subscribers and subscriptions. Users are associated with a customer, but are not owned by the customer.
customerstringrequiredUnique identifier for the customer.
customerenum<string>requiredWhether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.
values
CONSUMERBUSINESS
namestringrequiredThe customer's display name — the company name for business customers or the person's full name for consumers. Shown on invoices and throughout the API.
identitystringpersonal dataA government or company registration identifier for the entity, such as a personal identification number for consumers or an organization number for businesses. The expected format depends on the country and customer type; for example, Swedish customers use a 12-digit personal number or a 10-digit organization number.
preferredstringdefault en-USThe preferred locale for the customer, in IETF BCP 47 format (e.g., "en-US", "sv-SE").
humanstringA human-readable identifier for the customer that customers can state in support requests.
referencestringmax length 255A reference identifier provided by API clients to identify this customer in their own systems. Must be unique per tenant. Use this field to look up customers or to create/retrieve customers during order creation.
contactobjectrequiredContact details for the customer.
Show child attributes
emailstringemailpersonal dataThe primary contact email for the customer.
msisdnstringphonepersonal dataThe primary contact phone number for the customer.
billingobjectBilling configuration and payment preferences for the customer.
Show child attributes
methodenum<string>requiredHow invoices should be delivered to the customer.
How invoices are delivered to the customer: electronically (E_INVOICE), by email (EMAIL_INVOICE), or by postal mail (PAPER_INVOICE). EMAIL_INVOICE requires a billing email and PAPER_INVOICE requires a billing address.
values
E_INVOICEEMAIL_INVOICEPAPER_INVOICE
emailstringemailpersonal dataThe email address to send invoices to. Required if billing method is EMAIL_INVOICE.
addressobjectThe billing address of the customer. A paper invoice goes to this address, and it decides the tax of each charge.
A subscription with no service address of its own is served at this address. A delivery goes to this address when the customer holds no shipping address.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
currencystringrequiredThe currency for customer billing and payments.
The three-letter ISO 4217 code of the currency used for prices, billing, and payments.
defaultstringDefault payment profile to use for automatic payments and new orders. If specified, enables automatic payment collection for invoices and bills.
autobooleandefault falseWhether the customer authorized automatic charges to their default payment profile. An automatic charge also needs an active default payment profile that works off-session.
usersarray of EmbeddedCustomerUserThe users associated with this customer, each with the role that governs what they can manage on the customer's account.
Show child attributes
userstringrequiredUnique identifier for the user. Use it with the user endpoints to fetch full details.
namestringrequiredThe user's full name.
roleenum<string>The user's level of access when managing the customer's account. ADMIN grants full administrative control, MANAGER grants day-to-day management access, and MEMBER grants limited access.
values
MEMBERMANAGERADMIN
contactobjectThe primary contact person for the customer.
A user associated with a customer, including the role that governs what they can manage on the customer's account. Contains essential details only — use the user endpoints for the full profile.
Show child attributes
userstringrequiredUnique identifier for the user. Use it with the user endpoints to fetch full details.
namestringrequiredThe user's full name.
roleenum<string>The user's level of access when managing the customer's account. ADMIN grants full administrative control, MANAGER grants day-to-day management access, and MEMBER grants limited access.
values
MEMBERMANAGERADMIN
shippingobjectdeprecatedDeprecated. Use shippingAddress instead.
The shipping address for the customer. Only address holds a value.
Shipping information for order fulfillment. Only required if the order contains shippable items.
Show child attributes
namestringrequiredFull name of the person or department receiving the delivery, printed on the shipping label.
msisdnstringphonepersonal dataPhone number the carrier can use to reach the recipient about the delivery.
addressobjectrequiredThe address that the physical items of this order go to. It is a record of the order, and it does not change the shipping address of the customer.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
instructionsstringFree-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.
shippingobjectThe address where the customer gets physical goods, such as SIM cards or devices.
Absent when the customer gave no shipping address. A delivery then goes to the billing address.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
deliveryobjectThe address that a delivery to this customer uses. It is shippingAddress when the customer holds one, and billing.address when the customer holds none.
The platform resolves this field. To change it, change one of the two addresses.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
citystringrequiredThe city or municipality of the address.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*string400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
412A precondition for this request was not met.
application/json
A precondition for this request was not met.
A precondition for this request was not met.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
Auth required
Send one of
X-Api-KeyBearer JWT+X-Api-Key
The API key is always required; the bearer token is optional.
curl 'https://apiv2.example.com/api/v2/customers/CUSTOMER_ID/users?userId=USER_ID' \
--request DELETE \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'X-Api-Key: YOUR_API_KEY'fetch('https://apiv2.example.com/api/v2/customers/CUSTOMER_ID/users?userId=USER_ID', {
method: 'DELETE',
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-Api-Key': 'YOUR_API_KEY'
}
})requests.delete(
"https://apiv2.example.com/api/v2/customers/CUSTOMER_ID/users",
headers={
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"X-Api-Key": "YOUR_API_KEY"
},
params={
"userId": "USER_ID"
}
)package main
import (
"fmt"
"io"
"net/http"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/customers/CUSTOMER_ID/users?userId=USER_ID"
req, _ := http.NewRequest("DELETE", 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))
}{
"customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
"customerType": "CONSUMER",
"name": "John Doe",
"identity": "12-3456789",
"preferredLocale": "en-US",
"humanReadableId": "29A-BY3Z-X78",
"referenceId": "crm-customer-12345",
"contact": {
"email": "john.doe@example.com",
"msisdn": "+15551234567"
},
"billing": {
"method": "E_INVOICE",
"email": "billing@company.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"
},
"currency": "USD",
"defaultPaymentProfileId": "c1d2e3f4-a5b6-7890-1234-901234567890",
"autoPay": true
},
"users": [
{
"userId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
"name": "John Doe",
"role": "MEMBER"
}
],
"contactPerson": {
"userId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
"name": "John Doe",
"role": "MEMBER"
},
"shipping": {
"name": "John Doe",
"msisdn": "+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"
},
"instructions": "Leave at front door"
},
"shippingAddress": {
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"city": "Natick",
"zip": "01701",
"country": "US",
"state": "CA",
"region": "Ontario",
"attention": "John Doe"
},
"deliveryAddress": {
"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"
}
}{
"message": "The request body is invalid.",
"code": "bad_request",
"details": [
{
"message": "Email format is invalid.",
"code": "invalid_email",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields."
}{
"message": "Authentication is required to access this resource.",
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header."
}{
"message": "You do not have permission to perform this action.",
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions."
}{
"message": "The requested customer could not be found.",
"code": "not_found",
"hint": "Verify the customerId and try again."
}{
"message": "A precondition given in the request headers was not met.",
"code": "precondition_failed",
"hint": "Fetch the current resource and retry with an up-to-date precondition."
}{
"message": "An unexpected error occurred on the server.",
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support."
}Get customer product catalog
/customers/{customerId}/product-catalogGet the customer's product catalog, this is a combination of the default product catalog configured in the system and other product catalogs assigned to the customer.
Path parameters
customerstringrequiredThe unique identifier of the customer to fetch the product catalog for. 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.
Responses
200Customer product catalog.
application/json
Customer product catalog.
Customer product catalog.
object
The customer's product catalog is a combination of the default product catalog configured in the system and other product catalogs assigned to the customer.
productarray of ProductOfferingGroupThe product groups in this catalog.
Show child attributes
productstringrequiredUnique identifier for the product group.
namestringrequiredName of the product group in the requested locale.
descriptionstringDescription of the product group in the requested locale.
categoryenum<string>requiredA product category is a sub-type for grouping offerings of the same type.
Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.
Categories are grouped by their product type:
SUBSCRIPTION categories:
PRODUCT_CATEGORY_SUBSCRIPTION_CELL- Mobile cellular subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM- Data-only SIM subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND- Broadband internet subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_M2M- Machine-to-machine IoT subscriptionPRODUCT_CATEGORY_TRAVEL_ESIM- Travel eSIM subscription for international roaming
SUBSCRIPTION_ADDON categories:
PRODUCT_CATEGORY_EXTRA_DATA- Additional data package addonPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE- Travel eSIM data package with country/region coveragePRODUCT_CATEGORY_ABROAD- International roaming addon
EXTERNAL_PRODUCT categories:
PRODUCT_CATEGORY_EXTERNAL_PRODUCT- External purchasable productPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON- Addon for external product
SIM_CARD categories:
PRODUCT_CATEGORY_SIM_CARD- Physical SIM or eSIM replacement for an existing subscription
values
PRODUCT_CATEGORY_SUBSCRIPTION_CELLPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIMPRODUCT_CATEGORY_SUBSCRIPTION_BROADBANDPRODUCT_CATEGORY_SUBSCRIPTION_M2MPRODUCT_CATEGORY_TRAVEL_ESIMPRODUCT_CATEGORY_EXTRA_DATAPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGEPRODUCT_CATEGORY_ABROADPRODUCT_CATEGORY_EXTERNAL_PRODUCTPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDONPRODUCT_CATEGORY_SIM_CARD
internalstringInternal description of the product group for operational use only.
productarray of ProductOfferingThe product offerings available in this catalog.
Show child attributes
productstringrequiredUnique identifier for the product offering.
statusenum<string>deprecatedrequiredDeprecated. Use versionStatus instead.
The status of the product offering.
Archived offerings are not allowed to be created/ordered by customers, but can still be used for existing subscriptions.
values
AVAILABLEARCHIVED
versionenum<string>requiredThe stage of this version of the product offering.
DRAFT: The brand edits the version. Nobody can order it.TESTING: The brand tests the version. Nobody can order it.PUBLISHED: Each customer can order the version.UNPUBLISHED: Only a customer with a product catalog that holds the version can order it. Existing subscriptions keep it.ARCHIVED: Nobody can order the version. Existing subscriptions keep it.
values
DRAFTTESTINGPUBLISHEDUNPUBLISHEDARCHIVED
namestringrequiredName of the product offering.
descriptionstringDescription of the product offering.
richstringRich HTML content with detailed information about the product offering.
usparray of stringShort plain-text selling points, in the order the brand put them. A storefront shows them as a checklist.
productobjectrequiredEmbedded representation of a product.
Show child attributes
productstringrequiredThe unique identifier for the product.
internalstringrequiredThe name used to identify the product internally in the catalog. Not intended for customer display — use the product offering name instead.
typeenum<string>requiredThe type of product offering determines how it can be used and what kind of resource it creates.
SUBSCRIPTION Creates a standalone subscription resource (e.g., mobile plan, broadband, travel eSIM).
- Includes categories like
SUBSCRIPTION_CELL,TRAVEL_ESIM - Can be created via order or directly depending on configuration
- Has its own lifecycle (activation, suspension, termination)
SUBSCRIPTION_ADDON Adds features or resources to an existing subscription.
- Includes categories like
TRAVEL_ESIM_PACKAGE - Must be attached to a parent subscription
LICENSE Creates a license for business/PBX features.
- Typically used for enterprise telephony features
EXTERNAL_PRODUCT Represents purchasable items outside the core telecom platform.
- Can only be ordered via orders, not created directly
SIM_CARD Replaces the SIM card for an existing subscription through a subscription change order.
values
SUBSCRIPTIONSUBSCRIPTION_ADDONLICENSEEXTERNAL_PRODUCTSIM_CARD
categoryenum<string>requiredA product category is a sub-type for grouping offerings of the same type.
Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.
Categories are grouped by their product type:
SUBSCRIPTION categories:
PRODUCT_CATEGORY_SUBSCRIPTION_CELL- Mobile cellular subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM- Data-only SIM subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND- Broadband internet subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_M2M- Machine-to-machine IoT subscriptionPRODUCT_CATEGORY_TRAVEL_ESIM- Travel eSIM subscription for international roaming
SUBSCRIPTION_ADDON categories:
PRODUCT_CATEGORY_EXTRA_DATA- Additional data package addonPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE- Travel eSIM data package with country/region coveragePRODUCT_CATEGORY_ABROAD- International roaming addon
EXTERNAL_PRODUCT categories:
PRODUCT_CATEGORY_EXTERNAL_PRODUCT- External purchasable productPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON- Addon for external product
SIM_CARD categories:
PRODUCT_CATEGORY_SIM_CARD- Physical SIM or eSIM replacement for an existing subscription
values
PRODUCT_CATEGORY_SUBSCRIPTION_CELLPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIMPRODUCT_CATEGORY_SUBSCRIPTION_BROADBANDPRODUCT_CATEGORY_SUBSCRIPTION_M2MPRODUCT_CATEGORY_TRAVEL_ESIMPRODUCT_CATEGORY_EXTRA_DATAPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGEPRODUCT_CATEGORY_ABROADPRODUCT_CATEGORY_EXTERNAL_PRODUCTPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDONPRODUCT_CATEGORY_SIM_CARD
networkstringThe unique identifier for the network provider.
featuresobjectThe features included with the product, if any. Typically used for telecom products.
Show child attributes
priceobjectrequiredThe cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.
Show child attributes
netintegerint64The configured price of the offering, in minor currency units. When includesTax is
true, this amount is the total the customer pays, and the tax is a part of it.
includesbooleanTrue when the configured price includes its tax. The tax is then a part of
netPriceMinor rather than an amount on top of it.
currencystringrequiredThe ISO 4217 currency code the price is expressed in (e.g., "USD").
priceenum<string>requiredHow the price is charged.
- ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).
- RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).
values
ONE_TIMERECURRING
bindingobjectA commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.
Show child attributes
standardobjectA recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.
Show child attributes
customobjectBilling cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out.
Show child attributes
billingobjectHow often a recurring price is charged.
Show child attributes
currencyobject with string keysPer-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.
Show child attributes
groupobjectA product group organizes related product offerings.
Show child attributes
productstringrequiredUnique identifier for the product group.
namestringrequiredName of the product group in the requested locale.
descriptionstringDescription of the product group in the requested locale.
categoryenum<string>requiredA product category is a sub-type for grouping offerings of the same type.
Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though.
Categories are grouped by their product type:
SUBSCRIPTION categories:
PRODUCT_CATEGORY_SUBSCRIPTION_CELL- Mobile cellular subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM- Data-only SIM subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND- Broadband internet subscriptionPRODUCT_CATEGORY_SUBSCRIPTION_M2M- Machine-to-machine IoT subscriptionPRODUCT_CATEGORY_TRAVEL_ESIM- Travel eSIM subscription for international roaming
SUBSCRIPTION_ADDON categories:
PRODUCT_CATEGORY_EXTRA_DATA- Additional data package addonPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE- Travel eSIM data package with country/region coveragePRODUCT_CATEGORY_ABROAD- International roaming addon
EXTERNAL_PRODUCT categories:
PRODUCT_CATEGORY_EXTERNAL_PRODUCT- External purchasable productPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON- Addon for external product
SIM_CARD categories:
PRODUCT_CATEGORY_SIM_CARD- Physical SIM or eSIM replacement for an existing subscription
values
PRODUCT_CATEGORY_SUBSCRIPTION_CELLPRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIMPRODUCT_CATEGORY_SUBSCRIPTION_BROADBANDPRODUCT_CATEGORY_SUBSCRIPTION_M2MPRODUCT_CATEGORY_TRAVEL_ESIMPRODUCT_CATEGORY_EXTRA_DATAPRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGEPRODUCT_CATEGORY_ABROADPRODUCT_CATEGORY_EXTERNAL_PRODUCTPRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDONPRODUCT_CATEGORY_SIM_CARD
internalstringInternal description of the product group for operational use only.
customerenum<string>requiredWhether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.
values
CONSUMERBUSINESS
addonarray of ProductCategoryList of product categories this addon is applicable for.
Only populated when type is SUBSCRIPTION_ADDON.
For example, a TRAVEL_ESIM_PACKAGE addon might be applicable to TRAVEL_ESIM subscriptions.
internalstringInternal description of the product offering for operational use only.
imagestringuriURL to the image representing the product offering.
metadataobject with string keysA set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
Show child attributes
*stringbroadbandobjectThe values of the FCC Broadband Facts label that differ for each plan. A US storefront shows the label next to each plan it sells. Only an offering that the brand gave these values has them. The label shows the amounts in the currency of the price.
Show child attributes
planstringrequired15 characters of A-Z and 0-9, unique among the offerings of the brand. The unique plan
identifier on the label is M, then the FCC Registration Number of the brand, then this code.
monthlyarray of BroadbandFactsFeerequiredThe fees that the provider adds to the monthly price.
Show child attributes
singlearray of BroadbandFactsFeerequiredThe fees that the customer pays one time, when they buy the plan.
Show child attributes
earlyintegerint64requiredThe fee to end the plan early, in minor currency units. Always 0, because the platform charges no such fee.
overintegerint64requiredThe price of more data after the allowance, in minor currency units. Always 0, because the platform charges no such price.
additionalnumberrequiredThe amount of data, in GB, that overUsageDataPriceMinor buys. Always 0, because the platform sells no data after the allowance.
unlimitedbooleanrequiredTrue when the plan has no data limit. The label then shows "Unlimited" as the data that the monthly price includes, and not the data allowance of the product.
initialarray of stringThe initial product offerings. An order can take them on a SUBSCRIPTION line item or on an EXTERNAL_PRODUCT line item.
If no catalog of the customer limits its initial offerings, the list holds each product offering of the catalog.
A catalog that limits its initial offerings gives only the product offerings of its list.
An add-on and an offering change do not use this list.
400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
429Too many requests have been sent in a given amount of time.
application/json
Too many requests have been sent in a given amount of time.
Too many requests have been sent in a given amount of time.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
messagestringrequiredA human-readable message providing more details about the error.
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
hintstringA hint to help resolve the error.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
spanstringThe span within the trace that failed.
Auth required
Send one of
X-Api-KeyBearer JWT+X-Api-Key
The API key is always required; the bearer token is optional.
curl https://apiv2.example.com/api/v2/customers/CUSTOMER_ID/product-catalog \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'X-Api-Key: YOUR_API_KEY'fetch('https://apiv2.example.com/api/v2/customers/CUSTOMER_ID/product-catalog', {
headers: {
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'X-Api-Key': 'YOUR_API_KEY'
}
})requests.get(
"https://apiv2.example.com/api/v2/customers/CUSTOMER_ID/product-catalog",
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/customers/CUSTOMER_ID/product-catalog"
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))
}{
"productOfferingGroups": [
{
"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"
}
],
"productOfferings": [
{
"productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"status": "AVAILABLE",
"versionStatus": "PUBLISHED",
"name": "Seamless 10GB",
"description": "Basic mobile plan with 5GB data and unlimited calls",
"richContent": "<h3>Features</h3><ul><li>5GB monthly data</li><li>Unlimited calls & texts</li><li>No setup fees</li></ul>",
"uspList": [
"5GB of data every month",
"Unlimited calls and texts",
"No setup fee"
],
"product": {
"productId": "d4e5f6a7-b8c9-0123-4567-890123456789",
"internalName": "us-mobile-unlimited-5gb",
"type": "SUBSCRIPTION",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"networkProviderId": "tmobile-us",
"features": {
"dataMb": 2048,
"includedCallSeconds": 1000,
"includedSms": 500,
"validityDays": 30,
"countries": [
"USA",
"CAN",
"MEX"
],
"regions": [
"NORTH_AMERICA"
],
"activationType": "INSTANT",
"simCardType": "PSIM"
}
},
"price": {
"netPriceMinor": 2999,
"includesTax": false,
"currency": "USD",
"priceType": "ONE_TIME",
"bindingContract": {
"duration": {
"unit": "MONTHS",
"value": 3
},
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"standardDiscount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
},
"customUpfrontPayment": {
"billingCycles": 3,
"discount": {
"amountMinor": 500,
"duration": {
"unit": "MONTHS",
"value": 3
},
"source": "STANDARD",
"invoicingDescription": "Campaign discount"
}
},
"billingCycle": {
"period": "MONTHLY",
"interval": 1
},
"currencyOptionsMinor": {
"propertyName": 1
}
},
"group": {
"productOfferingGroupId": "mobile-plans",
"name": "Mobile Plans",
"description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
"category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
"internalDescription": "Core mobile offerings targeting consumer and business segments"
},
"customerType": "CONSUMER",
"addonCategories": [
"PRODUCT_CATEGORY_SUBSCRIPTION_CELL"
],
"internalDescription": "seamless_cell_10gb_us",
"imageUrl": "https://cdn.example.com/images/mobile-basic.png",
"metadata": {
"propertyName": "string"
},
"broadbandFacts": {
"planCode": "FLEXSTANDARD001",
"monthlyProviderFees": [
{
"name": "Federal Universal Service Fund",
"amountMinor": 21
}
],
"singlePurchaseFees": [
{
"name": "Federal Universal Service Fund",
"amountMinor": 21
}
],
"earlyTerminationFeeMinor": 0,
"overUsageDataPriceMinor": 0,
"additionalDataIncrementGb": 0,
"unlimitedData": false
}
}
],
"initialProductOfferingIds": [
"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": "Too many requests. Please slow down.",
"code": "too_many_requests",
"hint": "Retry after the number of seconds indicated in the Retry-After header."
}{
"message": "An unexpected error occurred on the server.",
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support."
}