The connector only reads data. It never creates, changes or deletes anything in Towbook.
Configuring Towbook as a Source
In the 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 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.
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.
4. Configure data source
Describe your data source for easy identification within your organization, not exceeding 140 characters. To define your Trigger, 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. Once you are ready, click Next to finalize the setup.5. Check your new source
You can view your new source on the Sources page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.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.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 examplejson_extract_scalar(row_data, '$["Call #"]'). Therow_idcolumn 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
Call Accounting Export
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 tablePayments Export
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 tableActive Calls
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 tableActive Impounds
Active Impounds
Vehicles currently in impound. A vehicle leaves this table once it is released.Table:
active_impounds · Primary key: id · Sync: Full tableDeleted Calls
Deleted Calls
Calls deleted in Towbook.Table:
deleted_calls · Primary key: id · Sync: Full tableFleet, people and setup
Companies
Companies
Towbook companies (locations) the credential can see.Table:
companies · Primary key: id · Sync: Full tableDrivers
Drivers
Drivers registered in Towbook.Table:
drivers · Primary key: id · Sync: Full tableTrucks
Trucks
Trucks of the fleet, with their full details.Table:
trucks · Primary key: id · Sync: Full tableUsers
Users
Towbook users (managers, dispatchers, drivers, accountants). Passwords are never loaded.Table:
users · Primary key: id · Sync: Full tableAccounts
Accounts
Customer accounts (motor clubs, police, dealers, private customers) that calls are billed to.Table:
accounts · Primary key: id · Sync: Full tableRate Items
Rate Items
Priced services and charges used on call invoices (tow, mileage, storage…).Table:
rate_items · Primary key: id · Sync: Full tableReasons
Reasons
Call reasons (accident, breakdown, impound…).Table:
reasons · Primary key: id · Sync: Full table