Back to help
16

Automation and API access

Approved commercial clients can use authorized API access to create and manage links from external systems such as campaign tools, CRM software, partner portals, and internal dashboards. API-created links follow the same destination quality, service-host, safety, length, custom slug, expiration, click limit, password, UTM, domain, and targeting rules that protect browser-created links, while supporting trusted high-volume workflows.

Public and commercial APIs

Creation via public API

POST /api/links Content-Type: application/json

{"url":"https://example.com/catalog","protocol":"https","isPermanent":true,"redirectStatusCode":302}

A successful HTTP 200 response contains shortCode, shortUrl, longUrl, originalUrl, dates, limit, counter, limit information, and isExisting. Use the returned shortUrl rather than collecting the domain and ID manually. The value isExisting=true means reuse of the matching entry.

The following fields are used for additional settings:

Request fields — Destination useCustomCode, customCode — Own ID startsAtUtc, expiresAtUtc, isPermanent — Start and date maxClicks, expirationRedirectUrl, redirectStatusCode — Link click limit and behavior password — Visitor password allowedReferrers, isPreviewEnabled, isWarningEnabled — Source and intermediate pages isEmailOtpEnabled, otpAllowedEmails — Email/OTP customDomainId — Available verified domain campaignId, utmTemplateId, utm — UTM; object utm contains source, medium, campaign, term, content ownerUserId — Create for the owner if the logged-in user is granted the appropriate right

Capabilities that require an account cannot be achieved by simply adding a JSON field. Login, permissions and feature availability are checked. For public creation there is a limit of 100 new links per hour per IP; exceeding this may result in a time limit of 24 hours. Matching existing records are not registered as new creations.

Verification and QR via API

GET /api/links/lookup?url=https%3A%2F%2Fclk.ms%2Fsale-2026 GET /api/links/sale-2026/qr GET /api/links/sale-2026/qr/download

In lookup, pass the full short URL with correct URL encoding. The response provides available information, including isExpired, isPasswordProtected, and moderation status. The destination URL of a secure link may be empty; This is not a JSON parsing error. Availability of QR depends on the settings and status of the link.

Commercial integration

A commercial API requires a token issued for integration with creation permission. Pass it as Authorization: Bearer YOUR_API_TOKEN or X-Api-Token: YOUR_API_TOKEN:

POST /api/commercial/links Authorization: Bearer YOUR_API_TOKEN Content-Type: application/json

{"url":"https://example.com/catalog","isPermanent":true,"customCode":"sale-api-2026","useCustomCode":true}

Do not publish such a token in the code of a public page, repository, or QR. The integration token and regular account login are not interchangeable. The presence of a token does not mean that the created link will automatically appear in the personal account of the user you have chosen.

For a commercial request, you can pass an object utm with fields source, medium, campaign, term and content; the first three are required when using tags. For example: "utm":{"source":"newsletter","medium":"email","campaign":"launch"}. These values ​​are appended to the target URL, preserving the remaining parameters and URL fragment. The commercial token does not give access to other people's campaigns, templates or domains: you cannot assign an owner through ownerUserId or use it campaignId and utmTemplateId.

The interactive specification is located on commercial API page if access is provided. Securing the specification page itself and authorizing the API are different mechanisms.

Error Handling

Check the HTTP status and response body. Basic situations: invalid URL or field, occupied identifier, missing login/token, insufficient rights, disabled function, prohibited target URL and exceeding restrictions. Service errors have machine code and sometimes a cause; Automatic model checking errors may have the format Problem Details with errors by fields. Don't assume that all errors are in the same JSON format.

Don't endlessly retry a request with bad data or a revoked token. When re-creating, consider isExisting and the own ID conflict. The error code is not translated; a user message can be matched to it in your application.

Complete user guide ยท Practical course

How to apply this section

Each topic explains a feature, the user decision behind it, and how to use it without making the link harder to manage. Read the checklist before changing a link that is already shared.

Before you publish or update

  • Start from the visitor experience: who opens the link, from where, on which device, and what should happen next.
  • Check that the destination is correct, opens quickly, and shows the expected page for the intended audience.
  • Choose only the controls that match the goal, such as expiration, password, referrer, QR design, UTM, routing, or analytics sharing.
  • Save a short note for important changes so future review, rollback, or teamwork stays clear.
  • Open the short link in a private browser session and, when relevant, test mobile, desktop, QR scan, and protected access paths.
  • Review analytics after sharing to confirm real visitors, source quality, device mix, and campaign performance.

Practical example

Example: create a test link for an internal page, add a clear slug, set a short expiration, enable preview if the destination is sensitive, scan the QR code from a phone, then check whether the visit appears in the link statistics.

Next step

After this topic is clear, combine it with one adjacent feature. For example, pair UTM with campaigns, QR with print layouts, targeting with fallback, or webhooks with conversion tracking.