Create with Alias

curl --request POST \
  --url https://jmpy.me/api/v1/short-urls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "<string>",
  "custom_alias": "<string>",
  "url_type": "<string>",
  "subdomain": "<string>",
  "branded_domain": "<string>",
  "name": "<string>",
  "campaign_id": "<string>",
  "expires_at": "<string>",
  "tracking_enabled": true
}
'

{
  "id": "<string>",
  "short_code": "<string>",
  "short_url": "<string>",
  "original_url": "<string>",
  "custom_alias": "<string>",
  "url_type": "<string>"
}

POST

short-urls

Create with Alias

curl --request POST \
  --url https://jmpy.me/api/v1/short-urls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "<string>",
  "custom_alias": "<string>",
  "url_type": "<string>",
  "subdomain": "<string>",
  "branded_domain": "<string>",
  "name": "<string>",
  "campaign_id": "<string>",
  "expires_at": "<string>",
  "tracking_enabled": true
}
'

{
  "id": "<string>",
  "short_code": "<string>",
  "short_url": "<string>",
  "original_url": "<string>",
  "custom_alias": "<string>",
  "url_type": "<string>"
}

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

Check Alias Availability Get by Alias

​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