domains

Reference

4 min read

Domains

Purchase a domain

post/v4/domains/buy

Allows to purchase the specified domain.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v4/domains/buy?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2  "body": {
3    "name": "example.com",
4    "expectedPrice": 10,
5    "renew": true
6  },
7  "headers": {
8    "Authorization": "Bearer <TOKEN>"
9  },
10  "method": "post"
11})

Parameters

Query Params

Body Params

Query Parameter	Description
slug	string The Team slug to perform the request on behalf of.
teamId	string The Team identifier to perform the request on behalf of.

Response

domainobjectRequired

Properties

Response Codes

Code	Description
`201`	Successful response for purchasing a Domain.
`202`	Domain purchase is being processed asynchronously.
`400`	One of the provided values in the request body is invalid.
`401`
`403`	You do not have permission to access this resource.
`409`
`429`

Optional params

fetch-request

1await fetch("https://api.vercel.com/v4/domains/buy?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2  "body": {
3    "name": "example.com",
4    "expectedPrice": 10,
5    "renew": true
6  },
7  "headers": {
8    "Authorization": "Bearer <TOKEN>"
9  },
10  "method": "post"
11})

Check the price for a domain

get/v4/domains/price

Check the price to purchase a domain and how long a single purchase period is.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v4/domains/price?name=example.com&slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE&type=new", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

Parameters

Query Params

Query Parameter	Description
name	string required The name of the domain for which the price needs to be checked. Example:`example.com`
slug	string The Team slug to perform the request on behalf of.
teamId	string The Team identifier to perform the request on behalf of.
type	string of the following In which status of the domain the price needs to be checked. Example:`new` Allowed values:`newrenewal`

Response

Successful response which returns the price of the domain and the period.

periodnumberRequired
The number of years the domain could be held before paying again.
Example: 1

pricenumberRequired
The domain price in USD.
Example: 20

Response Codes

Code	Description
`200`	Successful response which returns the price of the domain and the period.
`400`	One of the provided values in the request query is invalid.
`401`
`403`	You do not have permission to access this resource.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v4/domains/price?name=example.com&slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE&type=new", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

Check a Domain Availability

get/v4/domains/status

Check if a domain name is available for purchase.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v4/domains/status?name=example.com&slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

Parameters

Query Params

Query Parameter	Description
name	string required The name of the domain for which we would like to check the status. Example:`example.com`
slug	string The Team slug to perform the request on behalf of.
teamId	string The Team identifier to perform the request on behalf of.

Response

availablebooleanRequired

Response Codes

Code	Description
`200`	Successful response checking if a Domain's name is available.
`400`	One of the provided values in the request query is invalid.
`401`
`403`	You do not have permission to access this resource.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v4/domains/status?name=example.com&slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

Register or transfer-in a new Domain

post/v5/domains

This endpoint is used for adding a new apex domain name with Vercel for the authenticating user. Can also be used for initiating a domain transfer request from an external Registrar to Vercel.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v5/domains?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2  "body": {
3    "name": "example.com",
4    "cdnEnabled": true,
5    "zone": true,
6    "method": "add"
7  },
8  "headers": {
9    "Authorization": "Bearer <TOKEN>"
10  },
11  "method": "post"
12})

Parameters

Query Params

Body Params

Query Parameter	Description
slug	string The Team slug to perform the request on behalf of.
teamId	string The Team identifier to perform the request on behalf of.

Response

domainobjectRequired

Properties

Response Codes

Code	Description
`200`
`400`	One of the provided values in the request body is invalid.
`401`
`402`	The account was soft-blocked for an unhandled reason. The account is missing a payment so payment method must be updated
`403`	You do not have permission to access this resource.
`404`
`409`

Optional params

fetch-request

1await fetch("https://api.vercel.com/v5/domains?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2  "body": {
3    "name": "example.com",
4    "cdnEnabled": true,
5    "zone": true,
6    "method": "add"
7  },
8  "headers": {
9    "Authorization": "Bearer <TOKEN>"
10  },
11  "method": "post"
12})

Remove a domain by name

delete/v6/domains/{domain}

Delete a previously registered domain name from Vercel. Deleting a domain will automatically remove any associated aliases.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v6/domains/example.com?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "delete"
6})

Parameters

Path Params

Query Params

Path Parameter	Description
domain	string required The name of the domain. Example:`example.com`

Response

uidstringRequired

Response Codes

Code	Description
`200`	Successful response removing a domain.
`400`	One of the provided values in the request query is invalid.
`401`
`403`	You do not have permission to access this resource.
`404`
`409`

Optional params

fetch-request

1await fetch("https://api.vercel.com/v6/domains/example.com?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "delete"
6})

Get Information for a Single Domain

get/v5/domains/{domain}

Get information for a single domain in an account or team.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v5/domains/example.com?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

Parameters

Path Params

Query Params

Path Parameter	Description
domain	string required The name of the domain. Example:`example.com`

Response

domainobjectRequired

Properties

Response Codes

Code	Description
`200`	Successful response retrieving an information for a specific domains.
`400`	One of the provided values in the request query is invalid.
`401`
`403`	You do not have permission to access this resource.
`404`

Optional params

fetch-request

1await fetch("https://api.vercel.com/v5/domains/example.com?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

Get a Domain's configuration

get/v6/domains/{domain}/config

Get a Domain's configuration.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v6/domains/example.com/config?slug=SOME_STRING_VALUE&strict=true&teamId=SOME_STRING_VALUE", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

Parameters

Path Params

Query Params

Path Parameter	Description
domain	string required The name of the domain. Example:`example.com`

Response

acceptedChallengesarray
Which challenge types the domain can use for issuing certs.

configuredBystring or null
One of: CNAME | A | http | dns-01
How we see the domain's configuration. - CNAME: Domain has a CNAME pointing to Vercel. - A: Domain's A record is resolving to Vercel. - http: Domain is resolving to Vercel but may be behind a Proxy. - dns-01: Domain is not resolving to Vercel but dns-01 challenge is enabled. - null: Domain is not resolving to Vercel.

misconfiguredbooleanRequired
Whether or not the domain is configured AND we can automatically generate a TLS certificate.

Response Codes

Code	Description
`200`
`400`	One of the provided values in the request query is invalid.
`401`
`403`	You do not have permission to access this resource.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v6/domains/example.com/config?slug=SOME_STRING_VALUE&strict=true&teamId=SOME_STRING_VALUE", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

Get domain transfer info.

get/v1/domains/{domain}/registry

Fetch domain transfer availability or transfer status if a transfer is in progress.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/domains/domain/registry?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

Parameters

Query Params

Query Parameter	Description
slug	string The Team slug to perform the request on behalf of.
teamId	string The Team identifier to perform the request on behalf of.

Response

reasonstringRequired
Description associated with transferable state.

statusstringRequired
One of: pending_owner | pending_admin | pending_registry | completed | cancelled | undef | unknown
The current state of an ongoing transfer. pending_owner: Awaiting approval by domain's admin contact (every transfer begins with this status). If approval is not given within five days, the transfer is cancelled. pending_admin: Waiting for approval by Vercel Registrar admin. pending_registry: Awaiting registry approval (the transfer completes after 7 days unless it is declined by the current registrar). completed: The transfer completed successfully. cancelled: The transfer was cancelled. undef: No transfer exists for this domain. unknown: This TLD is not supported by Vercel's Registrar.

transferPolicystring or nullRequired
One of: charge-and-renew | no-charge-no-change | no-change | new-term | not-supported
The domain's transfer policy (depends on TLD requirements). charge-and-renew: transfer will charge for renewal and will renew the existing domain's registration. no-charge-no-change: transfer will have no change to registration period and does not require charge. no-change: transfer charge is required, but no change in registration period. new-term: transfer charge is required and a new registry term is set based on the transfer date. not-supported: transfers are not supported for this domain or TLD. null: This TLD is not supported by Vercel's Registrar.

transferablebooleanRequired
Whether or not the domain is transferable

Response Codes

Code	Description
`200`
`400`
`401`
`403`	You do not have permission to access this resource.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v1/domains/domain/registry?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

List all the domains

get/v5/domains

Retrieves a list of domains registered for the authenticated user or team. By default it returns the last 20 domains if no limit is provided.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v5/domains?limit=20&since=1609499532000&slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE&until=1612264332000", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

Parameters

Query Params

Query Parameter	Description
limit	number Maximum number of domains to list from a request. Example:`20`
since	number Get domains created after this JavaScript timestamp. Example:`1609499532000`
slug	string The Team slug to perform the request on behalf of.
teamId	string The Team identifier to perform the request on behalf of.
until	number Get domains created before this JavaScript timestamp. Example:`1612264332000`

Response

domainsarrayRequired
Properties
paginationRequired

Response Codes

Code	Description
`200`	Successful response retrieving a list of domains.
`400`	One of the provided values in the request query is invalid.
`401`
`403`	You do not have permission to access this resource.
`409`

Optional params

fetch-request

1await fetch("https://api.vercel.com/v5/domains?limit=20&since=1609499532000&slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE&until=1612264332000", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

Update or move apex domain

patch/v3/domains/{domain}

Update or move apex domain.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v3/domains/SOME_STRING_VALUE?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2  "body": {
3    "op": "update",
4    "renew": true,
5    "customNameservers": "SOME_ARRAY_VALUE",
6    "zone": true
7  },
8  "headers": {
9    "Authorization": "Bearer <TOKEN>"
10  },
11  "method": "patch"
12})

Parameters

Path Params

Query Params

Body Params

Path Parameter	Description
domain	string

Response

One of the following objects
One of

Response Codes

Code	Description
`200`
`400`	One of the provided values in the request body is invalid. One of the provided values in the request query is invalid.
`401`
`403`	You do not have permission to access this resource.
`404`
`409`

Optional params

fetch-request

1await fetch("https://api.vercel.com/v3/domains/SOME_STRING_VALUE?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2  "body": {
3    "op": "update",
4    "renew": true,
5    "customNameservers": "SOME_ARRAY_VALUE",
6    "zone": true
7  },
8  "headers": {
9    "Authorization": "Bearer <TOKEN>"
10  },
11  "method": "patch"
12})

Last updated on April 27, 2024

Update an existing DNS record

Purchase a domain

Was this helpful?