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

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

Check Alias Availability

Query Parameters

Response

Request Examples

Response Examples

Use Cases

Create Short URL

List Domains

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

​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