Skip to main content

Companies API

🚀 Why Use the Companies API?​

Companies are a foundational entity in DataDocks that represent organizations interacting with your warehouses—both carriers that transport goods and customers that send or receive them. The Companies API enables you to programmatically manage these relationships, synchronizing company data with your ERP, CRM, or other business systems.

Real Problems This API Solves​

  • Maintain a single source of truth: Sync company data between your enterprise systems and DataDocks
  • Streamline onboarding: Automatically create carrier and customer records when added to your systems
  • Enhance data accuracy: Keep contact information and shipping preferences current
  • Automate relationship management: Programmatically control which companies can interact with each other

5-Minute Quickstart​

Want to see the API in action right now? Follow these steps to get your first company created:

  1. Get your API token from support
  2. Find your location subdomain (e.g., your-warehouse.datadocks.com)
  3. Create a basic company with this command:
See cURL example
curl -X POST \
  https://your-warehouse.datadocks.com/api/v1/companies \
  -H 'Authorization: Token YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "company": {
      "name": "Acme Logistics",
      "company_type": "carrier",
      "company_number": "ACME-001",
      "email": "dispatch@acmelogistics.example.com",
      "phone": "+15551234567"
    }
  }'
  1. Voilà! You've created your first company. Check your DataDocks dashboard to see it.

API Architecture Overview​

┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐
│  Your System    │──────▶│  DataDocks API  │──────▶│  Warehouse Ops  │
│  (ERP/CRM/TMS)  │◀──────┤   (REST/JSON)   │◀──────┤  (Companies)    │
└─────────────────┘       └─────────────────┘       └─────────────────┘
                                  │  ▲
                                  │  │
                                  ▼  │
                           ┌─────────────────┐
                           │  Carrier/       │
                           │  Customer       │
                           │  Portals        │
                           └─────────────────┘

Authentication​

All API requests must include your API token in the Authorization header:

Authorization: Token YOUR_API_TOKEN

Listing Companies​

Purpose​

Retrieve a paginated list of companies with optional filtering by company type, name, or company number. Use this endpoint for syncing companies with your systems or generating reports.

Business Use Cases​

  • Sync companies with your ERP or CRM system
  • Generate reports on carriers or customers
  • Display company information in your custom dashboards
  • Filter companies by type for specialized processing

HTTP Request​

GET https://[location_subdomain].datadocks.com/api/v1/companies

Query Parameters​

ParameterTypeRequiredDescriptionExample
pageIntegerNoPage number for pagination (defaults to 1)page=2
company_typeStringNoFilter by company type (case-insensitive)company_type=carrier
nameStringNoFilter by company name (case-insensitive, starts with match)name=acme
company_numberStringNoFilter by company number (case-insensitive, exact match)company_number=ACME-001

Response Format​

The response contains a paginated array of company objects, each with the following fields:

FieldTypeDescription
idIntegerUnique identifier for the company
parent_idIntegerID of parent company (null if none)
company_typeStringType of company ("carrier", "customer", or "both")
nameStringName of the company
company_numberStringUnique external identifier for the company
emailStringPrimary email address for the company
phoneStringPrimary phone number for the company
streetStringStreet address
unitStringUnit or suite number
cityStringCity
provinceStringProvince or state
countryStringCountry code (2-letter ISO code)
postalStringPostal or ZIP code
categoryStringCategory or classification
auto_approve_appointmentsBooleanWhether appointments are automatically approved
can_create_carriersBooleanWhether this company can create carrier companies
notificationsBooleanWhether this company receives notifications
custom_valuesObjectKey-value pairs of custom fields
usersArrayList of users associated with this company

Code Examples​

cURL​

See cURL example
# Basic listing
curl -H "Authorization: Token YOUR_API_TOKEN" \
     https://YOUR_LOCATION.datadocks.com/api/v1/companies

# Filtered by company type and name
curl -H "Authorization: Token YOUR_API_TOKEN" \
     "https://YOUR_LOCATION.datadocks.com/api/v1/companies?company_type=carrier&name=logistic"

JavaScript​

See JavaScript example
// Using fetch API with filters
const getCompanies = async (companyType, nameFilter, companyNumber) => {
  const params = new URLSearchParams();
  if (companyType) params.append("company_type", companyType);
  if (nameFilter) params.append("name", nameFilter);
  if (companyNumber) params.append("company_number", companyNumber);

  const response = await fetch(
    `https://YOUR_LOCATION.datadocks.com/api/v1/companies?${params.toString()}`,
    {
      method: "GET",
      headers: {
        Authorization: "Token YOUR_API_TOKEN",
        "Content-Type": "application/json",
      },
    }
  );

  // Handle potential errors
  if (!response.ok) {
    const errorData = await response.json();
    throw new Error(`Failed to fetch companies: ${JSON.stringify(errorData)}`);
  }

  return response.json();
};

Sample Response​

See sample response example
[
  {
    "id": 1,
    "parent_id": null,
    "company_type": "carrier",
    "name": "Joe's Shipping",
    "company_number": "A17727959343",
    "email": "info@joesshipping.com",
    "phone": "+14161231234",
    "street": "1 Yonge St.",
    "unit": null,
    "city": "Toronto",
    "province": "ON",
    "country": "CA",
    "postal": "M8H 1G1",
    "category": null,
    "auto_approve_appointments": true,
    "can_create_carriers": false,
    "notifications": true,
    "custom_values": {
      "ap_contact": "Sue Brown",
      "sales_contact": "Tim Jones",
      "facility_contact": "John Green"
    },
    "users": [
      {
        "email": "driver@joesshipping.com",
        "name": "Joe Driver"
      }
    ]
  },
  {
    "id": 2,
    "parent_id": null,
    "company_type": "customer",
    "name": "Spatula City",
    "company_number": "B83582616848",
    "email": "info@spatulacity.com",
    "phone": "+14161231234",
    "street": "1 Yonge St.",
    "unit": "4",
    "city": "Toronto",
    "province": "ON",
    "country": "CA",
    "postal": "M8H 1G1",
    "category": null,
    "auto_approve_appointments": false,
    "can_create_carriers": true,
    "notifications": false,
    "custom_values": {
      "ap_contact": "",
      "sales_contact": "Al Yankovic",
      "facility_contact": ""
    },
    "users": []
  }
]

Pagination​

The response is paginated to manage data volume. For detailed information about pagination headers and navigation, please refer to the Pagination documentation.

Retrieving a Single Company​

Purpose​

Get detailed information about a specific company by ID. Use this endpoint when you need comprehensive data about a particular company.

Business Use Cases​

  • Display detailed company information in your application
  • Verify company details before processing transactions
  • Retrieve current contact information for communications
  • Access company-specific settings and preferences

HTTP Request​

GET https://[location_subdomain].datadocks.com/api/v1/companies/:id

Path Parameters​

ParameterTypeRequiredDescription
idIntegerYesUnique ID of the company

Response​

A successful request returns a 200 OK response with the full company object in the same format as the list response.

Code Examples​

cURL​

See cURL example
curl -H "Authorization: Token YOUR_API_TOKEN" \
     https://YOUR_LOCATION.datadocks.com/api/v1/companies/123

JavaScript​

See JavaScript example
const getCompany = async (companyId) => {
  try {
    const response = await fetch(
      `https://YOUR_LOCATION.datadocks.com/api/v1/companies/${companyId}`,
      {
        method: "GET",
        headers: {
          Authorization: "Token YOUR_API_TOKEN",
          "Content-Type": "application/json",
        },
      }
    );

    if (!response.ok) {
      if (response.status === 404) {
        throw new Error(`Company #${companyId} not found`);
      }

      const errorData = await response.json();
      throw new Error(
        `Failed to retrieve company: ${JSON.stringify(errorData)}`
      );
    }

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

Creating a Company​

Purpose​

Create a new company record in DataDocks. This endpoint allows you to add new carriers or customers to your system programmatically.

Decision Tree: When to Create a Company via API​

┌─────────────────┐
│ Need to add a   │
│    company?     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐     Yes     ┌─────────────────┐
│  Adding many    │────────────▶│   Consider      │
│  companies at   │             │   bulk import   │
│     once?       │             │                 │
└────────┬────────┘             └─────────────────┘
         │ No
         ▼
┌─────────────────┐     Yes     ┌─────────────────┐
│ Is this a one-  │────────────▶│   Use the web   │
│ time addition?  │             │   interface     │
└────────┬────────┘             └─────────────────┘
         │ No
         ▼
┌─────────────────┐
│   Perfect for   │
│   the API!      │
└─────────────────┘

Business Use Cases​

  • System Integration: Create companies directly from your ERP or CRM
  • Automated Onboarding: Programmatically set up new carriers or customers
  • Data Migration: Transfer company records from legacy systems
  • Partner Integration: Allow partners to register companies through your systems

HTTP Request​

POST https://[location_subdomain].datadocks.com/api/v1/companies

Request Body​

ParameterTypeRequiredDescriptionConstraintsDefaultExample
nameStringYesName of the company2-164 chars, unique within org (case-insensitive)None"Acme Logistics"
company_typeStringYesType of company"carrier", "customer", or "both"None"carrier"
company_numberStringNoExternal identifierUnique within orgRandom 11-digit number"ACME-001"
emailStringNoPrimary email addressValid email format, 4-128 charsNone"info@example.com"
phoneStringNoPrimary phone numberNoneNone"+15551234567"
streetStringNoStreet address4-64 chars if providedNone"123 Main St"
unitStringNoUnit or suite number1-64 chars if providedNone"Suite 400"
cityStringNoCity2-64 chars if providedNone"Chicago"
provinceStringNoProvince or stateNoneNone"IL"
countryStringNoCountry code2 chars if provided (ISO code)None"US"
postalStringNoPostal or ZIP code4-10 chars if providedNone"60601"
categoryStringNoCategory or classificationNoneNone"Premium"
auto_approve_appointmentsBooleanNoAuto-approve appointmentsNonefalsetrue
can_create_carriersBooleanNoCan create carriersNonefalsefalse
notificationsBooleanNoReceives notificationsNonefalsetrue
can_book_drop_trailersBooleanNoCan book drop trailersNonetruetrue
send_appointment_no_show_notificationsBooleanNoSends no-show notificationsNonetruetrue
send_appointment_late_notificationsBooleanNoSends late notificationsNonetruetrue
custom_valuesObjectNoCustom field valuesBased on location settings{}{"reference": "ABC123"}
invite_userStringNoInvite a user for this companyIf "true", uses email fieldfalse"true"
parent_idIntegerNoParent company IDMust be an existing companyNone123

Response​

A successful request returns a 200 OK response with the full company object, including the generated id and other system-assigned values.

Code Examples​

cURL​

See cURL example
curl -H "Authorization: Token YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{
       "company": {
         "name": "Quick Transport Inc",
         "company_type": "carrier",
         "company_number": "QT-2023-001",
         "email": "dispatch@quicktransport.example.com",
         "phone": "+15551234567",
         "street": "123 Logistics Way",
         "city": "Chicago",
         "province": "IL",
         "country": "US",
         "postal": "60601",
         "auto_approve_appointments": true,
         "notifications": true,
         "custom_values": {
           "insurance_policy": "INS-567890",
           "preferred_dock": "Dock 3"
         },
         "invite_user": "true",
         "parent_id": 123
       }
     }' \
     https://YOUR_LOCATION.datadocks.com/api/v1/companies

JavaScript​

See JavaScript example
const createCompany = async (companyData) => {
  try {
    const response = await fetch(
      `https://YOUR_LOCATION.datadocks.com/api/v1/companies`,
      {
        method: "POST",
        headers: {
          Authorization: "Token YOUR_API_TOKEN",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ company: companyData }),
      }
    );

    if (!response.ok) {
      const errorData = await response.json();
      const errorMessages = Object.entries(errorData.errors || {})
        .map(([field, messages]) => `${field}: ${messages.join(", ")}`)
        .join("\n");

      throw new Error(`Failed to create company:\n${errorMessages}`);
    }

    return await response.json();
  } catch (error) {
    console.error("API Error:", error);
    throw error;
  }
};

Updating a Company​

Purpose​

Update an existing company's details. This endpoint allows you to modify any aspect of a company's information.

Business Use Cases​

  • Keep Data Current: Update contact information or shipping preferences
  • Change Company Status: Modify notification settings or appointment approval rules
  • Manage Permissions: Adjust what a company is allowed to do in the system
  • Synchronize Systems: Keep DataDocks in sync with your ERP or CRM

HTTP Request​

PUT https://[location_subdomain].datadocks.com/api/v1/companies/:id

Path Parameters​

ParameterTypeRequiredDescription
idIntegerYesUnique ID of the company

Request Body​

The request body accepts the same parameters as the create endpoint. Only the fields you want to change need to be included.

Common Update Scenarios​

Updating Contact Information​

{
  "company": {
    "email": "new-contact@example.com",
    "phone": "+15559876543"
  }
}

Changing Notification Settings​

{
  "company": {
    "notifications": true,
    "auto_approve_appointments": false
  }
}

Updating Address​

{
  "company": {
    "street": "456 New Street",
    "city": "New City",
    "province": "NC",
    "postal": "90210"
  }
}

Code Examples​

cURL​

See cURL example
curl -H "Authorization: Token YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -X PUT \
     -d '{
       "company": {
         "name": "Updated Company Name",
         "email": "newemail@example.com",
         "custom_values": {
           "account_manager": "Jane Smith"
         }
       }
     }' \
     https://YOUR_LOCATION.datadocks.com/api/v1/companies/123

JavaScript​

See JavaScript example
const updateCompany = async (companyId, updateData) => {
  try {
    const response = await fetch(
      `https://YOUR_LOCATION.datadocks.com/api/v1/companies/${companyId}`,
      {
        method: "PUT",
        headers: {
          Authorization: "Token YOUR_API_TOKEN",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ company: updateData }),
      }
    );

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`Failed to update company: ${JSON.stringify(errorData)}`);
    }

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

// Example usage
const updateCompanyEmail = async (companyId, newEmail) => {
  try {
    const updatedCompany = await updateCompany(companyId, {
      email: newEmail,
    });

    console.log(`Successfully updated company #${updatedCompany.id} email`);
    return updatedCompany;
  } catch (error) {
    console.error(`Failed to update company #${companyId}:`, error);
    throw error;
  }
};

Error Handling​

Error CodeDescriptionPossible Cause
400Bad RequestInvalid values or format
404Not FoundCompany ID doesn't exist
422Unprocessable EntityValidation failed (e.g., duplicate name)
401UnauthorizedInvalid or missing API token
403ForbiddenInsufficient permissions to update

Deleting a Company​

Purpose​

Remove a company from the system. This endpoint allows you to delete companies that are no longer needed.

Important Considerations​

Before deleting a company, consider the following:

  • The company must not have any active appointments
  • The company must not be referenced by any active packing lists
  • Deletion is permanent and cannot be undone

Business Use Cases​

  • Clean Up Test Data: Remove test or dummy companies
  • Comply with Privacy Requests: Delete company information upon request
  • Remove Duplicate Records: Clean up after data de-duplication
  • System Maintenance: Remove old, unused company records

HTTP Request​

DELETE https://[location_subdomain].datadocks.com/api/v1/companies/:id

Path Parameters​

ParameterTypeRequiredDescription
idIntegerYesUnique ID of the company

Response​

A successful request returns a 204 No Content response, indicating that the company was deleted successfully.

Code Examples​

cURL​

See cURL example
curl -H "Authorization: Token YOUR_API_TOKEN" \
     -X DELETE \
     https://YOUR_LOCATION.datadocks.com/api/v1/companies/123

JavaScript​

See JavaScript example
const deleteCompany = async (companyId) => {
  try {
    const response = await fetch(
      `https://YOUR_LOCATION.datadocks.com/api/v1/companies/${companyId}`,
      {
        method: "DELETE",
        headers: {
          Authorization: "Token YOUR_API_TOKEN",
        },
      }
    );

    if (!response.ok) {
      if (response.status === 404) {
        throw new Error(`Company #${companyId} not found`);
      }

      const errorData = await response.json();
      throw new Error(`Failed to delete company: ${JSON.stringify(errorData)}`);
    }

    return true; // Successfully deleted
  } catch (error) {
    console.error("Error deleting company:", error);
    throw error;
  }
};

Error Handling​

Error CodeDescriptionPossible Cause
404Not FoundCompany ID doesn't exist
401UnauthorizedInvalid or missing API token
403ForbiddenInsufficient permissions to delete
422Unprocessable EntityCannot delete (e.g., has associated appointments or records)

Field Validation Rules​

When creating or updating companies, the following validation rules apply:

FieldValidation Rules
nameRequired, 2-164 characters, unique within org (case-insensitive)
company_typeRequired, must be "carrier", "customer", or "both"
company_numberOptional, must be unique within org
emailOptional, valid email format, 4-128 characters
streetOptional, 4-64 characters if provided
unitOptional, 1-64 characters if provided
cityOptional, 2-64 characters if provided
countryOptional, exactly 2 characters if provided (ISO country code)
postalOptional, 4-10 characters if provided

Automated User Invitation​

When creating or updating a company, you can automatically invite a user associated with that company by setting the invite_user parameter to "true", "yes", "y", or "t" (case-insensitive).

When this parameter is provided, the system will:

  1. Create a company user record with the company's email
  2. Send an invitation email to the provided email address
  3. The user can then set up their account and access the company in DataDocks

Example:

{
  "company": {
    "name": "New Carrier Inc",
    "company_type": "carrier",
    "email": "dispatch@newcarrier.example.com",
    "invite_user": "true"
  }
}

Best Practices​

Data Management​

  • Use Consistent Identifiers: Maintain consistent company numbers across systems
  • Validate Data Client-Side: Ensure data meets validation requirements before sending
  • Handle Custom Fields Properly: Only use custom fields that are configured for your location
  • Be Careful with Deletion: Consider updating instead of deleting when possible
  • Manage User Invitations Carefully: Only invite users who need access to the system

Performance Optimization​

  • Batch Your Updates: Group related company updates together
  • Use Pagination: Request only the companies you need using pagination
  • Filter Efficiently: Use the available filters to minimize data transfer
  • Cache Common Lookups: Store frequently accessed company information locally

Common Gotchas and Troubleshooting​

  • Name Uniqueness: Company names must be unique within an organization (case-insensitive). Ensure unique names when creating companies.
  • Email Formatting: Email addresses must be properly formatted and between 4-128 characters.
  • Custom Values: Custom fields will vary by location. Only fields configured for your location can be used.
  • Company Types: Only "carrier", "customer", or "both" are valid company types.
  • Company Number Auto-Generation: If not provided, company numbers are automatically generated as random numbers up to 11 digits long.
  • Country Codes: Country codes must be valid 2-letter ISO codes (e.g., "US", "CA", "MX").
  • Parent Companies: When creating a company with a parent, the parent company must already exist. The system will automatically create booking permissions between the parent and child.
  • Case Sensitivity: While the API supports case-insensitive filtering, internal validations (like name uniqueness) are also case-insensitive.

Help and Support​

If you're experiencing issues not covered in this documentation:

  1. Check the error response: Most API errors include specific information about what went wrong
  2. Verify permissions: Ensure your API token has sufficient permissions
  3. Test in smaller steps: Break down complex operations to identify the specific issue

Parent-Child Company Relationships​

When creating a company with a parent (setting parent_id), the system automatically establishes a relationship between the parent and child company. This relationship includes:

  1. The child company is linked to the parent via the parent_id field
  2. The system automatically creates booking permissions in both directions
    • Parent company can book for the child company
    • Child company can book for the parent company

This automatic permission creation simplifies management of related companies and ensures they can immediately interact with each other in the system without additional configuration.

Example creating a child company:

{
  "company": {
    "name": "Northeast Branch",
    "company_type": "carrier",
    "parent_id": 123,
    "email": "northeast@example.com"
  }
}