Hudu Companies

Hudu Companies Management

Overview

Companies are the foundational entity in Hudu, representing clients, vendors, or internal entities. All documentation, assets, passwords, articles, and websites are associated with a company. In Hudu, the "Company" label is customizable per instance -- some MSPs rename it to "Organization" or "Client" -- but the API endpoint is always /api/v1/companies.

Anti-triggers

• The client record of record — a Hudu company scopes documentation. Contracts, contacts, and service history live in the PSA; use autotask-crm, connectwise-psa-companies, or halopsa-clients. Hudu's id_in_integration field holds the PSA's ID precisely because the two are different records.
• The same client in IT Glue — IT Glue calls these Organizations; use itglue-api-patterns for its equivalent surface.
• The monitored client container — an RMM organization or site is a monitoring scope, not documentation; use ninjaone-organizations, atera-customers, or datto-rmm-sites.
• The client's licence or billing entity — use pax8-companies, sherweb-customers, or qbo-customers.

Key Concepts

Company Types

Unlike IT Glue, Hudu does not enforce built-in company types. Companies are typically organized using custom fields or naming conventions. Common patterns MSPs use:

Company Hierarchy

Companies can have parent/child relationships for multi-location or multi-division clients:

Parent Company (Acme Holdings)
+-- Child: Acme East Division
+-- Child: Acme West Division
+-- Child: Acme International

PSA Integration

Companies can be matched to PSA records using the id_in_integration and integration_slug fields, enabling cross-platform lookups between Hudu and tools like ConnectWise Manage, Autotask, or HaloPSA.

Field Reference

Core Fields

Integration Fields

Relationship Fields

Metadata Fields

API Patterns

List Companies

GET /api/v1/companies
x-api-key: YOUR_API_KEY
Content-Type: application/json

With Filters:

GET /api/v1/companies?name=Acme
GET /api/v1/companies?city=Springfield
GET /api/v1/companies?state=IL
GET /api/v1/companies?id_in_integration=12345
GET /api/v1/companies?search=acme

With Pagination:

GET /api/v1/companies?page=1
GET /api/v1/companies?page=2

Get Single Company

GET /api/v1/companies/123
x-api-key: YOUR_API_KEY

Create Company

POST /api/v1/companies
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "company": {
    "name": "New Client Corporation",
    "nickname": "NCC",
    "company_type": "Customer",
    "address_line_1": "123 Main Street",
    "city": "Portland",
    "state": "OR",
    "zip": "97201",
    "phone_number": "555-123-4567",
    "website": "https://newclient.com",
    "notes": "Onboarded February 2026. Primary contact: John Smith."
  }
}

Update Company

PUT /api/v1/companies/123
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "company": {
    "nickname": "NCC-UPDATED",
    "notes": "Updated: New primary contact is Jane Doe (555-987-6543)."
  }
}

Delete Company

DELETE /api/v1/companies/123
x-api-key: YOUR_API_KEY

Warning: Deleting a company removes all associated resources (assets, passwords, articles, etc.). Requires DELETE permission on the API key.

Archive / Unarchive Company

PUT /api/v1/companies/123/archive
x-api-key: YOUR_API_KEY

PUT /api/v1/companies/123/unarchive
x-api-key: YOUR_API_KEY

Search by PSA Integration ID

GET /api/v1/companies?id_in_integration=12345

Common Workflows

New Client Onboarding

1. Create company with basic info (name, address, phone, website)
2. Set integration ID to link with PSA
3. Add notes for quick reference (primary contact, contract info)
4. Create initial assets (servers, workstations, network devices)
5. Document passwords for the company
6. Create articles (network overview, procedures)
7. Add website records for monitoring

async function onboardClient(clientData) {
  // Step 1: Create company
  const company = await createCompany({
    name: clientData.companyName,
    nickname: clientData.nickname,
    company_type: 'Customer',
    address_line_1: clientData.address,
    city: clientData.city,
    state: clientData.state,
    zip: clientData.zip,
    phone_number: clientData.phone,
    website: clientData.website,
    notes: `Onboarded: ${new Date().toLocaleDateString()}\nPrimary contact: ${clientData.primaryContact}`
  });

  // Step 2: Link to PSA
  if (clientData.psaId) {
    await updateCompany(company.id, {
      id_in_integration: clientData.psaId
    });
  }

  return company;
}

Client Offboarding

1. Review and export critical documentation if needed
2. Archive passwords (do not delete for audit purposes)
3. Archive the company instead of deleting
4. Add offboarding notes with date and reason

async function offboardClient(companyId, reason) {
  // Add offboarding notes
  await updateCompany(companyId, {
    notes: `ARCHIVED: ${new Date().toLocaleDateString()} - ${reason}`
  });

  // Archive the company
  await archiveCompany(companyId);
}

PSA Sync Verification

async function verifyPsaSync() {
  const companies = await fetchAllCompanies();

  const syncStatus = {
    synced: [],
    unsynced: [],
    mismatched: []
  };

  for (const company of companies) {
    if (!company.id_in_integration) {
      syncStatus.unsynced.push(company);
    } else {
      const psaCompany = await lookupPsaCompany(company.id_in_integration);
      if (psaCompany) {
        syncStatus.synced.push(company);
      } else {
        syncStatus.mismatched.push(company);
      }
    }
  }

  return syncStatus;
}

Bulk Company Report

async function generateCompanyReport() {
  const companies = await fetchAllCompanies();

  return companies.map(company => ({
    name: company.name,
    nickname: company.nickname,
    city: company.city,
    state: company.state,
    psaSynced: !!company.id_in_integration,
    hasWebsite: !!company.website,
    createdAt: company.created_at,
    updatedAt: company.updated_at
  }));
}

Error Handling

Common API Errors

Validation Errors

Error Recovery Pattern

async function safeCreateCompany(data) {
  try {
    return await createCompany(data);
  } catch (error) {
    if (error.status === 422 && error.message?.includes('already been taken')) {
      // Company exists - find and return it
      const existing = await findCompanyByName(data.name);
      return existing;
    }

    if (error.status === 401) {
      throw new Error('API key invalid or expired. Check HUDU_API_KEY.');
    }

    throw error;
  }
}

Best Practices

1. Use descriptive names - Include location or identifier if needed for uniqueness
2. Set nicknames - Short abbreviations for quick reference
3. Maintain notes - Keep emergency contact info and contract details readily available
4. Link to PSA - Always set id_in_integration for cross-platform lookups
5. Use parent/child - Organize multi-location or division clients
6. Archive, don't delete - Preserve historical documentation
7. Include address info - Useful for dispatch and site visit planning
8. Document website - Track the company's primary website URL

Related Skills

• Hudu Assets - Asset management for companies
• Hudu Articles - Knowledge base articles
• Hudu Passwords - Credential storage
• Hudu Websites - Website monitoring
• Hudu API Patterns - API reference