Tools
Lookups that an order flow needs before the user commits to an offering.
Check network coverage
/tools/check-network-coverageCheck whether the network serves a location, and how well.
A shopper can read the verdict before they place an order.
Networks differ in what they can answer. Some place the exact address and grade the signal
there. Others read the zip code alone and only qualify the postal area for activation. Read
scope on the response to know which answer you got.
Headers
X-stringmax length 256A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request.
Modified requests with the same idempotency keys are rejected with a 409 Conflict status code.
BodyCheckNetworkCoverageRequestrequiredapplication/json
Request to check network coverage at a location.
addressobjectrequiredA location to check network coverage at.
Only the ZIP code and the country are required. Some networks qualify a whole postal area and read nothing else. Send the full address when you have it. A network that grades a point needs the street and the city to place it.
Show child attributes
citystringThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe 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').
Responses
200Network coverage information retrieved.
application/json
Network coverage information retrieved.
Network coverage information retrieved.
objectNetworkCoverage
Network coverage information for a location.
Networks answer two different questions. One resolves the address to a point and grades the
signal there. Another qualifies a whole postal area for activation and grades nothing. Read
scope to know which answer you got, and read serviceable for the verdict itself.
What data is returned depends on the underlying network provider, so only the required fields are guaranteed to be present.
addressobjectrequiredThe address that was checked.
A location to check network coverage at.
Only the ZIP code and the country are required. Some networks qualify a whole postal area and read nothing else. Send the full address when you have it. A network that grades a point needs the street and the city to place it.
Show child attributes
citystringThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe 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').
coordinatesobjectResolved coordinates for the address, if available.
A geographic location in WGS84 coordinates, the standard used by GPS.
Show child attributes
latitudenumberfloatpersonal datarequiredLatitude in decimal degrees. Positive values are north of the equator.
longitudenumberfloatpersonal datarequiredLongitude in decimal degrees. Negative values are west of the prime meridian.
coverageobject with string keysCoverage information per technology, if available.
Show child attributes
3gobjectrequiredCoverage details for a single network technology (such as 4G or 5G) at a checked location.
Show child attributes
availablebooleanrequiredWhether this technology is available at the checked location.
4gobjectrequiredCoverage details for a single network technology (such as 4G or 5G) at a checked location.
Show child attributes
availablebooleanrequiredWhether this technology is available at the checked location.
5gobjectrequiredCoverage details for a single network technology (such as 4G or 5G) at a checked location.
Show child attributes
availablebooleanrequiredWhether this technology is available at the checked location.
*objectCoverage details for a single network technology (such as 4G or 5G) at a checked location.
Show child attributes
availablebooleanrequiredWhether this technology is available at the checked location.
coverageenum<string>Overall network coverage quality at this location.
Absent when the network grades no signal. Do not read an absent grade as poor coverage:
read serviceable instead.
values
EXCELLENTGOODFAIRPOORNO_COVERAGE
networkstringWhich network this coverage data applies to.
roamingstringThe roaming status at this location, if reported by the network provider (e.g., whether the location is served by the home network or a roaming partner).
scopeenum<string>requiredWhat the verdict applies to.
ADDRESS means the network placed the exact address and answered about that point.
POSTAL_AREA means the network read the zip code alone, so the same answer applies to
every address in it.
values
ADDRESSPOSTAL_AREA
serviceablebooleanrequiredWhether the network serves this location. Every network answers this.
A network that grades signal reports true when at least one technology reaches the
location. A network that qualifies a postal area reports true when it can activate a
subscription there.
400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
429Too many requests have been sent in a given amount of time.
application/json
Too many requests have been sent in a given amount of time.
Too many requests have been sent in a given amount of time.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
501This endpoint is not available for this brand. The network it asks cannot
answer the question, so no request will succeed until the brand is configured
with a network that can.
application/json
This endpoint is not available for this brand. The network it asks cannot answer the question, so no request will succeed until the brand is configured with a network that can.
This endpoint is not available for this brand. The network it asks cannot answer the question, so no request will succeed until the brand is configured with a network that can.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
503The network this endpoint asks could not answer. The request was correct and
the endpoint is available for this brand, so the same request can succeed
later. Retry after a short delay.
application/json
The network this endpoint asks could not answer. The request was correct and the endpoint is available for this brand, so the same request can succeed later. Retry after a short delay.
The network this endpoint asks could not answer. The request was correct and the endpoint is available for this brand, so the same request can succeed later. Retry after a short delay.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
Auth required
Send
X-Api-Key+Bearer JWT
curl https://apiv2.example.com/api/v2/end-user/tools/check-network-coverage \
--request POST \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"address": {
"city": "Natick",
"country": "US",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
}
}'fetch('https://apiv2.example.com/api/v2/end-user/tools/check-network-coverage', {
method: 'POST',
headers: {
'X-Api-Key': 'YOUR_API_KEY',
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
address: {
city: 'Natick',
country: 'US',
state: 'CA',
street: '500 S Main St',
street1: 'string',
street2: 'Apt 1',
zip: '01701'
}
})
})requests.post(
"https://apiv2.example.com/api/v2/end-user/tools/check-network-coverage",
headers={
"X-Api-Key": "YOUR_API_KEY",
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"Content-Type": "application/json"
},
json={
"address": {
"city": "Natick",
"country": "US",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
}
}
)package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/end-user/tools/check-network-coverage"
payload := strings.NewReader(`{
"address": {
"city": "Natick",
"country": "US",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
}
}`)
req, _ := http.NewRequest("POST", requestUrl, payload)
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"address": {
"city": "Natick",
"country": "US",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"coordinates": {
"latitude": 40.7128,
"longitude": -74.006
},
"coverage": {
"3g": {
"available": true
},
"4g": {
"available": true
},
"5g": {
"available": true
},
"propertyName": {
"available": true
}
},
"coverageLevel": "GOOD",
"networkProviderId": "tmobile-us",
"roamingStatus": "HOME",
"scope": "ADDRESS",
"serviceable": true
}{
"code": "bad_request",
"details": [
{
"code": "invalid_email",
"message": "Email format is invalid.",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields.",
"message": "The request body is invalid."
}{
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header.",
"message": "Authentication is required to access this resource."
}{
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions.",
"message": "You do not have permission to perform this action."
}{
"code": "too_many_requests",
"hint": "Retry after the number of seconds indicated in the Retry-After header.",
"message": "Too many requests. Please slow down."
}{
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support.",
"message": "An unexpected error occurred on the server."
}{
"code": "not_implemented",
"hint": "The network behind this brand cannot answer this request.",
"message": "This endpoint is not available in this environment."
}{
"code": "unavailable",
"hint": "The network behind this brand did not answer. Try again in a moment.",
"message": "The service is temporarily unavailable. Please try again."
}Check number porting eligibility
/tools/check-porting-eligibilityCheck if a phone number is eligible for porting to this network.
This helps validate numbers before creating subscription line items with porting details. Returns information about the current carrier and porting requirements.
Headers
X-stringmax length 256A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request.
Modified requests with the same idempotency keys are rejected with a 409 Conflict status code.
BodyCheckPortingEligibilityRequestrequiredapplication/json
Request to check if a phone number is eligible for porting.
msisdnstringphonepersonal datarequiredThe phone number to check for porting eligibility.
Responses
200Porting eligibility check completed.
application/json
Porting eligibility check completed.
Porting eligibility check completed.
objectPortingEligibilityResult
Result of number porting eligibility check.
eligiblebooleanrequiredWhether the number is eligible for porting.
ineligibilitystringReason why number is not eligible (only present if eligible is false).
msisdnstringphonepersonal datarequiredThe phone number that was checked.
networkstringThe identifier for the current network provider, if detectable
400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
429Too many requests have been sent in a given amount of time.
application/json
Too many requests have been sent in a given amount of time.
Too many requests have been sent in a given amount of time.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
503The network this endpoint asks could not answer. The request was correct and
the endpoint is available for this brand, so the same request can succeed
later. Retry after a short delay.
application/json
The network this endpoint asks could not answer. The request was correct and the endpoint is available for this brand, so the same request can succeed later. Retry after a short delay.
The network this endpoint asks could not answer. The request was correct and the endpoint is available for this brand, so the same request can succeed later. Retry after a short delay.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
Auth required
Send
X-Api-Key+Bearer JWT
curl https://apiv2.example.com/api/v2/end-user/tools/check-porting-eligibility \
--request POST \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"msisdn": "+15551234567"
}'fetch('https://apiv2.example.com/api/v2/end-user/tools/check-porting-eligibility', {
method: 'POST',
headers: {
'X-Api-Key': 'YOUR_API_KEY',
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
msisdn: '+15551234567'
})
})requests.post(
"https://apiv2.example.com/api/v2/end-user/tools/check-porting-eligibility",
headers={
"X-Api-Key": "YOUR_API_KEY",
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"Content-Type": "application/json"
},
json={
"msisdn": "+15551234567"
}
)package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/end-user/tools/check-porting-eligibility"
payload := strings.NewReader(`{
"msisdn": "+15551234567"
}`)
req, _ := http.NewRequest("POST", requestUrl, payload)
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"eligible": true,
"ineligibilityReason": "Number not found or not portable",
"msisdn": "+15551234567",
"networkProviderId": "tmobile-us"
}{
"code": "bad_request",
"details": [
{
"code": "invalid_email",
"message": "Email format is invalid.",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields.",
"message": "The request body is invalid."
}{
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header.",
"message": "Authentication is required to access this resource."
}{
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions.",
"message": "You do not have permission to perform this action."
}{
"code": "too_many_requests",
"hint": "Retry after the number of seconds indicated in the Retry-After header.",
"message": "Too many requests. Please slow down."
}{
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support.",
"message": "An unexpected error occurred on the server."
}{
"code": "unavailable",
"hint": "The network behind this brand did not answer. Try again in a moment.",
"message": "The service is temporarily unavailable. Please try again."
}Get device information by IMEI
/tools/get-device-infoGet detailed information about a device using its IMEI number.
This helps validate device compatibility and capabilities before creating subscription line items. Particularly useful for eSIM activation requirements.
Headers
X-stringmax length 256A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request.
Modified requests with the same idempotency keys are rejected with a 409 Conflict status code.
BodyGetDeviceInfoRequestrequiredapplication/json
Request to get device information by IMEI.
imeistringpersonal datarequiredThe International Mobile Equipment Identity of the device.
Responses
200Device information retrieved.
application/json
Device information retrieved.
Device information retrieved.
objectDeviceInfo
Information about a device based on its IMEI.
esimbooleanrequiredWhether the device supports eSIM.
imeistringpersonal datarequiredThe device IMEI that was checked.
manufacturerstringDevice manufacturer.
marketingstringDevice marketing name.
modelstringDevice model.
tacstringThe device TAC (Type Allocation Code), which is the first 8 digits of the IMEI identifying the device model and manufacturer.
400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
404The requested resource was not found.
application/json
The requested resource was not found.
The requested resource was not found.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
429Too many requests have been sent in a given amount of time.
application/json
Too many requests have been sent in a given amount of time.
Too many requests have been sent in a given amount of time.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
501This endpoint is not available for this brand. The network it asks cannot
answer the question, so no request will succeed until the brand is configured
with a network that can.
application/json
This endpoint is not available for this brand. The network it asks cannot answer the question, so no request will succeed until the brand is configured with a network that can.
This endpoint is not available for this brand. The network it asks cannot answer the question, so no request will succeed until the brand is configured with a network that can.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
503The network this endpoint asks could not answer. The request was correct and
the endpoint is available for this brand, so the same request can succeed
later. Retry after a short delay.
application/json
The network this endpoint asks could not answer. The request was correct and the endpoint is available for this brand, so the same request can succeed later. Retry after a short delay.
The network this endpoint asks could not answer. The request was correct and the endpoint is available for this brand, so the same request can succeed later. Retry after a short delay.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
Auth required
Send
X-Api-Key+Bearer JWT
curl https://apiv2.example.com/api/v2/end-user/tools/get-device-info \
--request POST \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"imei": "356938035643809"
}'fetch('https://apiv2.example.com/api/v2/end-user/tools/get-device-info', {
method: 'POST',
headers: {
'X-Api-Key': 'YOUR_API_KEY',
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
imei: '356938035643809'
})
})requests.post(
"https://apiv2.example.com/api/v2/end-user/tools/get-device-info",
headers={
"X-Api-Key": "YOUR_API_KEY",
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"Content-Type": "application/json"
},
json={
"imei": "356938035643809"
}
)package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/end-user/tools/get-device-info"
payload := strings.NewReader(`{
"imei": "356938035643809"
}`)
req, _ := http.NewRequest("POST", requestUrl, payload)
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"esim": true,
"imei": "356938035643809",
"manufacturer": "Apple",
"marketingName": "iPhone 15 Pro",
"model": "A2653",
"tac": "35693803"
}{
"code": "bad_request",
"details": [
{
"code": "invalid_email",
"message": "Email format is invalid.",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields.",
"message": "The request body is invalid."
}{
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header.",
"message": "Authentication is required to access this resource."
}{
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions.",
"message": "You do not have permission to perform this action."
}{
"code": "not_found",
"hint": "Verify the customerId and try again.",
"message": "The requested customer could not be found."
}{
"code": "too_many_requests",
"hint": "Retry after the number of seconds indicated in the Retry-After header.",
"message": "Too many requests. Please slow down."
}{
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support.",
"message": "An unexpected error occurred on the server."
}{
"code": "not_implemented",
"hint": "The network behind this brand cannot answer this request.",
"message": "This endpoint is not available in this environment."
}{
"code": "unavailable",
"hint": "The network behind this brand did not answer. Try again in a moment.",
"message": "The service is temporarily unavailable. Please try again."
}Find devices by name
/tools/search-devicesFind devices whose name matches a query, with the capabilities of each one.
Use this when the customer knows their device by its everyday name and not by its IMEI. It answers whether each match supports eSIM, so the customer can pick the right SIM type before they order.
Headers
X-stringmax length 256A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request.
Modified requests with the same idempotency keys are rejected with a 409 Conflict status code.
BodySearchDevicesRequestrequiredapplication/json
Request to find devices by name.
Use this when the customer knows their device by its everyday name and not by its IMEI, for example to find out whether it supports eSIM before they order.
limitinteger>= 1<= 50default 20The largest number of devices to return.
querystringmin length 2requiredPart of the device name to match, such as the brand, the model, or both.
Responses
200The matching devices.
application/json
The matching devices.
The matching devices.
objectDeviceSearchResult
The devices whose name matches the query.
itemsarray of DeviceMatchrequiredOne entry per matching device. An empty list means the network knows no device by that name.
Show child attributes
esimbooleanrequiredWhether the device supports eSIM.
manufacturerstringDevice manufacturer.
marketingstringDevice marketing name.
modelstringDevice model.
tacstringThe device TAC (Type Allocation Code), which is the first 8 digits of an IMEI identifying the device model and manufacturer.
400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
429Too many requests have been sent in a given amount of time.
application/json
Too many requests have been sent in a given amount of time.
Too many requests have been sent in a given amount of time.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
501This endpoint is not available for this brand. The network it asks cannot
answer the question, so no request will succeed until the brand is configured
with a network that can.
application/json
This endpoint is not available for this brand. The network it asks cannot answer the question, so no request will succeed until the brand is configured with a network that can.
This endpoint is not available for this brand. The network it asks cannot answer the question, so no request will succeed until the brand is configured with a network that can.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
503The network this endpoint asks could not answer. The request was correct and
the endpoint is available for this brand, so the same request can succeed
later. Retry after a short delay.
application/json
The network this endpoint asks could not answer. The request was correct and the endpoint is available for this brand, so the same request can succeed later. Retry after a short delay.
The network this endpoint asks could not answer. The request was correct and the endpoint is available for this brand, so the same request can succeed later. Retry after a short delay.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
Auth required
Send
X-Api-Key+Bearer JWT
curl https://apiv2.example.com/api/v2/end-user/tools/search-devices \
--request POST \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"limit": 20,
"query": "iPhone 15"
}'fetch('https://apiv2.example.com/api/v2/end-user/tools/search-devices', {
method: 'POST',
headers: {
'X-Api-Key': 'YOUR_API_KEY',
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
limit: 20,
query: 'iPhone 15'
})
})requests.post(
"https://apiv2.example.com/api/v2/end-user/tools/search-devices",
headers={
"X-Api-Key": "YOUR_API_KEY",
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"Content-Type": "application/json"
},
json={
"limit": 20,
"query": "iPhone 15"
}
)package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/end-user/tools/search-devices"
payload := strings.NewReader(`{
"limit": 20,
"query": "iPhone 15"
}`)
req, _ := http.NewRequest("POST", requestUrl, payload)
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"items": [
{
"esim": true,
"manufacturer": "Apple",
"marketingName": "iPhone 15 Pro",
"model": "A2653",
"tac": "35693803"
}
]
}{
"code": "bad_request",
"details": [
{
"code": "invalid_email",
"message": "Email format is invalid.",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields.",
"message": "The request body is invalid."
}{
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header.",
"message": "Authentication is required to access this resource."
}{
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions.",
"message": "You do not have permission to perform this action."
}{
"code": "too_many_requests",
"hint": "Retry after the number of seconds indicated in the Retry-After header.",
"message": "Too many requests. Please slow down."
}{
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support.",
"message": "An unexpected error occurred on the server."
}{
"code": "not_implemented",
"hint": "The network behind this brand cannot answer this request.",
"message": "This endpoint is not available in this environment."
}{
"code": "unavailable",
"hint": "The network behind this brand did not answer. Try again in a moment.",
"message": "The service is temporarily unavailable. Please try again."
}Validate address
/tools/validate-addressValidate an address and get suggestions for corrections if the address is invalid.
This is particularly important for US addresses where precise addressing is required for service delivery and regulatory compliance.
Depending on setup, address validation is either shape based (e.g. this looks like an address), or verified against an address registry.
Headers
X-stringmax length 256A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request.
Modified requests with the same idempotency keys are rejected with a 409 Conflict status code.
BodyValidateAddressRequestrequiredapplication/json
Request to validate an address.
addressobjectrequiredThe address to validate. The platform does not store it.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
citystringrequiredThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
purposeenum<string>default SERVICEWhat the address is for. The purpose selects the rules that the address must obey.
SERVICE: the address where a line is used. On a US brand, it is the emergency (E911) address of the line. The platform applies the rules of the network operator, and can refuse a PO box.POSTAL: an address that only gets post, for example the address that a SIM card goes to. The platform applies only the address format of the country that the brand serves, and accepts a PO box.
If you do not send a purpose, the platform uses SERVICE.
values
SERVICEPOSTAL
Responses
200Address validation completed.
application/json
Address validation completed.
Address validation completed.
objectAddressValidationResult
Result of address validation with optional suggestions.
Depending on setup, address validation is either shape based (e.g. this looks like an address), or verified against an address registry.
suggestedobjectIf provided, a suggestion for a corrected address by the underlying address validation service.
Do note that this may be returned for seemingly valid addresses, where the network has a more precise or standardized version of the address. A typical example of this is the address is found in the networks' registry but under a different name because it contains aliases or minor formatting issues, mistyped zip codes, etc.
A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
Show child attributes
attentionstringpersonal dataAn optional line for specifying a person, department, or attention to a specific entity within an address.
citystringrequiredThe city or municipality of the address.
countrystringpattern ^[A-Z]{2}$requiredThe two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
regionstringA province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
statestringFor countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
streetstringpersonal dataThe first line of the address, typically street and house number.
street1stringpersonal datadeprecatedrequiredDeprecated. Use street instead.
The first line of the address, typically street and house number.
street2stringpersonal dataThe second line of the address, typically apartment, suite, unit, building, floor, etc.
zipstringpersonal datarequiredThe zip code of the address.
Depending on the country, this may be referred to as a postal code or postcode.
A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.
validbooleanrequiredWhether the provided address is valid.
validationobjectAdditional validation details.
Show child attributes
issuesarray of objectSpecific issues found with the address.
Show child attributes
messagestringrequiredDescription of the issue found.
propertystringThe property or field related to the issue (e.g., "street", "zipCode").
400The request was malformed or invalid.
application/json
The request was malformed or invalid.
The request was malformed or invalid.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
401Authentication is required to access this resource.
application/json
Authentication is required to access this resource.
Authentication is required to access this resource.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
403Access to this resource is forbidden.
application/json
Access to this resource is forbidden.
Access to this resource is forbidden.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
429Too many requests have been sent in a given amount of time.
application/json
Too many requests have been sent in a given amount of time.
Too many requests have been sent in a given amount of time.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
500An unexpected error occurred on the server.
application/json
An unexpected error occurred on the server.
An unexpected error occurred on the server.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
503The network this endpoint asks could not answer. The request was correct and
the endpoint is available for this brand, so the same request can succeed
later. Retry after a short delay.
application/json
The network this endpoint asks could not answer. The request was correct and the endpoint is available for this brand, so the same request can succeed later. Retry after a short delay.
The network this endpoint asks could not answer. The request was correct and the endpoint is available for this brand, so the same request can succeed later. Retry after a short delay.
objectError
The error body returned by every endpoint when a request fails. Branch on reason, show message
to a human, and check details for field-level problems when the request was invalid.
codestringdeprecatedrequiredDeprecated. Use reason.
This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.
detailsarray of objectAdditional details about the error, typically one entry per invalid field on validation failures.
Show child attributes
codestringdeprecatedrequiredDeprecated. Use reason. It is the status of the whole error, the same for each item.
messagestringrequiredA human-readable message providing more details about the error.
propertystringThe property or field related to the error. May be nested using dot notation (e.g., "billing.email").
reasonstringNames the problem with the property. property_required is a missing value,
property_invalid is a value with the wrong format, and property_conflict is two values
that cannot occur together. Other reasons name a business condition. Your client must
accept a reason that it does not know.
suggestionone ofA suggested value for the particular property.
For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.
A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.
Show child attributes
domainstringThe business area of the reason, for example customer or porting. It is for information
only. Do not branch on it.
externalstringThe code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.
externalstringThe third party that reported the failure.
hintstringA hint to help resolve the error.
internalstringThe number of the condition that failed. It is stable across releases. A condition that we
added after reason has no number, so branch on reason instead.
messagestringrequiredA human-readable message providing more details about the error.
reasonstringNames the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.
If the request has problems with different reasons, the reason is validation_failed. Then
each item of details names its own problem.
retryablebooleanTrue when the same request can pass later with no change. A 429 and a 503 are always
retryable.
spanstringThe span within the trace that failed.
tracestringIdentifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.
Auth required
Send
X-Api-Key+Bearer JWT
curl https://apiv2.example.com/api/v2/end-user/tools/validate-address \
--request POST \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"purpose": "SERVICE"
}'fetch('https://apiv2.example.com/api/v2/end-user/tools/validate-address', {
method: 'POST',
headers: {
'X-Api-Key': 'YOUR_API_KEY',
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
address: {
attention: 'John Doe',
city: 'Natick',
country: 'US',
region: 'Ontario',
state: 'CA',
street: '500 S Main St',
street1: 'string',
street2: 'Apt 1',
zip: '01701'
},
purpose: 'SERVICE'
})
})requests.post(
"https://apiv2.example.com/api/v2/end-user/tools/validate-address",
headers={
"X-Api-Key": "YOUR_API_KEY",
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"Content-Type": "application/json"
},
json={
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"purpose": "SERVICE"
}
)package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
requestUrl := "https://apiv2.example.com/api/v2/end-user/tools/validate-address"
payload := strings.NewReader(`{
"address": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"purpose": "SERVICE"
}`)
req, _ := http.NewRequest("POST", requestUrl, payload)
req.Header.Add("X-Api-Key", "YOUR_API_KEY")
req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}{
"suggestedAddress": {
"attention": "John Doe",
"city": "Natick",
"country": "US",
"region": "Ontario",
"state": "CA",
"street": "500 S Main St",
"street1": "string",
"street2": "Apt 1",
"zip": "01701"
},
"valid": false,
"validationDetails": {
"issues": [
{
"message": "Missing city",
"property": "city"
},
{
"message": "Invalid zip format",
"property": "zip"
}
]
}
}{
"code": "bad_request",
"details": [
{
"code": "invalid_email",
"message": "Email format is invalid.",
"property": "contact.email"
}
],
"hint": "Check the request payload and correct the highlighted fields.",
"message": "The request body is invalid."
}{
"code": "unauthorized",
"hint": "Provide a valid API key in the X-Api-Key header.",
"message": "Authentication is required to access this resource."
}{
"code": "forbidden",
"hint": "Ensure your API key or user has the required permissions.",
"message": "You do not have permission to perform this action."
}{
"code": "too_many_requests",
"hint": "Retry after the number of seconds indicated in the Retry-After header.",
"message": "Too many requests. Please slow down."
}{
"code": "internal_server_error",
"hint": "Retry the request later. If the problem persists, contact support.",
"message": "An unexpected error occurred on the server."
}{
"code": "unavailable",
"hint": "The network behind this brand did not answer. Try again in a moment.",
"message": "The service is temporarily unavailable. Please try again."
}