> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Towbook as a data source

> Bring calls, invoices, payments, impounds, drivers, trucks and customer accounts from Towbook to Nekt.

Towbook is towing and roadside dispatch management software: calls (jobs) taken by dispatchers, drivers and trucks sent to them, impounded vehicles, the customer accounts calls are billed to, invoices and payments. This connector reads Towbook's API and brings the call history with its invoice data, the payments, the calls and impounds open right now, the deleted calls, and the setup you need to read them: companies (locations), drivers, trucks, users, customer accounts, rate items and call reasons.

> [!NOTE]
>
> The connector only reads data. It never creates, changes or deletes anything in Towbook.

## Configuring Towbook as a Source

In the [Sources](https://app.nekt.ai/sources) tab, click on the "Add source" button located on the top right of your screen. Then, select the Towbook option from the list of connectors.

Click **Next** and you'll be prompted to add your access.

### 1. Add account access

Towbook does not let you create API keys yourself: API access is turned on by **Towbook support**. Email [support@towbook.com](mailto:support@towbook.com) and ask for API access for your account. Towbook answers with either an **API token** or the **username and password of an API user**; either one works here. The connector sees what that user sees, so ask for a manager-level user if you want the invoice and payment exports (Towbook reports are usually limited to managers).

The following configurations are available:

* **API Token**: The API token Towbook support sent you. Fill either this field, or Username and Password.
* **Username** and **Password**: The API user Towbook support created for you, when they sent a username and password instead of a token.
* **Start Date**: The earliest date read by the **Call Accounting Export** and **Payments Export** tables. Every sync reads these two tables again from this date to today, so pick the date your analysis needs to start from.

Once you're done, click **Next**.

### 2. Select streams

Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis. You can select entire groups of streams or pick specific ones.

> Tip: The stream can be found more easily by typing its name.

Select the streams and click **Next**.

### 3. Configure data streams

Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.

* **Layer**: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
* **Folder**: a folder can be created inside the selected layer to group all tables being created from this new data source.
* **Table name**: we suggest a name, but feel free to customize it. You have the option to add a **prefix** to all tables at once and make this process faster!
* **Sync Type**: every Towbook stream is FULL\_TABLE: every time the extraction happens, we get the current state of the data. Towbook's API cannot tell which records changed since the last sync, so the tables are read in full each time.

Once you are done configuring, click **Next**.

### 4. Configure data source

Describe your data source for easy identification within your organization, not exceeding 140 characters.

To define your [Trigger](https://docs.nekt.com/runs/scheduling-and-triggers.md), consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times).

Optionally, you can configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource [here](https://docs.nekt.com/get-started/core-concepts/resource-control).

Once you are ready, click **Next** to finalize the setup.

### 5. Check your new source

You can view your new source on the [Sources](https://app.nekt.ai/sources) page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.

> [!WARNING]
>
> For you to be able to see it on your [Catalog](https://app.nekt.ai/catalog), you need at least one successful source run.

# Streams and Fields

## Available streams

The table below lists every stream, its **slug** (the exact identifier to pass when creating the source via API) and a short description.

| Stream | Slug | Description |
| - | - | - |
| Call Accounting Export | `call_accounting_export` | Call history with invoice data (Towbook's Accounting Software Export), since the Start Date. |
| Payments Export | `payments_export` | Payments (Towbook's Export Payments export), since the Start Date. |
| Active Calls | `active_calls` | Calls open on the dispatch board right now. |
| Active Impounds | `active_impounds` | Vehicles in impound right now. |
| Deleted Calls | `deleted_calls` | Calls deleted in Towbook. |
| Companies | `companies` | Towbook companies (locations) the credential can see. |
| Drivers | `drivers` | Drivers. |
| Trucks | `trucks` | Trucks of the fleet, with their full details. |
| Users | `users` | Towbook users. |
| Accounts | `accounts` | Customer accounts calls are billed to. |
| Rate Items | `rate_items` | Priced services and charges used on invoices. |
| Reasons | `reasons` | Call reasons. |

### What to know about the tables

* **Call history comes from the exports.** Towbook's API only lists the calls and impounds that are open right now, so **Active Calls** and **Active Impounds** show the current picture: a completed call leaves Active Calls on the next sync. For past calls, invoices and payments, use **Call Accounting Export** and **Payments Export**.
* **Export columns are kept as JSON.** The columns of Towbook's exports depend on your account's export settings, so each exported line is loaded whole in `row_data`, as a JSON object of column name to value, exactly as Towbook exports it (amounts and dates stay as text). Read a column with your warehouse's JSON functions, for example `json_extract_scalar(row_data, '$["Call #"]')`. The `row_id` column only numbers the lines of each sync: it changes from one sync to the next, so never use it to join or track a line; use the export's own columns (call or invoice number) instead.
* **A month Towbook cannot export stops the sync of that table.** If Towbook answers a month of an export with something that is not a table (an empty answer or an error), the connector tries again; if it keeps happening, that table is not updated in the sync (your previous data stays) and the message names the month. Months before your company used Towbook are simply taken as months without activity, with a message listing them. If an export comes back without a single line for every month since the Start Date, or with different columns in different months, that table is also not updated and the message says why (an export that is always empty usually means the Towbook API user cannot run reports). If your company does not record payments in Towbook, the **Payments Export** is always empty: deselect that table.
* **Lines of the first day of a month may appear twice in the exports.** Each month is asked including the day where the next month starts, so that no day is ever missed. The connector removes those repeated lines when the export has a column with the date its report is filtered on (the payment date for payments, the call date for calls). If it does not, the sync shows a message saying that lines of the first day of a month may appear twice; when summing amounts, count each call or payment number once.
* **Every other table keeps the full record.** Besides its columns, each row of the other tables has `raw_data`: the whole record as Towbook returned it, including fields without a column of their own.
* **Times are your company's local time.** Towbook sends times without a time zone; they are loaded as Towbook shows them.
* **Permissions.** If the Towbook user cannot read a table (for example the exports, when the user is not a manager), that table is skipped in the sync with a message naming it, and the other tables keep syncing.

## Fields by stream

### Calls and invoices

> [accordion] Call Accounting Export
>
> Call history with invoice data, from Towbook's Accounting Software Export, one row per exported line, month by month since the Start Date. The columns of the export are kept in row\_data (header to value, exactly as exported).
>
> Table: `call_accounting_export` · Primary key: `row_id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `row_id` | String | Positional identifier of the row in this sync: the first day of its month window and its position in that month's export. Unique within a sync, but not stable across syncs; do not use it to join or track a row. |
> | `window_start` | Date | First day of the date range (month) the row was exported for (the dateStart sent to Towbook). |
> | `window_end` | Date | Last day of the date range the row was exported for (the dateEnd sent to Towbook: the next month's first day, or tomorrow for the current month). |
> | `row_number` | Integer | Position of the row in that month's export (1-based). |
> | `export_format` | String | Format Towbook answered the export in (csv, xlsx or json). |
> | `row_data` | String (JSON) | The exported row as a JSON object: column header -> value, exactly as Towbook exported it. |

> [accordion] Payments Export
>
> Payments from Towbook's Export Payments export, one row per exported line, month by month since the Start Date. The columns of the export are kept in row\_data.
>
> Table: `payments_export` · Primary key: `row_id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `row_id` | String | Positional identifier of the row in this sync: the first day of its month window and its position in that month's export. Unique within a sync, but not stable across syncs; do not use it to join or track a row. |
> | `window_start` | Date | First day of the date range (month) the row was exported for (the dateStart sent to Towbook). |
> | `window_end` | Date | Last day of the date range the row was exported for (the dateEnd sent to Towbook: the next month's first day, or tomorrow for the current month). |
> | `row_number` | Integer | Position of the row in that month's export (1-based). |
> | `export_format` | String | Format Towbook answered the export in (csv, xlsx or json). |
> | `row_data` | String (JSON) | The exported row as a JSON object: column header -> value, exactly as Towbook exported it. |

> [accordion] Active Calls
>
> Calls currently open on the dispatch board. A call leaves this table once it is completed or cancelled in Towbook; use the Call Accounting Export for the history.
>
> Table: `active_calls` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | Integer | Unique identifier of the call in Towbook. |
> | `call_number` | String | Call number shown to users in Towbook. |
> | `type` | Integer | Towbook call type code (numeric as Towbook stores it). |
> | `company_id` | Integer | Identifier of the Towbook company (location) that owns the call (joins companies.id). |
> | `status_id` | Integer | Identifier of the call's dispatch status. |
> | `status_name` | String | Name of the call's dispatch status (e.g. Waiting, Dispatched, En Route, Completed). |
> | `priority` | Integer | Priority of the call (numeric as Towbook stores it). |
> | `account_id` | Integer | Identifier of the account the call is billed to (joins accounts.id). |
> | `account_name` | String | Name of the account the call is billed to. |
> | `reason_id` | Integer | Identifier of the call reason (joins reasons.id). |
> | `reason_name` | String | Name of the call reason. |
> | `owner_id` | Integer | Identifier of the Towbook user who owns (created) the call. |
> | `owner_name` | String | Name of the Towbook user who owns (created) the call. |
> | `impound` | Boolean | Whether the vehicle of the call is impounded. |
> | `create_date` | Datetime | When the call was created; company local time. |
> | `notes` | String | Call notes. |
> | `purchase_order_number` | String | Purchase order (PO) number of the call. |
> | `invoice_number` | String | Invoice number of the call. |
> | `invoice_subtotal` | Number | Invoice subtotal (before tax). |
> | `invoice_tax` | Number | Invoice tax amount. |
> | `invoice_total` | Number | Invoice total. |
> | `balance_due` | Number | Amount of the invoice still unpaid. |
> | `tow_source` | String | Pickup location of the call. |
> | `tow_destination` | String | Destination of the call. |
> | `contacts` | String (JSON) | Contacts of the call: name, phone, email, address (JSON array of objects). |
> | `waypoints` | String (JSON) | Waypoints of the call: pickup, destination, with address and coordinates (JSON array of objects). |
> | `invoice_items` | String (JSON) | Invoice lines: rate item, price, quantity (JSON array of objects). |
> | `attributes` | String (JSON) | Custom call attributes as attribute id / value pairs (JSON array of objects). |
> | `assets` | String (JSON) | Vehicles of the call with make, model, VIN, plate and the drivers/trucks assigned (JSON array of objects). |
> | `groups` | String (JSON) | Dispatch groups of the call (JSON array). |
> | `raw_data` | String (JSON) | The whole record exactly as Towbook returned it (JSON object), including fields that have no column of their own. |

> [accordion] Active Impounds
>
> Vehicles currently in impound. A vehicle leaves this table once it is released.
>
> Table: `active_impounds` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | Integer | Unique identifier of the impound in Towbook. |
> | `call_number` | String | Call number shown to users in Towbook. |
> | `type` | Integer | Towbook call type code (numeric as Towbook stores it). |
> | `company_id` | Integer | Identifier of the Towbook company (location) that owns the call (joins companies.id). |
> | `status_id` | Integer | Identifier of the call's dispatch status. |
> | `status_name` | String | Name of the call's dispatch status (e.g. Waiting, Dispatched, En Route, Completed). |
> | `priority` | Integer | Priority of the call (numeric as Towbook stores it). |
> | `account_id` | Integer | Identifier of the account the call is billed to (joins accounts.id). |
> | `account_name` | String | Name of the account the call is billed to. |
> | `reason_id` | Integer | Identifier of the call reason (joins reasons.id). |
> | `reason_name` | String | Name of the call reason. |
> | `owner_id` | Integer | Identifier of the Towbook user who owns (created) the call. |
> | `owner_name` | String | Name of the Towbook user who owns (created) the call. |
> | `impound` | Boolean | Whether the vehicle of the call is impounded. |
> | `create_date` | Datetime | When the call was created; company local time. |
> | `notes` | String | Call notes. |
> | `purchase_order_number` | String | Purchase order (PO) number of the call. |
> | `invoice_number` | String | Invoice number of the call. |
> | `invoice_subtotal` | Number | Invoice subtotal (before tax). |
> | `invoice_tax` | Number | Invoice tax amount. |
> | `invoice_total` | Number | Invoice total. |
> | `balance_due` | Number | Amount of the invoice still unpaid. |
> | `tow_source` | String | Pickup location of the call. |
> | `tow_destination` | String | Destination of the call. |
> | `contacts` | String (JSON) | Contacts of the call: name, phone, email, address (JSON array of objects). |
> | `waypoints` | String (JSON) | Waypoints of the call: pickup, destination, with address and coordinates (JSON array of objects). |
> | `invoice_items` | String (JSON) | Invoice lines: rate item, price, quantity (JSON array of objects). |
> | `attributes` | String (JSON) | Custom call attributes as attribute id / value pairs (JSON array of objects). |
> | `assets` | String (JSON) | Vehicles of the call with make, model, VIN, plate and the drivers/trucks assigned (JSON array of objects). |
> | `groups` | String (JSON) | Dispatch groups of the call (JSON array). |
> | `raw_data` | String (JSON) | The whole record exactly as Towbook returned it (JSON object), including fields that have no column of their own. |

> [accordion] Deleted Calls
>
> Calls deleted in Towbook.
>
> Table: `deleted_calls` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | Integer | Unique identifier of the deleted call in Towbook. |
> | `call_number` | String | Call number shown to users in Towbook. |
> | `type` | Integer | Towbook call type code (numeric as Towbook stores it). |
> | `company_id` | Integer | Identifier of the Towbook company (location) that owns the call (joins companies.id). |
> | `status_id` | Integer | Identifier of the call's dispatch status. |
> | `status_name` | String | Name of the call's dispatch status (e.g. Waiting, Dispatched, En Route, Completed). |
> | `priority` | Integer | Priority of the call (numeric as Towbook stores it). |
> | `account_id` | Integer | Identifier of the account the call is billed to (joins accounts.id). |
> | `account_name` | String | Name of the account the call is billed to. |
> | `reason_id` | Integer | Identifier of the call reason (joins reasons.id). |
> | `reason_name` | String | Name of the call reason. |
> | `owner_id` | Integer | Identifier of the Towbook user who owns (created) the call. |
> | `owner_name` | String | Name of the Towbook user who owns (created) the call. |
> | `impound` | Boolean | Whether the vehicle of the call is impounded. |
> | `create_date` | Datetime | When the call was created; company local time. |
> | `notes` | String | Call notes. |
> | `purchase_order_number` | String | Purchase order (PO) number of the call. |
> | `invoice_number` | String | Invoice number of the call. |
> | `invoice_subtotal` | Number | Invoice subtotal (before tax). |
> | `invoice_tax` | Number | Invoice tax amount. |
> | `invoice_total` | Number | Invoice total. |
> | `balance_due` | Number | Amount of the invoice still unpaid. |
> | `tow_source` | String | Pickup location of the call. |
> | `tow_destination` | String | Destination of the call. |
> | `contacts` | String (JSON) | Contacts of the call: name, phone, email, address (JSON array of objects). |
> | `waypoints` | String (JSON) | Waypoints of the call: pickup, destination, with address and coordinates (JSON array of objects). |
> | `invoice_items` | String (JSON) | Invoice lines: rate item, price, quantity (JSON array of objects). |
> | `attributes` | String (JSON) | Custom call attributes as attribute id / value pairs (JSON array of objects). |
> | `assets` | String (JSON) | Vehicles of the call with make, model, VIN, plate and the drivers/trucks assigned (JSON array of objects). |
> | `groups` | String (JSON) | Dispatch groups of the call (JSON array). |
> | `raw_data` | String (JSON) | The whole record exactly as Towbook returned it (JSON object), including fields that have no column of their own. |

### Fleet, people and setup

> [accordion] Companies
>
> Towbook companies (locations) the credential can see.
>
> Table: `companies` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | Integer | Unique identifier of the company in Towbook. |
> | `name` | String | Company name. |
> | `short_name` | String | Short display name of the company. |
> | `address` | String | Street address of the company. |
> | `city` | String | City of the company. |
> | `state` | String | State or province of the company. |
> | `zip` | String | ZIP / postal code of the company. |
> | `country` | String | Country of the company. |
> | `latitude` | Number | Latitude of the company address. |
> | `longitude` | Number | Longitude of the company address. |
> | `timezone_offset` | Integer | Time zone offset of the company as Towbook stores it (hours, relative to Towbook's reference zone). |
> | `timezone_use_dst` | Boolean | Whether the company's time zone observes daylight saving time. |
> | `raw_data` | String (JSON) | The whole record exactly as Towbook returned it (JSON object), including fields that have no column of their own. |

> [accordion] Drivers
>
> Drivers registered in Towbook.
>
> Table: `drivers` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | Integer | Unique identifier of the driver in Towbook. |
> | `name` | String | Full name of the driver. |
> | `linked_user_id` | Integer | Identifier of the Towbook user linked to the driver (joins users.id). |
> | `operate_heavy` | Boolean | Whether the driver is qualified to operate heavy-duty trucks. |
> | `end_date` | Datetime | Date the driver stopped working for the company (empty while active); company local time. |
> | `company_id` | Integer | Identifier of the Towbook company (location) the record belongs to. |
> | `companies` | Array of integers | Identifiers of every Towbook company the driver works for. |
> | `create_date` | Datetime | When the driver was created in Towbook; company local time. |
> | `phone` | String | Phone number of the driver. |
> | `raw_data` | String (JSON) | The whole record exactly as Towbook returned it (JSON object), including fields that have no column of their own. |

> [accordion] Trucks
>
> Trucks of the fleet, with their full details.
>
> Table: `trucks` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | Integer | Unique identifier of the truck in Towbook. |
> | `name` | String | Name (unit number) of the truck. |
> | `type` | Integer | Towbook truck type code (e.g. flatbed, wrecker; numeric as Towbook stores it). |
> | `duty` | Integer | Towbook duty class code of the truck (light, medium, heavy; numeric as Towbook stores it). |
> | `make` | String | Truck manufacturer. |
> | `model` | String | Truck model. |
> | `company_id` | Integer | Identifier of the Towbook company (location) the record belongs to. |
> | `raw_data` | String (JSON) | The whole record exactly as Towbook returned it (JSON object), including fields that have no column of their own. |

> [accordion] Users
>
> Towbook users (managers, dispatchers, drivers, accountants). Passwords are never loaded.
>
> Table: `users` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | Integer | Unique identifier of the user in Towbook. |
> | `username` | String | Login name of the user. |
> | `full_name` | String | Full name of the user. |
> | `email` | String | Email address of the user. |
> | `type` | Integer | Towbook user role code (e.g. manager, dispatcher, driver; numeric as Towbook stores it). |
> | `disabled` | Boolean | Whether the user is disabled (can no longer sign in). |
> | `company_id` | Integer | Identifier of the Towbook company (location) the record belongs to. |
> | `raw_data` | String (JSON) | The whole record exactly as Towbook returned it (JSON object), including fields that have no column of their own. |

> [accordion] Accounts
>
> Customer accounts (motor clubs, police, dealers, private customers) that calls are billed to.
>
> Table: `accounts` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | Integer | Unique identifier of the account in Towbook (joins calls.account\_id). |
> | `name` | String | Account (customer) name. |
> | `company_id` | Integer | Identifier of the Towbook company (location) the record belongs to. |
> | `raw_data` | String (JSON) | The whole record exactly as Towbook returned it (JSON object), including fields that have no column of their own. |

> [accordion] Rate Items
>
> Priced services and charges used on call invoices (tow, mileage, storage...).
>
> Table: `rate_items` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | Integer | Unique identifier of the rate item in Towbook (joins the rateItemId of call invoice items). |
> | `name` | String | Name of the rate item (service or charge). |
> | `company_id` | Integer | Identifier of the Towbook company (location) the record belongs to. |
> | `raw_data` | String (JSON) | The whole record exactly as Towbook returned it (JSON object), including fields that have no column of their own. |

> [accordion] Reasons
>
> Call reasons (accident, breakdown, impound...).
>
> Table: `reasons` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | Integer | Unique identifier of the reason in Towbook (joins calls.reason\_id). |
> | `name` | String | Name of the reason. |
> | `company_id` | Integer | Identifier of the Towbook company (location) the record belongs to. |
> | `raw_data` | String (JSON) | The whole record exactly as Towbook returned it (JSON object), including fields that have no column of their own. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.