API access
The BidTroller API lets another system your company runs, like an ERP, a bid board or a spreadsheet, read your jobs. It is read-only: a token can read your company’s jobs and nothing else, and it cannot change a job, a status or a setting.
Make a token
Owners and admins make tokens on Admin › API (/app/admin/api).
- Type a name that says what will use the token, for example Our ERP, and click Make a token.
- Copy the token from the green box. It starts with bt_live_. It is shown once: BidTroller keeps only a fingerprint of it, so nobody, including BidTroller, can show it to you again.
- Paste it into the other system’s settings.
Treat a token like a password. Anyone who has it can read your company’s jobs. Don’t email it or paste it into a chat.
The page lists each token with its name, its first characters, when it was made and when it was last used. Revoke, then tick the box and click Revoke again, stops a token at once. It can’t be undone; make a new one if you need it again. A company can hold 10 tokens at a time.
Read your jobs
Send the token in the Authorization header of every request:
Authorization: Bearer bt_live_…
Two requests are available:
- GET https://bidtroller.com/api/v1/opportunities returns a list of your jobs.
- GET https://bidtroller.com/api/v1/opportunities/<job id> returns one job.
The list leaves out the same jobs the Opportunities page does: duplicates merged into another job, archived jobs, and jobs marked Not interested. It is sorted by when each job last changed, oldest first.
Filters go in the address after a ?, joined with &:
- status=pursuing,bidding keeps only those statuses. The statuses are new, reviewing, pursuing, bidding, submitted and no_bid.
- updated_since=2026-11-12T00:00:00Z keeps only jobs changed at or after that time.
- assigned=none keeps jobs nobody has taken; assigned=someone keeps jobs that have an estimator.
- limit=50 sets how many jobs come back, from 1 to 200. Without it you get 100.
When there are more jobs than the limit, the answer includes next_cursor. Send it back as cursor=… with the same filters to get the next page. next_cursor is null on the last page.
What comes back
The answer is JSON. The list is { "data": [ …jobs… ], "next_cursor": … } and one job is { "data": { …job… } }. Each job has:
- id and url (the job’s page in BidTroller)
- title, agency, city, county, state
- bid_due_at, prebid_at, prebid_mandatory, questions_due_at (times are in UTC)
- status
- fit_percent: how sure BidTroller is that the job is your kind of work, 0 to 100, or null if it hasn’t been checked yet
- value_low and value_high in dollars, when the listing gives a value
- fence_types and work_types
- distance_miles and nearest_office
- assigned_to: the estimator’s name and email, or null
- score and band (BID, REVIEW or PASS), only if your company has scoring turned on
- first_seen_at and updated_at
Limits and errors
- Each token can make 120 requests a minute. Past that the answer is 429; wait a minute.
- 401 means the token is missing, mistyped or revoked.
- 400 means a filter isn’t right; the error text says which one.
- 404 on one job means there is no job with that id in your company.
Need a field that isn’t here, or something other than jobs? Send it as Idea or request on the Feedback page.