Custom Domains

Manage your custom domains for branded short links. These endpoints allow you to register, list, and remove domains associated with your account or team.

Note: Custom domains are only available on paid plans (Basic, Pro, Business, Agency).

Add a Domain

Register a new custom domain. This initiates the configuration process with our platform. After adding a domain, you must configure the DNS records provided in the response to verify ownership and enable SSL.


POST /api/v1/domains

Request Body

Parameter	Type	Required	Description
`domain`	string	Yes	The fully qualified domain name (e.g., `link.mybrand.com`).
`teamId`	integer	No	The ID of the team to associate this domain with. If omitted, it will be added to your personal account.

Response

Returns the created domain object, including the DNS records required for verification.


{
  "id": 123,
  "domain": "link.mybrand.com",
  "userId": 45,
  "teamId": null,
  "verified": false,
  "cfHostnameId": "xxx-yyy-zzz",
  "cfOwnershipTxtName": "_cf-custom-hostname.link.mybrand.com",
  "cfOwnershipTxtValue": "uuid-value",
  "cfDcvCnameTarget": "dcv.cloudflare.com",
  "createdAt": "2023-10-27T10:00:00.000Z",
  "updatedAt": "2023-10-27T10:00:00.000Z"
}

DNS Configuration

After adding a domain, you must add the following DNS records to your domain provider:

CNAME Record: Point your domain (e.g., link) to cname.multi-upload-tool.com (or the cfDcvCnameTarget if provided for SSL validation).
TXT Record: Add a TXT record with the name provided in cfOwnershipTxtName and the value in cfOwnershipTxtValue.

Once these records are propagated, the domain will be automatically verified.

List Domains

Retrieve a list of all custom domains associated with your account or a specific team.


GET /api/v1/domains

Query Parameters

Parameter	Type	Required	Description
`teamId`	integer	No	Filter domains by team ID. If omitted, returns personal domains.

Response

Returns an array of domain objects.


[
  {
    "id": 123,
    "domain": "link.mybrand.com",
    "userId": 45,
    "teamId": null,
    "verified": true,
    "createdAt": "2023-10-27T10:00:00.000Z",
    "_count": {
      "shortLinks": 15
    }
  }
]

Verify a Domain

Manually trigger the verification process for a domain. Use this after you have updated your DNS records.


POST /api/v1/domains/:id/verify

Path Parameters

Parameter	Type	Required	Description
`id`	integer	Yes	The ID of the domain to verify.

Response

Returns the updated domain object. If verification fails, it returns a 400 Bad Request with a message explaining the issue.


{
  "id": 123,
  "domain": "link.mybrand.com",
  "userId": 45,
  "teamId": null,
  "verified": true,
  "updatedAt": "2023-10-27T10:05:00.000Z"
}

Delete a Domain

Remove a custom domain from your account. This will stop all short links using this domain from working.


DELETE /api/v1/domains/:id

Path Parameters

Parameter	Type	Required	Description
`id`	integer	Yes	The ID of the domain to delete.

Response

Returns the deleted domain object.


{
  "id": 123,
  "domain": "link.mybrand.com",
  "userId": 45,
  "teamId": null,
  "verified": true
}