Skip to main content

Custom domain

This feature allows you to use your own custom domain (or subdomain) for shortened links. Follow the steps below to configure and utilize this service.

Step 1: Create a New Domain via API​

To get started, you need to create a new custom domain using the API. Use the create domain endpoint:

POST /v1/domains
Content-Type: application/json

{
  "name": "your-custom-domain.com"
}

Replace "your-custom-domain.com" with the desired custom domain for your shortened links. You must own the domain or subdomain and can configure it to point to Lynkr's nameservers.

The API will respond with the following information:

{
  "id": "some-id",
  "name": "your-custom-domain.com",
  "active": false,
  "dnsConfigurationState": "pending_validation",
  "nameservers": [
    "ns1.example.com",
    "ns2.example.com"
  ],
  "createdAt": "2019-08-24T14:15:22Z"
}

Note the values of the active and dnsConfigurationState fields. You will need to configure your domain's DNS settings before you can use it.

Step 2: Setup name servers DNS configuration​

The API return the nameservers configuration to setup when you created the custom domain, or your can retrieve this information using the /v1/domains/{id} endpoint.

{
  "nameservers": [
    "ns1.example.com",
    "ns2.example.com"
  ]
}

Update your domain's DNS configuration with the provided nameservers. You must delegate us the domain or subdomain by setting up NS records.

Step 3: Check and validate your DNS configuration​

Once you have updated your domain's DNS configuration, call the domain validation endpoint to check and validate that the DNS configuration is correct:

PATCH /v1/domains/{id}/validate
Content-Type: application/json

If the DNS configuration is correct, the API will respond with the following information (note the value validated of the dnsConfigurationState field):

{
  "active": false,
  "dnsConfigurationState": "validated"
}

Note: the value of the active field will be false until the configuration is finalized on the Lynkr platorm : it could take up to 5 minutes.

If the DNS configuration is incorrect (or not yet propagated), the API will respond with a 400 http code, and the value of the dnsConfigurationState field will be validation_failed.

Now that your custom domain is validated, you can use it to shorten links. When calling the link shortening endpoint, provide the name of your validated custom domain:

POST /v1/links/shorten
Content-Type: application/json

{
"url": "https://long-url-to-shorten.com",
"domainName": "your-custom-domain.com"
}