Your API key identifies your organization to anything acting on its behalf. It lives on Settings → Integrations → API Key, and only owners can manage it.
Generating one
Generate the key from that panel. It's shown once — copy it straight into wherever it's going, because it can't be displayed again afterwards.
Lost it? Generate a new one. That invalidates the old key immediately, so update anything using it in the same sitting.
Sending it
Every request to the API carries the key in the Authorization header, after the word Bearer:
curl https://trackmyvendor.com/api/v1/me \
-H "Authorization: Bearer tmv_your_key_here"That endpoint answers with the organization the key belongs to, which makes it the quickest way to check a key works. A key in the URL or in any other header is refused.
Errors come back as JSON with a code and a readable message:
unauthorized— the key is missing, mistyped, or has been regenerated or revoked.plan_required— your plan no longer includes integrations. The key is kept, and starts working again as soon as the plan does.rate_limited— more than 120 requests in a minute. Wait a minute and retry.
What you can do
An overview — every parameter, response and error is in the API reference.
| Request | Returns |
|---|---|
GET /api/v1/contractors | Your contractors, newest first, 25 at a time. Add page and per_page (up to 100) to page through, sort (name, -updated_at, …) to reorder, and email, name, query or active to filter. |
GET /api/v1/contractors/:id | One contractor. |
POST /api/v1/contractors | Adds a contractor: name, and optionally email, phone, primary_contact_name, notes. Add request_documents=true (and a message) to email them an upload link straight away. |
PATCH /api/v1/contractors/:id | Changes the fields you send — the same ones as above, plus active and auto_reminders. |
POST /api/v1/contractors/:id/document_requests | Emails the contractor their upload link, exactly like Request Documents on their page, with an optional message. |
GET /api/v1/events?type=… | Examples of one webhook event, built from your own contractors, in the shape a delivery arrives in. |
POST /api/v1/hooks | Subscribes a url (HTTPS) to one event, and returns its id. |
DELETE /api/v1/hooks/:id | Removes a subscription made through the API. |
Each contractor comes with their contact details, whether they're active, and their compliance status with the reasons behind it — the same status as the badge on their page.
email and name match the whole value, ignoring capitals; query matches any part of the name.
Changes follow the same rules as the screens: your plan's contractor limit applies, names must be unique, and everything done through the API appears in the contractor's activity marked with where it came from — API for your key, or the name of the app you connected. A contractor emailed in the last 48 hours isn't emailed again — the request comes back with the code cooldown — unless you add force=true.
A subscription is an ordinary webhook endpoint: it shows on the Integrations tab, deliveries are signed and logged, and an owner can remove it there. Regenerating or revoking the key removes every subscription made with it.
Keeping it safe
- Treat it like a password. It speaks for your whole organization.
- Store it in your automation tool's secret store, not in a spreadsheet or a shared doc.
- Never put it in client-side code, a URL, or anything that ends up in a browser.
- Rotate it when someone with access to it leaves.
Careful
Key or webhook?
They point in opposite directions, and most people only need the second one.
| Direction | Good for | |
|---|---|---|
| API key | Your system asks us | Reading and updating your contractors from your own code |
| Webhook | We tell your system | Reacting the moment something changes |
If the question is "how do I get told when a contractor lapses?", the answer is a webhook, not the key.