Create Short URL

Create a new short URL from a long URL. You can optionally provide a custom alias, name, expiration date, domain settings, and other advanced features.

Custom Alias Uniqueness: Custom aliases are unique per domain context, not globally. This means:

jmpy.me/my-link and acme.jmpy.me/my-link can coexist as separate URLs
On the same domain, each alias must be unique

Before using a custom alias, you can check its availability using the Check Alias Availability endpoint.

Request Body

Required Parameters

url

string

required

The original URL to shorten. Must be a valid HTTP or HTTPS URL.Example: https://example.com/very-long-url-with-parameters?foo=bar

Optional Parameters

custom_alias

string

Optional custom alias for the short URL.Requirements:

Must be 3-50 characters
Alphanumeric with underscores (_) or dashes (-) only
Must be unique within the URL type/domain context

Example: my-campaign-link

Use the Check Alias Availability endpoint to verify an alias is available before creating a URL.

name

string

Optional friendly name for the short URL (for your reference).Constraints: 1-255 charactersExample: Q4 Marketing Campaign Link

expires_at

string

Optional expiration date in ISO 8601 format. The short URL will return a 410 Gone error after this date.Example: 2025-12-31T23:59:59.000Z

tracking_enabled

boolean

default:true

Whether to enable click tracking and analytics for this URL. When enabled, each click is logged with:

Geographic location (country, region, city)
Device information (browser, OS, device type)
Referrer data
UTM parameters

See Analytics API for retrieving click data.

URL Type and Domain Settings

Domain Prerequisite: Before using subdomain or branded URL types, you must first register and verify the domain via the Domains API or through the Dashboard.

url_type

string

default:"standard"

Type of URL to create. Determines the base domain for the short URL.

Value	Description	Example URL
`standard`	Uses the default `jmpy.me` domain	`https://jmpy.me/abc123`
`subdomain`	Uses your registered subdomain on jmpy.me	`https://acme.jmpy.me/abc123`
`branded`	Uses your own verified branded domain	`https://go.yourbrand.com/abc123`

subdomain

string

Subdomain to use when url_type is subdomain. Must be pre-registered and verified via the Create Subdomain endpoint.Requirements:

3-63 characters
Alphanumeric and dashes only
Cannot start or end with a dash
Must be owned by the authenticated user

Example: acme (results in https://acme.jmpy.me/alias)See List Subdomains to view your registered subdomains.

branded_domain

string

Branded domain to use when url_type is branded. Must be verified via DNS.Example: go.yourbrand.com (results in https://go.yourbrand.com/alias)

See Create Branded Domain to register a new branded domain and Verify Domain for DNS setup instructions.

Campaign and Organization

campaign_id

string

UUID of a campaign to associate this URL with. Must be a campaign owned by the authenticated user.

Campaigns help organize links and provide aggregate analytics. See Create Campaign to set up a new campaign or List Campaigns to find existing campaign IDs.

Password Protection

password

string

Optional password to protect the short URL. When set, users must enter this password before being redirected.Note: Passwords are hashed and stored securely. Cannot be retrieved, only reset.

Response

string

Unique identifier for the short URL (UUID).

short_code

string

The generated or custom short code.

short_url

string

The complete short URL ready to share.

original_url

string

The original (destination) URL.

name

string

The friendly name (if provided).

custom_alias

string

The custom alias (if provided).

tracking_enabled

boolean

Whether analytics tracking is enabled.

url_type

string

The URL type: standard, subdomain, or branded.

subdomain

string

The subdomain (if url_type is subdomain).

branded_domain

string

The branded domain (if url_type is branded).

expires_at

string

Expiration date (if set).

created_at

string

ISO 8601 timestamp of creation.

channel

string

Creation channel: web, api, mcp, extension, or bulk_import.

Request Examples

Standard
Subdomain
Branded Domain
With Campaign

curl -X POST "https://jmpy.me/api/v1/short-urls" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/very-long-url-with-parameters?foo=bar",
    "custom_alias": "my-link",
    "name": "Marketing Campaign Link",
    "tracking_enabled": true
  }'

# Requires a registered subdomain - see /api-reference/domains/create-subdomain
curl -X POST "https://jmpy.me/api/v1/short-urls" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/product-page",
    "custom_alias": "new-product",
    "url_type": "subdomain",
    "subdomain": "acme",
    "name": "New Product Launch",
    "tracking_enabled": true
  }'

# Requires a verified branded domain - see /api-reference/domains/create-branded
curl -X POST "https://jmpy.me/api/v1/short-urls" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/signup",
    "custom_alias": "join",
    "url_type": "branded",
    "branded_domain": "go.mycompany.com",
    "name": "Signup Link",
    "expires_at": "2025-12-31T23:59:59.000Z"
  }'

# Associate with a campaign - see /api-reference/campaigns/create
curl -X POST "https://jmpy.me/api/v1/short-urls" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/summer-sale",
    "custom_alias": "summer24",
    "name": "Summer Sale 2024",
    "campaign_id": "550e8400-e29b-41d4-a716-446655440000",
    "tracking_enabled": true
  }'

Standard
Subdomain
Branded Domain

const fetch = require('node-fetch');

const response = await fetch('https://jmpy.me/api/v1/short-urls', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://example.com/very-long-url-with-parameters?foo=bar',
    custom_alias: 'my-link',
    name: 'Marketing Campaign Link',
    tracking_enabled: true
  })
});
const data = await response.json();
console.log(data.data.short_url); // https://jmpy.me/my-link

const fetch = require('node-fetch');

// Requires a registered subdomain
// See: /api-reference/domains/create-subdomain
const response = await fetch('https://jmpy.me/api/v1/short-urls', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://example.com/product-page',
    custom_alias: 'new-product',
    url_type: 'subdomain',
    subdomain: 'acme',
    name: 'New Product Launch'
  })
});
const data = await response.json();
console.log(data.data.short_url); // https://acme.jmpy.me/new-product

const fetch = require('node-fetch');

// Requires a verified branded domain
// See: /api-reference/domains/create-branded
const response = await fetch('https://jmpy.me/api/v1/short-urls', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://example.com/signup',
    custom_alias: 'join',
    url_type: 'branded',
    branded_domain: 'go.mycompany.com',
    name: 'Signup Link'
  })
});
const data = await response.json();
console.log(data.data.short_url); // https://go.mycompany.com/join

Standard
Subdomain
Branded Domain

import axios from 'axios';

interface ShortUrlResponse {
  success: boolean;
  data: {
    id: string;
    short_code: string;
    short_url: string;
    original_url: string;
  };
}

const response = await axios.post<ShortUrlResponse>(
  'https://jmpy.me/api/v1/short-urls',
  {
    url: 'https://example.com/very-long-url-with-parameters?foo=bar',
    custom_alias: 'my-link',
    name: 'Marketing Campaign Link',
    tracking_enabled: true
  },
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
console.log(response.data.data.short_url);

import axios from 'axios';

// Requires a registered subdomain
// See: /api-reference/domains/create-subdomain
const response = await axios.post(
  'https://jmpy.me/api/v1/short-urls',
  {
    url: 'https://example.com/product-page',
    custom_alias: 'new-product',
    url_type: 'subdomain',
    subdomain: 'acme',
    name: 'New Product Launch'
  },
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
console.log(response.data.data.short_url); // https://acme.jmpy.me/new-product

import axios from 'axios';

// Requires a verified branded domain
// See: /api-reference/domains/create-branded
const response = await axios.post(
  'https://jmpy.me/api/v1/short-urls',
  {
    url: 'https://example.com/signup',
    custom_alias: 'join',
    url_type: 'branded',
    branded_domain: 'go.mycompany.com',
    name: 'Signup Link'
  },
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
console.log(response.data.data.short_url); // https://go.mycompany.com/join

Standard
Subdomain
Branded Domain

import requests

url = "https://jmpy.me/api/v1/short-urls"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
data = {
    "url": "https://example.com/very-long-url-with-parameters?foo=bar",
    "custom_alias": "my-link",
    "name": "Marketing Campaign Link",
    "tracking_enabled": True
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result["data"]["short_url"])  # https://jmpy.me/my-link

import requests

# Requires a registered subdomain
# See: /api-reference/domains/create-subdomain
url = "https://jmpy.me/api/v1/short-urls"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
data = {
    "url": "https://example.com/product-page",
    "custom_alias": "new-product",
    "url_type": "subdomain",
    "subdomain": "acme",
    "name": "New Product Launch"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result["data"]["short_url"])  # https://acme.jmpy.me/new-product

import requests

# Requires a verified branded domain
# See: /api-reference/domains/create-branded
url = "https://jmpy.me/api/v1/short-urls"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
data = {
    "url": "https://example.com/signup",
    "custom_alias": "join",
    "url_type": "branded",
    "branded_domain": "go.mycompany.com",
    "name": "Signup Link"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result["data"]["short_url"])  # https://go.mycompany.com/join

Standard
Subdomain
Branded Domain

<?php
$client = new GuzzleHttp\Client();
$response = $client->request('POST', 'https://jmpy.me/api/v1/short-urls', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_KEY',
        'Content-Type' => 'application/json'
    ],
    'json' => [
        'url' => 'https://example.com/very-long-url-with-parameters?foo=bar',
        'custom_alias' => 'my-link',
        'name' => 'Marketing Campaign Link',
        'tracking_enabled' => true
    ]
]);
$data = json_decode($response->getBody(), true);
echo $data['data']['short_url']; // https://jmpy.me/my-link
?>

<?php
// Requires a registered subdomain
// See: /api-reference/domains/create-subdomain
$client = new GuzzleHttp\Client();
$response = $client->request('POST', 'https://jmpy.me/api/v1/short-urls', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_KEY',
        'Content-Type' => 'application/json'
    ],
    'json' => [
        'url' => 'https://example.com/product-page',
        'custom_alias' => 'new-product',
        'url_type' => 'subdomain',
        'subdomain' => 'acme',
        'name' => 'New Product Launch'
    ]
]);
?>

<?php
// Requires a verified branded domain
// See: /api-reference/domains/create-branded
$client = new GuzzleHttp\Client();
$response = $client->request('POST', 'https://jmpy.me/api/v1/short-urls', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_KEY',
        'Content-Type' => 'application/json'
    ],
    'json' => [
        'url' => 'https://example.com/signup',
        'custom_alias' => 'join',
        'url_type' => 'branded',
        'branded_domain' => 'go.mycompany.com',
        'name' => 'Signup Link'
    ]
]);
?>

Standard
Subdomain
Branded Domain

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    url := "https://jmpy.me/api/v1/short-urls"
    data := map[string]interface{}{
        "url":              "https://example.com/very-long-url-with-parameters?foo=bar",
        "custom_alias":     "my-link",
        "name":             "Marketing Campaign Link",
        "tracking_enabled": true,
    }
    jsonData, _ := json.Marshal(data)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header.Add("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Add("Content-Type", "application/json")

    http.DefaultClient.Do(req)
}

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

// Requires a registered subdomain
// See: /api-reference/domains/create-subdomain
func main() {
    url := "https://jmpy.me/api/v1/short-urls"
    data := map[string]interface{}{
        "url":          "https://example.com/product-page",
        "custom_alias": "new-product",
        "url_type":     "subdomain",
        "subdomain":    "acme",
        "name":         "New Product Launch",
    }
    jsonData, _ := json.Marshal(data)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header.Add("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Add("Content-Type", "application/json")

    http.DefaultClient.Do(req)
}

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

// Requires a verified branded domain
// See: /api-reference/domains/create-branded
func main() {
    url := "https://jmpy.me/api/v1/short-urls"
    data := map[string]interface{}{
        "url":            "https://example.com/signup",
        "custom_alias":   "join",
        "url_type":       "branded",
        "branded_domain": "go.mycompany.com",
        "name":           "Signup Link",
    }
    jsonData, _ := json.Marshal(data)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header.Add("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Add("Content-Type", "application/json")

    http.DefaultClient.Do(req)
}

Standard
Subdomain
Branded Domain

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.URI;
import java.net.http.HttpResponse;

String json = """
{
    "url": "https://example.com/very-long-url-with-parameters?foo=bar",
    "custom_alias": "my-link",
    "name": "Marketing Campaign Link",
    "tracking_enabled": true
}""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://jmpy.me/api/v1/short-urls"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();
client.send(request, HttpResponse.BodyHandlers.ofString());

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.URI;
import java.net.http.HttpResponse;

// Requires a registered subdomain
// See: /api-reference/domains/create-subdomain
String json = """
{
    "url": "https://example.com/product-page",
    "custom_alias": "new-product",
    "url_type": "subdomain",
    "subdomain": "acme",
    "name": "New Product Launch"
}""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://jmpy.me/api/v1/short-urls"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();
client.send(request, HttpResponse.BodyHandlers.ofString());

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.URI;
import java.net.http.HttpResponse;

// Requires a verified branded domain
// See: /api-reference/domains/create-branded
String json = """
{
    "url": "https://example.com/signup",
    "custom_alias": "join",
    "url_type": "branded",
    "branded_domain": "go.mycompany.com",
    "name": "Signup Link"
}""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://jmpy.me/api/v1/short-urls"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();
client.send(request, HttpResponse.BodyHandlers.ofString());

Response Examples

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "short_code": "my-link",
    "short_url": "https://jmpy.me/my-link",
    "original_url": "https://example.com/very-long-url-with-parameters?foo=bar",
    "name": "Marketing Campaign Link",
    "custom_alias": "my-link",
    "tracking_enabled": true,
    "url_type": "standard",
    "subdomain": null,
    "branded_domain": null,
    "expires_at": null,
    "created_at": "2024-01-15T10:30:00.000Z",
    "channel": "api"
  }
}

{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440000",
    "short_code": "new-product",
    "short_url": "https://acme.jmpy.me/new-product",
    "original_url": "https://example.com/product-page",
    "name": "New Product Launch",
    "custom_alias": "new-product",
    "tracking_enabled": true,
    "url_type": "subdomain",
    "subdomain": "acme",
    "branded_domain": null,
    "expires_at": null,
    "created_at": "2024-01-15T10:30:00.000Z",
    "channel": "api"
  }
}

{
  "success": true,
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440000",
    "short_code": "join",
    "short_url": "https://go.mycompany.com/join",
    "original_url": "https://example.com/signup",
    "name": "Signup Link",
    "custom_alias": "join",
    "tracking_enabled": true,
    "url_type": "branded",
    "subdomain": null,
    "branded_domain": "go.mycompany.com",
    "expires_at": "2025-12-31T23:59:59.000Z",
    "created_at": "2024-01-15T10:30:00.000Z",
    "channel": "api"
  }
}

{
  "success": false,
  "error": {
    "code": "ALIAS_EXISTS",
    "message": "Custom alias 'my-link' already exists on jmpy.me",
    "details": {
      "field": "custom_alias",
      "context": {
        "url_type": "standard",
        "subdomain": null,
        "branded_domain": null
      }
    }
  }
}

{
  "success": false,
  "error": {
    "code": "ACCESS_DENIED",
    "message": "You do not own this subdomain or it is not verified"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "errors": [
        {
          "field": "url",
          "message": "URL is required and must be a valid HTTP/HTTPS URL"
        },
        {
          "field": "custom_alias",
          "message": "Custom alias must be 3-50 characters, alphanumeric with underscores or dashes only"
        }
      ]
    }
  }
}

Use Cases

Marketing Campaign Tracking

Create branded links for campaigns with full analytics tracking:

// First, create a campaign
const campaign = await fetch('https://jmpy.me/api/v1/campaigns', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Summer Sale 2024' })
}).then(r => r.json());

// Then create tracked links for the campaign
const link = await fetch('https://jmpy.me/api/v1/short-urls', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    url: 'https://myshop.com/summer-sale',
    custom_alias: 'summer24',
    campaign_id: campaign.data.id,
    tracking_enabled: true
  })
}).then(r => r.json());

// View analytics: /api-reference/analytics/url-overview

Temporary Promo Links

Create links that automatically expire after a promotion ends:

curl -X POST "https://jmpy.me/api/v1/short-urls" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://myshop.com/flash-sale",
    "custom_alias": "flash-sale",
    "name": "24hr Flash Sale",
    "expires_at": "2024-12-26T00:00:00Z"
  }'

After expiration, the link returns a 410 Gone response.

Brand-Consistent Links

Use your own domain for maximum brand trust:

// First, register and verify your branded domain
// See: /api-reference/domains/create-branded

// Then create links on your domain
const response = await fetch('https://jmpy.me/api/v1/short-urls', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    url: 'https://mycompany.com/careers',
    custom_alias: 'jobs',
    url_type: 'branded',
    branded_domain: 'go.mycompany.com'
  })
});
// Result: https://go.mycompany.com/jobs

Password-Protected Links

Protect sensitive content with a password:

curl -X POST "https://jmpy.me/api/v1/short-urls" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://drive.google.com/file/confidential-report",
    "custom_alias": "q4-report",
    "name": "Q4 Financial Report",
    "password": "SecurePass123"
  }'

Visitors must enter the password before being redirected.

Check Alias Availability

Check if a custom alias is available before creating a URL

List Branded Domains

View your registered branded domains

List Subdomains

View your registered subdomains

Create Campaign

Organize links into marketing campaigns

URL Analytics

View click analytics for your URLs

Create QR Code

Generate a QR code for your short URL

API Reference

Short URLs

Custom Aliases

QR Codes

Domains

Campaigns

Short URL Analytics

QR Code Analytics

Short URL A/B Testing

QR Code A/B Testing

Request Body

Required Parameters

Optional Parameters

URL Type and Domain Settings

Campaign and Organization

Password Protection

Response

Request Examples

Response Examples

Use Cases

Check Alias Availability

List Branded Domains

List Subdomains

Create Campaign

URL Analytics

Create QR Code

API Reference

Short URLs

Custom Aliases

QR Codes

Domains

Campaigns

Short URL Analytics

QR Code Analytics

Short URL A/B Testing

QR Code A/B Testing

​Request Body

​Required Parameters

​Optional Parameters

​URL Type and Domain Settings

​Campaign and Organization

​Password Protection

​Response

​Request Examples

​Response Examples

​Use Cases

​Related Endpoints

Check Alias Availability

List Branded Domains

List Subdomains

Create Campaign

URL Analytics

Create QR Code

Request Body

Required Parameters

Optional Parameters

URL Type and Domain Settings

Campaign and Organization

Password Protection

Response

Request Examples

Response Examples

Use Cases

Related Endpoints