Create with Alias

Create a new short URL and assign it a readable, custom alias immediately. You can create aliases on the standard jmpy.me domain, or on your custom subdomains and branded domains.

Custom Alias Scoping: Aliases are unique per domain context:

Standard URLs (jmpy.me): Alias must be unique among all standard URLs
Subdomain URLs (subdomain.jmpy.me): Alias must be unique within that specific subdomain
Branded URLs (yourdomain.com): Alias must be unique within that specific branded domain

This means jmpy.me/promo and acme.jmpy.me/promo can coexist as separate short URLs.

Body Parameters

url

string

required

The destination URL.Requirements:

Valid URL with http:// or https:// protocol

custom_alias

string

required

The custom alias you want to use.Requirements:

3-50 characters
Alphanumeric, underscores (_), or dashes (-) only
Must be unique in the chosen domain context

url_type

string

default:"standard"

The type of URL to create.

Value	Description
`standard`	Create on `jmpy.me` (default)
`subdomain`	Create on a specific subdomain
`branded`	Create on a branded domain

subdomain

string

The subdomain to use (required when url_type=subdomain). Also used for branded subdomains (e.g., promo.brand.com).

branded_domain

string

The branded domain to use (required when url_type=branded).

name

string

A friendly name for the short URL helps with management.

campaign_id

string

UUID of a campaign to associate this URL with.

expires_at

string

ISO 8601 formatted date string for when the link should expire (e.g. 2024-12-31T23:59:59Z).

tracking_enabled

boolean

default:"true"

Whether to track clicks and analytics for this URL.

Response

string

Unique identifier (UUID) for the short URL.

short_code

string

The generated short code (same as alias for custom aliases).

short_url

string

The full, clickable short URL (e.g., https://jmpy.me/alias).

original_url

string

The destination URL.

custom_alias

string

The custom alias that was assigned.

url_type

string

The type of URL context.

Request Examples

Standard
Subdomain
Branded Domain
Branded 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/summer-sale",
    "custom_alias": "summer-sale",
    "name": "Summer Notification"
  }'

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": "promo",
    "url_type": "subdomain",
    "subdomain": "acme"
  }'

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-now",
    "url_type": "branded",
    "branded_domain": "mycompany.com"
  }'

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/sale",
    "custom_alias": "black-friday",
    "url_type": "branded",
    "branded_domain": "mycompany.com",
    "subdomain": "deals"
  }'

Standard
Subdomain
Branded Domain
Branded Subdomain

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/summer-sale',
    custom_alias: 'summer-sale',
    name: 'Summer Notification'
  })
});
const data = await response.json();

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/summer-sale',
    custom_alias: 'promo',
    url_type: 'subdomain',
    subdomain: 'acme'
  })
});
const data = await response.json();

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/signup',
    custom_alias: 'join-now',
    url_type: 'branded',
    branded_domain: 'mycompany.com'
  })
});
const data = await response.json();

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/sale',
    custom_alias: 'black-friday',
    url_type: 'branded',
    branded_domain: 'mycompany.com',
    subdomain: 'deals'
  })
});
const data = await response.json();

Standard
Subdomain
Branded Domain
Branded Subdomain

import axios from 'axios';

const response = await axios.post(
  'https://jmpy.me/api/v1/short-urls',
  {
    url: 'https://example.com/summer-sale',
    custom_alias: 'summer-sale',
    name: 'Summer Notification'
  },
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);

import axios from 'axios';

const response = await axios.post(
  'https://jmpy.me/api/v1/short-urls',
  {
    url: 'https://example.com/summer-sale',
    custom_alias: 'promo',
    url_type: 'subdomain',
    subdomain: 'acme'
  },
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);

import axios from 'axios';

const response = await axios.post(
  'https://jmpy.me/api/v1/short-urls',
  {
    url: 'https://example.com/signup',
    custom_alias: 'join-now',
    url_type: 'branded',
    branded_domain: 'mycompany.com'
  },
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);

import axios from 'axios';

const response = await axios.post(
  'https://jmpy.me/api/v1/short-urls',
  {
    url: 'https://example.com/sale',
    custom_alias: 'black-friday',
    url_type: 'branded',
    branded_domain: 'mycompany.com',
    subdomain: 'deals'
  },
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);

Standard
Subdomain
Branded Domain
Branded Subdomain

import requests

url = "https://jmpy.me/api/v1/short-urls"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
data = {
    "url": "https://example.com/summer-sale",
    "custom_alias": "summer-sale",
    "name": "Summer Notification"
}

response = requests.post(url, headers=headers, json=data)

import requests

url = "https://jmpy.me/api/v1/short-urls"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
data = {
    "url": "https://example.com/summer-sale",
    "custom_alias": "promo",
    "url_type": "subdomain",
    "subdomain": "acme"
}

response = requests.post(url, headers=headers, json=data)

import requests

url = "https://jmpy.me/api/v1/short-urls"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
data = {
    "url": "https://example.com/signup",
    "custom_alias": "join-now",
    "url_type": "branded",
    "branded_domain": "mycompany.com"
}

response = requests.post(url, headers=headers, json=data)

import requests

url = "https://jmpy.me/api/v1/short-urls"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
data = {
    "url": "https://example.com/sale",
    "custom_alias": "black-friday",
    "url_type": "branded",
    "branded_domain": "mycompany.com",
    "subdomain": "deals"
}

response = requests.post(url, headers=headers, json=data)

Standard
Subdomain
Branded Domain
Branded Subdomain

<?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/summer-sale',
        'custom_alias' => 'summer-sale',
        'name' => 'Summer Notification'
    ]
]);
?>

<?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/summer-sale',
        'custom_alias' => 'promo',
        'url_type' => 'subdomain',
        'subdomain' => 'acme'
    ]
]);
?>

<?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/signup',
        'custom_alias' => 'join-now',
        'url_type' => 'branded',
        'branded_domain' => 'mycompany.com'
    ]
]);
?>

<?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/sale',
        'custom_alias' => 'black-friday',
        'url_type' => 'branded',
        'branded_domain' => 'mycompany.com',
        'subdomain' => 'deals'
    ]
]);
?>

Standard
Subdomain
Branded Domain
Branded Subdomain

package main

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

func main() {
    url := "https://jmpy.me/api/v1/short-urls"
    data := map[string]string{
        "url":          "https://example.com/summer-sale",
        "custom_alias": "summer-sale",
        "name":         "Summer Notification",
    }
    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"
)

func main() {
    url := "https://jmpy.me/api/v1/short-urls"
    data := map[string]string{
        "url":          "https://example.com/summer-sale",
        "custom_alias": "promo",
        "url_type":     "subdomain",
        "subdomain":    "acme",
    }
    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"
)

func main() {
    url := "https://jmpy.me/api/v1/short-urls"
    data := map[string]string{
        "url":            "https://example.com/signup",
        "custom_alias":   "join-now",
        "url_type":       "branded",
        "branded_domain": "mycompany.com",
    }
    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"
)

func main() {
    url := "https://jmpy.me/api/v1/short-urls"
    data := map[string]string{
        "url":            "https://example.com/sale",
        "custom_alias":   "black-friday",
        "url_type":       "branded",
        "branded_domain": "mycompany.com",
        "subdomain":      "deals",
    }
    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 jsonInfo = """
{
    "url": "https://example.com/summer-sale",
    "custom_alias": "summer-sale",
    "name": "Summer Notification"
}""";

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(jsonInfo))
    .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;

String jsonInfo = """
{
    "url": "https://example.com/summer-sale",
    "custom_alias": "promo",
    "url_type": "subdomain",
    "subdomain": "acme"
}""";

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(jsonInfo))
    .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;

String jsonInfo = """
{
    "url": "https://example.com/signup",
    "custom_alias": "join-now",
    "url_type": "branded",
    "branded_domain": "mycompany.com"
}""";

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(jsonInfo))
    .build();
client.send(request, HttpResponse.BodyHandlers.ofString());

Response Examples

201 Created
409 Alias Exists
422 Validation Error

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "short_code": "summer-sale",
    "short_url": "https://jmpy.me/summer-sale",
    "original_url": "https://example.com/summer-sale",
    "custom_alias": "summer-sale",
    "url_type": "standard",
    "subdomain": null,
    "branded_domain": null,
    "click_count": 0,
    "created_at": "2024-01-01T12:00:00Z",
    "tracking_enabled": true
  }
}

{
  "success": false,
  "error": {
    "code": "ALIAS_EXISTS",
    "message": "Custom alias 'summer-sale' already exists on jmpy.me",
    "field": "custom_alias"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "errors": [
        {
          "field": "custom_alias",
          "message": "Custom alias must be 3-50 characters"
        }
      ]
    }
  }
}

Use Cases

Marketing Campaigns

Create recognizable, branded links for your marketing campaigns to increase click-through rates.

await createShortUrl({
  url: 'https://myshop.com/products/summer-sale/page',
  custom_alias: 'summer24',
  campaign_id: 'campaign_uuid_here'
});
// Result: https://jmpy.me/summer24

Branded Links

Use your own domain for maximum brand consistency.

await createShortUrl({
  url: 'https://myshop.com/signup',
  custom_alias: 'join',
  url_type: 'branded',
  branded_domain: 'links.myshop.com'
});
// Result: https://links.myshop.com/join

Check Availability

Check if an alias is available before creating

Update Alias

Change the alias of an existing 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

Body Parameters

Response

Request Examples

Response Examples

Use Cases

Check Availability

Update Alias

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

​Body Parameters

​Response

​Request Examples

​Response Examples

​Use Cases

​Related Endpoints

Check Availability

Update Alias

Body Parameters

Response

Request Examples

Response Examples

Use Cases

Related Endpoints