> ## Documentation Index > Fetch the complete documentation index at: https://docs.name.com/llms.txt > Use this file to discover all available pages before exploring further. # Search > Searches for domain name suggestions based on a keyword or term. Important: Do not encode the `:` in the path. Use `/core/v1/domains:search`, not `/core/v1/domains%3Asearch`. **Discovery endpoint:** Returns `SearchResult` fields — `purchaseType`, `purchasePrice`, `premium`, `purchasable`. **Recommendation:** Set `purchaseType` to `registration`. Most resellers restrict results to domains with a `purchaseType` of `registration` to ensure predictable pricing and immediate fulfillment. Other purchase types (such as aftermarket) can introduce higher costs and non-instant transactions that may be delayed or declined by third parties. With `purchaseType: registration`, domains that do not match the filter are **omitted** from results (unlike Check Availability, which returns them with `purchasable: false`). When results show `premium: true` or a non-`registration` `purchaseType`, follow the [Domain pricing guide](/guides/domain-pricing) before calling Create Domain. For all types, re-check with Check Availability immediately before create — prices and availability can change. ## OpenAPI ````yaml post /core/v1/domains:search openapi: 3.1.0 info: contact: email: reseller@name.com name: Reseller Account Services description: >- RESTful API for managing domains, DNS records, and related services at name.com. Access via HTTPS at api.name.com (production) or api.dev.name.com (testing). Supports standard authentication, rate-limited to 20 requests/second. title: name.com Core API version: 1.29.4 termsOfService: https://www.name.com/policies/api-access-agreement servers: - description: Testing url: https://api.dev.name.com security: - BasicAuth: [] tags: - name: Hello description: >- Use the Hello endpoint to verify that your API connection and credentials are working properly. This simple call returns a success message (along with server time and version info) to confirm the API is reachable and authenticated. - name: Account Info description: >- Use Account Info endpoints to retrieve basic information about your name.com account. For example, you can check your account’s current credit balance and other account details using these endpoints. - name: Accounts description: >- Use Accounts endpoints (available upon request) to manage sub-accounts under your main account. For example, resellers can programmatically create new customer accounts with their own login credentials and permissions. - name: Domains description: >- Use Domains endpoints to search for domain availability, register new domains, and manage existing domains. - name: Contact Verification description: >- Use Contact Verification endpoints to query a reseller’s unverified domains/emails and to programmatically mark an end user’s email as verified if the reseller has already completed the verification process. These endpoints help resellers meet ICANN requirements by ensuring end users confirm they can receive email at their listed address. - name: DNS description: >- Use DNS endpoints to manage DNS records for your domains. You can list all existing DNS records for a domain and create, update, or delete records as needed. - name: DNSSECs description: >- Use DNSSEC endpoints to configure DNS Security Extensions for your domains. These endpoints allow you to add, retrieve, or remove DNSSEC records. - name: Email Forwardings description: >- Use Email Forwardings endpoints to set up and manage email forwarding addresses on your domains. - name: URL Forwardings description: >- Use URL Forwardings endpoints to control URL redirection settings for your domains. - name: Vanity Nameservers description: >- Use Vanity Nameservers endpoints to configure custom nameserver hostnames (glue records) for your domains. - name: Transfers description: >- Use Transfers endpoints to move domains into your name.com account. Start by creating a transfer request for inbound transfers from **external** registrars, then monitor and manage the status of pending transfers. Use **internal transfer in** to pull a domain from another name.com account into your reseller account (enterprise allowlist; requires auth code from the losing account’s dashboard). You can cancel an incoming transfer if needed, or cancel an outbound transfer (domain leaving name.com) via the external transfer-out cancel endpoint. Use the **transfer eligibility** endpoint to check whether a domain is currently at name.com before initiating a transfer, so you can route to the correct flow (external vs internal transfer). - name: Orders description: Use Orders endpoints to review and track purchases made via the API. - name: Refunds description: > Use the Refunds endpoint to delete eligible domains and advanced security products during the Add Grace Period (AGP) and automatically issue refunds for the associated order items. You can use the List Orders endpoint to retrieve order IDs, then pass those IDs into the Refunds endpoint to process eligible deletions and refunds. This endpoint enforces AGP delete limits and supports only domain registrations and advanced security add-ons. Refunds are issued to the original payment method on file. If the original payment method is unavailable, the refund will be credited to the account balance. - name: Webhook Notifications description: > Use Webhook Notification endpoints to subscribe to real-time notifications for account and domain events. This keeps your application updated on important changes without polling the API. Outbound webhook POSTs include an `X-NAMECOM-SIGNATURE` header. HMAC uses one API v4 token per account, chosen deterministically when multiple tokens exist (see HMAC Signature Verification in the developer docs). The signing input format is unchanged. - name: Domain Info description: >- Use Domain Info endpoints to retrieve information about TLD-specific requirements and registration rules. These endpoints help you understand what fields, documents, or constraints are needed to successfully register domains across different TLDs. - name: TLD Pricing description: >- Use TLD Pricing endpoints to retrieve general pricing information for your account. - name: Premium Domains description: APIs for working with Premium Domains. paths: /core/v1/domains:search: post: tags: - Domains summary: Search description: > Searches for domain name suggestions based on a keyword or term. Important: Do not encode the `:` in the path. Use `/core/v1/domains:search`, not `/core/v1/domains%3Asearch`. **Discovery endpoint:** Returns `SearchResult` fields — `purchaseType`, `purchasePrice`, `premium`, `purchasable`. **Recommendation:** Set `purchaseType` to `registration`. Most resellers restrict results to domains with a `purchaseType` of `registration` to ensure predictable pricing and immediate fulfillment. Other purchase types (such as aftermarket) can introduce higher costs and non-instant transactions that may be delayed or declined by third parties. With `purchaseType: registration`, domains that do not match the filter are **omitted** from results (unlike Check Availability, which returns them with `purchasable: false`). When results show `premium: true` or a non-`registration` `purchaseType`, follow the [Domain pricing guide](/guides/domain-pricing) before calling Create Domain. For all types, re-check with Check Availability immediately before create — prices and availability can change. operationId: Search requestBody: content: application/json: schema: $ref: '#/components/schemas/SearchRequest' description: SearchRequest is used to specify the search parameters. required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/SearchResponse' description: A successful response. '400': description: >- Returned when an invalid request is made. The message will contain information on the field that is failing validation. content: application/json: schema: $ref: '#/components/schemas/InvalidArgument400' '401': description: Unauthorized. content: application/json: schema: type: object required: - message properties: message: type: string description: >- A human-readable message providing more details about the error example: Unauthorized '403': description: Forbidden - you do not have permission to perform this action. content: application/json: schema: type: object required: - message properties: message: type: string description: >- A human-readable message providing more details about the error example: Permission denied details: type: - string - 'null' description: Additional context or information about the error example: Failed authentication '405': description: Method not allowed. content: application/json: schema: type: object required: - message properties: message: type: string description: >- A human-readable message providing more details about the error example: Method Not Allowed '415': description: >- All POST, PUT, PATCH requests for this API must include the `Content-Type: application/json` header in the requests. content: application/json: schema: $ref: '#/components/schemas/UnsupportedMedia415' '429': description: Rate limit has been exceeded. content: application/json: schema: type: object required: - message - details properties: message: type: string description: >- ### Too Many Requests You have exceeded the rate limit. **Headers returned:** * 'X-RateLimit-Reset': An integer (UTC epoch) indicating when you can retry. example: Rate Limit Exceeded headers: x-ratelimit-reset: description: >- Unix timestamp for the time at which the current rate limit will reset. schema: type: number example: 1747668270 '500': description: Internal server error. content: application/json: schema: type: object required: - message properties: message: type: string description: >- A human-readable message providing more details about the error. example: Internal Server Error details: type: - string - 'null' description: Additional context or information about the error. example: Something went wrong. '502': description: Bad Gateway content: application/json: schema: type: object required: - message properties: message: type: string description: >- A human-readable message providing more details about the error. example: >- The server received an invalid response from the upstream server. '504': description: Gateway Timeout content: application/json: schema: type: object required: - message properties: message: type: string description: >- A human-readable message providing more details about the error. example: The upstream server is taking too long to respond. components: schemas: SearchRequest: description: SearchRequest is used to specify the search parameters. properties: keyword: description: >- Keyword is the search term to search for. It can be just a word, or a whole domain name. type: string example: mydomain timeout: description: >- Timeout is a value in milliseconds on how long to perform the search for. Valid timeouts are between 500ms to 12,000ms. If not specified, timeout defaults to 12,000ms. Since some additional processing is performed on the results, a response may take longer then the timeout. format: int32 type: integer example: 2500 tldFilter: description: >- TLDFilter will limit results to only contain the specified TLDs. There is a maximum of 50 TLDs that can be used in this filter items: type: string type: array maxItems: 50 example: - com - net - org purchaseType: description: >- Optional. Limits results to the given `purchaseType`. **Recommended:** `registration` for most integrations — omit only if you choose to support acquisition types. See the [Domain purchase pricing guide](/guides/domain-pricing). allOf: - $ref: '#/components/schemas/SearchPurchaseType' type: object required: - keyword SearchResponse: description: SearchResponse returns a list of search results. properties: results: description: >- Results of the search are returned here, the order should not be relied upon. items: $ref: '#/components/schemas/SearchResult' type: array type: object InvalidArgument400: type: object required: - message properties: message: type: string description: A human-readable message providing more details about the error example: Bad Request details: type: - string - 'null' description: Additional context or information about the error example: '''domainName'' cannot be null' UnsupportedMedia415: type: object required: - message properties: message: type: string description: A human-readable message providing more details about the error example: >- The 'Content-Type' header must be 'application/json' for this request. SearchPurchaseType: description: > Purchase Type indicates what kind of purchase a discovery result represents. Returned by [Search](/api/v1/reference/domains/search) and [Check Availability](/api/v1/reference/domains/check-availability) — not [Zone Check](/api/v1/reference/domains/zone-check). Copy the value to [Create Domain](/api/v1/reference/domains/create-domain) as `purchaseType`. **Recommendation:** Pass `registration` on Search and Check Availability unless you choose to support acquisition inventory. Other values are supported but add integration complexity. **Pricing by type:** - `registration` — Standard or registry premium. Check the `premium` flag: when `false`, omit `purchasePrice` on create (Get Pricing with matching `years` is optional for preview only); when `true`, `purchasePrice` is required from Get Pricing with matching `years`. `years` controls price and registration length. - `aftermarket_s`, `aftermarket_b`, `aftermarket_i` — Flat acquisition fee from Search or Check Availability; `purchasePrice` required. `years` does not multiply price or guarantee registration length — omit or pass TLD default. - `expiring`, `backorder` — Flat acquisition fee from Search or Check Availability; `purchasePrice` required. Get Pricing does not return these prices. `years` does not multiply price or guarantee registration length — omit or pass TLD default. Renew after acquisition to extend registration. See the [Domain pricing guide](/guides/domain-pricing). type: string enum: - registration - aftermarket_i - expiring - backorder - aftermarket_s - aftermarket_b SearchResult: description: SearchResult is returned by the CheckAvailability and Search endpoints. properties: domainName: description: DomainName is the punycode encoding of the result domain name. type: string example: example.com premium: description: >- Premium indicates whether this discovery result has premium or non-standard pricing. Only returned for purchasable domains. When `true` with `purchaseType: registration` → registry premium (use [Get Pricing](/api/v1/reference/domains/get-pricing-for-domain) for multi-year totals). When `true` with aftermarket, expiring, or backorder `purchaseType` values → flat acquisition fee (use discovery `purchasePrice`; `years` on create does not multiply price or guarantee registration length). When `true`, `purchasePrice` must be passed on Create Domain. type: boolean example: true purchasable: description: >- Purchasable indicates whether the search result is available for purchase. type: boolean example: true purchasePrice: description: >- PurchasePrice is the minimum-term list or flat acquisition price from discovery, in USD. Only returned for purchasable domains. For `purchaseType: registration` when `purchasePrice` is required on create, use [Get Pricing](/api/v1/reference/domains/get-pricing-for-domain) with matching `years` instead. For aftermarket, expiring, and backorder types, pass this flat acquisition fee on Create Domain — not affected by `years`. Get Pricing does not return these acquisition prices. Recommended to re-check with Check Availability immediately before create for all types — prices can change. format: double type: number example: 10.99 purchaseType: description: >- PurchaseType indicates what kind of purchase this discovery result is for. Only returned for purchasable domains. Pass to Create Domain as `purchaseType`. See [SearchPurchaseType](#/components/schemas/SearchPurchaseType) for pricing behavior per value. When `premium: true` or the type is not `registration`, follow the [Domain pricing guide](/guides/domain-pricing). allOf: - $ref: '#/components/schemas/SearchPurchaseType' renewalPrice: description: >- RenewalPrice is the minimum-term renewal total for this domain (typically 1 year; varies by TLD). Only returned for purchasable domains. Informational for standard [Renew Domain](/api/v1/reference/domains/renew-domain) flows — do **not** use to calculate Create Domain `purchasePrice` or multi-year create totals. For premium renewals, use `renewalPrice` from [Get Pricing](/api/v1/reference/domains/get-pricing-for-domain) with matching `years`, not this discovery value. format: double type: number example: 10.99 sld: description: SLD is first portion of the domain_name. type: string example: example tld: description: TLD is the rest of the domain_name after the SLD. type: string example: com reason: description: >- Reason provides additional context when unavailable (e.g. registry is in maintenance). type: string type: object required: - domainName - sld - tld - purchasable securitySchemes: BasicAuth: scheme: basic type: http description: >- Authenticate via HTTP Basic with your account username and API token. Examples use an explicit 'Authorization: Basic ' header; 'curl -u username:token' is equivalent. For sandbox, append "-test" to your username and use your sandbox token on api.dev.name.com. ````