Customers

Manage customers.

List customers

GET/customers

List all customers.

Will return all customers the requester has access to.

Query parameters

filterstring

A free text search string to filter customers.

limitinteger>= 1<= 1000default 100

The maximum number of items to return.

cursorstring

Opaque pagination token from a previous response's nextCursor.

Responses

200

A list of customers.

application/json

A list of customers.

object

itemsarray of Customerrequired

Show child attributes

customerIdstringrequired

Unique identifier for the customer.

customerTypeenum<string>required

Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.

values

CONSUMER
BUSINESS

namestringrequired

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

identitystring

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

preferredLocalestringdefault en-US

The preferred locale for the customer, in IETF BCP 47 format (e.g., "en-US", "sv-SE").

humanReadableIdstring

A human-readable identifier for the customer that customers can state in support requests.

referenceIdstringmax length 255

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

contactobjectrequired

Contact details for the customer.

Show child attributes

emailstringemail

The primary contact email for the customer.

msisdnstringphone

The primary contact phone number for the customer.

billingobject

Billing configuration and payment preferences for the customer.

Show child attributes

methodenum<string>required

How 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_INVOICE
EMAIL_INVOICE
PAPER_INVOICE

emailstringemail

The email address to send invoices to. Required if billing method is EMAIL_INVOICE.

addressobject

The billing address for the customer. Required if billing method is PAPER_INVOICE.

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

Show child attributes

currencystringrequired

The currency for customer billing and payments.

The three-letter ISO 4217 code of the currency used for prices, billing, and payments.

defaultPaymentProfileIdstring

Default payment profile to use for automatic payments and new orders. If specified, enables automatic payment collection for invoices and bills.

autoPaybooleandefault false

Whether 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 EmbeddedCustomerUser

The users associated with this customer, each with the role that governs what they can manage on the customer's account.

Show child attributes

userIdstringrequired

Unique identifier for the user. Use it with the user endpoints to fetch full details.

namestringrequired

The 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

MEMBER
MANAGER
ADMIN

contactPersonobject

The 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

userIdstringrequired

Unique identifier for the user. Use it with the user endpoints to fetch full details.

namestringrequired

The 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

MEMBER
MANAGER
ADMIN

shippingobject

The shipping address for the customer.

This address is used for shipping physical goods to the customer, such as SIM cards or devices. It is also used to pre-fill the address when ordering physical goods.

Shipping information for order fulfillment. Only required if the order contains shippable items.

Show child attributes

namestringrequired

Full name of the person or department receiving the delivery, printed on the shipping label.

msisdnstringphone

Phone number the carrier can use to reach the recipient about the delivery.

addressobjectrequired

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

Show child attributes

instructionsstring

Free-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.

metadataobject with string keys

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

Show child attributes

*string

paginationobjectrequired

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

Show child attributes

nextCursorstring | nullrequired

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

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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

internalCodestring

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

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

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

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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

internalCodestring

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

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

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

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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

internalCodestring

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

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

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

spanIdstring

The span within the trace that failed.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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

internalCodestring

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

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

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

spanIdstring

The span within the trace that failed.

429

Too many requests have been sent in a given amount of time.

application/json

Too many requests have been sent in a given amount of time.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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

internalCodestring

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

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

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

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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

internalCodestring

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

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

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

spanIdstring

The span within the trace that failed.

Auth required

Send one of

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

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

GET /customers

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"
      },
      "shipping": {
        "name": "John Doe",
        "msisdn": "+15551234567",
        "address": {
          "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

POST/customers

Create a new customer.

Headers

X-Idempotency-Keystringmax length 256

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

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

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.

customerTypeenum<string>required

Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.

values

CONSUMER
BUSINESS

namestringrequired

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

identitystring

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

referenceIdstringmax length 255

Optional reference ID to assign to the customer. Must be unique per tenant.

preferredLocalestringdefault en-US

The preferred locale for the customer, in IETF BCP 47 format (e.g., "en-US", "sv-SE").

contactobjectrequired

Contact details for the customer.

Show child attributes

emailstringemailrequired

The primary contact email for the customer.

msisdnstringphone

The primary contact phone number for the customer.

billingobjectrequired

Billing configuration and payment preferences for the customer.

Show child attributes

methodenum<string>required

How 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_INVOICE
EMAIL_INVOICE
PAPER_INVOICE

emailstringemail

The email address to send invoices to. Required if billing method is EMAIL_INVOICE.

addressobject

The billing address for the customer. Used for invoicing and tax calculation.

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

Show child attributes

streetstring

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

street1stringdeprecatedrequired

Deprecated. Use street instead.

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

street2string

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

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

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

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

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

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

statestring

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

regionstring

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

attentionstring

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

currencystringrequired

The currency for customer billing and payments.

The three-letter ISO 4217 code of the currency used for prices, billing, and payments.

defaultPaymentProfileIdstring

Default payment profile to use for automatic payments and new orders. Must be a payment profile that will be accessible to this customer.

autoPaybooleandefault false

Whether to automatically charge the default payment profile for invoices and bills. Requires defaultPaymentProfileId to be set.

userIdsarray of stringrequired

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

contactPersonUserIdstringrequired

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

shippingobject

The default shipping address for the customer.

This address is used for shipping physical goods to the customer, such as SIM cards or devices. It is also used to pre-fill the address when ordering physical goods.

Shipping information for order fulfillment. Only required if the order contains shippable items.

Show child attributes

namestringrequired

Full name of the person or department receiving the delivery, printed on the shipping label.

msisdnstringphone

Phone number the carrier can use to reach the recipient about the delivery.

addressobjectrequired

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

Show child attributes

streetstring

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

street1stringdeprecatedrequired

Deprecated. Use street instead.

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

street2string

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

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

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

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

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

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

statestring

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

regionstring

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

attentionstring

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

instructionsstring

Free-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.

metadataobject with string keys

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

Show child attributes

*string

Responses

201

Customer created successfully.

application/json

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.

customerIdstringrequired

Unique identifier for the customer.

customerTypeenum<string>required

Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.

values

CONSUMER
BUSINESS

namestringrequired

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

identitystring

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

preferredLocalestringdefault en-US

The preferred locale for the customer, in IETF BCP 47 format (e.g., "en-US", "sv-SE").

humanReadableIdstring

A human-readable identifier for the customer that customers can state in support requests.

referenceIdstringmax length 255

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

contactobjectrequired

Contact details for the customer.

Show child attributes

emailstringemail

The primary contact email for the customer.

msisdnstringphone

The primary contact phone number for the customer.

billingobject

Billing configuration and payment preferences for the customer.

Show child attributes

methodenum<string>required

How 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_INVOICE
EMAIL_INVOICE
PAPER_INVOICE

emailstringemail

The email address to send invoices to. Required if billing method is EMAIL_INVOICE.

addressobject

The billing address for the customer. Required if billing method is PAPER_INVOICE.

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

Show child attributes

streetstring

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

street1stringdeprecatedrequired

Deprecated. Use street instead.

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

street2string

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

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

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

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

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

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

statestring

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

regionstring

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

attentionstring

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

currencystringrequired

The currency for customer billing and payments.

The three-letter ISO 4217 code of the currency used for prices, billing, and payments.

defaultPaymentProfileIdstring

Default payment profile to use for automatic payments and new orders. If specified, enables automatic payment collection for invoices and bills.

autoPaybooleandefault false

Whether 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 EmbeddedCustomerUser

The users associated with this customer, each with the role that governs what they can manage on the customer's account.

Show child attributes

userIdstringrequired

Unique identifier for the user. Use it with the user endpoints to fetch full details.

namestringrequired

The 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

MEMBER
MANAGER
ADMIN

contactPersonobject

The 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

userIdstringrequired

Unique identifier for the user. Use it with the user endpoints to fetch full details.

namestringrequired

The 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

MEMBER
MANAGER
ADMIN

shippingobject

The shipping address for the customer.

This address is used for shipping physical goods to the customer, such as SIM cards or devices. It is also used to pre-fill the address when ordering physical goods.

Shipping information for order fulfillment. Only required if the order contains shippable items.

Show child attributes

namestringrequired

Full name of the person or department receiving the delivery, printed on the shipping label.

msisdnstringphone

Phone number the carrier can use to reach the recipient about the delivery.

addressobjectrequired

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

Show child attributes

streetstring

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

street1stringdeprecatedrequired

Deprecated. Use street instead.

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

street2string

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

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

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

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

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

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

statestring

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

regionstring

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

attentionstring

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

instructionsstring

Free-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.

metadataobject with string keys

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

Show child attributes

*string

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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

internalCodestring

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

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

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

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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

internalCodestring

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

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

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

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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

internalCodestring

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

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

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

spanIdstring

The span within the trace that failed.

409

The request conflicts with the current state of the resource.

application/json

The request conflicts with the current state of the resource.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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

internalCodestring

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

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

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

spanIdstring

The span within the trace that failed.

429

Too many requests have been sent in a given amount of time.

application/json

Too many requests have been sent in a given amount of time.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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

internalCodestring

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

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

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

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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

internalCodestring

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

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

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

spanIdstring

The span within the trace that failed.

Auth required

Send one of

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

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

POST /customers

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",
  "shipping": {
    "name": "John Doe",
    "msisdn": "+15551234567",
    "address": {
      "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',
    shipping: {
      name: 'John Doe',
      msisdn: '+15551234567',
      address: {
        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",
      "shipping": {
        "name": "John Doe",
        "msisdn": "+15551234567",
        "address": {
          "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",
  "shipping": {
    "name": "John Doe",
    "msisdn": "+15551234567",
    "address": {
      "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"
  },
  "shipping": {
    "name": "John Doe",
    "msisdn": "+15551234567",
    "address": {
      "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

GET/customers/{customerId}

Get a customer by ID or referenceId.

Path parameters

customerIdstringrequired

The 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

200

Customer details.

application/json

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.

customerIdstringrequired

Unique identifier for the customer.

customerTypeenum<string>required

Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.

values

CONSUMER
BUSINESS

namestringrequired

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

identitystring

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

preferredLocalestringdefault en-US

The preferred locale for the customer, in IETF BCP 47 format (e.g., "en-US", "sv-SE").

humanReadableIdstring

A human-readable identifier for the customer that customers can state in support requests.

referenceIdstringmax length 255

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

contactobjectrequired

Contact details for the customer.

Show child attributes

emailstringemail

The primary contact email for the customer.

msisdnstringphone

The primary contact phone number for the customer.

billingobject

Billing configuration and payment preferences for the customer.

Show child attributes

methodenum<string>required

How 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_INVOICE
EMAIL_INVOICE
PAPER_INVOICE

emailstringemail

The email address to send invoices to. Required if billing method is EMAIL_INVOICE.

addressobject

The billing address for the customer. Required if billing method is PAPER_INVOICE.

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

Show child attributes

streetstring

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

street1stringdeprecatedrequired

Deprecated. Use street instead.

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

street2string

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

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

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

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

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

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

statestring

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

regionstring

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

attentionstring

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

currencystringrequired

The currency for customer billing and payments.

The three-letter ISO 4217 code of the currency used for prices, billing, and payments.

defaultPaymentProfileIdstring

Default payment profile to use for automatic payments and new orders. If specified, enables automatic payment collection for invoices and bills.

autoPaybooleandefault false

Whether 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 EmbeddedCustomerUser

The users associated with this customer, each with the role that governs what they can manage on the customer's account.

Show child attributes

userIdstringrequired

Unique identifier for the user. Use it with the user endpoints to fetch full details.

namestringrequired

The 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

MEMBER
MANAGER
ADMIN

contactPersonobject

The 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

userIdstringrequired

Unique identifier for the user. Use it with the user endpoints to fetch full details.

namestringrequired

The 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

MEMBER
MANAGER
ADMIN

shippingobject

The shipping address for the customer.

This address is used for shipping physical goods to the customer, such as SIM cards or devices. It is also used to pre-fill the address when ordering physical goods.

Shipping information for order fulfillment. Only required if the order contains shippable items.

Show child attributes

namestringrequired

Full name of the person or department receiving the delivery, printed on the shipping label.

msisdnstringphone

Phone number the carrier can use to reach the recipient about the delivery.

addressobjectrequired

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

Show child attributes

streetstring

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

street1stringdeprecatedrequired

Deprecated. Use street instead.

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

street2string

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

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

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

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

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

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

statestring

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

regionstring

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

attentionstring

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

instructionsstring

Free-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.

metadataobject with string keys

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

Show child attributes

*string

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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

internalCodestring

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

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

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

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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

internalCodestring

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

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

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

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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

internalCodestring

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

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

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

spanIdstring

The span within the trace that failed.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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

internalCodestring

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

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

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

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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

internalCodestring

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

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

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

spanIdstring

The span within the trace that failed.

Auth required

Send one of

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

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

GET /customers/{customerId}

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"
  },
  "shipping": {
    "name": "John Doe",
    "msisdn": "+15551234567",
    "address": {
      "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

PUT/customers/{customerId}

Update an existing customer.

Path parameters

customerIdstringrequired

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

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

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

BodyUpdateCustomerRequestrequiredapplication/json

The customer fields to change. Only provided fields are updated; omitted fields keep their current values.

namestring

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

identitystring

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

preferredLocalestring

The preferred locale for the customer, in IETF BCP 47 format (e.g., "en-US", "sv-SE").

contactobject

Contact details for the customer.

Show child attributes

emailstringemail

The primary contact email for the customer.

msisdnstringphone

The primary contact phone number for the customer.

billingobject

Billing 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_INVOICE
EMAIL_INVOICE
PAPER_INVOICE

emailstringemail

The email address to send invoices to.

Required if billing method is EMAIL_INVOICE.

addressobject

The billing address for the customer.

Required if billing method is PAPER_INVOICE.

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

Show child attributes

streetstring

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

street1stringdeprecatedrequired

Deprecated. Use street instead.

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

street2string

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

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

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

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

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

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

statestring

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

regionstring

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

attentionstring

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

currencystring

The currency for the customer billing.

The three-letter ISO 4217 code of the currency used for prices, billing, and payments.

defaultPaymentProfileIdstring

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

autoPayboolean

Whether to automatically pay invoices for this customer if a valid payment method is available.

userIdsarray of string

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

shippingAddressobject

The shipping address for the customer.

This address is used for shipping physical goods to the customer, such as SIM cards or devices. It is also used to pre-fill the address when ordering physical goods.

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

Show child attributes

streetstring

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

street1stringdeprecatedrequired

Deprecated. Use street instead.

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

street2string

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

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

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

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

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

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

statestring

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

regionstring

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

attentionstring

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

metadataobject with string keys

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

Show child attributes

*string

Responses

200

Customer updated successfully.

application/json

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.

customerIdstringrequired

Unique identifier for the customer.

customerTypeenum<string>required

Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.

values

CONSUMER
BUSINESS

namestringrequired

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

identitystring

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

preferredLocalestringdefault en-US

The preferred locale for the customer, in IETF BCP 47 format (e.g., "en-US", "sv-SE").

humanReadableIdstring

A human-readable identifier for the customer that customers can state in support requests.

referenceIdstringmax length 255

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

contactobjectrequired

Contact details for the customer.

Show child attributes

emailstringemail

The primary contact email for the customer.

msisdnstringphone

The primary contact phone number for the customer.

billingobject

Billing configuration and payment preferences for the customer.

Show child attributes

methodenum<string>required

How 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_INVOICE
EMAIL_INVOICE
PAPER_INVOICE

emailstringemail

The email address to send invoices to. Required if billing method is EMAIL_INVOICE.

addressobject

The billing address for the customer. Required if billing method is PAPER_INVOICE.

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

Show child attributes

streetstring

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

street1stringdeprecatedrequired

Deprecated. Use street instead.

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

street2string

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

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

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

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

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

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

statestring

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

regionstring

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

attentionstring

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

currencystringrequired

The currency for customer billing and payments.

The three-letter ISO 4217 code of the currency used for prices, billing, and payments.

defaultPaymentProfileIdstring

Default payment profile to use for automatic payments and new orders. If specified, enables automatic payment collection for invoices and bills.

autoPaybooleandefault false

Whether 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 EmbeddedCustomerUser

The users associated with this customer, each with the role that governs what they can manage on the customer's account.

Show child attributes

userIdstringrequired

Unique identifier for the user. Use it with the user endpoints to fetch full details.

namestringrequired

The 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

MEMBER
MANAGER
ADMIN

contactPersonobject

The 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

userIdstringrequired

Unique identifier for the user. Use it with the user endpoints to fetch full details.

namestringrequired

The 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

MEMBER
MANAGER
ADMIN

shippingobject

The shipping address for the customer.

This address is used for shipping physical goods to the customer, such as SIM cards or devices. It is also used to pre-fill the address when ordering physical goods.

Shipping information for order fulfillment. Only required if the order contains shippable items.

Show child attributes

namestringrequired

Full name of the person or department receiving the delivery, printed on the shipping label.

msisdnstringphone

Phone number the carrier can use to reach the recipient about the delivery.

addressobjectrequired

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

Show child attributes

streetstring

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

street1stringdeprecatedrequired

Deprecated. Use street instead.

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

street2string

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

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

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

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

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

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

statestring

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

regionstring

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

attentionstring

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

instructionsstring

Free-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.

metadataobject with string keys

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

Show child attributes

*string

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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

internalCodestring

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

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

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

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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

internalCodestring

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

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

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

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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

internalCodestring

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

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

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

spanIdstring

The span within the trace that failed.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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

internalCodestring

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

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

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

spanIdstring

The span within the trace that failed.

409

The request conflicts with the current state of the resource.

application/json

The request conflicts with the current state of the resource.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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

internalCodestring

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

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

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

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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

internalCodestring

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

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

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

spanIdstring

The span within the trace that failed.

Auth required

Send one of

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

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

PUT /customers/{customerId}

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"
  },
  "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

DELETE/customers/{customerId}/users

Remove 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

customerIdstringrequired

The 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

userIdstringrequired

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

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

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

Responses

200

User removed from customer successfully.

application/json

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.

customerIdstringrequired

Unique identifier for the customer.

customerTypeenum<string>required

Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.

values

CONSUMER
BUSINESS

namestringrequired

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

identitystring

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

preferredLocalestringdefault en-US

The preferred locale for the customer, in IETF BCP 47 format (e.g., "en-US", "sv-SE").

humanReadableIdstring

A human-readable identifier for the customer that customers can state in support requests.

referenceIdstringmax length 255

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

contactobjectrequired

Contact details for the customer.

Show child attributes

emailstringemail

The primary contact email for the customer.

msisdnstringphone

The primary contact phone number for the customer.

billingobject

Billing configuration and payment preferences for the customer.

Show child attributes

methodenum<string>required

How 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_INVOICE
EMAIL_INVOICE
PAPER_INVOICE

emailstringemail

The email address to send invoices to. Required if billing method is EMAIL_INVOICE.

addressobject

The billing address for the customer. Required if billing method is PAPER_INVOICE.

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

Show child attributes

streetstring

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

street1stringdeprecatedrequired

Deprecated. Use street instead.

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

street2string

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

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

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

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

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

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

statestring

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

regionstring

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

attentionstring

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

currencystringrequired

The currency for customer billing and payments.

The three-letter ISO 4217 code of the currency used for prices, billing, and payments.

defaultPaymentProfileIdstring

Default payment profile to use for automatic payments and new orders. If specified, enables automatic payment collection for invoices and bills.

autoPaybooleandefault false

Whether 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 EmbeddedCustomerUser

The users associated with this customer, each with the role that governs what they can manage on the customer's account.

Show child attributes

userIdstringrequired

Unique identifier for the user. Use it with the user endpoints to fetch full details.

namestringrequired

The 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

MEMBER
MANAGER
ADMIN

contactPersonobject

The 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

userIdstringrequired

Unique identifier for the user. Use it with the user endpoints to fetch full details.

namestringrequired

The 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

MEMBER
MANAGER
ADMIN

shippingobject

The shipping address for the customer.

This address is used for shipping physical goods to the customer, such as SIM cards or devices. It is also used to pre-fill the address when ordering physical goods.

Shipping information for order fulfillment. Only required if the order contains shippable items.

Show child attributes

namestringrequired

Full name of the person or department receiving the delivery, printed on the shipping label.

msisdnstringphone

Phone number the carrier can use to reach the recipient about the delivery.

addressobjectrequired

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

Show child attributes

streetstring

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

street1stringdeprecatedrequired

Deprecated. Use street instead.

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

street2string

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

citystringrequired

The city or municipality of the address.

zipstringrequired

The zip code of the address.

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

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

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

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

statestring

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

regionstring

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

attentionstring

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

instructionsstring

Free-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.

metadataobject with string keys

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

Show child attributes

*string

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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

internalCodestring

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

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

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

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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

internalCodestring

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

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

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

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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

internalCodestring

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

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

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

spanIdstring

The span within the trace that failed.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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

internalCodestring

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

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

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

spanIdstring

The span within the trace that failed.

412

A precondition for this request was not met.

application/json

A precondition for this request was not met.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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

internalCodestring

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

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

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

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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

internalCodestring

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

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

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

spanIdstring

The span within the trace that failed.

Auth required

Send one of

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

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

DELETE /customers/{customerId}/users

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"
  },
  "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

GET/customers/{customerId}/product-catalog

Get 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

customerIdstringrequired

The 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

200

Customer product catalog.

application/json

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.

productOfferingGroupsarray of ProductOfferingGroup

The product groups in this catalog.

Show child attributes

productOfferingGroupIdstringrequired

Unique identifier for the product group.

namestringrequired

Name of the product group in the requested locale.

descriptionstring

Description of the product group in the requested locale.

categoryenum<string>required

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

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

Categories are grouped by their product type:

SUBSCRIPTION categories:

PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming

SUBSCRIPTION_ADDON categories:

PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
PRODUCT_CATEGORY_ABROAD - International roaming addon

EXTERNAL_PRODUCT categories:

PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

SIM_CARD categories:

PRODUCT_CATEGORY_SIM_CARD - Physical SIM or eSIM replacement for an existing subscription

values

PRODUCT_CATEGORY_SUBSCRIPTION_CELL
PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
PRODUCT_CATEGORY_SUBSCRIPTION_M2M
PRODUCT_CATEGORY_TRAVEL_ESIM
PRODUCT_CATEGORY_EXTRA_DATA
PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
PRODUCT_CATEGORY_ABROAD
PRODUCT_CATEGORY_EXTERNAL_PRODUCT
PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
PRODUCT_CATEGORY_SIM_CARD

internalDescriptionstring

Internal description of the product group for operational use only.

productOfferingsarray of ProductOffering

The product offerings available in this catalog.

Show child attributes

productOfferingIdstringrequired

Unique identifier for the product offering.

statusenum<string>required

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

AVAILABLE
ARCHIVED

namestringrequired

Name of the product offering.

descriptionstring

Description of the product offering.

richContentstring

Rich HTML content with detailed information about the product offering.

uspListarray of string

Short plain-text selling points, in the order the brand put them. A storefront shows them as a checklist.

productobjectrequired

Embedded representation of a product.

Show child attributes

productIdstringrequired

The unique identifier for the product.

internalNamestringrequired

The name used to identify the product internally in the catalog. Not intended for customer display — use the product offering name instead.

typeenum<string>required

The 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

SUBSCRIPTION
SUBSCRIPTION_ADDON
LICENSE
EXTERNAL_PRODUCT
SIM_CARD

categoryenum<string>required

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

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

Categories are grouped by their product type:

SUBSCRIPTION categories:

PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming

SUBSCRIPTION_ADDON categories:

PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
PRODUCT_CATEGORY_ABROAD - International roaming addon

EXTERNAL_PRODUCT categories:

PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

SIM_CARD categories:

PRODUCT_CATEGORY_SIM_CARD - Physical SIM or eSIM replacement for an existing subscription

values

PRODUCT_CATEGORY_SUBSCRIPTION_CELL
PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
PRODUCT_CATEGORY_SUBSCRIPTION_M2M
PRODUCT_CATEGORY_TRAVEL_ESIM
PRODUCT_CATEGORY_EXTRA_DATA
PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
PRODUCT_CATEGORY_ABROAD
PRODUCT_CATEGORY_EXTERNAL_PRODUCT
PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
PRODUCT_CATEGORY_SIM_CARD

networkProviderIdstring

The unique identifier for the network provider.

featuresobject

The features included with the product, if any. Typically used for telecom products.

Show child attributes

priceobjectrequired

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

Show child attributes

netPriceMinorintegerint64

The configured price of the offering, in minor currency units.

currencystringrequired

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

priceTypeenum<string>required

How the price is charged.

ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).
RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).

values

ONE_TIME
RECURRING

bindingContractobject

A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment.

Show child attributes

standardDiscountobject

A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all.

Show child attributes

customUpfrontPaymentobject

Billing cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out.

Show child attributes

billingCycleobject

How often a recurring price is charged.

Show child attributes

currencyOptionsMinorobject with string keys

Per-currency price overrides keyed by three-letter ISO currency code (e.g. "USD", "SEK"). Each value is the cost in that currency, in minor currency units.

Show child attributes

groupobject

A product group organizes related product offerings.

Show child attributes

productOfferingGroupIdstringrequired

Unique identifier for the product group.

namestringrequired

Name of the product group in the requested locale.

descriptionstring

Description of the product group in the requested locale.

categoryenum<string>required

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

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

Categories are grouped by their product type:

SUBSCRIPTION categories:

PRODUCT_CATEGORY_SUBSCRIPTION_CELL - Mobile cellular subscription
PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM - Data-only SIM subscription
PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND - Broadband internet subscription
PRODUCT_CATEGORY_SUBSCRIPTION_M2M - Machine-to-machine IoT subscription
PRODUCT_CATEGORY_TRAVEL_ESIM - Travel eSIM subscription for international roaming

SUBSCRIPTION_ADDON categories:

PRODUCT_CATEGORY_EXTRA_DATA - Additional data package addon
PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE - Travel eSIM data package with country/region coverage
PRODUCT_CATEGORY_ABROAD - International roaming addon

EXTERNAL_PRODUCT categories:

PRODUCT_CATEGORY_EXTERNAL_PRODUCT - External purchasable product
PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON - Addon for external product

SIM_CARD categories:

PRODUCT_CATEGORY_SIM_CARD - Physical SIM or eSIM replacement for an existing subscription

values

PRODUCT_CATEGORY_SUBSCRIPTION_CELL
PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM
PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND
PRODUCT_CATEGORY_SUBSCRIPTION_M2M
PRODUCT_CATEGORY_TRAVEL_ESIM
PRODUCT_CATEGORY_EXTRA_DATA
PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE
PRODUCT_CATEGORY_ABROAD
PRODUCT_CATEGORY_EXTERNAL_PRODUCT
PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON
PRODUCT_CATEGORY_SIM_CARD

internalDescriptionstring

Internal description of the product group for operational use only.

customerTypeenum<string>required

Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.

values

CONSUMER
BUSINESS

addonCategoriesarray of ProductCategory

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

internalDescriptionstring

Internal description of the product offering for operational use only.

imageUrlstringuri

URL to the image representing the product offering.

metadataobject with string keys

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

Show child attributes

*string

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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

internalCodestring

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

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

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

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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

internalCodestring

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

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

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

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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

internalCodestring

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

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

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

spanIdstring

The span within the trace that failed.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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

internalCodestring

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

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

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

spanIdstring

The span within the trace that failed.

429

Too many requests have been sent in a given amount of time.

application/json

Too many requests have been sent in a given amount of time.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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

internalCodestring

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

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

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

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

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

messagestringrequired

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

codestringdeprecatedrequired

Deprecated. Use internalCode.

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

internalCodestring

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

detailsarray of object

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

Show child attributes

messagestringrequired

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

codestringrequired

A machine-readable code for the specific detail.

propertystring

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

suggestionone of

A suggested value for the particular property.

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

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

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

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

spanIdstring

The span within the trace that failed.

Auth required

Send one of

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

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

GET /customers/{customerId}/product-catalog

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",
      "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,
        "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"
      }
    }
  ]
}

{
  "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."
}

Customers

List customers

Query parameters

Responses

Create customer

Headers

Body·CreateCustomerRequestrequiredapplication/json

Responses

Get customer

Path parameters

Responses

Update customer

Path parameters

Headers

Body·UpdateCustomerRequestrequiredapplication/json

Responses

Remove user from customer

Path parameters

Query parameters

Headers

Responses

Get customer product catalog

Path parameters

Responses

BodyCreateCustomerRequestrequiredapplication/json

BodyUpdateCustomerRequestrequiredapplication/json