This guide answers the questions integrators ask most: the behavior and policy questions the API reference doesn't cover directly. The reference stays the source of truth for endpoints, fields, and schemas.
Getting access
How do I get or rotate an API key? Keys are issued and rotated through Support; there is no self-serve screen for this yet. A key stays valid until it is rotated on request.
Can I get a read-only key? Keys don't carry their own permissions. Every key inherits the permissions of the user it belongs to, so all keys of the same user behave identically. To build a read-only integration, create a dedicated user with limited permissions and use that user's key. This also keeps your integration's access auditable and easy to revoke.
Which API version should I build on? Use the latest version of each resource, for example /v3/transactions. V1 and V2 transaction endpoints are deprecated and may lack newer fields and features.
Rate limits
What are the limits? 100 requests per 10 seconds, 2,000 requests per hour, and 100 failed requests per hour.
How do I stay under them? Watch the live counters in every response: X-Brokermint-Burst-Remaining, X-Brokermint-Hour-Remaining, X-Brokermint-Errors-Remaining. When you get a 429, stop and wait: X-Brokermint-Hour-Reset (a 13-digit Unix timestamp) tells you exactly when the next cycle starts. Build the 429 handler first; it is much cheaper than discovering the limit in production.
Can my limit be raised? In almost every case the real fix is fewer calls, not a higher ceiling. Before asking: use batch endpoints (listing transactions returns up to 1,000 per request), cache data that rarely changes, and use webhooks instead of re-polling everything. Support can review your query pattern with engineering if you still hit the ceiling.
Staying in sync: webhooks and polling
Which events have webhooks? Transactions (created, updated, deleted), transaction participants (added, updated, removed), buyer offers and their participants, and incoming transactions (accepted, discarded). Each user can hold up to 5 subscriptions. Payloads are HMAC-SHA256 signed (X-Brokermint-Webhook-Signature); verify with the secret_token you receive at creation, and save it then, it is shown once.
There are no document events. How do I track document changes? Correct, document uploads, replacements, deletions, and signature completion have no webhook events today. The supported path is polling the Activities API (/v1/activities) filtered by created_since and event_types, up to 200 records per page. A polling interval of a few minutes fits comfortably inside the hourly rate limit.
What delivery guarantees do webhooks have? Delivery can lag up to 2 minutes, events can arrive out of order or more than once, and a delete event can occasionally arrive before its create. Log the event_id of everything you process and skip events you have already seen. Failed deliveries are retried over 4 hours (5, 10, 15, 30, 60, 120 minutes); after 6 failures the subscription is deactivated and you are emailed.
Documents and e-signatures
How do I know a document is fully signed? Every document carries an esign object: an overall status, a has_signatures flag, and per-signer statuses. A completed package is one where every signer shows "signed". A partially signed one will show a mix, for example one "signed" and one "sent".
How do I download a document? The document's url field is a temporary link that expires after 15 minutes. Request the document again whenever you need a fresh link; don't store the URL.
Can I retrieve a signature certificate or audit trail? The API does not currently expose a certificate or audit-trail object.
Document versions and deduplication
Is there a revision ID, checksum, or last-modified timestamp? No. The document object carries none of these today, so plan your sync around document IDs and the Activities feed rather than content hashes.
Does the document ID stay the same when a document is replaced or re-signed? The answer determines your dedup strategy: if the ID is stable, re-fetch on activity; if a replacement gets a new ID, treat the old one as superseded.
Data retention and account termination
Can we keep copies of documents in our own portal after closing? What happens if the BTBO account is terminated? These are contractual questions, not API ones, and this guide won't answer them authoritatively. They are governed by your service agreement; contact Support and we will route you to the right owner.