# Integrate our Search API ## How does it work? * The .box Search API enables your users to search for .box domains through your platform and get redirected to the purchase flow on my.box * You will be rewarded $18 USDC per domain sold via your platform (15% of our revenue) {% hint style="success" %} If you are interested in becoming a Search API referral partner, don't hesitate to get in touch with us at or message our Community Lead, [@ohmsdotbox](https://t.me/ohmsdotbox) on Telegram {% endhint %} ## **Initial Setup Steps** 1. Send the My.box team a **wallet address**. This wallet address is where your referral rewards will be received 2. Send the My.box team your development environment identifiers to be whitelisted. These will be **URLs/IPs** depending on your integration approach:

Frontend Integration

**Send us your Allowed Origins** (**URLs**) to be configured for frontend access: 1. **HTTPS/HTTP** and **wildcards for** **subdomains** are supported (e.g. \*domain.box) 2. **Ports for** **localhost dev access** are supported by adding the origin: `https?://[a-z].?localhost:[0-9]*`

Backend Integration

1. **Send us your Allowed Servers (IPs)** to be configured for server access: 1. All server access IPV4 (0.0.0.0/0) is supported for development if required 2. All server access IPV6 (::/0) is supported for development if required 3. Server IP ranges are supported (ideally to limit access) 2. **(Optional)** Send us your Allowed Origins (URLs) to be configured for frontend access \ \ If your integration also includes a frontend component, we recommend sending us the corresponding URLs to be whitelisted as well for best security practices. See:[#frontend-integration](#frontend-integration "mention") 3. **(Optional)** For testing purposes only: Please advise us if your developers need TEMPORARY API access from their local environments and tools like Postman and we can add a special "allow ALL IPs" configuration: `0.0.0.0/0`\ \ **Note**: this will make our API with your API Key accessible from all IPs. While you are still protected by your dedicated API Key, we recommend that this option be removed as soon as you go live.

2. The My.box team will send you an **API key** 3. Your team can find the **registry.swagger.json** file below which can be imported into Postman or Insomnia {% file src="" %} ## Integrating the Search API 1. Import the **Swagger file** into Postman or Insomnia 2. Edit the Authorization tab with the provided `x-api-key` 3. Update the `domain` query param with the desired domain name to search #### **Open API 3.0 Spec (swagger)** The open API spec can be imported into Postman for testing the endpoint. Once imported, edit the authorization tab with the provided `x-api-key` and update the `domain` query param with the desired domain name you’d like to search **Domain status descriptions:** * **“LIVE”** Domain is **Unavailable** and **Tokenized.** Examples, josh.box, areeb.box, adam.box, ronen.box * **“UNAVAILABLE”** - Domain is **Unavailable** and **NOT Tokenized** (Reserved/Evergreen, Banned, serverHold, pendingDelete, PendingCreate). Examples, china.box * **“INVALID\_DOMAIN”** domain name failed validation. Examples, josh--.box, domains >63 chars * **“AVAILABLE”** Domain is available for purchase/registration {% hint style="info" %} For domains with the **AVAILABLE** status, we recommend using the “href” callback URL parameter to route your users to my.box. This will ensure proper referral attribution. {% endhint %} #### **Sample Response - 200 - AVAILABLE domain** ``` { "success": true, "data": { "available": true, "domain": "victor1.box", "is_premium": false, "href": "https://my.box/search?domain=victor1&ref=abc123", "status": "AVAILABLE" } } ``` #### **Sample Response - 200 - LIVE (unavailable and tokenized) domain** ``` { "success": true, "data": { "available": false, "domain": "victor.box", "is_premium": false, "href": "https://my.box/profile/victor.box?ref=abc123", "status": "LIVE" } } ``` #### **Sample Response - 200 - UNAVAILABLE (unavailable and NOT tokenized -banned, reserved) domain** ``` { "success": true, "data": { "available": false, "domain": "china.box", "is_premium": false, "href": "https://my.box?ref=abc123", "status": "UNAVAILABLE" } } ``` #### **Sample Response - 400 - Error** ``` { "success": false, "error": { "code": "ICP_302", "message": "Domain query parameter is required" } } ``` #### **Error Codes (Registry API)** ``` // Registry API errors ICP_301: { code: 'ICP_301', message: 'API Timeout', }, ICP_302: { code: 'ICP_302', message: 'Domain query parameter is required', }, ICP_303: { code: 'ICP_303', message: 'Error checking domain availability', }, }; ``` #### **Validation Notes** * Domains can have a total length of 63 characters. * i.e., \[up-to-63-characters].box ## **Example Screenshots**