> ## Documentation Index
> Fetch the complete documentation index at: https://core.anylayer.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Check Name Availability

> Check if a ZKS ID name is available for minting

## Overview

Check if a desired ZKS ID name is available before attempting to mint. This endpoint validates the name format and checks if it's already taken. If unavailable, it provides alternative suggestions.

<Tip>
  Always check availability before minting to avoid errors and provide a better user experience with name suggestions.
</Tip>

## Parameters

<ParamField path="name" type="string" required>
  The desired ZKS ID name to check (without .zks suffix). Must be 3-32 characters, lowercase letters, numbers, and hyphens only.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="name" type="string">
  The name that was checked
</ResponseField>

<ResponseField name="available" type="boolean">
  Whether the name is available for minting
</ResponseField>

<ResponseField name="valid" type="boolean">
  Whether the name meets format requirements
</ResponseField>

<ResponseField name="reason" type="string">
  If unavailable or invalid, explains why
</ResponseField>

<ResponseField name="suggestions" type="array">
  Array of alternative name suggestions if the requested name is unavailable
</ResponseField>

## Examples

<CodeGroup>
  ```bash cURL (Available Name) theme={null}
  curl https://api.onzks.com/v1/identity/check/alice \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash cURL (Taken Name) theme={null}
  curl https://api.onzks.com/v1/identity/check/john \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  async function checkNameAvailability(name) {
    const response = await fetch(
      `https://api.onzks.com/v1/identity/check/${name}`,
      {
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY'
        }
      }
    );

    const data = await response.json();
    
    if (data.available) {
      console.log(`${name} is available!`);
    } else {
      console.log(`${name} is taken. Try: ${data.suggestions.join(', ')}`);
    }
    
    return data;
  }

  // Usage
  await checkNameAvailability('alice');
  ```

  ```python Python theme={null}
  import requests

  def check_name_availability(name):
      response = requests.get(
          f'https://api.onzks.com/v1/identity/check/{name}',
          headers={'Authorization': 'Bearer YOUR_API_KEY'}
      )
      
      data = response.json()
      
      if data['available']:
          print(f"{name} is available!")
      else:
          print(f"{name} is taken. Try: {', '.join(data['suggestions'])}")
      
      return data

  # Usage
  check_name_availability('alice')
  ```
</CodeGroup>

## Response Examples

### Available Name

```json theme={null}
{
  "success": true,
  "name": "alice",
  "available": true,
  "valid": true
}
```

### Unavailable Name (Taken)

```json theme={null}
{
  "success": true,
  "name": "john",
  "available": false,
  "valid": true,
  "reason": "Name is already taken",
  "suggestions": [
    "john1",
    "john-zk",
    "john2024",
    "john-defi",
    "johndoe"
  ]
}
```

### Invalid Name Format

```json theme={null}
{
  "success": true,
  "name": "al",
  "available": false,
  "valid": false,
  "reason": "Name must be at least 3 characters long",
  "suggestions": [
    "alice",
    "alex",
    "alan"
  ]
}
```

### Invalid Characters

```json theme={null}
{
  "success": true,
  "name": "Alice",
  "available": false,
  "valid": false,
  "reason": "Name must contain only lowercase letters, numbers, and hyphens",
  "suggestions": [
    "alice",
    "alice1",
    "alice-zk"
  ]
}
```

## Validation Rules

### Valid Name Requirements

* **Length**: 3-32 characters (excluding .zks suffix)
* **Characters**: Lowercase letters (a-z), numbers (0-9), hyphens (-)
* **Start/End**: Must start and end with a letter or number (not hyphen)
* **No consecutive hyphens**: Cannot have multiple hyphens in a row

### Examples

| Name                                       | Valid | Reason              |
| ------------------------------------------ | ----- | ------------------- |
| `alice`                                    | ✅     | Perfect             |
| `defi-master`                              | ✅     | Valid with hyphen   |
| `user123`                                  | ✅     | Valid with numbers  |
| `al`                                       | ❌     | Too short (min 3)   |
| `Alice`                                    | ❌     | Contains uppercase  |
| `-alice`                                   | ❌     | Starts with hyphen  |
| `alice-`                                   | ❌     | Ends with hyphen    |
| `alice--bob`                               | ❌     | Consecutive hyphens |
| `alice.eth`                                | ❌     | Contains period     |
| `this-name-is-way-too-long-for-validation` | ❌     | Too long (max 32)   |

## Use Cases

### 1. Real-time Name Validation

Check availability as user types:

```javascript theme={null}
let checkTimeout;

function onNameInput(name) {
  // Debounce API calls
  clearTimeout(checkTimeout);
  
  checkTimeout = setTimeout(async () => {
    const result = await checkNameAvailability(name);
    
    if (result.available) {
      showSuccess(`${name}.zks is available!`);
    } else {
      showError(`${name}.zks is taken`);
      showSuggestions(result.suggestions);
    }
  }, 500); // Wait 500ms after user stops typing
}
```

### 2. Name Suggestion Flow

Provide alternatives if name is taken:

```javascript theme={null}
async function findAvailableName(desiredName) {
  let result = await checkNameAvailability(desiredName);
  
  if (result.available) {
    return desiredName;
  }
  
  // Try suggestions
  for (const suggestion of result.suggestions) {
    result = await checkNameAvailability(suggestion);
    
    if (result.available) {
      console.log(`${desiredName} is taken, using ${suggestion} instead`);
      return suggestion;
    }
  }
  
  // Generate custom suggestion
  const customName = `${desiredName}${Math.floor(Math.random() * 1000)}`;
  return customName;
}
```

### 3. Batch Name Checking

Check multiple names at once:

```javascript theme={null}
async function checkMultipleNames(names) {
  const results = await Promise.all(
    names.map(name => checkNameAvailability(name))
  );
  
  const available = results
    .filter(r => r.available)
    .map(r => r.name);
  
  const taken = results
    .filter(r => !r.available)
    .map(r => r.name);
  
  return { available, taken };
}

// Usage
const { available, taken } = await checkMultipleNames([
  'alice', 'bob', 'charlie', 'david'
]);

console.log('Available:', available);
console.log('Taken:', taken);
```

### 4. Smart Suggestions

Generate intelligent name suggestions:

```javascript theme={null}
async function getSmartSuggestions(baseName) {
  const result = await checkNameAvailability(baseName);
  
  if (result.available) {
    return [baseName];
  }
  
  // Try API suggestions first
  const suggestions = [...result.suggestions];
  
  // Add custom suggestions
  suggestions.push(
    `${baseName}-defi`,
    `${baseName}-nft`,
    `${baseName}${new Date().getFullYear()}`,
    `${baseName}-trader`,
    `${baseName}-dev`
  );
  
  // Check which suggestions are available
  const availableSuggestions = [];
  
  for (const suggestion of suggestions) {
    const check = await checkNameAvailability(suggestion);
    if (check.available) {
      availableSuggestions.push(suggestion);
    }
    
    // Limit to 5 suggestions
    if (availableSuggestions.length >= 5) break;
  }
  
  return availableSuggestions;
}
```

## Best Practices

### 1. Debounce API Calls

Avoid excessive API calls during typing:

```javascript theme={null}
import { debounce } from 'lodash';

const checkAvailability = debounce(async (name) => {
  const result = await fetch(`/v1/identity/check/${name}`);
  return result.json();
}, 500);
```

### 2. Cache Results

Cache availability checks to reduce API calls:

```javascript theme={null}
const availabilityCache = new Map();

async function checkWithCache(name) {
  if (availabilityCache.has(name)) {
    return availabilityCache.get(name);
  }
  
  const result = await checkNameAvailability(name);
  availabilityCache.set(name, result);
  
  // Clear cache after 5 minutes
  setTimeout(() => availabilityCache.delete(name), 5 * 60 * 1000);
  
  return result;
}
```

### 3. Validate Locally First

Check format locally before API call:

```javascript theme={null}
function isValidNameFormat(name) {
  // Check length
  if (name.length < 3 || name.length > 32) {
    return { valid: false, reason: 'Length must be 3-32 characters' };
  }
  
  // Check characters
  if (!/^[a-z0-9-]+$/.test(name)) {
    return { valid: false, reason: 'Only lowercase letters, numbers, and hyphens' };
  }
  
  // Check start/end
  if (name.startsWith('-') || name.endsWith('-')) {
    return { valid: false, reason: 'Cannot start or end with hyphen' };
  }
  
  // Check consecutive hyphens
  if (name.includes('--')) {
    return { valid: false, reason: 'Cannot have consecutive hyphens' };
  }
  
  return { valid: true };
}

// Use before API call
const validation = isValidNameFormat(name);
if (!validation.valid) {
  showError(validation.reason);
  return;
}

// Only call API if format is valid
const result = await checkNameAvailability(name);
```

### 4. Show Real-time Feedback

Provide immediate visual feedback:

```javascript theme={null}
async function validateNameInput(inputElement) {
  const name = inputElement.value.toLowerCase();
  
  // Local validation
  const validation = isValidNameFormat(name);
  if (!validation.valid) {
    inputElement.classList.add('invalid');
    showError(validation.reason);
    return;
  }
  
  // API check
  const result = await checkNameAvailability(name);
  
  if (result.available) {
    inputElement.classList.add('valid');
    inputElement.classList.remove('invalid');
    showSuccess(`${name}.zks is available!`);
  } else {
    inputElement.classList.add('invalid');
    inputElement.classList.remove('valid');
    showSuggestions(result.suggestions);
  }
}
```

## Error Responses

<ResponseExample>
  ```json 400 Bad Request theme={null}
  {
    "success": false,
    "error": "INVALID_NAME_FORMAT",
    "message": "Name must be 3-32 characters, lowercase letters, numbers, and hyphens only"
  }
  ```

  ```json 429 Too Many Requests theme={null}
  {
    "success": false,
    "error": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again later."
  }
  ```
</ResponseExample>

## Integration Example

Complete name selection flow:

```javascript theme={null}
class NameSelector {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.cache = new Map();
  }

  async checkAvailability(name) {
    // Validate format
    const validation = this.validateFormat(name);
    if (!validation.valid) {
      return validation;
    }

    // Check cache
    if (this.cache.has(name)) {
      return this.cache.get(name);
    }

    // API call
    const response = await fetch(
      `https://api.onzks.com/v1/identity/check/${name}`,
      { headers: { 'Authorization': `Bearer ${this.apiKey}` } }
    );

    const result = await response.json();
    this.cache.set(name, result);

    return result;
  }

  validateFormat(name) {
    if (name.length < 3 || name.length > 32) {
      return { 
        valid: false, 
        available: false,
        reason: 'Length must be 3-32 characters' 
      };
    }

    if (!/^[a-z0-9-]+$/.test(name)) {
      return { 
        valid: false, 
        available: false,
        reason: 'Only lowercase letters, numbers, and hyphens' 
      };
    }

    if (name.startsWith('-') || name.endsWith('-')) {
      return { 
        valid: false, 
        available: false,
        reason: 'Cannot start or end with hyphen' 
      };
    }

    return { valid: true };
  }

  async getSuggestions(baseName) {
    const result = await this.checkAvailability(baseName);
    
    if (result.available) {
      return [baseName];
    }

    return result.suggestions || [];
  }
}

// Usage
const selector = new NameSelector('YOUR_API_KEY');
const result = await selector.checkAvailability('alice');

if (result.available) {
  console.log('Name is available!');
} else {
  const suggestions = await selector.getSuggestions('alice');
  console.log('Try these:', suggestions);
}
```

## Related Endpoints

* [Mint Identity](/api-reference/identity/mint-identity) - Create a new identity
* [Get Identity](/api-reference/identity/get-identity) - Retrieve identity information
* [Activate Identity](/api-reference/identity/activate-identity) - Activate an identity

## Troubleshooting

### "Too many requests"

**Cause**: Exceeded rate limits for availability checks.

**Solution**:

* Implement debouncing (wait 500ms after user stops typing)
* Cache results locally
* Reduce frequency of checks

### "Invalid name format"

**Cause**: Name doesn't meet validation requirements.

**Solution**:

* Validate locally before API call
* Show clear validation rules to users
* Provide real-time format feedback

## Rate Limits

Name availability checks are subject to rate limits:

* **Free tier**: 100 checks per minute
* **Starter tier**: 500 checks per minute
* **Professional tier**: 2,000 checks per minute
* **Enterprise tier**: Custom limits

Implement debouncing and caching to stay within limits.