Skip to main content
Use GET /tax_credits to discover your company’s R&D credits across tax years, and GET /tax_credits/{id} to retrieve one credit. Both require API access: Manage and Taxes: View, checked against the API key owner’s current permissions. The credential selects the company; there is no company-ID parameter. Each record represents one credit per type, jurisdiction, and tax year. Currently the API supports research_and_development credits in US, with usd amounts. Estimates, undecided years, and years where you declined credits are included so a caller can explain why a year has no claimed credit.

​
Discovering credits

Omit year to discover all available years, newest first:
Optional filters compose:
The list uses the standard pagination envelope. An initial query with no matching records returns data: [], has_more: false, and next_cursor: null. Empty type, year, and claim_status values are invalid; omit a filter to leave it unconstrained. There is no jurisdiction filter in this version. If has_more is true, continue with starting_after=next_cursor. Pagination is live, not a snapshot. A credit whose claim status changes can stop matching your filters; an unavailable or filtered-out cursor returns 404 resource_missing with param: "starting_after". Restart from the first page with the desired filters.

​
Example response

Synthetic values for GET /tax_credits:
This is a $25,000 total credit, with $5,000 applied against income tax and $20,000 allocated to payroll. It is included in the filed income-tax return, while the payroll submission is still pending.
A payroll credit allocation is not a refund received. Finta does not track provider acceptance or refunds received, and this API does not assert either.
Retrieve that credit by passing its ID unchanged:
Retrieval returns the tax_credit object directly, without the list envelope. tcred_ IDs remain stable for a company/type/jurisdiction/year even when the source questionnaire changes. If onboarding was restarted for a year, a filed return takes precedence; otherwise the latest-created questionnaire supplies the record. All timestamps use Unix seconds. created is the source questionnaire’s creation time; updated is the most recent change to that questionnaire, its income-tax filing, or its return package. Reads do not calculate credits, change claim decisions, file returns, or submit credits to payroll.

​
Amounts and their source

All amounts are integer cents. Recorded return totals take precedence over estimates. A declined year may still show an estimate of its potential credit; that is not an amount claimed. amount_basis explains where amount_cents came from: An unverified database-default zero does not establish a known amount. A zero return total with an explicit zero income-tax allocation establishes a known zero. Never convert a null amount to zero: null means unknown, while 0 means a known zero. A filed income-tax workflow alone does not turn an estimate into a filed credit amount. If the return total is unknown, the API can retain the estimate and label it estimate. Payroll allocations can be available before filing, but only when the return total and income-tax allocation are known.

​
Claim status

claim_status describes the decision and inclusion in the income-tax return: An explicit decline takes precedence over other claim signals. Historical filed returns with positive recorded credits can be claimed without a saved opt-in. claimed says nothing about payroll submission, provider confirmation, or refunds received.

​
Payroll submission

payroll_submission always contains provider and status. The provider is the recorded R&D payroll selection, otherwise Gusto/Rippling detection or the sole recorded payroll provider. It is null when unresolved. Finta also marks the payroll task done automatically when credits are fully offset against income tax. A known zero payroll allocation therefore returns not_required even when that task is marked done. If staff later revises that offset or replaces the draft, an automatic completion remains distinct from an explicit submission. A newly positive payroll allocation can therefore return pending or action_required rather than submitted. Resaving the unchanged done field does not assert submission. Historical done flags without a known completion reason return unknown when payroll submission is required. A submission timestamp alone is insufficient because other state changes also set it. submitted means recorded as submitted in Finta. It is not a provider acknowledgment, a guarantee of acceptance, or evidence of a refund. Treat future status values as unknown until you understand their documented meaning rather than inferring stronger guarantees.

​
Errors

submitted is a payroll-submission status, not a claim status. This request is rejected:
IDs must be tcred_ followed by a nonempty alphanumeric suffix. Numeric IDs and UUIDs are not accepted. A valid-format ID absent from the company produces this response, including when it belongs to another company:
Both reads count toward the normal API allowance. Successful responses and burst-limit rejections include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset; early authentication, authorization, and monthly-limit errors can omit them. Honor Retry-After on burst-limit rejections. Monthly-limit rejections do not send it and are not an immediate retry condition. See Errors for shared error codes and retry guidance.