The DOTS Public API allows you to securely retrieve up-to-date information about your employees, assets, locations, warehouses, orders, and credits.

Connect Dots with your HR, IT service management (ITSM), finance, procurement, or inventory tools to automate reporting, track equipment, monitor orders, and access operational information without manually checking your Dots dashboard.

The API is read-only, returning structured JSON responses. API requests cannot create, edit, cancel, or approve records, or change information in your dashboard.

1. Available API Endpoints

Base URL

https://dots-public-api.dotstech.com/api/v1

All endpoints use the GET method.

Category	Endpoint	Description
Employees	`GET /company-staff?email={EMAIL}`	Employee information and assigned asset IDs
Assets	`GET /asset/{ASSET_ID}`	Asset information by Dots ID
Assets	`GET /asset/{SERIAL_NUMBER}`	Asset information by serial number
Locations	`GET /location`	Office locations and stored assets
Warehouses	`GET /warehouse`	Available warehouses and asset counts
Warehouses	`GET /warehouse/{WAREHOUSE_ID}/assets`	Assets stored in a specific warehouse
Orders — New	`GET /orders`	Orders with filtering and pagination
Orders — New	`GET /orders/{ORDER_ID}`	Detailed information about one order
Orders — New	`GET /orders/{ORDER_ID}/status-log`	Order status history and progress
Orders — New	`GET /orders/{ORDER_ID}/confirmation-forms`	Employee delivery and pickup confirmation forms
Credits — New	`GET /credits`	Current company credit balance
Credits — New	`GET /credits/logs`	Credit purchase, usage, and transaction history

Important: Your API key determines which company's information you can access. All responses are limited to your organization's data.

2. Authentication

Every API request requires an API key.

To generate your API key:

Log in to your Dots Client Dashboard.
Navigate to Settings → API Access.
Generate or retrieve your API key.
Include the key in every API request.

Required request header
authorization: YOUR_API_KEY

Pass the API key directly, without adding Bearer or another prefix.

Example request


curl "https://dots-public-api.dotstech.com/api/v1/orders" \
  -H "authorization: YOUR_API_KEY"
You do not need to provide your company ID.

Keep your API key confidential and store it securely in your integration environment.

3. Employees & Assets

3.1 Get Employee Details

Endpoint

GET /api/v1/company-staff?email={EMPLOYEE_EMAIL}

Retrieve information about an employee using their email address.

The response includes personal and employment information available in Dots, along with the IDs of assets currently assigned to the employee.

Example response


{
  "id": "5bd9d28f-13cb-4f64-98cb-3b3e6219cccc",
  "email": "jane.doe@example.com",
  "phone": "+15551234567",
  "fullName": "Jane Doe",
  "status": "EMPLOYED",
  "wasOffboarded": false,
  "wasOnboarded": true,
  "role": {
    "name": "Head of R&D"
  },
  "team": {
    "name": "R&D"
  },
  "addressInfo": {
    "address": "Eliezer Kaplan Street 2, Tel Aviv-Yafo, Israel",
    "addressLine2": null,
    "addressAdditionalInfo": "2nd floor",
    "zipCode": "0432",
    "country": {
      "name": "Israel",
      "alphaCode2": "IL"
    },
    "city": {
      "name": "Tel Aviv-Yafo"
    },
    "state": {
      "name": null
    }
  },
  "assetsId": [
    "b16fea6a-e935-4d31-a508-8e4005c9ad27",
    "7c08e001-1fe8-4e88-8d71-ae8c598392ce"
  ]
}

Common use cases

Match employees to their assigned IT equipment.
Synchronize asset ownership with HR or ITSM systems.
Retrieve an employee's assigned asset IDs for further API lookups.
Support automated onboarding and offboarding reporting.

3.2 Get Asset Details

Endpoint

GET /api/v1/asset/{ASSET_ID}

Retrieve detailed information about a specific asset using its Dots asset ID.

Example response


{
  "id": "0ac8facb-a822-4557-ae17-346a20644018",
  "name": "Jane's MacBook",
  "model": "MacBook Air (13-inch, M4, 2024)",
  "condition": "USED",
  "serialNumber": "SDKSMW820",
  "diskEncryption": "No disc encryption",
  "purchaseDate": "2025-11-03T00:00:00.000Z",
  "status": "IN_USE",
  "dpn": "CS-NT-APL-2445-0024",
  "application": "[{\"name\":\"Activity Monitor\",\"version\":\"10.14\"}]",
  "keyboardLanguage": "UK ENGLISH",
  "productCode": "Z1600076U",
  "ipAddress": "192.168.0.10",
  "notes": "Asset note",
  "sku": null,
  "price": 100,
  "image": "https://example.com/image.png",
  "warrantyUntil": "2027-11-25T00:00:00.000Z",
  "assignee": {
    "fullName": "Jane Doe",
    "email": "jane.doe@example.com"
  },
  "os": {
    "name": "Mac",
    "version": "15.7.2"
  },
  "brand": {
    "name": "Apple"
  },
  "subcategory": {
    "name": "Notebooks & Laptops"
  },
  "category": {
    "name": "Computer systems"
  }
}

The application field can contain a JSON-encoded string representing installed applications reported by your MDM integration. Parse the string to retrieve its application records.

Fields without available information may return null.

3.3 Get Asset by Serial Number

Endpoint

GET /api/v1/asset/{SERIAL_NUMBER}

Retrieve asset information using its serial number instead of its Dots asset ID.

The response contains the same asset details described above.

This endpoint is useful when your internal inventory or MDM system identifies assets primarily by serial number.

3.4 Asset Status Values

The API returns the asset's current lifecycle status.

Status	Meaning
`PENDING`	The asset is expected but has not yet been received or assigned
`IN_USE`	The asset is assigned to an employee
`IN_STORAGE`	The asset is stored in a Dots warehouse or company office
`IN_TRANSIT`	The asset is being shipped
`ARCHIVED`	The asset has been archived

Note: IN_TRANSIT is available when retrieving asset details by Dots asset ID.

4. Locations & Warehouses

4.1 Get Locations

Endpoint

GET /api/v1/location

Retrieve your organization's office locations and the assets associated with each location.

Example response


[
  {
    "id": "location_id",
    "name": "Berlin Office",
    "country": "Germany",
    "region": "Europe",
    "city": "Berlin",
    "assetsCount": 8,
    "assets": [
      "asset_uuid_1",
      "asset_uuid_2",
      "asset_uuid_3"
    ],
    "spaces": [
      {
        "id": "space_uuid_1",
        "name": "Floor 1"
      }
    ]
  }
]

4.2 Get Warehouses

Endpoint

GET /api/v1/warehouse

Retrieve the warehouses storing your organization's assets and their corresponding asset counts.

Example response


[
  {
    "id": "warehouse_id",
    "name": "London Warehouse",
    "country": "United Kingdom",
    "assetsCount": 1947
  }
]

4.3 Get Warehouse Assets

Endpoint

GET /api/v1/warehouse/{WAREHOUSE_ID}/assets

Retrieve the assets currently stored in a particular warehouse.

Example response


{
  "id": "warehouse_id",
  "name": "London Warehouse",
  "country": "United Kingdom",
  "assetsCount": 590,
  "assets": [
    "asset_id_1",
    "asset_id_2",
    "asset_id_3"
  ]
}

These endpoints can support regional inventory reporting, warehouse-level reconciliation, and visibility into equipment stored across multiple locations.

5. Orders — New

The Orders API lets you retrieve your Dots orders directly into your own systems.

Use it to monitor order progress, track shipments, connect orders to employee records, and review the confirmation process associated with employee deliveries and collections.

5.1 Which Orders Are Available?

The Orders API supports:

Delivery orders
Purchase orders
Stocking orders
Onboarding orders
Offboarding orders

Orders are included regardless of their current status, including canceled, dismissed, expired, and completed orders.

Excluded orders

Draft orders that have not yet been submitted
Deleted orders

Financial data is excluded from the Orders API. Order responses do not include prices, taxes, totals, credit usage, budgets, invoices, payment details, commercial offers, or internal Dots notes.

5.2 List Orders

Endpoint

GET /api/v1/orders

Retrieve your company's orders, sorted by newest first.

The endpoint supports optional filters and pagination.

Available query parameters

Parameter	Description	Example
`page`	Page number, starting at 1. Default: 1	`page=2`
`limit`	Orders per page. Default: 20, maximum: 100	`limit=50`
`search`	Case-insensitive partial search by dashboard order number or custom order name	`search=087d`
`employeeEmail`	Orders involving a specific employee	`employeeEmail=jane.doe@example.com`
`employeeId`	Same employee filter, using the Dots employee ID	`employeeId=EMPLOYEE_ID`
`status`	Filter by one or more order statuses	`status=SHIPPING`
`type`	Filter by `DELIVERY` or `PURCHASE`	`type=PURCHASE`
`subtype`	Filter by `DELIVERY`, `PURCHASE`, `STOCKING`, `ONBOARDING`, or `OFFBOARDING`	`subtype=OFFBOARDING`

The employee filter includes orders where the employee is receiving equipment, having equipment collected, or is designated as the future owner.

Use either employeeEmail or employeeId, not both.

Combining filters

Multiple filters can be combined in the same request.

To search for multiple values of a parameter, repeat that parameter instead of providing comma-separated values.

Example: Find an employee's offboarding orders that are awaiting collection or in transit


curl "https://dots-public-api.dotstech.com/api/v1/orders?employeeEmail=jane.doe@example.com&subtype=OFFBOARDING&status=PICKING_UP&status=SHIPPING" \
  -H "authorization: YOUR_API_KEY"

If no employee matches the supplied email, the API returns an empty order list rather than an error.

Example response


{
  "result": [
    {
      "id": "087d1736-6e0e-40df-b890-53aef026e8c9",
      "name": "#087d1736",
      "customOrderName": "Offboarding - Jane Doe",
      "type": "DELIVERY",
      "subtype": "OFFBOARDING",
      "status": "DELIVERED",
      "createdAt": "2026-06-21T07:53:12.359Z",
      "updatedAt": "2026-09-23T19:04:42.946Z",
      "onboardingDate": null,
      "offboardingDate": "2026-07-17",
      "futureOwner": null,
      "pickUp": {
        "employee": {
          "id": "36165cc0-ef70-42b5-8612-4ee3c9b5bc86",
          "fullName": "Jane Doe",
          "email": "jane.doe@example.com"
        },
        "office": null,
        "warehouse": null,
        "address": {
          "country": "United States",
          "state": null,
          "city": "Salt Lake City",
          "zipCode": "84102",
          "details": null
        }
      },
      "delivery": {
        "employee": null,
        "office": null,
        "warehouse": {
          "id": "287d06fc-e92f-4994-b87c-d42221484115",
          "name": "USA - Dots' warehouse"
        },
        "address": {
          "country": "United States",
          "state": null,
          "city": null,
          "zipCode": null,
          "details": null
        },
        "trackingNumber": null,
        "trackingLink": null,
        "deliveryStartDate": "2026-06-21",
        "deliveryEndDate": null,
        "deliveryDate": null
      },
      "products": [],
      "assets": [
        {
          "id": "d01c5b71-21cb-4102-84e7-4cf17cb41af8",
          "assetId": "d93961ec-5a31-4206-bc64-0b821fbfadeb",
          "name": "MacBook Pro M4",
          "brand": "Apple",
          "model": null,
          "sku": null,
          "serialNumber": "36523652"
        }
      ]
    }
  ],
  "totalCount": 1
}

Understanding pagination

result contains the orders returned for the requested page.
totalCount represents the total number of matching orders across all pages.

5.3 Get Order Details

Endpoint

GET /api/v1/orders/{ORDER_ID}

Retrieve the complete available information for one order.

The response uses the same structure as an individual order returned by GET /orders.

Example request


curl "https://dots-public-api.dotstech.com/api/v1/orders/31dbd4d7-c1e7-4329-83c7-f56929e5a919" \
  -H "authorization: YOUR_API_KEY"

Example: Purchase order in transit


{
  "id": "31dbd4d7-c1e7-4329-83c7-f56929e5a919",
  "name": "#31dbd4d7",
  "customOrderName": "New hire monitors",
  "type": "PURCHASE",
  "subtype": "PURCHASE",
  "status": "SHIPPING",
  "createdAt": "2024-11-15T08:19:03.872Z",
  "updatedAt": "2026-09-24T04:00:02.936Z",
  "onboardingDate": null,
  "offboardingDate": null,
  "futureOwner": {
    "id": "57fdecb2-cac9-4213-b3fd-4b6a96039214",
    "fullName": "John Smith",
    "email": "john.smith@example.com"
  },
  "pickUp": null,
  "delivery": {
    "employee": {
      "id": "57fdecb2-cac9-4213-b3fd-4b6a96039214",
      "fullName": "John Smith",
      "email": "john.smith@example.com"
    },
    "office": null,
    "warehouse": null,
    "address": {
      "country": "Germany",
      "state": "Berlin",
      "city": "Berlin",
      "zipCode": "10115",
      "details": null
    },
    "trackingNumber": "1Z999AA10123456784",
    "trackingLink": "https://www.ups.com/track?tracknum=1Z999AA10123456784",
    "deliveryStartDate": "2024-11-15",
    "deliveryEndDate": "2024-11-16",
    "deliveryDate": null
  },
  "products": [
    {
      "id": "583fbf6d-038f-47d1-8e42-c95cb3405e9a",
      "productId": "fae656ef-f9c4-4f9f-b09a-fc09d33cf0f8",
      "name": "DELL UltraSharp 27 USB-C Hub Monitor - U2722DE",
      "brand": "Dell",
      "model": null,
      "sku": null,
      "quantity": 1
    }
  ],
  "assets": [
    {
      "id": "c6c66fbf-6dc8-4099-8ff2-f20064a6a2fa",
      "assetId": "70831404-bf49-451d-ad4c-24226a03a55b",
      "name": "DELL UltraSharp 27 USB-C Hub Monitor - U2722DE",
      "brand": "Dell",
      "model": null,
      "sku": null,
      "serialNumber": null
    }
  ]
}

General order fields

Field	Description
`id`	Unique Dots order ID
`name`	Order number displayed in the dashboard
`customOrderName`	Custom order name, when provided
`type`	`DELIVERY` or `PURCHASE`
`subtype`	Delivery, purchase, stocking, onboarding, or offboarding
`status`	Current order status
`createdAt`	Order creation timestamp
`updatedAt`	Most recent update timestamp
`onboardingDate`	Employee's onboarding date, when relevant
`offboardingDate`	Employee's offboarding date, when relevant
`futureOwner`	Employee who will receive ownership of the equipment

Creation and update timestamps use ISO 8601 in UTC. Onboarding and offboarding dates use YYYY-MM-DD.

Delivery information

The delivery object identifies where the equipment is going.

Field	Description
`employee`	Employee receiving the shipment
`office`	Destination company office
`warehouse`	Destination warehouse
`address`	Destination country, state, city, ZIP code, and additional details
`trackingNumber`	Shipment tracking number, when available
`trackingLink`	Shipment tracking URL, when available
`deliveryStartDate`	Start of the estimated delivery window
`deliveryEndDate`	End of the estimated delivery window
`deliveryDate`	Actual delivery date, when available

Typically, only one destination type—employee, office, or warehouse—is populated.

Pickup information

The pickUp object identifies where the equipment is collected from or shipped from.

It includes the corresponding employee, office, warehouse, and address information.

For example, pickup information can be available on offboarding orders or onboarding orders originating from a Dots warehouse.

The object is null when no pickup information applies.

Products and assets

products identifies the products ordered in a purchase order, including product name, brand, model, SKU, and quantity.
assets identifies the physical assets included in an order, including the asset ID, name, brand, model, SKU, and serial number.

For purchase orders, the product information reflects the approved product when an alternative product was proposed and accepted.

Delivery orders may contain only assets, with an empty products list.

Use assets[].assetId with the Asset Details endpoint to retrieve more information about a specific asset.

Assets hidden in the dashboard are also excluded from order responses.

Missing information

Fields that have not yet been populated in Dots return null.

If an order does not exist, has been deleted, is still a draft, or belongs to another company, the endpoint returns 404 Not Found.

5.4 Order Status Values

The Orders API uses the following status codes.

API status	Dashboard label	Meaning
`PROCESSING`	Drafting Proposal	Dots is preparing the offer
`PENDING_OFFER`	Pending Approval	Waiting for client approval
`PICKING_UP`	Pending Collection	Equipment is awaiting collection
`PREPARING`	Processing	Order is being prepared
`SHIPPING`	In Transit	Shipment is on its way
`PARTIALLY_DELIVERED`	Partially Delivered	Some items have been delivered
`DELIVERED`	Delivered	All items have been delivered
`CONFIRMED`	Confirmed	Delivery has been confirmed
`PENDING_PAYMENT`	Pending payment	Waiting for payment
`COMPLETED`	Completed	Order is finished
`IN_DISPUTE`	In dispute	An issue or dispute is open
`CANCELED`	Canceled	Order was canceled
`DISMISSED`	Dismissed	Order was dismissed
`EXPIRED`	Expired Offer	Offer expired before approval

Use these status codes when filtering orders through GET /orders.

The status log endpoint, described next, returns the corresponding dashboard labels.

5.5 Get Order Status Log

Endpoint

GET /api/v1/orders/{ORDER_ID}/status-log

Retrieve an order's status timeline.

This includes completed stages, the current stage, and future stages, allowing you to monitor the order's progress without opening the Dots dashboard.

Example response: Order in transit


[
  {
    "status": "Drafting Proposal",
    "stage": "completed",
    "date": "2026-04-16T14:03:35.510Z",
    "changedBy": "John Smith"
  },
  {
    "status": "Pending Approval",
    "stage": "completed",
    "date": "2026-04-17T09:12:01.004Z",
    "changedBy": "Dots Admin"
  },
  {
    "status": "Processing",
    "stage": "completed",
    "date": "2026-04-18T10:00:00.000Z",
    "changedBy": "John Smith"
  },
  {
    "status": "In Transit",
    "stage": "current",
    "date": "2026-04-20T08:30:00.000Z",
    "changedBy": "System"
  },
  {
    "status": "Delivered",
    "stage": "pending",
    "date": null,
    "changedBy": null
  },
  {
    "status": "Confirmed",
    "stage": "pending",
    "date": null,
    "changedBy": null
  },
  {
    "status": "Pending payment",
    "stage": "pending",
    "date": null,
    "changedBy": null
  },
  {
    "status": "Completed",
    "stage": "pending",
    "date": null,
    "changedBy": null
  }
]

Response fields

Field	Description
`status`	Status label displayed in the Dots dashboard
`stage`	Whether the stage is completed, current, pending, or refused
`date`	Timestamp when the order reached this stage
`changedBy`	Person or system responsible for the status change

Stage values

completed — A stage the order has already passed.
current — The order's current stage.
pending — A stage that has not yet been reached.
refused — The order ended without completing its normal workflow, such as cancellation, dismissal, expiry, or dispute.

For pending stages, date and changedBy are null.

The changedBy value may contain an employee's name, email address, Dots Admin, Slack, or System.

5.6 Get Order Confirmation Forms

Endpoint

GET /api/v1/orders/{ORDER_ID}/confirmation-forms

Retrieve employee confirmation forms associated with an order.

When an employee is asked to confirm delivery information or equipment collection arrangements, Dots records the form's progress.

This endpoint provides visibility into whether the employee has received, opened, or completed their confirmation form.

It also exposes relevant confirmed information, such as the address, contact person, availability, and notes.

If no confirmation form was sent for the order, the API returns an empty array.

Example response


[
  {
    "id": "e4b1c2d3-0000-4a5b-9c8d-1234567890ab",
    "type": "PICK_UP",
    "status": "APPROVED",
    "step": "OVERVIEW",
    "createdAt": "2026-06-21T08:00:00.000Z",
    "expiresAt": "2026-06-28T08:00:00.000Z",
    "approvedAt": "2026-06-22T11:45:10.000Z",
    "approvedBy": "EMPLOYEE",
    "address": {
      "addressLine1": "100 Main Street",
      "addressLine2": "Apt 4",
      "country": "United States",
      "state": "Utah",
      "city": "Salt Lake City",
      "zipCode": "84102",
      "details": "Ring the bell twice"
    },
    "contactPerson": {
      "name": "Jane Doe",
      "phone": "+15551234567",
      "email": "jane.doe@example.com",
      "privateEmail": "jane.personal@example.com"
    },
    "taxId": null,
    "assetsNote": "Charger is missing",
    "availability": {
      "dateFrom": "2026-06-24",
      "dateTo": "2026-06-26",
      "redirectToDelegatedRecipient": false,
      "delegatedRecipient": null
    },
    "progress": [
      {
        "event": "SENT_EMAIL",
        "text": "...",
        "createdAt": "2026-06-21T08:00:01.000Z"
      },
      {
        "event": "OPENED",
        "text": "...",
        "createdAt": "2026-06-21T09:15:42.000Z"
      },
      {
        "event": "SUBMITTED",
        "text": "...",
        "createdAt": "2026-06-22T11:45:10.000Z"
      }
    ]
  }
]

Form type

Value	Meaning
`PICK_UP`	Equipment is being collected from the employee
`DELIVERY`	Equipment is being delivered to the employee

Form status

Value	Meaning
`PENDING`	Form sent but not opened
`VISITED`	Form opened but not submitted
`APPROVED`	Form submitted or confirmed
`EXPIRED`	Form expired

Form step

The step field indicates the latest form step reached.

Possible values:

NONE
ADDRESS_CONFIRMATION
ASSETS_INVENTORY
BOXES
YOUR_AVAILABILITY
OVERVIEW

Additional fields

Field	Description
`expiresAt`	Form expiry timestamp
`approvedAt`	Date and time the form was confirmed
`approvedBy`	Who confirmed the form
`address`	Confirmed address information
`contactPerson`	Contact information supplied in the form
`taxId`	Tax ID, where required
`assetsNote`	Notes about the employee's equipment
`availability`	Employee's availability or delegated collection arrangements
`progress`	Form activity and notification history

Approved-by values

EMPLOYEE — Confirmed by the employee.
COMPANY_ADMIN — Confirmed by your company administrator.
DOTS_ADMIN — Confirmed by the Dots team.
CRON — Confirmed automatically by the system.

Progress events

The progress array can contain the following events:

SENT_EMAIL
SENT_SMS
RESENT_EMAIL
FIRST_REMINDER_SENT
SECOND_REMINDER_SENT
FIRST_SMS_REMINDER_SENT
SECOND_SMS_REMINDER_SENT
OPENED
SUBMITTED
ESCALATED

Security note: Confirmation form links are not exposed through the Public API.

6. Credits — New

The Credits API lets you retrieve your company's credit balance and transaction history.

You can connect this data to your finance or reporting systems to monitor credit spending, reconcile purchases, and track credits used for Dots services.

The information corresponds to the Credits section of your Dots dashboard, including Credits → Transaction History.

These endpoints are available to Public API customers even if the Credits feature is not included in their plan.

Organizations that have never used credits receive a balance of zero and an empty transaction history.

6.1 Get Credit Balance

Endpoint

GET /api/v1/credits

Retrieve your company's current available credit balance.

Example request


curl "https://dots-public-api.dotstech.com/api/v1/credits" \
  -H "authorization: YOUR_API_KEY"

Example response


{
  "amount": 120
}

The amount field represents the current number of available credits.

It corresponds to the credit balance displayed in your Dots dashboard.

Common use cases

Display the current Dots credit balance in finance tools.
Monitor available credits.
Create an alert in your own system when the balance falls below a chosen threshold.
Support credit usage reporting.

6.2 Get Credit Transaction History

Endpoint

GET /api/v1/credits/logs

Retrieve your company's credit transaction history, including purchases, additions, removals, spending, and refunds.

The endpoint supports pagination, date filtering, and sorting.

Available query parameters

Parameter	Description	Example
`page`	Page number, starting at 1. Default: 1	`page=2`
`limit`	Records per page. Default: 10, maximum: 100	`limit=100`
`sortBy`	Sort by `date`, `action`, `creditsInOut`, `source`, `orderName`, or `comment`. Default: `date`	`sortBy=creditsInOut`
`sortOrder`	`DESC` (default) or `ASC`	`sortOrder=ASC`
`startDate`	Include transactions from this date onward, UTC	`startDate=2026-09-01`
`endDate`	Include transactions through this date, UTC	`endDate=2026-09-30`

Dates must use YYYY-MM-DD format.

The endDate filter includes the entire selected day.

Example: Retrieve September 2026 transactions


curl "https://dots-public-api.dotstech.com/api/v1/credits/logs?startDate=2026-09-01&endDate=2026-09-30&limit=100" \
  -H "authorization: YOUR_API_KEY"

Example response


{
  "result": [
    {
      "date": "2026-09-18T12:04:33.120Z",
      "action": "Used",
      "creditsInOut": "-12",
      "event": "Onboarding",
      "orderName": "#a5406585",
      "orderId": "a5406585-5083-44c8-8ac3-41c43e953f45",
      "orderType": "DELIVERY",
      "purchaseOrderNumber": null,
      "comment": null
    },
    {
      "date": "2026-09-02T08:00:00.000Z",
      "action": "Purchased",
      "creditsInOut": "+50",
      "event": "Purchase",
      "orderName": "-",
      "orderId": null,
      "orderType": null,
      "purchaseOrderNumber": "PO-2026-0917",
      "comment": null
    }
  ],
  "totalCount": 2
}

Transaction fields

Field	Description
`date`	Date and time of the transaction in UTC
`action`	Type of credit transaction
`creditsInOut`	Signed credit change, returned as text
`event`	Activity or service that generated the transaction
`orderName`	Related order number, when available
`orderId`	Related Dots order ID
`orderType`	`DELIVERY` or `PURCHASE`, when applicable
`purchaseOrderNumber`	Your purchase order number, when supplied
`comment`	Associated note or explanation
`totalCount`	Total matching transactions across all pages

Transaction action values

Action	Meaning
`Purchased`	Credits purchased by your company
`Added`	Credits added by the Dots team
`Removed`	Credits removed by the Dots team
`Used`	Credits spent on an order
`Refunded`	Credits returned following an order

Event values

Transaction events may include:

Dots Team
Purchase
Delivery
Warehousing (stocking)
Onboarding
Offboarding

The creditsInOut field is a string that includes the transaction direction:

"+50" indicates 50 credits added.
"-12" indicates 12 credits deducted.

When a transaction is not associated with an order, orderName returns "-" and orderId returns null.

Monthly reconciliation example

To retrieve a complete month's credit transactions:

Set startDate to the first day of the month.
Set endDate to the last day of the month.
Use limit=100 to reduce the number of API calls.
Request additional pages until all records in totalCount have been retrieved.

7. Pagination

The following endpoints support pagination:

GET /orders
GET /credits/logs

Both return responses using this structure:


{
  "result": [],
  "totalCount": 836
}

Pagination parameters

page — The page to retrieve, beginning with 1.
limit — The maximum number of records per page, up to 100.

totalCount represents the total number of matching records, not just the number included in the current response.

To calculate the total number of pages:

Total pages = round up (totalCount / limit)

For large data synchronizations, we recommend using limit=100 and retrieving subsequent pages as needed.

8. Error Handling

The API uses standard HTTP response codes.

Successful requests return JSON responses with the requested data.

Unsuccessful requests return a short explanation of the error.

Example: Validation error


{
  "error": "\"limit\" must be less than or equal to 100"
}

Example: Authentication error


{
  "message": "Unauthorized"
}

Code	Meaning	Recommended action
`200 OK`	Request completed successfully	Process the response
`400 Bad Request`	Invalid or missing parameters	Review request parameters
`401 Unauthorized`	Missing, invalid, or expired API key	Verify the authorization header and key
`404 Not Found`	Requested record not found or not available to your company	Verify the record ID and access
`429 Too Many Requests`	API rate limit exceeded	Wait until the applicable limit resets
`500 Internal Server Error`	Unexpected server-side error	Retry later or contact Dots support

Examples of 400 Bad Request include an invalid order status, limit greater than 100, startDate later than endDate, or providing both employeeEmail and employeeId.

For order endpoints, drafts and deleted orders also return 404 Not Found.

9. Rate Limits

To maintain stable API performance, Dots applies request limits at the organization level.

Rate limits apply to both:

Requests per minute.
Requests per day.

These limits use sliding windows:

Each request counts toward the per-minute limit for 60 seconds.
Each request counts toward the daily limit for 24 hours.

If a limit is exceeded, the API returns:

429 Too Many Requests

Rate Limit Response Headers

API responses include the following headers:

Header	Description
`x-ratelimit-limit-minute`	Maximum requests allowed per minute
`x-ratelimit-remaining-minute`	Remaining requests within the minute window
`x-ratelimit-reset-minute`	Reset timestamp for the minute window
`x-ratelimit-limit-day`	Maximum requests allowed per day
`x-ratelimit-remaining-day`	Remaining requests within the daily window
`x-ratelimit-reset-day`	Reset timestamp for the daily window

Reset timestamps are expressed as Unix timestamps in milliseconds.

Best Practices

Monitor the remaining request counters and slow down before reaching zero.
If you receive 429 Too Many Requests, wait until the relevant reset time before retrying.
Avoid repeatedly retrying during a rate-limit period. Requests made while exceeding the limit still count toward it.
Use pagination efficiently, including limit=100 where supported, when synchronizing large datasets.
Schedule recurring data retrieval according to your integration requirements rather than making unnecessary repeated requests.

10. Common Integration Use Cases

HR and IT asset visibility

Use the Employees and Assets endpoints to synchronize employee records and assigned equipment with your HR or ITSM platform.

Inventory reconciliation

Use Locations and Warehouses endpoints to retrieve equipment information across your offices and Dots warehouses.

Order tracking

Use the Orders endpoints to retrieve onboarding, offboarding, purchasing, stocking, or delivery orders. Monitor progress using the status history and shipment tracking fields.

Employee confirmation monitoring

Use the Confirmation Forms endpoint to identify whether employees have completed the required pickup or delivery confirmation process.

Credit monitoring and financial reporting

Use the Credits endpoints to retrieve available balances and transaction records, enabling credit consumption reporting and reconciliation.

11. Need Assistance?

If you have questions about the Dots Public API, authentication, data availability, or integration setup, contact our support team: support@dotstech.com

DOTS Public API – Getting Started Guide

1. Available API Endpoints

2. Authentication

3. Employees & Assets

3.1 Get Employee Details

3.2 Get Asset Details

3.3 Get Asset by Serial Number

3.4 Asset Status Values

4. Locations & Warehouses

4.1 Get Locations

4.2 Get Warehouses

4.3 Get Warehouse Assets

5. Orders — New

5.1 Which Orders Are Available?

5.2 List Orders

5.3 Get Order Details

5.4 Order Status Values

5.5 Get Order Status Log

5.6 Get Order Confirmation Forms

6. Credits — New

6.1 Get Credit Balance

6.2 Get Credit Transaction History

7. Pagination

8. Error Handling

9. Rate Limits

Rate Limit Response Headers

Best Practices

10. Common Integration Use Cases

11. Need Assistance?