API

Bulk Generate Short Links via the REST API

If you need to create dozens, hundreds, or thousands of short links at once — from an external content pipeline, a migration script, or a recurring sync job — URL Shortify's bulk API endpoint lets you do it in a single authenticated request.

This guide walks through how to authenticate, how to format your payload, and what to do when you're sending more than the default batch limit.

Endpoint

POST /wp-json/url-shortify/v1/links/bulk

Creates multiple short links in one request. Each link in the payload is validated and created independently — one bad row doesn't fail the whole batch, and you get a status for every input.

Authentication

The bulk endpoint accepts two authentication methods. Pick whichever fits your environment.

X-URL-SHORTIFY-CONSUMER-KEY: ck_live_xxxxxxxxxxxx
X-URL-SHORTIFY-CONSUMER-SECRET: cs_live_xxxxxxxxxxxx

Option B — HTTP Basic Auth

Authorization: Basic base64(consumer_key:consumer_secret)

Generating API Keys

  1. Go to URL Shortify → Settings → API tab.
  2. Click Generate API Key.
  3. Give the key a name (e.g. "Content sync bot") and choose the permissions (read, write, or both).
  4. Copy the Consumer Key and Consumer Secret — the secret is shown only once.

Store the credentials in your environment variables or a secrets manager. Never commit them to source control.

Note: The REST API is a URL Shortify PRO feature.

Request Body

Send a JSON object with a links array. Each item describes one short link.

{
  "links": [
    {
      "url": "https://example.com/products/blue-widget",
      "slug": "blue-widget",
      "title": "Blue Widget Product Page",
      "group_id": 7,
      "tags": [3, 12],
      "expiration_date": "2026-12-31T23:59:59Z"
    },
    {
      "url": "https://example.com/products/red-widget",
      "slug": "red-widget",
      "title": "Red Widget Product Page"
    },
    {
      "url": "https://example.com/products/green-widget"
    }
  ]
}

Field Reference

Field Type Required Notes
url string (URL) yes The destination URL. Must include the scheme (https://).
slug string no Custom short slug. URL Shortify auto-generates a unique slug if you leave it empty.
title string no Human-readable name for the link, shown in the admin.
group_id integer no Numeric ID of an existing group. Use GET /groups to look up IDs.
tags integer[] no Array of existing tag IDs.
expiration_date ISO-8601 string no Date/time after which the link stops redirecting.

Response

A successful bulk request returns HTTP 201 with a per-item status array:

{
  "success": true,
  "data": [
    {
      "original_url": "https://example.com/products/blue-widget",
      "short_url": "https://yoursite.com/blue-widget",
      "slug": "blue-widget",
      "status": "created"
    },
    {
      "original_url": "https://example.com/products/red-widget",
      "short_url": "https://yoursite.com/red-widget",
      "slug": "red-widget",
      "status": "created"
    },
    {
      "original_url": "https://example.com/products/green-widget",
      "short_url": "https://yoursite.com/abc123",
      "slug": "abc123",
      "status": "created"
    }
  ]
}

If an individual link fails validation, that single item carries a status of error and a message. The rest of the batch still gets created.

{
  "original_url": "not-a-valid-url",
  "status": "error",
  "message": "Invalid URL."
}

Batch Size Limits

By default, the bulk endpoint accepts up to 50 links per request. You can raise or lower this limit:

  1. Go to URL Shortify → Settings → API → Bulk API.
  2. Set Bulk Request Limit to the maximum you need.
  3. Save.

If you send more than the configured limit, the whole request returns HTTP 400 with a clear message — none of the links are created. Stay below the limit, or split your payload into multiple requests.

Tip for very large migrations: Send batches of 50 in a loop with a short delay between them. This gives your server breathing room and keeps individual requests under typical PHP/proxy timeout limits.

Working Examples

cURL

curl -X POST 'https://yoursite.com/wp-json/url-shortify/v1/links/bulk' \
  -H 'Content-Type: application/json' \
  -H "X-URL-SHORTIFY-CONSUMER-KEY: $US_KEY" \
  -H "X-URL-SHORTIFY-CONSUMER-SECRET: $US_SECRET" \
  -d '{
    "links": [
      { "url": "https://example.com/a", "slug": "promo-a" },
      { "url": "https://example.com/b", "slug": "promo-b" }
    ]
  }'

Python

import os
import requests

KEY    = os.environ['US_KEY']
SECRET = os.environ['US_SECRET']

resp = requests.post(
    'https://yoursite.com/wp-json/url-shortify/v1/links/bulk',
    headers={
        'X-URL-SHORTIFY-CONSUMER-KEY': KEY,
        'X-URL-SHORTIFY-CONSUMER-SECRET': SECRET,
    },
    json={
        'links': [
            {'url': 'https://example.com/a', 'slug': 'promo-a'},
            {'url': 'https://example.com/b', 'slug': 'promo-b'},
        ]
    },
    timeout=30,
)

resp.raise_for_status()
for item in resp.json()['data']:
    print(f"{item['status']:<8} {item.get('short_url', item.get('message'))}")

Node.js (axios)

const axios = require('axios');

const { US_KEY, US_SECRET } = process.env;

async function bulkCreate(links) {
    const response = await axios.post(
        'https://yoursite.com/wp-json/url-shortify/v1/links/bulk',
        { links },
        {
            headers: {
                'X-URL-SHORTIFY-CONSUMER-KEY': US_KEY,
                'X-URL-SHORTIFY-CONSUMER-SECRET': US_SECRET,
            },
        }
    );

    return response.data.data;
}

bulkCreate([
    { url: 'https://example.com/a', slug: 'promo-a' },
    { url: 'https://example.com/b', slug: 'promo-b' },
]).then(console.log);

Common Use Cases

  • CSV-style migrations. Read rows from a spreadsheet or external system and POST them in batches of 50.
  • Content publishing pipelines. When your CMS publishes new posts, automatically create a tracked short link for sharing.
  • E-commerce catalogs. Generate a short link for every product on import or sync.
  • Email campaign builders. Create a unique short link per recipient (or per cohort) for granular click tracking.
  • Affiliate networks. Programmatically generate creator-specific short links with pre-assigned tags and groups.

Best Practices

  1. Always set a slug when you can predict the destination. Auto-generated slugs are fine, but predictable ones make external systems easier to reason about.
  2. Validate URLs before sending. Saves round-trips and keeps the response array clean.
  3. Handle partial failures. Iterate the response and retry only the items with status: error — don't re-send the whole batch.
  4. Watch the rate. If you're bulk-creating thousands of links, throttle to one request per second to stay friendly to your server.
  5. Use distinct API keys per integration. If you have multiple systems creating links, give each its own key so you can revoke one without affecting the others.

Bulk Link Generate API available in URL Shortify PRO.

Was this page helpful?

Previous
API Reference
Next
Frequently Asked Questions