Organization API

Why Use the Organization API?

Connect your ERP, TMS, or WMS to multiple DataDocks locations through one organization URL. List records across your accessible warehouses, or read and update a record by ID without naming its warehouse.

• Manage multiple warehouses — Use one base URL for appointments, products, and purchase orders across your locations.
• Discover available locations — Retrieve the locations your API user can access.
• Create orders before assigning a warehouse — Add a purchase order now and assign its location later.

For an organization named Acme, the base URL is:

https://acme.datadocks.com/api/v1

You can continue using the location API at URLs such as https://toronto-acme.datadocks.com/api/v1.

5-Minute Quickstart

Let's retrieve the products at one of your warehouses:

1. Get Your API Token

   Contact support@datadocks.com with your organization name and the locations you need to access. If you already have an API token, you can use it with the organization API.

2. Find Your Locations

See cURL example

curl -H "Authorization: Token YOUR_API_TOKEN" \
     https://acme.datadocks.com/api/v1/locations

A successful response returns the available location names:

[
  { "name": "Toronto", "url": "toronto-acme" },
  { "name": "Vancouver", "url": "vancouver-acme" }
]

3. Get Products at a Location

Use a name from the response as location_name:

See cURL example

curl -H "Authorization: Token YOUR_API_TOKEN" \
     "https://acme.datadocks.com/api/v1/products?location_name=Toronto"

A successful request returns 200 OK with the location's products. See Organization API Resources for appointment, product, company, and product-limit examples.

Authentication and Access

Include your API token in every request:

Authorization: Token YOUR_API_TOKEN

Your API user needs:

• Admin access at a location in the organization.
• Access to each location you want to work with, with permission to perform the requested action.

For example, an admin at Toronto also needs access to Vancouver to work with Vancouver's appointments. If their Vancouver role is read-only, they can view those appointments but cannot create or update them.

Contact support if you need to add another location to your integration.

At least one location in your organization must have a paid subscription. Once this requirement is met, you can use the organization API for any location your API user can access, including unpaid locations.

Choosing a Location

Use the location's display name from GET /locations, such as Toronto. Names are case-insensitive, and spaces at the beginning or end are ignored. If a location is renamed, update the name in your integration.

Resource	Is location_name Required?	More Information
Appointments	Only for create	Appointments
Products	Only for create	Products
Companies	No	Companies
Product limits	No	Product Limits
Locations	No	Listing Locations
Purchase orders	No	Purchase Orders

Reading or Deleting Records

Omit location_name to list records across accessible locations. Show, update, and supported delete actions infer the location from the record ID. Add location_name to narrow the lookup; an ID outside that filter returns 404. Use --data-urlencode for names containing spaces:

curl -G -H "Authorization: Token YOUR_API_TOKEN" \
     --data-urlencode "location_name=Toronto Warehouse" \
     https://acme.datadocks.com/api/v1/products

Creating or Updating Records

Creating an appointment or product requires location_name inside the record or URL. Updates infer the existing location and do not require it. Companies never require a location. For example, to create a product:

{
  "product": {
    "location_name": "Toronto",
    "name": "Premium Widget",
    "sku": "WIDGET-001"
  }
}

You can also provide the location in the URL. If you send it in both places, the names must match. Packing lists and purchase-order items use the location from the main request.

Changing location_name does not move an appointment or product to another warehouse. Purchase orders support changing their assigned location.

Location Names in Responses

Resource	Location Field
Appointments	location_name; location remains as a compatibility alias
Products and product limits	location_name
Purchase orders	location_name, or null when unassigned
Locations	name
Companies	None; companies belong to the organization

Packing lists and purchase-order items inherit their parent's location. Nested booked appointments include their own location_name and the compatibility alias location. Use location_name in new integrations.

Timestamps and Time Zones

Every returned date-time uses ISO 8601 with a UTC offset, including created_at, updated_at, and nested timestamps. Each entity uses its own warehouse's time zone at that instant. An entity without a location uses UTC. A location filter does not change this rule.

A mixed-location appointment list can include:

[
  { "id": 123, "location": "Toronto", "scheduled_at": "2026-10-01T12:00:00-04:00" },
  { "id": 456, "location": "Vancouver", "scheduled_at": "2026-10-01T09:00:00-07:00" }
]

These timestamps represent the same instant. Offsets account for daylight saving time. Packing lists and order items inherit their parent's location; nested booked appointments use their own location. Missing times remain null.

Include an offset in timestamp inputs when possible. Without one, create/update uses the entity's effective location, or UTC if unassigned. Collection time filters use the optional filter location, or UTC when searching across locations. Invalid time filters return 400.

Date-only fields retain YYYY-MM-DD. Product-limit recurring start/end times remain local wall-clock times, not dated timestamps. Arbitrary JSON and text custom values retain their original meaning.

Pagination

Use page to retrieve additional results from appointments, products, companies, purchase orders, and product limits:

curl -H "Authorization: Token YOUR_API_TOKEN" \
     "https://acme.datadocks.com/api/v1/products?location_name=Toronto&page=2"

The response headers include Current-Page, Page-Items, Total-Pages, Total-Count, and Link. Follow the URLs in Link to move between pages; they retain a location filter only when you supplied one.

Location listings are not paginated. The purchase-order endpoint for booked appointments uses limit and offset instead.

Rate Limits

Organization and location API requests share the following limits when using the same Authorization header:

Limit	Requests
Per minute	120
Per hour	5,000

If you exceed a limit, the API returns 429 Too Many Requests with a JSON error and these headers:

Header	Description
X-RateLimit-Limit	The limit that was exceeded
X-RateLimit-Remaining	0
X-RateLimit-Reset	When requests can resume, as an ISO 8601 UTC timestamp

Wait until the reset time before retrying. These headers are provided on rate-limit errors; a Retry-After header is not provided.

Error Handling

Error Code	Description	What to Check
400	Bad Request	Include a valid location name where required. If it appears in both the URL and body, use the same name.
401	Unauthorized	Check your API token and Authorization header.
402	Payment Required	Confirm that your organization has at least one paid location.
403	Forbidden	Confirm that your API user has admin access in the organization and the required access at the selected location.
404	Not Found	Check the location name and record ID. The record must be accessible at that location.
422	Unprocessable Entity	Read the response's errors for fields that need correcting.
429	Too Many Requests	Wait until the rate-limit reset time before retrying.

For example, creating a product without a location returns 400:

{
  "error": "location_name is required"
}

Next Steps

• Organization API Resources — Work with appointments, products, companies, product limits, and locations.
• Organization API Purchase Orders — Create orders, assign warehouses, and track booked appointments.
• Authentication — Get an API token and review authentication examples.

For help with your integration, contact support@datadocks.com.