The FinShare API does everything the dashboard does over HTTPS: create requests, check status, refresh and roll forward, download reports, manage webhooks. It uses JSON in and out.
Base URL: https://app.finshare.io/v1
Create an API key
Developers › API keys.
- Go to Developers in the app. You need to be an account owner.
- Click Create key and name it after the system that will use it, for example "Deal room integration".
- Copy the key. It starts with
fl_live_. FinShare stores only a hash and can't show it again.
Store the key in your secrets manager. A key acts for your whole organization: requests it creates belong to the team, and everything it does is recorded in the audit log under that key.
To revoke a key, click Revoke next to it. Anything using it stops working at once. This can't be undone.
Authenticate
Send the key as a bearer token on every request.
curl https://app.finshare.io/v1/report_types \
-H "Authorization: Bearer fl_live_..."A missing or invalid key returns 401:
{ "error": { "code": "unauthorized", "message": "Missing or invalid API key" } }Errors
Every error has the same shape:
{
"error": {
"code": "invalid_request",
"message": "Invalid request",
"details": [
{ "path": "items.0.period", "message": "A/R Aging Summary is an as-of report; use period kind \"as_of\" or \"fixed_as_of\"" }
]
}
}| Status | code | Typical cause |
|---|---|---|
| 400 | invalid_request | The body failed validation. details lists each field with a message. |
| 400 | invalid_json | The body isn't valid JSON. |
| 401 | unauthorized | Missing or invalid API key. |
| 403 | forbidden | The action needs an account owner. |
| 403 | connectors_not_enabled | Connector endpoints called on an account without connector mode. |
| 404 | not_found | No such request, report or endpoint for your organization. |
| 409 | conflict | The request isn't in a state that allows this, for example a refresh while another round is open. |
| 409 | report_not_ready | The report didn't tie out or wasn't delivered, so it can't be downloaded. |
| 422 | idempotency_mismatch | An Idempotency-Key was reused with a different body. |
message is always safe to show to a person.
Idempotency
POST endpoints that create things accept an Idempotency-Key header: /requests, /requests/:id/rounds, /connectors and /connectors/:id/pulls.
curl https://app.finshare.io/v1/requests \
-H "Authorization: Bearer fl_live_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: file-request-8812-attempt-1" \
-d @request.jsonRepeating a call with the same key and the same body returns the original response, without creating anything new. Reusing a key with a different body returns 422 idempotency_mismatch. Keys are scoped to your organization and can be up to 200 characters. Use one per logical operation, such as your own record id.
Usage
Developers › Usage this month shows how many requests your organization created, how many reports were delivered, and how many QuickBooks calls those took.