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

# Company Registration Guide

> Learn how to register your property management company with the Arqqin platform and set up your first admin user.

## Overview

The company registration endpoint allows property management companies to onboard themselves to the Arqqin platform. This creates a company record in the system and is typically the first step before you can start managing locations and vehicle whitelists.

<Note>
  Company registration requires an API key for authentication. Contact [hello@arqqin.com](mailto:hello@arqqin.com) to obtain a registration API key.
</Note>

## Registration Process

### Step 1: Prepare Company Information

Gather the following required information:

* **Company details**: Name, slug, business address
* **Optional details**: External company ID, description, contact information, logo
* **Settings**: Company-specific configuration (optional)

### Step 2: Register Your Company

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://apistg.arqq.in/api/register/company" \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Downtown Property Management",
      "slug": "downtown-pm",
      "externalCompanyId": "EXT_12345",
      "description": "Premium property management services",
      "address": "123 Business Street, Dubai",
      "phone": "+1234567890",
      "email": "contact@downtownpm.com",
      "website": "https://downtownpm.com",
      "logo": "https://storage.example.com/logo.png",
      "settings": {}
    }'
  ```

  ```javascript JavaScript theme={null}
  async function registerCompany(companyData, apiKey) {
    try {
      const response = await fetch('https://apistg.arqq.in/api/register/company', {
        method: 'POST',
        headers: {
          'X-API-Key': apiKey,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(companyData)
      });

      if (!response.ok) {
        throw new Error(`Registration failed: ${response.statusText}`);
      }

      return await response.json();
    } catch (error) {
      console.error('Error registering company:', error);
      throw error;
    }
  }

  // Example usage
  const companyData = {
    name: "Downtown Property Management",
    slug: "downtown-pm",
    externalCompanyId: "EXT_12345",
    description: "Premium property management services",
    address: "123 Business Street, Dubai",
    phone: "+1234567890",
    email: "contact@downtownpm.com",
    website: "https://downtownpm.com",
    logo: "https://storage.example.com/logo.png",
    settings: {}
  };

  registerCompany(companyData, 'YOUR_API_KEY')
    .then(result => console.log('Company registered:', result))
    .catch(error => console.error('Registration failed:', error));
  ```

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

  def register_company(company_data, api_key):
      """Register a new company with the Arqqin platform"""
      url = "https://apistg.arqq.in/api/register/company"
      headers = {
          'X-API-Key': api_key,
          'Content-Type': 'application/json'
      }

      try:
          response = requests.post(url, headers=headers, json=company_data)
          response.raise_for_status()
          return response.json()
      except requests.exceptions.RequestException as e:
          print(f"Registration failed: {e}")
          if hasattr(e, 'response') and e.response is not None:
              print(f"Response: {e.response.text}")
          raise

  # Example usage
  company_data = {
      "name": "Downtown Property Management",
      "slug": "downtown-pm",
      "externalCompanyId": "EXT_12345",
      "description": "Premium property management services",
      "address": "123 Business Street, Dubai",
      "phone": "+1234567890",
      "email": "contact@downtownpm.com",
      "website": "https://downtownpm.com",
      "logo": "https://storage.example.com/logo.png",
      "settings": {}
  }

  try:
      result = register_company(company_data, 'YOUR_API_KEY')
      print("Company registered successfully:", result)
  except Exception as e:
      print("Registration failed:", e)
  ```
</CodeGroup>

### Step 3: Registration Complete

After successful registration, you'll receive confirmation with your company details:

```json theme={null}
{
  "success": true,
  "message": "Company created successfully",
  "data": {
    "companyId": "k17abc123def456ghi789jkl012mno345"
  }
}
```

<Note>
  After registration, you can use the `/companies` endpoint to list your registered companies and begin adding locations.
</Note>

## Required Fields

<ResponseField name="name" type="string" required>
  Your company's display name (1-100 characters, alphanumeric with spaces and common symbols)
</ResponseField>

<ResponseField name="slug" type="string" required>
  URL-friendly company identifier (lowercase letters, numbers, hyphens only, 1-50 characters)
</ResponseField>

<ResponseField name="address" type="string" required>
  Your company's business address (1-200 characters)
</ResponseField>

## Optional Fields

<ResponseField name="externalCompanyId" type="string">
  External system reference ID (max 50 characters)
</ResponseField>

<ResponseField name="description" type="string">
  Company description (max 500 characters)
</ResponseField>

<ResponseField name="phone" type="string">
  Company phone number (max 20 characters)
</ResponseField>

<ResponseField name="email" type="string">
  Company email address (must be valid email format or empty string)
</ResponseField>

<ResponseField name="website" type="string">
  Company website URL (must be valid URL or empty string)
</ResponseField>

<ResponseField name="logo" type="string">
  Company logo URL (must be valid URL or empty string)
</ResponseField>

<ResponseField name="settings" type="object">
  Company-specific settings (optional object)
</ResponseField>

## Validation Rules

### Company Name Format

* Must contain only alphanumeric characters, spaces, and common symbols: `-&.,()`
* Must be between 1-100 characters
* Cannot be empty or only whitespace

### Company Slug Format

* Must contain only lowercase letters, numbers, and hyphens
* Cannot start or end with a hyphen
* Cannot contain consecutive hyphens (`--`)
* Must be between 1-50 characters
* Must be unique across all companies

### Address Requirements

* Must be between 1-200 characters
* Cannot be empty or only whitespace

### Optional Field Validation

* **Email**: Must be valid email format or empty string
* **Website/Logo**: Must be valid URL format or empty string
* **Phone**: Maximum 20 characters
* **Description**: Maximum 500 characters
* **External Company ID**: Maximum 50 characters

## Common Errors

### Company Slug Already Exists

```json theme={null}
{
  "success": false,
  "error": {
    "code": "CONFLICT_ERROR",
    "message": "Company slug already exists"
  }
}
```

**Solution**: Choose a different company slug that's unique.

### Invalid Company Name

```json theme={null}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Company name contains invalid characters"
  }
}
```

**Solution**: Ensure the company name only contains alphanumeric characters, spaces, and allowed symbols.

### Invalid Address

```json theme={null}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Business address is required"
  }
}
```

**Solution**: Provide a valid business address between 1-200 characters.

### Invalid Slug Format

```json theme={null}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Company slug must contain only lowercase letters, numbers, and hyphens"
  }
}
```

**Solution**: Ensure your slug follows the format requirements (lowercase, alphanumeric, hyphens only).

## Error Handling Best Practices

<CodeGroup>
  ```javascript JavaScript Error Handling theme={null}
  async function registerCompanyWithErrorHandling(companyData) {
    try {
      const response = await fetch('https://apistg.arqq.in/api/register/company', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(companyData)
      });

      const result = await response.json();

      if (!response.ok) {
        // Handle specific error cases
        if (result.error?.code === 'CONFLICT') {
          if (result.error.message.includes('slug')) {
            throw new Error('Company slug already taken. Please choose a different one.');
          }
          if (result.error.message.includes('email')) {
            throw new Error('Email already registered. Please use a different email.');
          }
        }

        if (result.error?.code === 'VALIDATION_ERROR') {
          throw new Error(`Invalid input: ${result.error.message}`);
        }

        throw new Error(result.error?.message || 'Registration failed');
      }

      return result;
    } catch (error) {
      console.error('Company registration error:', error.message);
      throw error;
    }
  }
  ```

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

  def register_company_with_error_handling(company_data):
      """Register company with comprehensive error handling"""
      url = "https://apistg.arqq.in/api/register/company"
      headers = {'Content-Type': 'application/json'}

      try:
          response = requests.post(url, headers=headers, json=company_data)
          result = response.json()

          if not response.ok:
              error_code = result.get('error', {}).get('code')
              error_message = result.get('error', {}).get('message', 'Unknown error')

              if error_code == 'CONFLICT':
                  if 'slug' in error_message:
                      raise ValueError('Company slug already taken. Please choose a different one.')
                  if 'email' in error_message:
                      raise ValueError('Email already registered. Please use a different email.')

              if error_code == 'VALIDATION_ERROR':
                  raise ValueError(f'Invalid input: {error_message}')

              raise Exception(f'Registration failed: {error_message}')

          return result

      except requests.exceptions.RequestException as e:
          raise Exception(f'Network error during registration: {e}')
  ```
</CodeGroup>

## Next Steps

After successful company registration:

1. **Add your first location** - Use the [Location Management](/guides/location-management) guide
2. **Set up vehicle whitelists** - Follow the [Whitelist Management](/guides/whitelist-management) guide
3. **Integrate with your system** - Check out [Integration Examples](/guides/integration-examples)

## Testing Your Registration

You can test the registration process using the staging environment:

* **Staging URL**: `https://apistg.arqq.in/api/register/company`
* Use test data during development
* The staging environment is isolated from production data

<Tip>
  During development, use obviously fake company names and email addresses to avoid confusion with real data.
</Tip>