Check Alias Availability

Check if a custom alias is available for use within a specific domain context. This endpoint helps you verify alias availability before creating a short URL, preventing conflicts.

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.

Query Parameters

alias

string

required

The custom alias to check for availability.Requirements:

3-50 characters
Alphanumeric with underscores (_) or dashes (-) only
Case-sensitive
Must match the regex ^[a-zA-Z0-9_-]+$

Example: my-custom-alias

url_type

string

default:"standard"

The type of URL context to check within.

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

subdomain

string

The subdomain to check within (required when url_type=subdomain).Example: acme (checks acme.jmpy.me)

branded_domain

string

The branded domain to check within (required when url_type=branded).Example: go.mycompany.com

Response

available

boolean

Whether the alias is available for use.

alias

string

The alias that was checked.

url_type

string

The URL type context that was checked.

subdomain

string

The subdomain context (if applicable).

branded_domain

string

The branded domain context (if applicable).

full_url

string

The full URL that would be created if this alias is used.

message

string

Human-readable status message.

Request Examples

Standard
Subdomain
Branded Domain
Branded Subdomain

curl -X GET "https://jmpy.me/api/v1/short-urls/check-alias?alias=my-custom-alias" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X GET "https://jmpy.me/api/v1/short-urls/check-alias?alias=promo&url_type=subdomain&subdomain=acme" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X GET "https://jmpy.me/api/v1/short-urls/check-alias?alias=signup&url_type=branded&branded_domain=mycompany.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X GET "https://jmpy.me/api/v1/short-urls/check-alias?alias=summer-sale&url_type=branded&branded_domain=go.mycompany.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

Standard
Subdomain
Branded Domain
Branded Subdomain

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

const response = await fetch(
  'https://jmpy.me/api/v1/short-urls/check-alias?alias=my-custom-alias',
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
const data = await response.json();

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

const params = new URLSearchParams({
  alias: 'promo',
  url_type: 'subdomain',
  subdomain: 'acme'
});

const response = await fetch(
  `https://jmpy.me/api/v1/short-urls/check-alias?${params}`,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
const data = await response.json();

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

const params = new URLSearchParams({
  alias: 'signup',
  url_type: 'branded',
  branded_domain: 'mycompany.com'
});

const response = await fetch(
  `https://jmpy.me/api/v1/short-urls/check-alias?${params}`,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
const data = await response.json();

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

const params = new URLSearchParams({
  alias: 'summer-sale',
  url_type: 'branded',
  branded_domain: 'go.mycompany.com'
});

const response = await fetch(
  `https://jmpy.me/api/v1/short-urls/check-alias?${params}`,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
const data = await response.json();

Standard
Subdomain
Branded Domain
Branded Subdomain

import axios from 'axios';

const response = await axios.get(
  'https://jmpy.me/api/v1/short-urls/check-alias',
  {
    params: { alias: 'my-custom-alias' },
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  }
);

import axios from 'axios';

const response = await axios.get(
  'https://jmpy.me/api/v1/short-urls/check-alias',
  {
    params: {
      alias: 'promo',
      url_type: 'subdomain',
      subdomain: 'acme'
    },
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  }
);

import axios from 'axios';

const response = await axios.get(
  'https://jmpy.me/api/v1/short-urls/check-alias',
  {
    params: {
      alias: 'signup',
      url_type: 'branded',
      branded_domain: 'mycompany.com'
    },
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  }
);

import axios from 'axios';

const response = await axios.get(
  'https://jmpy.me/api/v1/short-urls/check-alias',
  {
    params: {
      alias: 'summer-sale',
      url_type: 'branded',
      branded_domain: 'go.mycompany.com'
    },
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  }
);

Standard
Subdomain
Branded Domain
Branded Subdomain

import requests

url = "https://jmpy.me/api/v1/short-urls/check-alias"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

response = requests.get(url, headers=headers, params={
    "alias": "my-custom-alias"
})

import requests

url = "https://jmpy.me/api/v1/short-urls/check-alias"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

response = requests.get(url, headers=headers, params={
    "alias": "promo",
    "url_type": "subdomain",
    "subdomain": "acme"
})

import requests

url = "https://jmpy.me/api/v1/short-urls/check-alias"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

response = requests.get(url, headers=headers, params={
    "alias": "signup",
    "url_type": "branded",
    "branded_domain": "mycompany.com"
})

import requests

url = "https://jmpy.me/api/v1/short-urls/check-alias"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

response = requests.get(url, headers=headers, params={
    "alias": "summer-sale",
    "url_type": "branded",
    "branded_domain": "go.mycompany.com"
})

Standard
Subdomain
Branded Domain
Branded Subdomain

<?php
$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://jmpy.me/api/v1/short-urls/check-alias', [
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY'],
    'query' => ['alias' => 'my-custom-alias']
]);
?>

<?php
$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://jmpy.me/api/v1/short-urls/check-alias', [
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY'],
    'query' => [
        'alias' => 'promo',
        'url_type' => 'subdomain',
        'subdomain' => 'acme'
    ]
]);
?>

<?php
$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://jmpy.me/api/v1/short-urls/check-alias', [
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY'],
    'query' => [
        'alias' => 'signup',
        'url_type' => 'branded',
        'branded_domain' => 'mycompany.com'
    ]
]);
?>

<?php
$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://jmpy.me/api/v1/short-urls/check-alias', [
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY'],
    'query' => [
        'alias' => 'summer-sale',
        'url_type' => 'branded',
        'branded_domain' => 'go.mycompany.com'
    ]
]);
?>

Standard
Subdomain
Branded Domain
Branded Subdomain

package main

import "net/http"

func main() {
    req, _ := http.NewRequest("GET", "https://jmpy.me/api/v1/short-urls/check-alias", nil)
    req.Header.Add("Authorization", "Bearer YOUR_API_KEY")
    
    q := req.URL.Query()
    q.Add("alias", "my-custom-alias")
    req.URL.RawQuery = q.Encode()
    
    http.DefaultClient.Do(req)
}

package main

import "net/http"

func main() {
    req, _ := http.NewRequest("GET", "https://jmpy.me/api/v1/short-urls/check-alias", nil)
    req.Header.Add("Authorization", "Bearer YOUR_API_KEY")
    
    q := req.URL.Query()
    q.Add("alias", "promo")
    q.Add("url_type", "subdomain")
    q.Add("subdomain", "acme")
    req.URL.RawQuery = q.Encode()
    
    http.DefaultClient.Do(req)
}

package main

import "net/http"

func main() {
    req, _ := http.NewRequest("GET", "https://jmpy.me/api/v1/short-urls/check-alias", nil)
    req.Header.Add("Authorization", "Bearer YOUR_API_KEY")
    
    q := req.URL.Query()
    q.Add("alias", "signup")
    q.Add("url_type", "branded")
    q.Add("branded_domain", "mycompany.com")
    req.URL.RawQuery = q.Encode()
    
    http.DefaultClient.Do(req)
}

package main

import "net/http"

func main() {
    req, _ := http.NewRequest("GET", "https://jmpy.me/api/v1/short-urls/check-alias", nil)
    req.Header.Add("Authorization", "Bearer YOUR_API_KEY")
    
    q := req.URL.Query()
    q.Add("alias", "summer-sale")
    q.Add("url_type", "branded")
    q.Add("branded_domain", "go.mycompany.com")
    req.URL.RawQuery = q.Encode()
    
    http.DefaultClient.Do(req)
}

Standard
Subdomain
Branded Domain
Branded Subdomain

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

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://jmpy.me/api/v1/short-urls/check-alias?alias=my-custom-alias"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .GET()
    .build();
client.send(request, HttpResponse.BodyHandlers.ofString());

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

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://jmpy.me/api/v1/short-urls/check-alias?alias=promo&url_type=subdomain&subdomain=acme"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .GET()
    .build();
client.send(request, HttpResponse.BodyHandlers.ofString());

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

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://jmpy.me/api/v1/short-urls/check-alias?alias=signup&url_type=branded&branded_domain=mycompany.com"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .GET()
    .build();
client.send(request, HttpResponse.BodyHandlers.ofString());

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

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://jmpy.me/api/v1/short-urls/check-alias?alias=summer-sale&url_type=branded&branded_domain=go.mycompany.com"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .GET()
    .build();
client.send(request, HttpResponse.BodyHandlers.ofString());

Response Examples

Standard
Subdomain
Branded Domain
Branded Subdomain

{
  "success": true,
  "data": {
    "available": true,
    "alias": "my-custom-alias",
    "url_type": "standard",
    "subdomain": null,
    "branded_domain": null,
    "full_url": "https://jmpy.me/my-custom-alias",
    "message": "Alias 'my-custom-alias' is available"
  }
}

{
  "success": true,
  "data": {
    "available": true,
    "alias": "promo",
    "url_type": "subdomain",
    "subdomain": "acme",
    "branded_domain": null,
    "full_url": "https://acme.jmpy.me/promo",
    "message": "Alias 'promo' is available"
  }
}

{
  "success": true,
  "data": {
    "available": true,
    "alias": "signup",
    "url_type": "branded",
    "subdomain": null,
    "branded_domain": "mycompany.com",
    "full_url": "https://mycompany.com/signup",
    "message": "Alias 'signup' is available"
  }
}

{
  "success": true,
  "data": {
    "available": true,
    "alias": "summer-sale",
    "url_type": "branded",
    "subdomain": null,
    "branded_domain": "go.mycompany.com",
    "full_url": "https://go.mycompany.com/summer-sale",
    "message": "Alias 'summer-sale' is available"
  }
}

{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid query parameters supplied",
    "details": "Missing required field: subdomain"
  }
}

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

{
  "success": false,
  "error": {
    "code": "ACCESS_DENIED",
    "message": "You do not have permission to check aliases for this domain"
  }
}

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

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests, please try again later"
  }
}

Use Cases

Pre-validate before creating a URL

Check if an alias is available before creating a short URL to provide better user experience:

async function createShortUrl(url, alias) {
  // First check if alias is available
  const checkResponse = await fetch(
    `https://jmpy.me/api/v1/short-urls/check-alias?alias=${alias}`,
    { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
  );
  const checkResult = await checkResponse.json();
  
  if (!checkResult.data.available) {
    throw new Error(`Alias "${alias}" is not available`);
  }
  
  // Create the short URL
  const createResponse = 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, custom_alias: alias })
  });
  
  return createResponse.json();
}

Check across multiple domains

An alias might be available on one domain but not another:

async function findAvailableDomain(alias, domains) {
  for (const domain of domains) {
    const params = new URLSearchParams({ alias });
    
    if (domain.type === 'subdomain') {
      params.set('url_type', 'subdomain');
      params.set('subdomain', domain.name);
    } else if (domain.type === 'branded') {
      params.set('url_type', 'branded');
      params.set('branded_domain', domain.name);
    }
    
    const response = await fetch(
      `https://jmpy.me/api/v1/short-urls/check-alias?${params}`,
      { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
    );
    const result = await response.json();
    
    if (result.data.available) {
      return { domain, url: result.data.full_url };
    }
  }
  
  return null; // Not available on any domain
}

Create Short URL

Create a short URL with your chosen alias

List Domains

View your registered subdomains and branded domains

​Query Parameters

​Response

​Request Examples

​Response Examples

​Use Cases

​Related Endpoints

Create Short URL

List Domains

Query Parameters

Response

Request Examples

Response Examples

Use Cases

Related Endpoints