Set Up a Custom Domain

A custom domain replaces bit.ly in your short links with a domain of your own, such as example.link/abc123. Set one up in two ways.

• Register a domain through Bitly. Bitly buys the domain and configures its DNS for you. Plans that include this allow a set number of registrations.
• Add a domain you already own. Bitly returns the DNS records to create at your registrar.

Both paths end with the same result: a custom domain on your organization, verified and ready for new links.

Before you start

• You need an organization admin role. Every write in this guide returns 403 for other members.
• You need your organization_guid. Get it from GET /v4/organizations.
• Your plan must include custom domains. Without the entitlement, a registration returns 409.
• DNS verification is asynchronous and takes 24 to 48 hours. No endpoint waits for it, so check the domain when your user comes back rather than on a timer.

Register a domain through Bitly

1. Find an available domain

GET /v4/domains returns only domains Bitly can register.

GET /v4/domains?query=example&limit=5&organization_guid=Oa1bcd234eF
{
  "input_domain": { "domain": "example.link", "status": "AVAILABLE" },
  "results": [
    { "domain": "example.link" },
    { "domain": "exampleapp.link" }
  ]
}

2. Get the registrar agreements

GET /v4/domains/{domain}/agreements returns the terms the registrant must accept. Show the title and the URL to your user, and collect each agreement_key.

GET /v4/domains/example.link/agreements?organization_guid=Oa1bcd234eF
{
  "domain_agreements": [
    { "agreement_key": "DNRA", "title": "Domain Name Registration Agreement", "url": "https://...", "content": "..." }
  ]
}

3. Register the domain

POST /v4/domains registers the domain and starts Bitly's DNS configuration. It returns 201.

POST /v4/domains
{
  "domain": "example.link",
  "organization_guid": "Oa1bcd234eF",
  "agreement_keys": ["DNRA"]
}

201 Created
{
  "custom_domain": "example.link",
  "organization_guid": "Oa1bcd234eF",
  "validation_status": "pending"
}

Registration is one way. There is no endpoint to cancel it, and each organization can register only the number of domains its plan includes. A further attempt returns 409 ALREADY_RECEIVED_COMPLIMENTARY_DOMAIN.

4. Wait for verification

Bitly sets the DNS records at the registrar, then verifies them. This takes 24 to 48 hours. Read the state as described in Check the status.

Add a domain you already own

1. Check the domain first

Send POST /v4/custom_domains with prevalidate set to true. The call checks the domain and creates nothing, so use it to catch a typo or a domain another Bitly account holds.

POST /v4/custom_domains
{
  "organization_guid": "Oa1bcd234eF",
  "custom_domain": "links.example.com",
  "prevalidate": true
}

2. Add the domain

Send the same call without prevalidate. Add group_guids to choose which groups may use the domain. The call returns 201 and queues verification.

POST /v4/custom_domains
{
  "organization_guid": "Oa1bcd234eF",
  "custom_domain": "links.example.com",
  "group_guids": ["Ba1bc23dE4F"]
}

A domain another Bitly account holds returns 409 INVALID_DOMAIN_ALREADY_TAKEN.

3. Create the DNS records

GET /v4/custom_domains/{custom_domain}/dns returns the records to create, the records that resolve today, and whether they match. It answers only for a domain already on the organization, so call it after step 2.

GET /v4/custom_domains/links.example.com/dns?organization_guid=Oa1bcd234eF
{
  "domain": "links.example.com",
  "dns_provider": "cloudflare",
  "type": "CNAME",
  "records": [],
  "required_records": [
    { "type": "CNAME", "host": "links", "value": "cname.bitly.com" }
  ],
  "records_valid": false
}

A root domain such as example.link needs two A records instead, each with the host @. Create every record in required_records, and remove any other record that points the same host elsewhere.

4. Wait for verification

Verification usually completes within 24 hours of the records propagating. Read the state as described next.

Check the status

GET /v4/custom_domains lists the domains of an organization. GET /v4/custom_domains/{custom_domain} returns one.

GET /v4/custom_domains?organization_guid=Oa1bcd234eF
{
  "custom_domains": [
    {
      "custom_domain": "links.example.com",
      "validation_status": "pending",
      "group_guids": ["Ba1bc23dE4F"],
      "configuration_last_check_ts": "2026-09-15T18:04:11+0000",
      "is_active": true
    }
  ]
}

validation_status reports the setup state.

To request another check, send POST /v4/custom_domains again for the same domain, without prevalidate.

Use the domain

Once the status is ok, pass the domain when you shorten a link.

POST /v4/shorten
{
  "long_url": "https://example.com/landing",
  "domain": "links.example.com",
  "group_guid": "Ba1bc23dE4F"
}

GET /v4/bsds lists the verified domains the authenticated user can shorten with, across every organization and group they belong to. Any member can call it, so use it to build a domain picker.

Errors