How to Create Short Links via the CodeQR API: Complete Guide
Learn how to use the CodeQR API to programmatically create short links and integrate this functionality into your applications.

What is the CodeQR API?
The CodeQR API is a RESTful interface that lets you create, manage, and track short links programmatically. With it, you can:
- Create short links with custom URLs and branded domains
- Customize appearance with custom preview for social networks
- Cloak URLs with link cloaking for complex URLs
- Track conversions with advanced conversion tracking
- Optimize SEO with links indexable by search engines
- Configure behaviors like expiration, password, and redirect
- Track analytics and real-time clicks
- Integrate webhooks for automated events
Why use the CodeQR API?
Advantages of integration via API
- Full automation: Create short links with no manual intervention
- Scalability: Generate thousands of links quickly
- Advanced customization: Full control over appearance and behavior
- Simple integration: Works with any programming language
- Detailed analytics: Track performance and engagement
Common use cases
- Marketing: Promotional campaigns with conversion tracking
- E-commerce: Product links with custom preview
- Social media: Optimized sharing with custom preview
- Email marketing: Trackable links in campaigns
- Affiliates: Referral links and commissions
- SEO: Indexable links for better ranking
- Complex URLs: Cloaking to mask long URLs
- Analytics: Detailed conversion tracking
Initial Setup
1. Get your API key
To get started, you need a valid API key:
- Go to Settings > API Keys in your CodeQR dashboard
- Click "Create" to generate a new key
- Select the necessary permissions
- Copy and store the key securely
2. Set up authentication
All requests must include your API key in the authorization header:
Authorization: Bearer codeqr_xxxxxxxx
3. Get Your Project Slug
In addition to your API key, you need your project's project slug. This parameter is required for all requests:
How to find your project slug:
- Access your project in the CodeQR dashboard
- The slug appears in the URL: app.codeqr.io/[acme]
- Example: if the URL is app.codeqr.io/acme, the slug is marketing
- Or go to Settings > Project to see the configured slug
4. API Base URL
All requests must be made to:
https://api.codeqr.io
Important: All requests must include the projectSlug parameter in the query string.
Creating Your First Short Link
Basic link
The minimum required parameter is the destination url:
curl --request POST \ --url https://api.codeqr.io/links \ --header 'Authorization: Bearer codeqr_your_api_key' \ --header 'Content-Type: application/json' \ --data '{"url": "https://codeqr.io"}'
API response:
{ "id": "clwc7hxcd0001ab6tqskb0h7v", "domain": "codeqr.link", "key": "site", "url": "https://codeqr.io", "archived": false, "expiresAt": null, "expiredUrl": null, "password": null, "externalId": null, "trackConversion": true, "proxy": true, "title": "CodeQR - Smart QR Codes, Short Links & Custom Pages", "description": "Create, manage, and track intelligent QR Codes, dynamic short links, and personalized landing pages. Boost engagement and gain valuable insights for your business.", "image": "https://res.cloudinary.com/dhnaggn4g/image/upload/c_thumb,w_200,g_face/v1750078911/static/codeqr_thumbnail_abgafw.png", "video": null, "utm_source": null, "utm_medium": null, "utm_campaign": null, "utm_term": null, "utm_content": null, "rewrite": false, "doIndex": false, "flexible": false, "filled": false, "ios": null, "android": null, "geo": null, "userId": "cloukebiw0000ig8g2q4w6vbp", "projectId": "clwazhjsm00002nx4heuc6vge", "preRedirection": false, "pageId": null, "pageUrl": null, "isFormMandatory": false, "publicStats": false, "clicks": 21, "lastClicked": "2025-08-30T12:16:06.000Z", "leads": 0, "sales": 0, "saleAmount": 0, "createdAt": "2024-05-18T14:31:08.557Z", "updatedAt": "2025-09-06T12:21:07.873Z", "tagId": null, "comments": "Link para landing page ", "notificationToken": null, "tags": [], "shortLink": "https://codeqr.link/site", "webhookIds": [], "qrCode": "https://api.codeqr.io/qr?url=https://codeqr.link/site?qr=1" }
Important response fields
The API response contains several useful fields you can use in your application:
shortLink - Short link URL
- Use this field to share the link
- Example: https://codeqr.link/claim
id - Unique identifier
- Use for future operations (update, delete)
- Example: clwc7hxcd0001ab6tqskb0h7v
key - Link slug
- Custom name (if provided)
- Example: claim
url - Destination URL
- Original URL where the link redirects
- Example: https://codeqr.io
domain - Short link domain
- Domain used for the short link
- Example: codeqr.link
qrCode - QR code image URL
- Automatically generated QR code
- Example: https://api.codeqr.io/qr?url=https://codeqr.link/site?qr=1
title - Link title
- Custom title (if provided)
- Example: "CodeQR - Smart QR Codes, Short Links & Custom Pages"
description - Link description
- Custom description (if provided)
- Example: "Create, manage, and track intelligent QR Codes"
image - Link image
- Custom image URL (if provided)
- Example: https://res.cloudinary.com/.../codeqr_thumbnail.png
clicks - Click counter
- Updated in real time
- Example: 21
leads - Leads counter
- Number of leads generated
- Example: 0
sales - Sales counter
- Number of sales made
- Example: 0
saleAmount - Total sales amount
- Sum of sales values
- Example: 0
lastClicked - Last click
- Timestamp of last registered click
- Example: 2025-08-30T12:16:06.000Z
createdAt - Creation date
- ISO 8601 timestamp
- Example: 2024-05-18T14:31:08.557Z
updatedAt - Last update date
- Timestamp of last modification
- Example: 2025-09-06T12:21:07.873Z
externalId - External ID
- Your system's identifier (if provided)
- Example: PROD-001
userId - User ID
- Identifier of the user who created the link
- Example: cloukebiw0000ig8g2q4w6vbp
projectId - Project ID
- Project identifier (if applicable)
- Example: clwazhjsm00002nx4heuc6vge
trackConversion - Conversion tracking
- Whether the link is set up to track conversions
- Example: true
proxy - Custom preview
- Whether the link uses custom preview
- Example: true
rewrite - Link cloaking
- Whether the link uses URL masking
- Example: false
doIndex - SEO indexing
- Whether the link can be indexed by search engines
- Example: false
archived - Archived link
- Whether the link is archived
- Example: false
expiresAt - Expiration date
- Timestamp for when the link expires (if set)
- Example: null
password - Password protection
- Whether the link is password protected
- Example: null
comments - Comments
- Internal comments about the link
- Example: "Link to landing page"
tags - Associated tags
- Array of link tags
- Example: []
💡 Tip: The fields shortLink, clicks, leads, sales, and lastClicked are especially useful for monitoring the real-time performance of your links.
JavaScript Example
const response = await fetch("https://api.codeqr.io/links", { method: "POST", headers: { Authorization: "Bearer sua_chave_api", "Content-Type": "application/json", }, body: JSON.stringify({ url: "https://codeqr.io", }), }); const link = await response.json(); console.log("Link criado:", link.shortLink); console.log("QR Code:", link.qrCode);
Using the Short Link
Now that you've created the short link, you can use it anywhere:
Practical example:
Marketing Campaign
Access our special promotion: https://codeqr.link/site
Click the link for quick access!
💡 Tip: Use the shortLink field from the API response to share the link in campaigns, on social networks, in emails, or any platform.
Customizing Short Links
Appearance and identification
You can completely customize your short link:
Custom Link Preview
Customize the look of your links when shared on social networks:
curl --request POST \ --url https://api.codeqr.io/links \ --header 'Authorization: Bearer codeqr_your_api_key' \ --header 'Content-Type: application/json' \ --data '{ "url": "https://example.com", "proxy": true, "title": "Special Promotion - 50% OFF", "description": "Take advantage of our special promotion with 50% off on all products. Offer valid for a limited time!", "image": "https://example.com/promo-banner.jpg" }'
Custom Link Preview parameters:
proxy (boolean) - If the short link uses the Custom Link Preview feature
- Default: false
- Required: Yes
- Example: true
title (string | null) - The title of the short link
- Required: Yes
- Example: "Special Promotion - 50% OFF"
description (string | null) - The description of the short link
- Required: Yes
- Example: "Take advantage of our special promotion with 50% off"
image (string | null) - The short link image
- Required: Yes
- Example: "https://exemplo.com/promo-banner.jpg"
💡 Tip: When proxy is true, the short link will display a custom preview page before redirecting to the final URL, giving full control over how the link appears on social networks.
Organization with tags
curl --request POST \ --url https://api.codeqr.io/links \ --header 'Authorization: Bearer codeqr_your_api_key' \ --header 'Content-Type: application/json' \ --data '{ "url": "https://codeqr.io", "tagIds": ["tag1", "tag2"], "tagNames": "marketing-campaign" }'
Advanced Settings
Access control
Protect your links with password and expiration date:
curl --request POST \ --url https://api.codeqr.io/links \ --header 'Authorization: Bearer codeqr_your_api_key' \ --header 'Content-Type: application/json' \ --data '{ "url": "https://codeqr.io/", "password": "123456", "expiresAt": "2026-12-31T23:59:59Z", "expiredUrl": "https://examplo.com/expirado" }'
Click the link below and use password 123456 to access:
Device-based redirection
Redirect users to different URLs based on device:
curl --request POST \ --url https://api.codeqr.io/links \ --header 'Authorization: Bearer codeqr_your_api_key' \ --header 'Content-Type: application/json' \ --data '{ "url": "https://examplo.com", "ios": "https://apps.apple.com/app/examplo", "android": "https://play.google.com/store/apps/details?id=com.examplo" }'
Location-based redirection
Personalize the experience based on user's location:
curl --request POST \ --url https://api.codeqr.io/links \ --header 'Authorization: Bearer codeqr_your_api_key' \ --header 'Content-Type: application/json' \ --data '{ "url": "https://examplo.com", "geo": { "BR": "https://examplo.com/brasil", "US": "https://examplo.com/usa", "GB": "https://examplo.com/uk" } }'
UTM parameters for analytics
Track your link performance:
curl --request POST \ --url https://api.codeqr.io/links \ --header 'Authorization: Bearer codeqr_your_api_key' \ --header 'Content-Type: application/json' \ --data '{ "url": "https://examplo.com", "utm_source": "marketing", "utm_medium": "email", "utm_campaign": "promotion_2025", "utm_term": "product", "utm_content": "banner" }'
Conversion Tracking
Monitor conversions to measure your marketing campaign effectiveness:
curl --request POST \ --url https://api.codeqr.io/links \ --header 'Authorization: Bearer codeqr_your_api_key' \ --header 'Content-Type: application/json' \ --data '{ "url": "https://examplo.com", "trackConversion": true, "utm_source": "facebook", "utm_medium": "social", "utm_campaign": "black_friday" }'
Conversion Tracking parameters:
trackConversion (boolean) - Whether to track conversions for the short link
- Default: false
- Example: true
💡 Tip: With conversion tracking enabled, you can monitor leads, sales, and conversion values directly from the CodeQR dashboard.
Link Cloaking
Mask your destination URL so users only see the short link in the address bar:
curl --request POST \ --url https://api.codeqr.io/links \ --header 'Authorization: Bearer codeqr_your_api_key' \ --header 'Content-Type: application/json' \ --data '{ "url": "https://example.com/very-long-and-complex-page", "rewrite": true, "key": "clean-link" }'
Link Cloaking parameters:
rewrite (boolean) - Whether the short link uses link cloaking
- Default: false
- Required: Yes
- Example: true
💡 Tip: With rewrite: true, the destination URL is completely hidden. Users will always see only the short link in the address bar, even after redirection.
Search Engine Indexing
Allow search engines to index your short link:
curl --request POST \ --url https://api.codeqr.io/links \ --header 'Authorization: Bearer codeqr_your_api_key' \ --header 'Content-Type: application/json' \ --data '{ "url": "https://example.com", "doIndex": true, "title": "Important Page", "description": "Content that should be indexed by search engines" }'
Search Engine Indexing parameters:
doIndex (boolean) - Allow search engines to index your short link
- Default: false
- Example: true
💡 Tip: By default, short links are not indexed by search engines. Use doIndex: true only if you want your short link to appear in search results. Learn more: https://codeqr.link/noindex
Batch Operations
Creating multiple links
Create up to 100 links at once:
curl --request POST \ --url https://api.codeqr.io/links/bulk \ --header 'Authorization: Bearer codeqr_your_api_key' \ --header 'Content-Type: application/json' \ --data '[ { "url": "https://product1.com", "key": "product-1" }, { "url": "https://product2.com", "key": "product-2" }, { "url": "https://product3.com", "key": "product-3" } ]'
⚠️ Batch operation limitations:
- Does not support custom previews
- Does not trigger webhook events
- Maximum of 100 links per request
Updating multiple links
Update up to 100 links with the same data:
curl --request PATCH \ --url https://api.codeqr.io/links/bulk \ --header 'Authorization: Bearer codeqr_your_api_key' \ --header 'Content-Type: application/json' \ --data '{ "link_ids": ["link1", "link2", "link3"], "data": { "utm_source": "facebook", "utm_medium": "cpc", "tagIds": ["campaign-2025"] } }'
Deleting multiple links
curl --request DELETE \ --url https://api.codeqr.io/links/bulk?linkIds=link1,link2,link3 \ --header 'Authorization: Bearer codeqr_your_api_key'
Organization of Links
External ID
Use externalId to associate links with your system:
curl --request POST \ --url https://api.codeqr.io/links \ --header 'Authorization: Bearer codeqr_your_api_key' \ --header 'Content-Type: application/json' \ --data '{ "url": "https://example.com", "externalId": "12345" }'
Retrieve link by externalId:
curl --request GET \ --url "https://api.codeqr.io/links/info?external_id=12345" \ --header 'Authorization: Bearer codeqr_your_api_key'
Tenant ID
Group links by tenant (user/team):
curl --request POST \ --url https://api.codeqr.io/links \ --header 'Authorization: Bearer codeqr_your_api_key' \ --header 'Content-Type: application/json' \ --data '{ "url": "https://example.com", "tenantId": "usuario123" }'
Retrieve links by tenantId:
curl --request GET \ --url "https://api.codeqr.io/links?tenantId=usuario123" \ --header 'Authorization: Bearer codeqr_your_api_key'
Tags
Organize links with tags:
curl --request POST \ --url https://api.codeqr.io/links \ --header 'Authorization: Bearer codeqr_your_api_key' \ --header 'Content-Type: application/json' \ --data '{ "url": "https://example.com", "tagIds": ["clux0rgak00011..."] }'
Retrieve links by tags:
curl --request GET \ --url "https://api.codeqr.io/links?tagNames=marketing" \ --header 'Authorization: Bearer codeqr_your_api_key'
Practical Examples
1. Link for E-commerce
async function criarLinkProduto(produto) { const response = await fetch("https://api.codeqr.io/links", { method: "POST", headers: { Authorization: "Bearer codeqr_your_api_key", "Content-Type": "application/json", }, body: JSON.stringify({ url: `https://loja.com/produto/${produto.id}`, key: `produto-${produto.id}`, title: produto.nome, description: `Link para ${produto.nome}`, externalId: produto.sku, utm_source: "ecommerce", utm_medium: "link_curto", utm_campaign: "produto", tagIds: ["produtos", "ecommerce"], }), }); return await response.json(); } // Uso const produto = { id: 123, nome: "Smartphone XYZ", sku: "SP-123", }; const link = await criarLinkProduto(produto); console.log("Link criado:", link.shortLink);
2. Link for Marketing Campaign
import requests import json def criar_link_campanha(url_destino, nome_campanha, canal): data = { "url": url_destino, "key": f"campanha-{nome_campanha.lower().replace(' ', '-')}", "title": f"Campanha - {nome_campanha}", "description": f"Link para campanha {nome_campanha} via {canal}", "utm_source": canal, "utm_medium": "link_curto", "utm_campaign": nome_campanha.lower().replace(' ', '-'), "tagNames": [nome_campanha, canal] } response = requests.post( 'https://api.codeqr.io/links', headers={ 'Authorization': 'Bearer codeqr_your_api_key', 'Content-Type': 'application/json' }, data=json.dumps(data) ) if response.status_code == 200: return response.json() else: raise Exception(f"Erro: {response.status_code} - {response.text}") # Uso link_campanha = criar_link_campanha( "https://promocao.com/desconto-50", "Black Friday 2025", "email" ) print(f"Link da campanha criado: {link_campanha['shortLink']}")
3. Link for Affiliates
<?php function criarLinkAfiliado($url_destino, $afiliado_id, $produto_id) { $data = [ 'url' => $url_destino, 'key' => "afiliado-{$afiliado_id}-{$produto_id}", 'title' => "Link de Afiliado - Produto {$produto_id}", 'description' => "Link de afiliado para produto {$produto_id}", 'externalId' => "afiliado_{$afiliado_id}_{$produto_id}", 'utm_source' => 'afiliado', 'utm_medium' => 'link_curto', 'utm_campaign' => "produto_{$produto_id}", 'utm_content' => "afiliado_{$afiliado_id}", 'tagIds' => ['afiliados', "produto-{$produto_id}"] ]; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://api.codeqr.io/links'); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data)); curl_setopt($ch, CURLOPT_HTTPHEADER, [ 'Authorization: Bearer codeqr_your_api_key', 'Content-Type: application/json' ]); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); if ($httpCode === 200) { return json_decode($response, true); } else { throw new Exception("Erro ao criar link: $httpCode"); } } // Uso $link_afiliado = criarLinkAfiliado( "https://loja.com/produto/123", "AF001", "123" ); echo "Link de afiliado criado: " . $link_afiliado['shortLink']; ?>
4. Link with Custom Preview for Social Media
async function criarLinkComPreview(url, titulo, descricao, imagem) { const response = await fetch("https://api.codeqr.io/links", { method: "POST", headers: { Authorization: "Bearer codeqr_your_api_key", "Content-Type": "application/json", }, body: JSON.stringify({ url: url, proxy: true, title: titulo, description: descricao, image: imagem, trackConversion: true, utm_source: "social_media", utm_medium: "custom_preview", utm_campaign: "viral_campaign", }), }); return await response.json(); } // Uso const linkPreview = await criarLinkComPreview( "https://exemplo.com/promocao", "🔥 Promoção Relâmpago - 70% OFF!", "Últimas 24h! Aproveite nossa maior promoção do ano com 70% de desconto em todos os produtos. Frete grátis!", "https://exemplo.com/banner-promocao.jpg" ); console.log("Link com preview criado:", linkPreview.shortLink);
5. Link with Cloaking for Complex URLs
import requests import json def criar_link_cloaking(url_original, slug_personalizado): """ Cria um link curto com cloaking para mascarar URLs complexas """ data = { "url": url_original, "key": slug_personalizado, "rewrite": True, "title": "Acesso Direto", "description": "Link direto para o conteúdo", "trackConversion": True, "utm_source": "cloaking", "utm_medium": "clean_url" } response = requests.post( 'https://api.codeqr.io/links', headers={ 'Authorization': 'Bearer codeqr_your_api_key', 'Content-Type': 'application/json' }, data=json.dumps(data) ) if response.status_code == 200: return response.json() else: raise Exception(f"Erro: {response.status_code} - {response.text}") # Uso url_complexa = "https://exemplo.com/categoria/produto/123?utm_source=email&utm_medium=newsletter&utm_campaign=promocao&ref=cliente&token=abc123" link_limpo = criar_link_cloaking(url_complexa, "produto-especial") print(f"URL original: {url_complexa}") print(f"Link limpo: {link_limpo['shortLink']}")
6. Indexable Link for SEO
<?php function criarLinkIndexavel($url, $titulo, $descricao, $palavras_chave) { $data = [ 'url' => $url, 'key' => strtolower(str_replace(' ', '-', $palavras_chave)), 'title' => $titulo, 'description' => $descricao, 'doIndex' => true, 'trackConversion' => true, 'utm_source' => 'seo', 'utm_medium' => 'organic', 'tagNames' => ['seo', 'indexavel'] ]; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://api.codeqr.io/links'); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data)); curl_setopt($ch, CURLOPT_HTTPHEADER, [ 'Authorization: Bearer sua_chave_api', 'Content-Type: application/json' ]); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); if ($httpCode === 200) { return json_decode($response, true); } else { throw new Exception("Erro ao criar link indexável: $httpCode"); } } // Uso $link_seo = criarLinkIndexavel( "https://exemplo.com/guia-completo-marketing-digital", "Guia Completo de Marketing Digital 2025", "Aprenda as melhores estratégias de marketing digital para 2025. Dicas práticas, ferramentas e cases de sucesso.", "marketing digital 2025" ); echo "Link indexável criado: " . $link_seo['shortLink']; ?>
Managing Links
Updating a link
Use the link ID to update it:
curl --request PATCH \ --url https://api.codeqr.io/links/link_eBKA4MT44XnI17hYLchkjUOd \ --header 'Authorization: Bearer codeqr_your_api_key' \ --header 'Content-Type: application/json' \ --data '{ "url": "https://novo-destino.com", "title": "Novo título" }'
Upsert (Create or Update)
Upsert creates a new link if it doesn't exist, or updates it if it does:
curl --request POST \ --url https://api.codeqr.io/links/update \ --header 'Authorization: Bearer codeqr_your_api_key' \ --header 'Content-Type: application/json' \ --data '{ "url": "https://exemplo.com", "key": "link-estavel" }'
Deleting a link
curl --request DELETE \ --url https://api.codeqr.io/links/link_eBKA4MT44XnI17hYLchkjUOd \ --header 'Authorization: Bearer codeqr_your_api_key'
Error Handling
Common error codes
bad_request (400) - Badly formed request
- Solution: Check data format
unauthorized (401) - Invalid API key
- Solution: Check API key
forbidden (403) - No permission
- Solution: Check key permissions
not_found (404) - Resource not found
- Solution: Check link ID/URL
conflict (409) - Conflict (e.g., duplicate key)
- Solution: Use a unique key
rate_limit_exceeded (429) - Rate limit exceeded
- Solution: Wait and try again
internal_server_error (500) - Internal server error
- Solution: Try again later
Best Practices
1. Security
- Never expose API keys in the frontend
- Use environment variables to store credentials
- Implement regular key rotation
- Use keys with the minimum necessary permissions
2. Performance
- Use batch operations to create multiple links
- Monitor rate limits and implement retry logic
- Consider webhooks for real-time updates
3. Monitoring
- Implement logging for all operations
- Use UTM parameters for tracking
- Set up alerts for critical errors
- Monitor unusual API usage
4. Organization
- Use tags to categorize links
- Implement externalId for system integration
- Use tenantId for multi-tenancy
- Maintain consistent naming conventions
Next Steps
Now that you know how to create short links via API, explore these advanced features:
1. Link Management
2. Batch Operations
3. Advanced Features
4. SDK Integration
Additional Resources
Official Documentation
Related Articles
- How to use link cloaking on CodeQR
- How to create password-protected links
- How to use tags on CodeQR
- Integration with ActiveCampaign
Support
Conclusion
The CodeQR API offers a complete and flexible solution for programmatically creating short links. With this guide, you have learned:
- ✅ How to set up authentication and make your first request
- ✅ How to customize link appearance and behavior
- ✅ Conversion tracking to measure campaign effectiveness
- ✅ Custom link preview for social media
- ✅ Link cloaking for masking complex URLs
- ✅ Search engine indexing for SEO optimization
- ✅ Different ways to organize and categorize links
- ✅ Advanced settings for specific cases
- ✅ Practical examples in JavaScript, Python, and PHP
- ✅ Error handling and best practices
Now you are ready to integrate short link creation into your applications and take full advantage of the CodeQR platform!
Was this article helpful? Share it with your team and explore other resources in the CodeQR documentation.