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"
    }
  }'

4. 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

Parameter	Type	Required	Description	Example
page	Integer	No	Page number for pagination (defaults to 1)	page=2
company_type	String	No	Filter by company type (case-insensitive)	company_type=carrier
name	String	No	Filter by company name (case-insensitive, starts with match)	name=acme
company_number	String	No	Filter 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:

Field	Type	Description
id	Integer	Unique identifier for the company
parent_id	Integer	ID of parent company (null if none)
company_type	String	Type of company ("carrier", "customer", or "both")
name	String	Name of the company
company_number	String	Unique external identifier for the company
email	String	Primary email address for the company
phone	String	Primary phone number for the company
street	String	Street address
unit	String	Unit or suite number
city	String	City
province	String	Province or state
country	String	Country code (2-letter ISO code)
postal	String	Postal or ZIP code
category	String	Category or classification
auto_approve_appointments	Boolean	Whether appointments are automatically approved
can_create_carriers	Boolean	Whether this company can create carrier companies
notifications	Boolean	Whether this company receives notifications
custom_values	Object	Key-value pairs of custom fields
users	Array	List 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

Parameter	Type	Required	Description
id	Integer	Yes	Unique 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

Parameter	Type	Required	Description	Constraints	Default	Example
name	String	Yes	Name of the company	2-164 chars, unique within org (case-insensitive)	None	"Acme Logistics"
company_type	String	Yes	Type of company	"carrier", "customer", or "both"	None	"carrier"
company_number	String	No	External identifier	Unique within org	Random 11-digit number	"ACME-001"
email	String	No	Primary email address	Valid email format, 4-128 chars	None	"info@example.com"
phone	String	No	Primary phone number	None	None	"+15551234567"
street	String	No	Street address	4-64 chars if provided	None	"123 Main St"
unit	String	No	Unit or suite number	1-64 chars if provided	None	"Suite 400"
city	String	No	City	2-64 chars if provided	None	"Chicago"
province	String	No	Province or state	None	None	"IL"
country	String	No	Country code	2 chars if provided (ISO code)	None	"US"
postal	String	No	Postal or ZIP code	4-10 chars if provided	None	"60601"
category	String	No	Category or classification	None	None	"Premium"
auto_approve_appointments	Boolean	No	Auto-approve appointments	None	false	true
can_create_carriers	Boolean	No	Can create carriers	None	false	false
notifications	Boolean	No	Receives notifications	None	false	true
can_book_drop_trailers	Boolean	No	Can book drop trailers	None	true	true
send_appointment_no_show_notifications	Boolean	No	Sends no-show notifications	None	true	true
send_appointment_late_notifications	Boolean	No	Sends late notifications	None	true	true
custom_values	Object	No	Custom field values	Based on location settings	{}	{"reference": "ABC123"}
invite_user	String	No	Invite a user for this company	If "true", uses email field	false	"true"
parent_id	Integer	No	Parent company ID	Must be an existing company	None	123

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

Parameter	Type	Required	Description
id	Integer	Yes	Unique 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 Code	Description	Possible Cause
400	Bad Request	Invalid values or format
404	Not Found	Company ID doesn't exist
422	Unprocessable Entity	Validation failed (e.g., duplicate name)
401	Unauthorized	Invalid or missing API token
403	Forbidden	Insufficient 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

Parameter	Type	Required	Description
id	Integer	Yes	Unique 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 Code	Description	Possible Cause
404	Not Found	Company ID doesn't exist
401	Unauthorized	Invalid or missing API token
403	Forbidden	Insufficient permissions to delete
422	Unprocessable Entity	Cannot delete (e.g., has associated appointments or records)

Field Validation Rules

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

Field	Validation Rules
name	Required, 2-164 characters, unique within org (case-insensitive)
company_type	Required, must be "carrier", "customer", or "both"
company_number	Optional, must be unique within org
email	Optional, valid email format, 4-128 characters
street	Optional, 4-64 characters if provided
unit	Optional, 1-64 characters if provided
city	Optional, 2-64 characters if provided
country	Optional, exactly 2 characters if provided (ISO country code)
postal	Optional, 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"
  }
}