DEVELOPER REFERENCE

URLZ.li API documentation

Authentication, short links, file and photo uploads, click analytics and paid-link APIs, with examples ready to use.

01

Overview

Build short-link, upload, analytics and paid-access workflows with the URLZ API. This reference separates server API-key integrations from authenticated account sessions.

Server-to-server

Use your active API key to create and search links from a backend, automation or internal tool.

apikey=YOUR_API_KEY

Account session

Use a Bearer session for account-owned links, uploads, analytics and monetization.

Authorization: Bearer …
02

Quick start

Create your first short link in three steps, then use the detailed reference for production.

  1. 1
    Create an account

    Open the dashboard and activate an API plan.

  2. 2
    Copy your API key

    Keep it on your server; never expose it in public code.

  3. 3
    Send the request

    Post the destination and read result.short_url from the JSON response.

Curl
curl -X POST "https://api.urlz.li/url/create" \
  --data-urlencode "apikey=YOUR_API_KEY" \
  --data-urlencode "fullUrl=https://example.com/private-report"
03

Authentication

URLZ supports two authentication modes. Choose the one that matches your integration.

A

API key

For backend integrations. Send apikey in the query string or form body. The key and subscription must be active.

apikey=YOUR_API_KEY
B

Bearer session

For account features. Obtain a session token from the login endpoint and send it in the Authorization header.

Authorization: Bearer SESSION_TOKEN
Keep credentials server-side

Never publish an API key, password or Bearer token in browser JavaScript, mobile logs, source control or a public repository.

04

Endpoint index

Select an endpoint to jump directly to its parameters, request and response examples.

05

API key endpoints

Stable server-to-server routes for creating and searching short links.

06

Account endpoints

Account-owned links, uploads, click analytics and deletion.

POST/mobile/v1/auth/login.php

Open an account session

Exchange account credentials for a Bearer session token.

No authentication

Parameters

ParameterTypeRequiredDefault
emailemailYes—
passwordstringYes—
Request
curl -X POST "https://api.urlz.li/mobile/v1/auth/login.php" \
  -H "Content-Type: application/json" \
  -d '{"email":"developer@example.com","password":"YOUR_PASSWORD"}'
Response
{
  "token": "SESSION_TOKEN",
  "user": {
    "id": 42,
    "email": "developer@example.com",
    "apiKey": "ACCOUNT_API_KEY",
    "planActive": true
  }
}
POST/mobile/v1/shorten.php

Create an account-linked link

Create a normal or password-protected link. Bearer authentication is optional unless a password is used.

Optional Bearer token

Parameters

ParameterTypeRequiredDefault
urlURLYes—
passwordstring (min. 4)No—
Request
curl -X POST "https://api.urlz.li/mobile/v1/shorten.php" \
  -H "Authorization: Bearer SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/private","password":"safe-pass"}'
Response
{
  "shortUrl": "https://urlz.li/Ab3dE91x",
  "destination": "https://example.com/private",
  "hash": "Ab3dE91x",
  "protected": true
}
POST/mobile/v1/upload.php

Upload a file or photo

Upload an allowed file up to 10 MB and receive a short URL.

Optional Bearer token

Parameters

ParameterTypeRequiredDefault
filemultipart fileYes—
kindphoto | documentNodocument
passwordstring (min. 4)No—
Request
curl -X POST "https://api.urlz.li/mobile/v1/upload.php" \
  -H "Authorization: Bearer SESSION_TOKEN" \
  -F "file=@./photo.jpg" \
  -F "kind=photo"
Response
{
  "shortUrl": "https://urlz.li/P8kLm21q",
  "destination": "https://urlz.li/cloud/app/photo_….jpg",
  "hash": "P8kLm21q",
  "protected": false
}
GET/mobile/v1/clicks.php

Read click analytics

Retrieve click totals, unique visitors, top countries and paginated access events.

Bearer

Parameters

ParameterTypeRequiredDefault
linkIdintegerYes—
limitinteger (1–100)No100
offsetintegerNo0
Request
curl "https://api.urlz.li/mobile/v1/clicks.php?linkId=1204&limit=25" \
  -H "Authorization: Bearer SESSION_TOKEN"
Response
{
  "link": { "id": 1204, "shortUrl": "https://urlz.li/7b3c2e5a" },
  "summary": {
    "totalClicks": 18,
    "uniqueVisitors": 14,
    "clicksLast24Hours": 2,
    "clicksLast7Days": 9
  },
  "countries": [{ "country": "France", "countryCode": "FR", "clicks": 8 }],
  "items": []
}
07

URLZ Chat & Request

Add private conversations, collect requested documents, schedule reminders and track submissions.

POST/mobile/v1/collaboration/configure.php

Enable URLZ Chat or URLZ Request

Attach a private conversation and/or a document request to an existing account link. A Bearer session token or API key is accepted.

Bearer or API key

Parameters

ParameterTypeRequiredDefault
hashstringYes—
chat.enabledbooleanNofalse
request.enabledbooleanNofalse
request.titlestringNo—
request.itemsstring[]No[]
request.recipientsemail[]No[]
request.deadlineISO datetimeNo—
request.paymentRequiredbooleanNofalse
Request
curl -X POST "https://api.urlz.li/mobile/v1/collaboration/configure.php" \
  -H "Authorization: Bearer SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"hash":"7b3c2e5a","chat":{"enabled":true},"request":{"enabled":true,"title":"Accounting documents","items":["Invoices","Bank statement"]}}'
Response
{"featureId":14,"hash":"7b3c2e5a","chatEnabled":true,"requestEnabled":true}
GET/mobile/v1/collaboration/chats.php

List link conversations

Return chat-enabled links and message totals. Add id to retrieve messages.

Bearer

Parameters

ParameterTypeRequiredDefault
idintegerNo—
afterintegerNo0
Request
curl "https://api.urlz.li/mobile/v1/collaboration/chats.php?id=14" \
  -H "Authorization: Bearer SESSION_TOKEN"
Response
{"items":[{"id":14,"hash":"7b3c2e5a","messageCount":3,"messages":[]}]}
GET/mobile/v1/collaboration/requests.php

Track document requests

List requests, expected items, recipients, submissions and secure files. Add id for full detail.

Bearer

Parameters

ParameterTypeRequiredDefault
idintegerNo—
Request
curl "https://api.urlz.li/mobile/v1/collaboration/requests.php?id=14" \
  -H "Authorization: Bearer SESSION_TOKEN"
Response
{"items":[{"id":14,"title":"Accounting documents","recipients":1,"submissions":1,"files":2}]}
08

Errors & status codes

Modern endpoints return JSON with a human-readable message. API-key routes return an error field. Always branch on the HTTP status, not the message text.

{ "message": "A valid link is required." }{ "error": "Invalid API key" }
200
Success

The request completed successfully.

201
Created

The link or upload was created.

400
Invalid request

Malformed JSON or invalid request syntax.

401
Authentication required

The Bearer token is missing or expired.

403
Forbidden

The API key, plan or account cannot perform this action.

404
Not found

The requested link or resource does not exist.

409
Conflict

The requested state conflicts with an existing resource.

422
Validation failed

One or more fields are missing or invalid.

429
Too many requests

Slow down and retry with exponential backoff.

500/503
Server unavailable

Retry later and keep the original request idempotent.

09

Security & limits

Apply these rules to every production integration.

  • Use HTTPS only.
  • Keep API keys private and rotate them regularly.
  • Validate and encode user-supplied parameters.
  • Use pagination for list and log requests.
  • Recommended maximum: 10 requests per second per key.
Need help with an integration?

Send the endpoint, HTTP status and a sanitized request example. Never include credentials.

URLZ FOR iPHONE

The new iOS version is almost here

The updated URLZ app for iPhone is being finalized and will arrive on the App Store in the next few days. Thank you for your patience.