POST /clean_domain • Credits: 0.5 credits per call

Clean Domain normalizes a messy URL or domain string into a clean root domain. Send a POST request with the messy_url parameter. The response holds the cleaned URL, the root domain, and a DNS validation flag. Each call costs 0.5 credits.

What does Clean Domain do?

Company lists hold the same website in many forms. One record holds https://www.acme.com/about?ref=google. Another record holds ACME.COM. Clean Domain reduces both records to the root domain acme.com, so you can group them. Clean Domain is a utility endpoint. It runs inside RichAPI and calls no external data provider. The only network operation is a DNS lookup, which confirms that the hostname exists.

Which endpoint does Clean Domain use?

Method: POST
URL: https://api.richapi.ai/api/v1/clean_domain
Authentication: x-api-key header
Response: Synchronous JSON
Credits: 0.5 credits per call

How to send a Clean Domain request

Copy your API key from the RichAPI dashboard.
Set the messy_url parameter to the raw URL or domain string.
Send a POST request to https://api.richapi.ai/api/v1/clean_domain.
Send the API key in the x-api-key header.
Read the clean_domain field from the response.
If validated_domain is false, treat the input as a bad domain.

cURL

curl -X POST https://api.richapi.ai/api/v1/clean_domain   
  -H "x-api-key: YOUR_API_KEY"   
  -H "Content-Type: application/json"   
  -d '{
    "messy_url": "https://www.acme.com/about?ref=google"
  }'

Python

import requests

response = requests.post(
    "https://api.richapi.ai/api/v1/clean_domain",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={"messy_url": "https://www.acme.com/about?ref=google"},
    timeout=60,
)
response.raise_for_status()
print(response.json())

Node.js

const response = await fetch("https://api.richapi.ai/api/v1/clean_domain", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    messy_url: "https://www.acme.com/about?ref=google",
  }),
});

const data = await response.json();
console.log(data);

Which parameters does Clean Domain accept?

Parameter	Type	Required	Default	Description
`messy_url`	string	Yes	`""`	The raw URL or domain string to normalize. An empty value returns a `400` error.

What does Clean Domain return for ten messy inputs?

The table below shows a real input and the exact cleaned result for each field.

`messy_url` you send	`clean_url`	`clean_domain`	`validated_domain`
`https://www.acme.com/about?ref=google`	`https://www.acme.com/about?ref=google`	`acme.com`	`true`
`HTTP://WWW.Microsoft.COM/en-us/`	`http://www.microsoft.com/en-us/`	`microsoft.com`	`true`
`blog.hubspot.com`	`https://blog.hubspot.com`	`hubspot.com`	`true`
`www.bbc.co.uk/news`	`https://www.bbc.co.uk/news`	`bbc.co.uk`	`true`
`https://www.stripe.com:443/pricing`	`https://www.stripe.com/pricing`	`stripe.com`	`true`
`https://shop.myer.com.au/cart?utm_source=x#top`	`https://shop.myer.com.au/cart?utm_source=x#top`	`myer.com.au`	`true`
`https://www.notion.so/product`	`https://www.notion.so/product`	`notion.so`	`true`
`acme.com.`	`null`	`null`	`false`
`192.168.1.1`	`null`	`null`	`false`
`javascript:alert(1)`	`null`	`null`	`false`

The two output fields do two different jobs. The clean_url field holds the same page in a normal form. The clean_domain field holds the company root domain, without the path and without the subdomain.

Which normalization rules does Clean Domain apply?

Rule	What Clean Domain does	Example
Whitespace	Removes leading and trailing spaces.	`acme.com` becomes `acme.com`
Missing scheme	Adds `https://`.	`acme.com` becomes `https://acme.com`
Scheme case	Lowercases the scheme and keeps `http` as `http`.	`HTTP://acme.com` becomes `http://acme.com`
Hostname case	Lowercases the hostname. The path and the query keep their case.	`WWW.Acme.COM/Page` becomes `www.acme.com/Page`
Default port	Removes port `80` and port `443`. Keeps every other port.	`acme.com:443` becomes `acme.com`
Root path	Removes a path of exactly `/`.	`https://acme.com/` becomes `https://acme.com`
Path, query, fragment	Keeps all three in `clean_url`. Drops all three from `clean_domain`.	`acme.com/a?b=1#c` keeps `/a?b=1#c`
Subdomain	Keeps the subdomain in `clean_url`. Removes it from `clean_domain`.	`blog.acme.com` gives the domain `acme.com`
Two-part TLD	Keeps three labels for a public suffix such as `co.uk` or `com.au`.	`www.bbc.co.uk` gives the domain `bbc.co.uk`
DNS check	Resolves the hostname. If the hostname does not resolve, the response reports a failure.	An unregistered domain returns `validated_domain: false`

Clean Domain rejects the inputs below. Each one returns clean_url: null, clean_domain: null, and validated_domain: false.

Rejected input	Reason
`javascript:`, `data:`, `file:`, `ftp:`, `mailto:`, `tel:`, `vbscript:`, `mhtml:`, `jar:`, `gopher:`, `dict:`	The scheme is dangerous.
A string that holds `<`, `>`, `{`, `}`, `\\|`, `\`, `^`, `, `[` or `]`	The character is not valid in a URL.
`192.168.1.1`, `8.8.8.8`	The host is an IP address, not a domain.
`xn--bcher-kva.example`	The host is a punycode or IDN domain.
`localhost`, `notadomain`	The host holds fewer than two labels.
`acme.com.`	A trailing dot creates an empty label.
A host that does not resolve in DNS	The domain does not exist.

What does the Clean Domain response look like?

The block below is an example response for the request body {"messy_url": "https://www.acme.com/about?ref=google"}.

{
  "clean_url": "https://www.acme.com/about?ref=google",
  "clean_domain": "acme.com",
  "validated_domain": true
}

Which fields does the Clean Domain response hold?

Field	Type	Description
`clean_url`	string or null	The normalized URL. It keeps the scheme, the hostname, the port that is not a default, the path, the query and the fragment. It is `null` on a failure.
`clean_domain`	string or null	The root domain, without a scheme, a subdomain, a port or a path. It is `null` on a failure.
`validated_domain`	boolean	The value is `true` for a hostname that passed every rule and resolved in DNS. The value is `false` on a failure.

How to normalize a domain before deduplication

A raw company list holds one website in many forms, so a count of unique values is wrong. Use clean_domain as the group key.

Read the raw website value from each record in your list.
Send one Clean Domain request for each value.
Read the clean_domain field from each response.
Skip every record where validated_domain is false.
Group the records by the clean_domain value.
Keep one record for each group.
Send the enrichment request once for each group.

CAUTION: Do not send an enrichment request before you deduplicate the list. A duplicate company costs the full enrichment price a second time.

Clean Domain costs 0.5 credits and Website Intelligence costs 5 credits. One Clean Domain call that removes one duplicate saves 4.5 credits.

How much does Clean Domain cost?

Clean Domain costs 0.5 credits per call. At $0.02 a credit, the rate on the 1,000 and 5,000 credit packs, one call costs $0.01. Larger packs cost less per credit. RichAPI charges the credit on a 200 response. A 400 response, a 403 response and a 429 response cost no credits.

Calls	Credits	Cost
1	0.5	$0.01
100	50	$1.00
1,000	500	$10.00
10,000	5,000	$100.00

CAUTION: A response with validated_domain: false is still a 200 response. RichAPI charges 0.5 credits for it.

Which errors can Clean Domain return?

Status	Meaning	What to do
`400`	The request body is missing, the JSON is not valid, or `messy_url` is empty.	Send a JSON object that holds a non-empty `messy_url` value.
`401`	The API key is missing, wrong or revoked.	Send a valid key in the `x-api-key` header.
`403`	This API key has no access to this endpoint (`Endpoint not available on your plan`).	Call `GET /api/v1/my-endpoints` to see the endpoints that this key can use. Contact support for access.
`405`	The request used a method other than `POST`.	Send the request again with the `POST` method.
`429`	The request rate is over the limit for the account.	Wait, then send the request again.
`500`	The API failed.	Send the request again. If the failure repeats, contact support.

Every error response holds an error field with a plain-language message.

Frequently asked questions

Does Clean Domain remove www from the URL?

Clean Domain removes www from the clean_domain field, because www is a subdomain. Clean Domain keeps www in the clean_url field, together with the path and the query.

What does validated_domain: false mean?

The value validated_domain: false means that Clean Domain rejected the input or that the hostname did not resolve in DNS. In that case, clean_url and clean_domain are both null. The call still returns HTTP 200 and still costs 0.5 credits.

How does Clean Domain handle a .co.uk or .com.au domain?

Clean Domain holds a list of two-part public suffixes, such as co.uk, com.au, co.jp and com.br. For a hostname that ends in one of those suffixes, Clean Domain keeps three labels. The input www.bbc.co.uk/news returns the domain bbc.co.uk, not co.uk.

Can I send the clean_domain value to Company Enrichment?

No. Company Enrichment accepts a LinkedIn company URL, not a root domain. Use the clean_domain value as a deduplication key, and send the LinkedIn company URL to Company Enrichment.

Is Clean Domain synchronous?

Yes. Clean Domain returns the result in the same response. The endpoint needs no second call, no polling and no webhook.

Does Clean Domain call an external provider?

No. Clean Domain runs inside RichAPI. The one network operation is the DNS lookup that sets the validated_domain field.

Clean Domain API