TruDriveSync API — Staff Guide

TruDriveSync API — Staff Guide

This guide is written for someone who has never used an API before. It starts with what an API is in plain terms, walks you through making your first request with nothing but your browser and the built-in test screen, and then explains each part of the module in turn. If you already work with APIs, jump to the reference sections lower down.

1. What is an API, in plain terms?

An API is a way for another program to talk to your TruDriveSync data directly, without a person clicking around the admin screens. Think of the admin panel as the front door that people walk through, and the API as a service window other software can use to ask for the same things — "give me customer #28", "create a new invoice", "list all open tickets".

You would use the API when you want to connect TruDriveSync to another tool — for example, to have a website form create a lead automatically, to sync invoices into an accounting tool, or to build an automation in a platform like Zapier. If your goal can be done by hand in the admin panel and doesn't need to connect to outside software, you probably don't need the API at all.

A few terms you'll see in this guide:

• Request — one message asking the API to do something (read, create, update, or delete a record).
• Endpoint — the address you send a request to, one per type of data (there's a customers endpoint, an invoices endpoint, and so on).
• Token (also called an API key) — a long secret password that proves the request is allowed. Every request must include one.
• JSON — a plain-text format the API uses to send data back. It looks like a list of "label": value pairs and is readable once you've seen it a couple of times.

2. Quick Start: your first request in 5 minutes

This walkthrough gets you one successful request using only the admin panel — no code, nothing to install. Do these in order.

1. Generate a token. Open API → API Management and choose Generate / Add New. Copy the token it gives you and keep it somewhere safe — you'll need it in a moment, and it acts like a password.
2. Open the Sandbox. Go to API → Sandbox. This is a built-in test screen that lets you send a real request and see the real answer, without writing anything.
3. Pick a simple read. Choose the Customers endpoint and the GET action (GET means "read / fetch", the safest kind of request — it only looks, it never changes anything).
4. Add your token where the Sandbox asks for it, then Run the request.
5. Read the answer. You should get back a block of JSON listing your customers. A successful read looks something like this:

{
  "id": "28",
  "company": "Test Company",
  "phonenumber": "123456789",
  "city": "London"
}

If you see that, congratulations — you've made a working API request. If instead you get a message like { "status": false, "message": "..." }, the most common cause is a missing or mistyped token; go back to step 1 and try a freshly generated one.

Everything else in this guide builds on those five steps. Once you're comfortable reading data in the Sandbox, you can move on to creating and updating records, and to connecting outside tools.

3. What a full request looks like (outside the Sandbox)

The Sandbox fills in the technical details for you. When another tool or a developer makes the same request directly, it looks like the example below. You don't need to memorize this — it's here so the pieces are familiar when you see them:

curl https://your-subdomain.tdshub.net/api/customers/28 \
  -H "authtoken: YOUR_API_KEY"

Reading that line by line: curl is a common tool for sending requests; the web address is the endpoint (here, customer #28); and -H "authtoken: YOUR_API_KEY" attaches your token as a header — an extra piece of information sent along with the request. Every request needs that token attached, however it's sent.

4. Where everything lives

The module sits in the admin sidebar under an API entry, with these children:

• API Management — generate, view, and revoke API tokens (keys) and manage which users hold them.
• Webhooks — subscribe external URLs to CRM events so they're notified automatically when records change.
• Sandbox — the built-in test screen you used in the Quick Start.
• Statistics — per-user API usage figures.
• Reporting — request activity and history for auditing and troubleshooting.
• Settings — module-wide options, including webhook delivery behavior.
• Automation Connectors — downloads and setup for Zapier, Make, and n8n.
• Documentation — the full, always-current endpoint reference for your instance.

The API menu is only visible to administrators and to staff whose role grants API permissions (see section 14).

5. The base URL is per-tenant

Every request goes to your instance's own address followed by /api/. Because each tenant runs on its own subdomain, the base URL is specific to your instance:

https://your-subdomain.tdshub.net/api/

For example, a tenant reached at acme.tdshub.net uses https://acme.tdshub.net/api/. Always use your own instance's address — the Documentation page fills this in automatically for you, so copying an example from there gives you the correct URL every time.

6. Managing your API tokens

You created a token in the Quick Start. Here's the fuller picture. Open API → API Management to:

• Generate a new token and associate it with the intended user or purpose.
• Review the tokens that already exist.
• Revoke any token that's no longer needed or may have been exposed. Revoking it immediately stops it from working.

Keep tokens secret. A token grants API access to your CRM data — treat it like a password. Never paste it into a public page, a shared document, or anywhere others can read it. If a token is ever exposed, revoke it and generate a new one.

7. Authenticating a request

Every request must carry your token. The standard way is the authtoken header (the "extra information" shown in section 3):

authtoken: YOUR_API_KEY

For quick tests or tools that cannot set custom headers, the token may instead be added to the end of the web address as a query parameter (an option tacked onto a URL after a ?) — for example ?authtoken=YOUR_API_KEY. The header method is preferred for real use because web addresses are more likely to be logged and seen.

8. The request pattern (read / create / update / delete)

The API uses four standard actions, and most types of data follow the same shape. In the Quick Start you used the first one (GET):

• GET with an ID reads one record — e.g. GET api/customers/28. GET only reads; it never changes anything.
• GET with no ID lists records (in pages) — e.g. GET api/invoices.
• GET .../search/{term} (or ?q={term}) searches — e.g. GET api/customers/search?q=acme.
• POST creates a new record — e.g. POST api/customers with the new record's details.
• PUT updates an existing record by ID — e.g. PUT api/customers/28.
• DELETE removes a record — e.g. DELETE api/invoices/19.

The answer always comes back as JSON. Reading returns the record (or a list of records); creating, updating, and deleting return a short status such as { "status": true, "message": "..." } telling you whether it worked. The exact details each record needs are on the Documentation page (section 12).

9. Pagination (getting long lists in pages)

When you ask for a whole list — a GET with no ID — the results come back a page at a time so a huge list doesn't arrive all at once. Use page to choose the page number (starting at 1) and limit to set how many records per page — e.g. api/customers?page=2&limit=50. Asking for a single record by ID is never paged; you just get that one record.

10. Webhooks (getting notified automatically)

Everything above is your software asking the API for data. Webhooks work the other way around: TruDriveSync tells an outside tool the moment something happens, so that tool doesn't have to keep asking. Under API → Webhooks you point a destination web address at one or more events — for example a customer being created, an invoice being paid, a lead's status changing, or a task being assigned. When that event happens, TruDriveSync sends a message to your address automatically. Webhooks fire whether the change was made in the admin panel or through the API.

Delivery can run through the CRM's scheduled background task (cron) for reliable, queued sending; on instances without cron configured, delivery happens during admin activity instead. This behavior is set in Settings. Use Reporting to confirm events are being sent and to troubleshoot a destination that isn't receiving them.

11. Automation connectors (Zapier / Make / n8n) and Postman

Automation Connectors is where you connect no-code platforms — tools that let you build automations by clicking rather than programming. From here (and from the Documentation page) you can download:

• A Postman collection — Postman is a free app for trying out APIs; this is a ready-made set of requests you can import into it, already set up for your instance. Generating it asks for your token so the requests arrive pre-filled and ready to run.
• Connector manifests for Zapier, Make, and n8n — setup files used when building integrations on those platforms.

These downloads point at your own instance automatically, so the connections use your correct per-tenant base URL without you having to type it.

12. The Documentation page (the detailed reference)

Once you've made a request or two and want the exact details for a specific type of data — which fields are required to create an invoice, what a customer record contains, what an error means — the Documentation menu opens the full reference for your instance. It lists every endpoint, the details each one needs and returns, and copy-ready examples with your instance's base URL already filled in. This staff guide teaches the concepts and gets you started; the Documentation page is where you look things up.

13. Statistics and Reporting

• Statistics — shows API usage per user, useful for seeing who or what is calling the API and how heavily.
• Reporting — a log of API request and webhook activity for auditing and troubleshooting. When an integration misbehaves, start here to see what actually reached the server and how it responded.

14. Permissions

Access to the module and its actions is governed by staff role capabilities. Administrators see everything; other staff see the API menu and its screens only if their role grants the relevant API permissions. Token generation should be limited to trusted staff, since a token carries broad access to CRM data.

15. Good to know

• Start in the Sandbox. It's the safest place to learn — begin with GET (read-only) requests before trying anything that creates or changes data. It runs against live data, so treat writes with production-level care.
• Every request needs a token in the authtoken header (or as ?authtoken= for quick tests).
• Tokens are secrets. Store them securely, never expose them publicly, and revoke + regenerate if one leaks.
• The base URL is per-tenant — always https://your-subdomain.tdshub.net/api/. Copy examples from the Documentation page so it's filled in correctly.
• Same pattern everywhere — GET to read (ID = one record, no ID = a list), /search to search, POST to create, PUT to update, DELETE to remove.
• Lists come in pages via page and limit; single-ID reads do not.
• Webhooks push, requests pull. Subscribe an address to events instead of repeatedly asking the API whether something changed.
• Connector downloads are pre-pointed at your instance — use them rather than building base URLs by hand.
• Documentation is where you look up details; this guide is how to get started.