Skip to content
Docs

Add a domain to a project

POSThttps://api.vercel.com/v10/projects/{idOrName}/domains
Add a domain to the project by passing its domain name and by specifying the project by either passing the project id or name in the URL. If the domain is not yet verified to be used on this project, the request will return verified = false, and the domain will need to be verified according to the verification challenge via POST /projects/:idOrName/domains/:domain/verify. If the domain already exists on the project, the request will fail with a 400 status code.
https://api.vercel.com/v10/projects/{idOrName}/domains
const response = await fetch('https://api.vercel.com/v10/projects/idOrName/domains?teamId=string&slug=string', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "www.example.com",
    "gitBranch": "null",
    "customEnvironmentId": "example_id",
    "redirect": "foobar.com",
    "redirectStatusCode": "307"
  }),
});


const data = await response.json();
console.log(data);
Response
{
  "name": "Example Name",
  "apexName": "Example Name",
  "projectId": "example_id",
  "redirect": "string",
  "redirectStatusCode": "301",
  "gitBranch": "string",
  "customEnvironmentId": "example_id",
  "updatedAt": "123",
  "createdAt": "123",
  "verified": "false",
  "verification": [
    {
      "type": "string",
      "domain": "string",
      "value": "string",
      "reason": "Customer requested refund"
    }
  ]
}

Authentication

AuthorizationbearerToken

Default authentication mechanism

Path parameters

idOrNamestringRequired
The unique project identifier or the project name

Query parameters

teamIdstringOptional
The Team identifier to perform the request on behalf of.
slugstringOptional
The Team slug to perform the request on behalf of.

Body

application/json
namestringRequired
The project domain name
gitBranchstringOptional
Git branch to link the project domain
customEnvironmentIdstringOptional
The unique custom environment identifier within the project
redirectstringOptional
Target destination domain for redirect
redirectStatusCodeintegerOptional
Status code for domain redirect

Response

200The domain was successfully added to the project
namestringRequired
apexNamestringRequired
projectIdstringRequired
redirectstringOptional
redirectStatusCodenumberOptional
gitBranchstringOptional
customEnvironmentIdstringOptional
updatedAtnumberOptional
createdAtnumberOptional
verifiedbooleanRequired
true if the domain is verified for use with the project. If false it will not be used as an alias on this project until the challenge in verification is completed.
verificationarrayOptional
A list of verification challenges, one of which must be completed to verify the domain for use on the project. After the challenge is complete POST /projects/:idOrName/domains/:domain/verify to verify the domain. Possible challenges: - If verification.type = TXT the verification.domain will be checked for a TXT record matching verification.value.

Errors

400One of the provided values in the request body is invalid. One of the provided values in the request query is invalid. The domain is not valid You can't set both a git branch and a redirect for the domain The domain can not be added because the latest production deployment for the project was not successful The domain redirect is not valid A domain cannot redirect to itself You can not set the production branch as a branch for your domain
401The request is not authorized.
402The account is missing a payment so payment method must be updated
403You do not have permission to access this resource. You don't have access to the domain you are adding
409The domain is already assigned to another Vercel project Cannot create project domain since owner already has `domain` on their account, but it's not verified yet. Cannot create project domain since owner already has `domain` on their account, and it's verified. The domain is not allowed to be used The project is currently being transferred
410Error