UniLink API: Domains Endpoint (Manage Custom Domains Programmatically)

The /domains endpoint lets you connect, verify, and remove custom domains via API — the foundation for agencies that provision branded pages at scale without manual dashboard work.

For agencies managing dozens of client UniLink pages, manually connecting a custom domain through the dashboard for each client is a significant time sink. The /domains endpoint removes that friction entirely: your onboarding workflow can add the domain, monitor verification status, and confirm the SSL certificate is active — all without anyone touching the dashboard. The same endpoint powers automated provisioning tools, white-label reseller platforms, and client onboarding scripts that need to set up a fully branded UniLink page as part of a larger workflow.

What the Domains Endpoint Does

The GET /domains endpoint returns a list of all custom domains connected to your UniLink account. Each domain object includes the domain string (e.g., links.example.com), the status field with one of three values (pending, active, or error), the ssl_status field (pending, active, or failed), and the page_id of the UniLink page the domain is mapped to. This single list call tells you the complete state of your domain infrastructure without needing to check each domain individually.

Adding a new domain with POST /domains creates a domain record in pending status and returns the DNS records your customer needs to configure with their domain registrar. The response includes a cname_target value — the hostname your customer must point their DNS CNAME record to — and optionally a txt_verification token for TXT-based domain ownership verification if CNAME verification is not available. Once your customer configures DNS, you poll GET /domains/{id}/verify to check propagation status; the response updates to active once the DNS record is detected and the SSL certificate is issued.

Removing a domain with DELETE /domains/{id} disconnects the custom domain from the page and removes the SSL certificate. The domain is not deleted from the customer's registrar — that is outside UniLink's control — but traffic arriving on that domain will no longer resolve to the UniLink page. If the domain is later re-added to the same or a different page, it goes through the verification flow again from the beginning. The associated UniLink page continues to function on its default unil.ink/username URL regardless of whether a custom domain is connected.

How to Get Started

1. Generate an API key with write scope from Settings → API in your dashboard at app.unilink.us. POST and DELETE operations on domains require at minimum write scope; DELETE requires admin scope.
2. List your existing domains to understand the response structure: curl -H "Authorization: Bearer YOUR_KEY" https://unilink.us/api/v1/domains. Review the status, ssl_status, and page_id field values.
3. Identify the page ID you want to attach a domain to by calling GET /pages and noting the ID of the target page.
4. Add a test domain: POST /domains with body {"domain": "test.yourdomain.com", "page_id": "{page_id}"}. The response contains the cname_target DNS record to configure.
5. Poll the verification endpoint after configuring DNS: GET /domains/{id}/verify. Expect the status to remain pending during DNS propagation (minutes to hours) before transitioning to active.

How to Use the Domains Endpoint

1. List domains and check status: GET /domains — scan the list for any entries with status: "error" or ssl_status: "failed" to surface domains that need attention in your monitoring dashboard.
2. Add a domain: POST /domains with JSON body {"domain": "links.clientsite.com", "page_id": "abc123"}. Extract cname_target from the response and display it to the client as the DNS record to set.
3. Check verification status: GET /domains/{id}/verify — poll this endpoint every 5 minutes after DNS configuration. The response returns {"status": "pending"} until DNS propagates, then {"status": "active", "ssl_status": "active"}.
4. Fetch a single domain: GET /domains/{id} returns the full domain object including current status, SSL status, and associated page ID. Use this for status display in your agency client portal.
5. Remove a domain: DELETE /domains/{id} requires admin scope. The domain is disconnected immediately; the associated page remains accessible on its default unil.ink URL.

Key Settings

Get the Most Out Of the Domains Endpoint

Design your client onboarding workflow as a step-by-step state machine driven by the domain status field. Step 1: create the UniLink page and record the page ID. Step 2: call POST /domains and surface the cname_target to the client. Step 3: poll GET /domains/{id}/verify on a schedule and email the client when status reaches active. Step 4: confirm with a final status check that ssl_status is also active. Each step has a clear API call and a clear completion condition, making the workflow automatable end-to-end.

For white-label reseller platforms, store the UniLink domain ID alongside the client record in your database. This gives you the reference needed to check status, update the page association, or delete the domain if a client churns — without scanning all your domains to find the right one. Include the domain ID in your client object at provisioning time, not as an afterthought.

DNS propagation times vary from minutes to 48 hours depending on the registrar and TTL settings. Design your verification polling with exponential backoff rather than a fixed interval: poll at 5, 10, 20, 40 minute intervals rather than every minute. This keeps your API call volume low during long propagation windows while still detecting fast propagations quickly. After 48 hours without an active status, escalate to a human review — the DNS configuration likely has an error.

If you manage domains across multiple UniLink accounts — for example, each agency client has their own UniLink account — you will need a separate API key per account. The domains endpoint is scoped to a single account; there is no cross-account domain management endpoint. Structure your provisioning script to accept an account API key as a parameter and call the domains endpoint with that key for each client account independently.

Troubleshooting

• The domains endpoint base URL is https://unilink.us/api/v1/domains — POST to add, GET to monitor, DELETE to remove.
• After adding a domain, surface the cname_target value to clients — it is the only DNS record they need to configure.
• Poll GET /domains/{id}/verify with exponential backoff to track verification progress without hammering the API.
• Monitor all domains daily for status: "error" — proactive alerting catches broken domains before clients notice.
• Store the UniLink domain ID in your client database at provisioning time for clean lifecycle management later.