Introduction - Synthetic API

Synthetic keeps a company’s books. It connects to the company’s bank accounts, payroll and business tools, records what happened, and produces accrual-basis financial statements. The Synthetic API lets your own software read that data, and write it where a route allows. The API is a REST API at https://app.synthetic.ai/api/v1. Reads use GET, or QUERY where a read takes a JSON body; QUERY changes nothing, like GET. Send every request body as JSON, with Content-Type: application/json. A route that takes parameters refuses a query parameter or body field it does not take with 400, so a misspelled name is never ignored. Responses from the API are JSON. An amount is an object with a value, a whole number of the currency’s smallest unit such as cents, and a currencyCode. For example, { "value": 200000, "currencyCode": "USD" } is $2,000.00. Timestamps are ISO 8601 strings. A field that holds a day rather than a moment, such as a contract’s startAt, is midnight UTC on that day, and only the date matters.

Terms used in this API

Term	Meaning
Entity	The business whose books Synthetic keeps. An API key belongs to one entity and reads and writes only its data. The `GET /me` route returns the entity a key belongs to.
Customer	Someone the entity bills.
Contract	An agreement between the entity and one of its customers. It sets what the customer is billed for, from when and until when, and whether the agreement renews when it ends.
Reference id	The entity’s own id for a customer or contract, such as the record’s id in its CRM. No two customers share one, and no two contracts, but once one is deleted, its reference id can be given to another. `GET /customers` and `GET /contracts` find records by it with the `referenceIds` filter.
Amendment	A change to a contract’s terms from a date, holding every term from that date. Amendment 0 holds the terms the contract was created with. An amendment is a draft until it is agreed; an agreed amendment is `FINALIZING` while the contract’s invoices are updated, then `FINALIZED`.
Current amendment	The amendment whose terms apply today: the latest finalized one that has started, or amendment 0 until one has.
Invoice	A bill the entity raises for a customer.
Invoice line	One charge on an invoice: what it is for, the days it covers and its amount.
Invoice preview	An invoice that would be billed if a change went ahead, such as a contract’s draft amendment being agreed. It is worked out on each request and never stored, so it has no id.
Contract line item	Something a contract charges for, such as a subscription or a one-time fee. The app calls it a billable. Each invoice line names the contract line item it charges for.
Billing setup	The stage before an entity bills its customers through Synthetic, in which it records its past invoices.
Payment	Money a customer paid the entity. Synthetic applies a payment to the customer’s invoices; the part not yet applied is its unapplied amount.
Bank fee	The fee a bank charged for processing a payment. Synthetic records it as a payment of type `BANK_FEE`, nested inside the payment it was charged against.
Processor fee	The fee a payment provider kept from a card payment. Synthetic records it as a payment of type `PROCESSOR_FEE`, nested inside the card payment it was charged against.
API key	A secret your software sends to prove who it is. Created in Synthetic under Settings → API keys.
Claim	A permission a key holds, such as reading payments. `GET /me` lists a key’s claims.

What you can read

Route	Returns
`GET /health`	Confirms the API is reachable. No key needed.
`GET /me`	The entity your key belongs to, the claims it holds, and the key itself.
`GET /contracts`	The entity’s contracts, one page at a time. Deleted contracts only when you ask for them.
`GET /contracts/{id}`	One contract by id, a deleted one included. Name one of its amendments with `amendmentId` to read the contract as it stood under that amendment.
`GET /contract-line-items`	What one contract charges for, one page at a time, a deleted contract included. Name the contract with `contractId`, and one of its amendments with `amendmentId` to read the line items under that amendment, such as terms agreed for later.
`GET /amendments`	One contract’s amendments, amendment 0 first, one page at a time. Name the contract with `contractId`.
`GET /amendments/{id}`	One amendment by id.
`QUERY /invoice-previews`	The invoices a change would bill before it is made, all on one page. Send one of `contractId` for the contract’s draft amendment, `terms` for terms not saved yet, or `cancellation` for a cancellation from a date.
`QUERY /invoice-previews/pdf`	A link to download one invoice a change would bill, as a PDF marked PREVIEW. Name the change with `contractId`, `terms` or `cancellation`, and the invoice with its `scheduledIssueAt`. Terms also need the customer, as `terms.customerId`.
`GET /customers`	The entity’s customers, one page at a time.
`GET /customers/{id}`	One customer by id.
`GET /invoices`	The entity’s invoices, one page at a time. Voided invoices only when you ask for them.
`GET /invoices/{id}`	One invoice by id, with every one of its lines.
`GET /invoices/{id}/pdf`	A link to download one invoice’s PDF. For an invoice Synthetic emailed, the PDF is the file attached to the latest email.
`GET /payments`	The entity’s cash and card payments, one page at a time.
`GET /payments/{id}`	One payment of any type by id, including a fee or a voided card payment.
`GET /openapi.json`	The OpenAPI document describing the routes above. No key needed.

On GET /invoices, needsApproval=true lists the drafts waiting for someone to approve them. A draft is listed once its period has started or is fewer than 31 days away, and can take a day or more to appear, for example one from a contract agreed today. A draft on a contract set to issue automatically does not wait for anyone, unless its period started on or before the day billing setup finished, or a person was asked to review it. A draft with usageLineCount above 0 is listed only from its scheduledIssueAt, once its awaitingUsageLineCount is 0. Nothing is listed while the entity is still in billing setup. Each payment carries its amount, how much of it has been applied to invoices, the customer it came from once one has been attributed, the date it was received, and its fees: bank, the fee a bank charged on a cash payment, and processor, the fee a payment provider kept from a card payment. Each is null when there is no such fee. A fee is a payment too, so it can also be read on its own. The bankFee field repeats fees.bank and is deprecated; read fees.bank instead.

Your first request

In Synthetic, open Settings → API keys and create a key. Copy the secret when it is shown, because it is shown only once.

Confirm the key works:

curl https://app.synthetic.ai/api/v1/me \
  -H "Authorization: Bearer <key>"

List payments:

curl "https://app.synthetic.ai/api/v1/payments?limit=10" \
  -H "Authorization: Bearer <key>"

The API Reference tab lists every route except GET /openapi.json, with its parameters and response fields. It is generated from the API’s own OpenAPI document at https://app.synthetic.ai/api/v1/openapi.json.

​Terms used in this API

​What you can read

​Your first request

Terms used in this API

What you can read

Your first request