API reference

TicoQuickBooks API Reference

This page documents each public endpoint with inputs, outputs, auth requirements, and example requests. It is modeled after the structure commonly used in API references like Stripe and Twilio, where each endpoint clearly lists parameters, response fields, and example calls.

Open JSON document FastAPI OpenAPI

Machine-readable sources

Public API JSON: /static/api-docs.json
FastAPI OpenAPI: /openapi.json

The public JSON document is curated for external tools and keeps the important auth and endpoint behavior simple. The OpenAPI document is generated directly by FastAPI and includes the full route schema.

Authentication

Protected endpoints accept the shared API key either in the X-API-Key header or as the api_key query parameter. OAuth endpoints do not require the API key because they are part of the QuickBooks login flow.

curl -sS -H "X-API-Key: YOUR_API_KEY" \
  "https://quickbooks.ticosync.com/api/token/beach-blend"

Endpoint Reference

GET /health

Returns a simple health payload for load balancers, uptime checks, and deployment verification.

Auth
None

Input
No path, query, or body parameters

Output
JSON health payload

Example request

curl -sS "https://quickbooks.ticosync.com/health"

Example response

{
  "status": "ok"
}

Status codes

200 OK The service is up and responding.

GET /oauth/start/{company_key}

Starts the QuickBooks OAuth flow for a named company connection. The returned response is a redirect to Intuit’s OAuth authorization URL.

Auth
None

Input
Path parameter plus optional query parameter

Output
HTTP redirect to QuickBooks authorization

Path parameters

Name	Type	Required	Description
`company_key`	string	Yes	Stable identifier for the QuickBooks connection, such as `beach-blend` or `beach-blend-sandbox`.

Query parameters

Name	Type	Required	Description
`company_name`	string	No	Human-readable company name saved with the connection record.

Behavior notes

Rule	Description
Sandbox credential routing	If either `company_key` or `company_name` contains `sandbox`, the service uses `QUICKBOOKS_SANDBOX_CLIENT_ID` and `QUICKBOOKS_SANDBOX_CLIENT_SECRET`.
Stored state	The service stores an OAuth state nonce in DynamoDB before redirecting to Intuit.

Example request

curl -i "https://quickbooks.ticosync.com/oauth/start/beach-blend?company_name=Beach%20Blend"

Example response

HTTP/1.1 302 Found
Location: https://appcenter.intuit.com/connect/oauth2?...state=beach-blend%3A...

Status codes

302 Found Redirect to QuickBooks OAuth.

400 Bad Request Missing or invalid company_key.

500 Internal Server Error Missing required environment configuration.

GET /oauth/callback

Completes the QuickBooks OAuth flow, exchanges the authorization code for tokens, and stores the connection record in DynamoDB.

Auth
None

Input
Query parameters from Intuit

Output
HTML success page

Query parameters

Name	Type	Required	Description
`code`	string	Yes	OAuth authorization code returned by Intuit.
`state`	string	Yes	OAuth state value previously created by the service.
`realmId`	string	No	QuickBooks company identifier returned by Intuit.

Stored output

Field	Description
`company_key`	Connection key associated with the callback state.
`company_name`	Human-readable company label.
`realm_id`	QuickBooks company ID returned by Intuit.
`access_token`	Short-lived QuickBooks access token.
`refresh_token`	Refresh token used for later renewal.
`access_token_expires_at`	Unix timestamp for access-token expiry.
`refresh_token_expires_at`	Unix timestamp for refresh-token expiry.
`uses_sandbox_credentials`	Whether sandbox credentials were used for this connection.

Status codes

200 OK Callback completed and tokens were stored.

400 Bad Request Missing code, missing state, or invalid OAuth state.

404 Not Found No stored company connection was found for the callback state.

502 Bad Gateway Intuit token exchange failed.

GET /api/token/{company_key}

Returns a valid QuickBooks access token for a company connection. If the stored token is expired or close to expiry, the service refreshes it before returning the response.

Auth
Required: X-API-Key header or api_key query parameter

Input
Path parameter plus API key

Output
JSON token payload

Path parameters

Name	Type	Required	Description
`company_key`	string	Yes	Connection key for the company token to retrieve.

Authentication inputs

Name	Location	Required	Description
`X-API-Key`	Header	No*	Preferred shared API key for protected endpoints.
`api_key`	Query	No*	Alternative query-string API key input.

* One of these two auth inputs is required.

Response fields

Field	Type	Description
`company_key`	string	Stored company connection key.
`company_name`	string	Stored company display name.
`realm_id`	string	QuickBooks company ID.
`access_token`	string	Current valid QuickBooks access token.
`access_token_expires_at`	integer	Unix timestamp for access-token expiry.
`refresh_token_expires_at`	integer	Unix timestamp for refresh-token expiry.
`updated_at`	integer	Unix timestamp for last record update.
`last_refresh_at`	integer	Unix timestamp for the most recent token refresh operation.
`uses_sandbox_credentials`	boolean	Whether the connection uses sandbox QuickBooks credentials.

Example request

curl -sS -H "X-API-Key: YOUR_API_KEY" \
  "https://quickbooks.ticosync.com/api/token/beach-blend"

Example response

{
  "company_key": "beach-blend",
  "company_name": "Beach Blend",
  "realm_id": "12314585920123",
  "access_token": "eyJ...",
  "access_token_expires_at": 1775689200,
  "refresh_token_expires_at": 1784000000,
  "updated_at": 1775685600,
  "last_refresh_at": 1775685600,
  "uses_sandbox_credentials": false
}

Status codes

200 OK Valid token returned.

401 Unauthorized API key missing or invalid.

404 Not Found Company connection not found.

409 Conflict Missing refresh token on stored record.

502 Bad Gateway Refresh against Intuit failed.

POST /api/token/{company_key}/refresh

Forces a refresh of the stored QuickBooks token for a company connection, even if the current access token has not yet expired.

Auth
Required API key

Input
Path parameter plus API key

Output
Same JSON shape as token retrieval

Example request

curl -sS -X POST -H "X-API-Key: YOUR_API_KEY" \
  "https://quickbooks.ticosync.com/api/token/beach-blend/refresh"

Example response

{
  "company_key": "beach-blend",
  "company_name": "Beach Blend",
  "realm_id": "12314585920123",
  "access_token": "eyJ...",
  "access_token_expires_at": 1775689200,
  "refresh_token_expires_at": 1784000000,
  "updated_at": 1775685600,
  "last_refresh_at": 1775685600,
  "uses_sandbox_credentials": false
}

GET /api/connections/{company_key}

Returns non-secret metadata about a stored company connection. This endpoint is useful for confirming which realm is tied to a company key without exposing the access token.

Auth
Required API key

Input
Path parameter plus API key

Output
JSON metadata payload

Response fields

Field	Type	Description
`company_key`	string	Stored company connection key.
`company_name`	string	Stored display name.
`realm_id`	string	QuickBooks company ID.
`environment`	string	Stored environment label, typically `production` or `sandbox`.
`access_token_expires_at`	integer	Unix expiry timestamp for the access token.
`refresh_token_expires_at`	integer	Unix expiry timestamp for the refresh token.
`updated_at`	integer	Last update timestamp.
`created_at`	integer	Creation timestamp.
`last_refresh_at`	integer	Most recent refresh timestamp.
`connected`	boolean	Whether access and refresh tokens are currently stored.

Example request

curl -sS -H "X-API-Key: YOUR_API_KEY" \
  "https://quickbooks.ticosync.com/api/connections/beach-blend"

Example response

{
  "company_key": "beach-blend",
  "company_name": "Beach Blend",
  "realm_id": "12314585920123",
  "environment": "production",
  "access_token_expires_at": 1775689200,
  "refresh_token_expires_at": 1784000000,
  "updated_at": 1775685600,
  "created_at": 1775600000,
  "last_refresh_at": 1775685600,
  "connected": true
}

GET /api/connections

Returns a placeholder response explaining that full connection listing is not implemented yet without a DynamoDB scan path.

Auth
Required API key

Input
API key only

Output
JSON message payload

Example response

{
  "message": "Connection listing is not implemented without a DynamoDB scan path. Use /api/connections/{company_key} for known companies.",
  "path": "/api/connections"
}

Machine-readable documents

For tools that want structured docs instead of HTML, use /static/api-docs.json. For the generated FastAPI schema, use /openapi.json.