--- title: Tools description: Tools for address validation, number porting, device info, and network coverage. --- # Tools Tools for address validation, number porting, device info, and network coverage. ## [POST /tools/validate-address](/api-reference/tools#tag/tools/POST/tools/validate-address) Validate address Validate 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. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ### Request body (required) Type: `object` - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. ### Responses #### 200 Address validation completed. Type: [AddressValidationResult](/api-reference/models.md#models/AddressValidationResult) #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) #### 503 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. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/tools/validate-address \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "address": { "street": "500 S Main St", "street1": "string", "street2": "Apt 1", "city": "Natick", "zip": "01701", "country": "US", "state": "CA", "region": "Ontario", "attention": "John Doe" } }' ``` ## [POST /tools/check-porting-eligibility](/api-reference/tools#tag/tools/POST/tools/check-porting-eligibility) Check number porting eligibility Check 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. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ### Request body (required) Type: `object` - `msisdn` (`string`, required, phone, example +15551234567) — The phone number to check for porting eligibility. ### Responses #### 200 Porting eligibility check completed. Type: [PortingEligibilityResult](/api-reference/models.md#models/PortingEligibilityResult) #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) #### 503 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. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/tools/check-porting-eligibility \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "msisdn": "+15551234567" }' ``` ## [POST /tools/get-device-info](/api-reference/tools#tag/tools/POST/tools/get-device-info) Get device information by IMEI Get 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. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ### Request body (required) Type: `object` - `imei` (`string`, required, example 356938035643809) — The International Mobile Equipment Identity of the device. ### Responses #### 200 Device information retrieved. Type: [DeviceInfo](/api-reference/models.md#models/DeviceInfo) #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) #### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) #### 501 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. Type: [Error](/api-reference/models.md#models/Error) #### 503 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. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/tools/get-device-info \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "imei": "356938035643809" }' ``` ## [POST /tools/search-devices](/api-reference/tools#tag/tools/POST/tools/search-devices) Find devices by name Find 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. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ### Request body (required) Type: `object` - `query` (`string`, required, min length 2, example iPhone 15) — Part of the device name to match, such as the brand, the model, or both. - `limit` (`integer`, optional, >= 1, <= 50, default 20, example 20) — The largest number of devices to return. ### Responses #### 200 The matching devices. Type: [DeviceSearchResult](/api-reference/models.md#models/DeviceSearchResult) #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) #### 501 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. Type: [Error](/api-reference/models.md#models/Error) #### 503 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. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/tools/search-devices \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "query": "iPhone 15", "limit": 20 }' ``` ## [POST /tools/check-network-coverage](/api-reference/tools#tag/tools/POST/tools/check-network-coverage) Check network coverage Check 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. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ### Request body (required) Type: `object` - `address` (`object`, required) — 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. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, optional, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, optional, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). ### Responses #### 200 Network coverage information retrieved. Type: [NetworkCoverage](/api-reference/models.md#models/NetworkCoverage) #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) #### 501 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. Type: [Error](/api-reference/models.md#models/Error) #### 503 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. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/tools/check-network-coverage \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "address": { "street": "500 S Main St", "street1": "string", "street2": "Apt 1", "city": "Natick", "zip": "01701", "country": "US", "state": "CA" } }' ```