A API Overview#

a. Regions

#

The FRAGMENT API is available in the following AWS regions:

  • us-east-1
  • us-east-2
  • us-west-2
  • eu-west-1

The region for a workspace can be found in the API URL in the settings tab of the dashboard. Use the top-left dropdown in the dashboard to create a new workspace.

Contact us if you don't see your desired AWS region.

b. Authentication

#

FRAGMENT uses OAuth2's client credentials flow to authenticate API clients. The call requesting an access token follows the OAuth2 spec. Use an OAuth2 library that supports the client credentials grant to retrieve the token or make an HTTP request. The flow is:

  1. Create an API client in the FRAGMENT dashboard. API Clients have complete access to the workspace.
  2. Note the auth endpoint URL and OAuth scope for the API Client. This is specific to the AWS region for a given workspace.
  3. Get a fresh access token from the token endpoint. The access token expires in 1 hour. We recommend retrieving a new token for each set of calls needed to be made. Multiple tokens can be generated and use simultaneously.
  4. To use the token, add the Authorization request header with the value Bearer {{access_token}} when calling the GraphQL API.

The token request payload should be in x-www-form-urlencoded format, with the keys grant_type, scope and client_id.

Token request body
grant_type=client_credentials&scope={{scope}}&client_id={{client_id}}

The token request headers should contain the following items, where client_credentials is the Base64-encoded version of: {{client_id}}:{client_secret}}.

Token request headers
{
    "Content-Type": "application/x-www-form-urlencoded",
    "Authorization": "Basic {{client_credentials}}",
    "Accept": "*/*"
}

The response is a JSON object containing the access token.

Token response body
{
    "access_token": "<access token>",
    "expires_in": 3600,
    "token_type": "Bearer"
}

Putting it all together:

Javascript
import axios from "axios";

const btoa = (str) => Buffer.from(str).toString("base64");

// credentials from the dashboard
const clientId = "2h4t0cv7qv5c9r0qgs1o3erkuk";
const secret = "superSecretClientSecret";
const scope = "https://api.us-west-2.fragment.dev/*";
const authUrl = "https://auth.us-west-2.fragment.dev/oauth2/token";

const getToken = async () => {

  // encode the client id and secret
  const auth = btoa(`${clientId}:${secret}`);

  // create the request body
  const data = new URLSearchParams();
  data.append("grant_type", "client_credentials");
  data.append("scope", scope);
  data.append("client_id", clientId);

  // retrieve the token
  const response = await axios.request({
    method: "POST",
    url: authUrl,
    headers: {
      "Content-Type": "application/x-www-form-urlencoded",
      Authorization: `Basic ${auth}`,
      Accept: "*/*",
    },
    data,
  });

  if (!response.data.access_token) {
    throw new Error(
      "didn't get an access token from auth endpoint"
    );
  }
  return response.data.access_token;
};
 

c. Idempotency

#

To ensure write operations are executed exactly once, all write mutations in FRAGMENT are idempotent. This enables applications to safely retry operations without risk of duplicate effects. Applications only need to guarantee that the API is called at least once.

Mutations require a unique idempotency key (ik). For calls to reconcileTx, syncCustomAccounts and syncCustomTxs, FRAGMENT internally uses the transaction or account ID from the request as the idempotency key.

Additional requests with the same ik are ignored and the original response is returned with isIkReplay: true in the response.

Idempotency keys are scoped per-Ledger; requests with the same IK to different Ledgers will execute the mutation and return isIkReplay: false.

d. Errors

#

According to the GraphQL spec, all responses will return an object containing data and errors.

data: the result of a query or mutation. In the FRAGMENT API, all successful mutations return a union type that represents an application error or a successful result.

For example, the response type of the addLedgerEntry mutation is:

API Response Union Types
union AddLedgerEntryResponse =
    AddLedgerEntryResult | BadRequestError | InternalError

Queries can return null if an error was raised during the request. This is accompanied by a non-empty errors list.

errors: a list of errors raised during the request. This typically gets populated when issuing a query if a required argument is missing or an invalid ID is provided.

When calling the API, handle errors in the following order:

  1. Handle retryable HTTP errors. These are 429 or 5XX.
  2. Handle non-retryable HTTP errors such as other 4XX status codes. This typically happens if the query does not conform to the GraphQL spec, like omitting a required variable or selecting a nonexistent field. This class of error can be avoided by using a generated, typed SDK.
  3. Handle null responses from queries by checking the errors key. This typically happens when querying an item with an invalid ID.
  4. Query the __typename field. This contains BadRequestError, InternalError or the appropriate <Mutation>Result type.
  5. Handle InternalError with retries and exponential backoff.
  6. Handle BadRequestError by failing the operation.
  7. Handle <Mutation>Result types such as AddLedgerEntryResult.

An example of this written in TypeScript:

Handling API Responses
import assert from 'assert';

type RequestParams = {
  query: string;
  variables: Record<string, unknown>;
};

const makeRequest = async ({ query, variables }: RequestParams): Promise<Response> => {
  const token = await getToken();
  return fetch('Fragment GraphQL URL', {
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ query, variables }),
  });
};

const query = '''
  mutation addLedgerEntry($ik: SafeString, $entry: LedgerEntryInput!) {
    addLedgerEntry(ik: $ik, entry: $entry) {
      __typename
      ...
    }
  }
''';
const variables = { ik: 'sample-ik', entry: {...} };

const handleRequest = (req: Response) => {
  if (req.status === 429 || req.status >= 500) {
    // Rate-limited or intermittent http failures. Retry the request.
    return handleRequest(await makeRequest({ query, variables }));
  }
  if ((req.status >= 400 || req.status < 500) && req.status !== 429) {
    // Invalid GraphQL request provided to Fragment. Handle the error.
    throw new Error('Invalid GraphQL request');
  }

  // .json() checks that it was a 200
  const response = await req.json();
  if (response.data.addLedgerEntry.__typename === 'InternalError') {
    // Retry the request in case of internal errors, with backoff.
    return handleRequest(await makeRequest({ query, variables }));
  }
  if (response.data.addLedgerEntry.__typename === 'BadRequestError') {
    // Invalid request provided to Fragment. Handle the error.
    throw new Error('Invalid API request to Fragment');
  }
  return response;
};

const response = handleRequest(await makeRequest({ query, variables }));
// Entry successfully posted to Fragment. Handle the response.
assert(response.data.addLedgerEntry.__typename === 'AddLedgerEntryResult');
handlePostedEntry(response.data.addLedgerEntry);
 

To test how your application handles errors, use the X-Fragment-Return-Error request header to instruct the API to return erroneous responses.

Set the X-Fragment-Return-Error header to:

  • internalError to instruct the API to return an InternalError
  • badRequestError to instruct the API to return a BadRequestError

When requesting an erroneous response, FRAGMENT will skip processing your request and return the error immediately.

B API Queries#

customCurrencies

#

Query Custom Currencies in the workspace

Response

Returns a CustomCurrenciesConnection!

Query
query CustomCurrencies(
  $after: String,
  $before: String,
  $first: Int,
  $last: Int
) {
  customCurrencies(
    after: $after,
    before: $before,
    first: $first,
    last: $last
  ) {
    nodes {
      ...CurrencyFragment
    }
    pageInfo {
      ...PageInfoFragment
    }
  }
}

Variables
{"after": "abc123", "before": "abc123", "first": 2277, "last": 2277}

Response
{
  "data": {
    "customCurrencies": {
      "nodes": [Currency],
      "pageInfo": PageInfo
    }
  }
}

Arguments
Name Description
after - String Where to start paginating from, when paginating forwards. Send endCursor from a response to get its next page. Learn more about pagination .
before - String Where to start paginating from, when paginating backwards. Send startCursor from a response to get the previous page. Learn more about pagination .
first - Int The number of currencies to return per page, when paginating forwards. Defaults to 20, maximum is 200.
last - Int The number of currencies to return per page, when paginating backwards. Defaults to 20, maximum is 200.

externalAccount

#

Get External Account by Link and External ID or FRAGMENT ID.

Response

Returns an ExternalAccount

Query
query ExternalAccount($externalAccount: ExternalAccountMatchInput!) {
  externalAccount(externalAccount: $externalAccount) {
    currency {
      ...CurrencyFragment
    }
    currencyMode
    externalId
    id
    ledgerAccounts {
      ...LedgerAccountsConnectionFragment
    }
    link {
      ...LinkFragment
    }
    linkId
    name
    txs {
      ...TxsConnectionFragment
    }
  }
}

Variables
{"externalAccount": ExternalAccountMatchInput}

Response
{
  "data": {
    "externalAccount": {
      "currency": Currency,
      "currencyMode": "multi",
      "externalId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
      "id": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
      "ledgerAccounts": LedgerAccountsConnection,
      "link": Link,
      "linkId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
      "name": "abc123",
      "txs": TxsConnection
    }
  }
}

Arguments
Name Description
externalAccount - ExternalAccountMatchInput!

ledger

#

Get a Ledger by ID

Response

Returns a Ledger

Query
query Ledger($ledger: LedgerMatchInput!) {
  ledger(ledger: $ledger) {
    balanceUTCOffset
    created
    dashboardUrl
    id
    ik
    ledgerAccounts {
      ...LedgerAccountsConnectionFragment
    }
    ledgerEntries {
      ...LedgerEntriesConnectionFragment
    }
    ledgerEntryGroup {
      ...LedgerEntryGroupFragment
    }
    ledgerEntryGroups {
      ...LedgerEntryGroupsConnectionFragment
    }
    migrations {
      ...LedgerMigrationConnectionFragment
    }
    name
    schema {
      ...SchemaFragment
    }
    type
    workspaceId
  }
}

Variables
{"ledger": LedgerMatchInput}

Response
{
  "data": {
    "ledger": {
      "balanceUTCOffset": "-08:00",
      "created": "2007-12-03T10:15:30Z",
      "dashboardUrl": "abc123",
      "id": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
      "ik": "some-safe-string-ik",
      "ledgerAccounts": LedgerAccountsConnection,
      "ledgerEntries": LedgerEntriesConnection,
      "ledgerEntryGroup": LedgerEntryGroup,
      "ledgerEntryGroups": LedgerEntryGroupsConnection,
      "migrations": LedgerMigrationConnection,
      "name": "abc123",
      "schema": Schema,
      "type": "double",
      "workspaceId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1"
    }
  }
}

Arguments
Name Description
ledger - LedgerMatchInput! An object specifying the ID of the ledger you want to query

ledgerAccount

#

Get a Ledger Account by ID

Response

Returns a LedgerAccount

Query
query LedgerAccount($ledgerAccount: LedgerAccountMatchInput!) {
  ledgerAccount(ledgerAccount: $ledgerAccount) {
    balance
    balanceChange
    balanceChanges {
      ...CurrencyAmountConnectionFragment
    }
    balances {
      ...CurrencyAmountConnectionFragment
    }
    childBalance
    childBalanceChange
    childBalanceChanges {
      ...CurrencyAmountConnectionFragment
    }
    childBalances {
      ...CurrencyAmountConnectionFragment
    }
    childLedgerAccounts {
      ...LedgerAccountsConnectionFragment
    }
    consistencyConfig {
      ...LedgerAccountConsistencyConfigFragment
    }
    created
    currency {
      ...CurrencyFragment
    }
    currencyMode
    dashboardUrl
    id
    ik
    ledger {
      ...LedgerFragment
    }
    ledgerId
    lines {
      ...LedgerLinesConnectionFragment
    }
    link {
      ...LinkFragment
    }
    linkedAccount {
      ...ExternalAccountFragment
    }
    name
    ownBalance
    ownBalanceChange
    ownBalanceChanges {
      ...CurrencyAmountConnectionFragment
    }
    ownBalances {
      ...CurrencyAmountConnectionFragment
    }
    parentLedgerAccount {
      ...LedgerAccountFragment
    }
    parentLedgerAccountId
    path
    type
    unreconciledTxs {
      ...TxsConnectionFragment
    }
    workspaceId
  }
}

Variables
{"ledgerAccount": LedgerAccountMatchInput}

Response
{
  "data": {
    "ledgerAccount": {
      "balance": "999999999999",
      "balanceChange": "999999999999",
      "balanceChanges": CurrencyAmountConnection,
      "balances": CurrencyAmountConnection,
      "childBalance": "999999999999",
      "childBalanceChange": "999999999999",
      "childBalanceChanges": CurrencyAmountConnection,
      "childBalances": CurrencyAmountConnection,
      "childLedgerAccounts": LedgerAccountsConnection,
      "consistencyConfig": LedgerAccountConsistencyConfig,
      "created": "2007-12-03T10:15:30Z",
      "currency": Currency,
      "currencyMode": "multi",
      "dashboardUrl": "abc123",
      "id": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
      "ik": "abc123",
      "ledger": Ledger,
      "ledgerId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
      "lines": LedgerLinesConnection,
      "link": Link,
      "linkedAccount": ExternalAccount,
      "name": "abc123",
      "ownBalance": "999999999999",
      "ownBalanceChange": "999999999999",
      "ownBalanceChanges": CurrencyAmountConnection,
      "ownBalances": CurrencyAmountConnection,
      "parentLedgerAccount": LedgerAccount,
      "parentLedgerAccountId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
      "path": "abc123",
      "type": "asset",
      "unreconciledTxs": TxsConnection,
      "workspaceId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1"
    }
  }
}

Arguments
Name Description
ledgerAccount - LedgerAccountMatchInput! An object specifying the ID of the ledger account you want to query

ledgerEntry

#

Get Ledger Entry by ID.

Response

Returns a LedgerEntry

Query
query LedgerEntry($ledgerEntry: LedgerEntryMatchInput!) {
  ledgerEntry(ledgerEntry: $ledgerEntry) {
    conditions {
      ...LedgerEntryConditionFragment
    }
    created
    dashboardUrl
    date
    description
    groups {
      ...LedgerEntryGroupFragment
    }
    id
    ik
    ledger {
      ...LedgerFragment
    }
    ledgerId
    lines {
      ...LedgerLinesConnectionFragment
    }
    parameters
    posted
    tags {
      ...LedgerEntryTagFragment
    }
    type
    workspaceId
  }
}

Variables
{"ledgerEntry": LedgerEntryMatchInput}

Response
{
  "data": {
    "ledgerEntry": {
      "conditions": [LedgerEntryCondition],
      "created": "2007-12-03T10:15:30Z",
      "dashboardUrl": "abc123",
      "date": "2022-03-28",
      "description": "abc123",
      "groups": [LedgerEntryGroup],
      "id": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
      "ik": "abc123",
      "ledger": Ledger,
      "ledgerId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
      "lines": LedgerLinesConnection,
      "parameters": {"bank_name": "bank-name", "deposit_amount": "10000"},
      "posted": "2007-12-03T10:15:30Z",
      "tags": [LedgerEntryTag],
      "type": "some-safe-string-ik",
      "workspaceId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1"
    }
  }
}

Arguments
Name Description
ledgerEntry - LedgerEntryMatchInput! An object specifying the ID of the Ledger Entry you want to query.

ledgerEntryGroup

#

Query a Ledger Entry Group given its Ledger, key, and value.

Response

Returns a LedgerEntryGroup

Query
query LedgerEntryGroup($ledgerEntryGroup: LedgerEntryGroupMatchInput!) {
  ledgerEntryGroup(ledgerEntryGroup: $ledgerEntryGroup) {
    balances {
      ...LedgerEntryGroupBalanceConnectionFragment
    }
    created
    dashboardUrl
    key
    ledger {
      ...LedgerFragment
    }
    ledgerEntries {
      ...LedgerEntriesConnectionFragment
    }
    ledgerId
    value
  }
}

Variables
{"ledgerEntryGroup": LedgerEntryGroupMatchInput}

Response
{
  "data": {
    "ledgerEntryGroup": {
      "balances": LedgerEntryGroupBalanceConnection,
      "created": "2007-12-03T10:15:30Z",
      "dashboardUrl": "abc123",
      "key": "some-safe-string-ik",
      "ledger": Ledger,
      "ledgerEntries": LedgerEntriesConnection,
      "ledgerId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
      "value": "some-safe-string-ik"
    }
  }
}

Arguments
Name Description
ledgerEntryGroup - LedgerEntryGroupMatchInput!

ledgerLine

#

Get LedgerLine by ID

Response

Returns a LedgerLine

Query
query LedgerLine($ledgerLine: LedgerLineMatchInput!) {
  ledgerLine(ledgerLine: $ledgerLine) {
    account {
      ...LedgerAccountFragment
    }
    accountId
    amount
    created
    currency {
      ...CurrencyFragment
    }
    date
    description
    externalTransferId
    externalTransferType
    externalTxId
    id
    key
    ledger {
      ...LedgerFragment
    }
    ledgerEntry {
      ...LedgerEntryFragment
    }
    ledgerEntryId
    ledgerId
    otherTxExternalAccountExternalId
    otherTxExternalAccountId
    otherTxExternalId
    otherTxId
    posted
    tx {
      ...TxFragment
    }
    txId
    type
    workspaceId
  }
}

Variables
{"ledgerLine": LedgerLineMatchInput}

Response
{
  "data": {
    "ledgerLine": {
      "account": LedgerAccount,
      "accountId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
      "amount": "999999999999",
      "created": "2007-12-03T10:15:30Z",
      "currency": Currency,
      "date": "2022-03-28",
      "description": "abc123",
      "externalTransferId": "abc123",
      "externalTransferType": "ach",
      "externalTxId": "abc123",
      "id": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
      "key": "abc123",
      "ledger": Ledger,
      "ledgerEntry": LedgerEntry,
      "ledgerEntryId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
      "ledgerId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
      "otherTxExternalAccountExternalId": "abc123",
      "otherTxExternalAccountId": "abc123",
      "otherTxExternalId": "abc123",
      "otherTxId": "abc123",
      "posted": "2007-12-03T10:15:30Z",
      "tx": Tx,
      "txId": "abc123",
      "type": "credit",
      "workspaceId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1"
    }
  }
}

Arguments
Name Description
ledgerLine - LedgerLineMatchInput! An object specifying the ID of the LedgerLine you want to query

ledgers

#

Query Ledgers in workspace. Ledgers are paginated and returned in reverse-chronological order by their created date.

Response

Returns a LedgersConnection!

Query
query Ledgers(
  $after: String,
  $before: String,
  $filter: LedgersFilterSet,
  $first: Int,
  $last: Int
) {
  ledgers(
    after: $after,
    before: $before,
    filter: $filter,
    first: $first,
    last: $last
  ) {
    nodes {
      ...LedgerFragment
    }
    pageInfo {
      ...PageInfoFragment
    }
  }
}

Variables
{
  "after": "abc123",
  "before": "abc123",
  "filter": LedgersFilterSet,
  "first": 2277,
  "last": 2277
}

Response
{
  "data": {
    "ledgers": {
      "nodes": [Ledger],
      "pageInfo": PageInfo
    }
  }
}

Arguments
Name Description
after - String Where to start paginating from, when paginating forwards. Send endCursor from a response to get its next page. Learn more about pagination .
before - String Where to start paginating from, when paginating backwards. Send startCursor from a response to get the previous page. Learn more about pagination .
filter - LedgersFilterSet Filter the Ledgers returned. Learn more about querying Ledgers .
first - Int The number of Ledgers to return per page, when paginating forwards. Defaults to 20, maximum is 200.
last - Int The number of Ledgers to return per page, when paginating backwards. Defaults to 20, maximum is 200.

schema

#

Get a Schema by key.

Response

Returns a Schema

Query
query Schema($schema: SchemaMatchInput!) {
  schema(schema: $schema) {
    key
    ledgers {
      ...LedgersConnectionFragment
    }
    name
    version {
      ...SchemaVersionFragment
    }
    versions {
      ...SchemaVersionConnectionFragment
    }
  }
}

Variables
{"schema": SchemaMatchInput}

Response
{
  "data": {
    "schema": {
      "key": "some-safe-string-ik",
      "ledgers": LedgersConnection,
      "name": "abc123",
      "version": SchemaVersion,
      "versions": SchemaVersionConnection
    }
  }
}

Arguments
Name Description
schema - SchemaMatchInput! This contains the key of the Schema you want to retrieve.

schemas

#

Retrieve all of the Schemas in the workspace.

Response

Returns a SchemaConnection!

Query
query Schemas(
  $after: String,
  $before: String,
  $first: Int,
  $last: Int
) {
  schemas(
    after: $after,
    before: $before,
    first: $first,
    last: $last
  ) {
    nodes {
      ...SchemaFragment
    }
    pageInfo {
      ...PageInfoFragment
    }
  }
}

Variables
{"after": "abc123", "before": "abc123", "first": 2277, "last": 2277}

Response
{
  "data": {
    "schemas": {
      "nodes": [Schema],
      "pageInfo": PageInfo
    }
  }
}

Arguments
Name Description
after - String Where to start paginating from, when paginating forwards. Send endCursor from a response to get its next page. Learn more about pagination .
before - String Where to start paginating from, when paginating backwards. Send startCursor from a response to get the previous page. Learn more about pagination .
first - Int The number of schemas to return per page, when paginating forwards. Defaults to 20, maximum is 200.
last - Int The number of schemas to return per page, when paginating backwards. Defaults to 20, maximum is 200.

tx

#

Get a Tx by ID

Response

Returns a Tx

Query
query Tx($tx: TxMatchInput!) {
  tx(tx: $tx) {
    accountId
    amount
    currency {
      ...CurrencyFragment
    }
    date
    description
    externalAccount {
      ...ExternalAccountFragment
    }
    externalAccountId
    externalId
    id
    ledgerEntries {
      ...LedgerEntriesConnectionFragment
    }
    ledgerEntryIds
    ledgerLineIds
    ledgerLines {
      ...LedgerLinesConnectionFragment
    }
    link {
      ...LinkFragment
    }
    linkId
    posted
    workspaceId
  }
}

Variables
{"tx": TxMatchInput}

Response
{
  "data": {
    "tx": {
      "accountId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
      "amount": "999999999999",
      "currency": Currency,
      "date": "2022-03-28",
      "description": "abc123",
      "externalAccount": ExternalAccount,
      "externalAccountId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
      "externalId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
      "id": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
      "ledgerEntries": LedgerEntriesConnection,
      "ledgerEntryIds": ["3116551f-5efc-4c9e-84ac-5a36a51b09c1"],
      "ledgerLineIds": ["3116551f-5efc-4c9e-84ac-5a36a51b09c1"],
      "ledgerLines": LedgerLinesConnection,
      "link": Link,
      "linkId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
      "posted": "2007-12-03T10:15:30Z",
      "workspaceId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1"
    }
  }
}

Arguments
Name Description
tx - TxMatchInput! The transaction you're querying. You can specify either: * The FRAGMENT ID of the transaction (id) * The external system's transaction ID (externalId) and FRAGMENT ID of the external account (accountId) * The external system's transaction ID (externalId), the external system's account ID (externalAccountId) and FRAGMENT ID of the Link (linkId)

workspace

#

Get the current Workspace

Response

Returns a Workspace!

Query
query Workspace {
  workspace {
    id
    name
  }
}


Response
{"data": {"workspace": {"id": "abc123", "name": "abc123"}}}

Arguments
C API Mutations#

addLedgerEntry

#

Adds a Ledger Entry to a Ledger. This Ledger Entry cannot be into a Linked Ledger Account. For that, use reconcileTx

Response

Returns an AddLedgerEntryResponse!

Query
mutation AddLedgerEntry(
  $entry: LedgerEntryInput!,
  $ik: SafeString!
) {
  addLedgerEntry(
    entry: $entry,
    ik: $ik
  ) {
    ... on AddLedgerEntryResult {
      ...AddLedgerEntryResultFragment
    }
    ... on BadRequestError {
      ...BadRequestErrorFragment
    }
    ... on InternalError {
      ...InternalErrorFragment
    }
  }
}

Variables
{"entry": LedgerEntryInput, "ik": "some-safe-string-ik"}

Response
{"data": {"addLedgerEntry": AddLedgerEntryResult}}

Arguments
Name Description
entry - LedgerEntryInput! An object containing the Ledger Lines as well as an optional description and posted timestamp.
ik - SafeString! The Idempotency Key

createCustomCurrency

#

Creates a custom currency.

Response

Returns a CreateCustomCurrencyResponse!

Query
mutation CreateCustomCurrency($customCurrency: CreateCustomCurrencyInput!) {
  createCustomCurrency(customCurrency: $customCurrency) {
    ... on BadRequestError {
      ...BadRequestErrorFragment
    }
    ... on CreateCustomCurrencyResult {
      ...CreateCustomCurrencyResultFragment
    }
    ... on InternalError {
      ...InternalErrorFragment
    }
  }
}

Variables
{"customCurrency": CreateCustomCurrencyInput}

Response
{"data": {"createCustomCurrency": BadRequestError}}

Arguments
Name Description
customCurrency - CreateCustomCurrencyInput! The custom currency to be created.

createLedger

#

Creates a Ledger.

Response

Returns a CreateLedgerResponse!

Query
mutation CreateLedger(
  $ik: SafeString!,
  $ledger: CreateLedgerInput!,
  $schema: SchemaMatchInput
) {
  createLedger(
    ik: $ik,
    ledger: $ledger,
    schema: $schema
  ) {
    ... on BadRequestError {
      ...BadRequestErrorFragment
    }
    ... on CreateLedgerResult {
      ...CreateLedgerResultFragment
    }
    ... on InternalError {
      ...InternalErrorFragment
    }
  }
}

Variables
{
  "ik": "some-safe-string-ik",
  "ledger": CreateLedgerInput,
  "schema": SchemaMatchInput
}

Response
{"data": {"createLedger": BadRequestError}}

Arguments
Name Description
ik - SafeString! The Idempotency Key
ledger - CreateLedgerInput! The payload representing the Ledger to be created
schema - SchemaMatchInput The Schema to create this Ledger with

reconcileTx

#

This mutation is used to reconcile transactions from an external system into a Ledger Entry. This mutation does not require an idempotency key since a transaction can only be reconciled once per Linked Ledger Account. If you are reconciling a transfer between two Link Accounts which are both linked to the same Ledger, use a transit account in between to split the transfer into two reconcileTx calls.

Response

Returns a ReconcileTxResponse!

Query
mutation ReconcileTx($entry: LedgerEntryInput!) {
  reconcileTx(entry: $entry) {
    ... on BadRequestError {
      ...BadRequestErrorFragment
    }
    ... on InternalError {
      ...InternalErrorFragment
    }
    ... on ReconcileTxResult {
      ...ReconcileTxResultFragment
    }
  }
}

Variables
{"entry": LedgerEntryInput}

Response
{"data": {"reconcileTx": BadRequestError}}

Arguments
Name Description
entry - LedgerEntryInput! The ledger entry containing lines that specify the transaction from a linked ledger account to reconcile, as well as the ledger account with which to offset the external transaction.

storeSchema

#

Stores a Schema in your workspace. If no Schema with the same key exists in your worksapce, a new Schema is created. Else, the Schema is updated, and every Ledger associated with it is migrated to the latest version.

Response

Returns a StoreSchemaResponse!

Query
mutation StoreSchema($schema: SchemaInput!) {
  storeSchema(schema: $schema) {
    ... on BadRequestError {
      ...BadRequestErrorFragment
    }
    ... on InternalError {
      ...InternalErrorFragment
    }
    ... on StoreSchemaResult {
      ...StoreSchemaResultFragment
    }
  }
}

Variables
{"schema": SchemaInput}

Response
{"data": {"storeSchema": BadRequestError}}

Arguments
Name Description
schema - SchemaInput! The Schema to store.

syncCustomAccounts

#

Once you've created a Custom Link, create accounts under it using this mutation. Each Custom Account is an immutable, single-entry view of all the transactions in the external account. You can sync up to 100 Custom Accounts in one API call.

Response

Returns a SyncCustomAccountsResponse!

Query
mutation SyncCustomAccounts(
  $accounts: [CustomAccountInput!]!,
  $link: LinkMatchInput!
) {
  syncCustomAccounts(
    accounts: $accounts,
    link: $link
  ) {
    ... on BadRequestError {
      ...BadRequestErrorFragment
    }
    ... on InternalError {
      ...InternalErrorFragment
    }
    ... on SyncCustomAccountsResult {
      ...SyncCustomAccountsResultFragment
    }
  }
}

Variables
{
  "accounts": [CustomAccountInput],
  "link": LinkMatchInput
}

Response
{"data": {"syncCustomAccounts": BadRequestError}}

Arguments
Name Description
accounts - [CustomAccountInput!]! A list of external accounts to sync
link - LinkMatchInput! An object containing the ID of a Custom Link.

syncCustomTxs

#

You can create transactions under a Custom Account in a Custom Link using this mutation. Once you've imported transactions, you can use the reconcileTx mutation to add them to a Ledger via the Linked Ledger Account. You can sync up to 100 Custom Transactions in one API call.

Response

Returns a SyncCustomTxsResponse!

Query
mutation SyncCustomTxs(
  $link: LinkMatchInput!,
  $txs: [CustomTxInput!]!
) {
  syncCustomTxs(
    link: $link,
    txs: $txs
  ) {
    ... on BadRequestError {
      ...BadRequestErrorFragment
    }
    ... on InternalError {
      ...InternalErrorFragment
    }
    ... on SyncCustomTxsResult {
      ...SyncCustomTxsResultFragment
    }
  }
}

Variables
{
  "link": LinkMatchInput,
  "txs": [CustomTxInput]
}

Response
{"data": {"syncCustomTxs": BadRequestError}}

Arguments
Name Description
link - LinkMatchInput! An object containing the ID of a Custom Link.
txs - [CustomTxInput!]! A list of external transactions to sync

updateLedger

#

Updates a Ledger. Currently, you can change only the Ledger 'name'.

Response

Returns an UpdateLedgerResponse!

Query
mutation UpdateLedger(
  $ledger: LedgerMatchInput!,
  $update: UpdateLedgerInput!
) {
  updateLedger(
    ledger: $ledger,
    update: $update
  ) {
    ... on BadRequestError {
      ...BadRequestErrorFragment
    }
    ... on InternalError {
      ...InternalErrorFragment
    }
    ... on UpdateLedgerResult {
      ...UpdateLedgerResultFragment
    }
  }
}

Variables
{
  "ledger": LedgerMatchInput,
  "update": UpdateLedgerInput
}

Response
{"data": {"updateLedger": BadRequestError}}

Arguments
Name Description
ledger - LedgerMatchInput! An object containing the ID of the Ledger to update.
update - UpdateLedgerInput! A payload of fields to update. Currently, you can change only the Ledger 'name'.

updateLedgerEntry

#

Update a ledger entry

Response

Returns an UpdateLedgerEntryResponse!

Query
mutation UpdateLedgerEntry(
  $ledgerEntry: LedgerEntryMatchInput!,
  $update: UpdateLedgerEntryInput!
) {
  updateLedgerEntry(
    ledgerEntry: $ledgerEntry,
    update: $update
  ) {
    ... on BadRequestError {
      ...BadRequestErrorFragment
    }
    ... on InternalError {
      ...InternalErrorFragment
    }
    ... on UpdateLedgerEntryResult {
      ...UpdateLedgerEntryResultFragment
    }
  }
}

Variables
{
  "ledgerEntry": LedgerEntryMatchInput,
  "update": UpdateLedgerEntryInput
}

Response
{"data": {"updateLedgerEntry": BadRequestError}}

Arguments
Name Description
ledgerEntry - LedgerEntryMatchInput! The Ledger Entry that is being updated
update - UpdateLedgerEntryInput! The payload containing the fields to update. Only a Ledger Entry's tags can be updated.
D API Types#

Core Types

#

ExternalAccount#

Example
{
  "currency": Currency,
  "currencyMode": "multi",
  "externalId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
  "id": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
  "ledgerAccounts": LedgerAccountsConnection,
  "link": Link,
  "linkId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
  "name": "abc123",
  "txs": TxsConnection
}

Field Name Description
currency - Currency The currency of this external account.
currencyMode - CurrencyMode! Indicates if the account allows multiple currencies or is restricted to a single currency
externalId - ID! ID used for the external account
id - ID! FRAGMENT ID of External Account
ledgerAccounts - LedgerAccountsConnection! Ledger Accounts linked to this External Account. Ledger Accounts are paginated and sorted in reverse-chronological order by created date.
Arguments

after - String

Where to start paginating from, when paginating forwards. Send endCursor from a response to get its next page. Learn more about pagination.

before - String

Where to start paginating from, when paginating backwards. Send startCursor from a response to get the previous page. Learn more about pagination.

first - Int

The number of Ledger Accounts to return per page, when paginating forwards. Defaults to 20, maximum is 200.

last - Int

The number of Ledger Accounts to return per page, when paginating backwards. Defaults to 20, maximum is 200.
link - Link! The Link that this External Account belongs to.
linkId - ID! FRAGMENT ID of this transaction's external link
name - String!
txs - TxsConnection! All Txs in this External Account.
Arguments

after - String

Where to start paginating from, when paginating forwards. Send endCursor from a response to get its next page. Learn more about pagination.

before - String

Where to start paginating from, when paginating backwards. Send startCursor from a response to get the previous page. Learn more about pagination.

first - Int

The number of transactions to return per page, when paginating forwards. Defaults to 20, maximum is 200.

last - Int

The number of transactions to return per page, when paginating backwards. Defaults to 20, maximum is 200.

Ledger#

Ledgers are databases designed for managing money


Example
{
  "balanceUTCOffset": "-08:00",
  "created": "2007-12-03T10:15:30Z",
  "dashboardUrl": "abc123",
  "id": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
  "ik": "some-safe-string-ik",
  "ledgerAccounts": LedgerAccountsConnection,
  "ledgerEntries": LedgerEntriesConnection,
  "ledgerEntryGroup": LedgerEntryGroup,
  "ledgerEntryGroups": LedgerEntryGroupsConnection,
  "migrations": LedgerMigrationConnection,
  "name": "abc123",
  "schema": Schema,
  "type": "double",
  "workspaceId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1"
}

Field Name Description
balanceUTCOffset - UTCOffset! When aggregating balances, all transactions within a 24 hour period starting at midnight UTC plus this offset are included in each day.
created - DateTime!
dashboardUrl - String! URL to the FRAGMENT Dashboard for this Ledger.
id - ID!
ik - SafeString! The IK passed into the createLedger mutation. This is treated as a unique identifier for this Ledger.
ledgerAccounts - LedgerAccountsConnection! Query LedgerAccounts in Ledger. Ledger Accounts are paginated and returned in reverse-chronological order by their created date.
Arguments

after - String

Where to start paginating from, when paginating forwards. Send endCursor from a response to get its next page. Learn more about pagination.

before - String

Where to start paginating from, when paginating backwards. Send startCursor from a response to get the previous page. Learn more about pagination.

filter - LedgerAccountsFilterSet

Filter the Ledger Accounts returned. Learn more about querying Ledger Accounts.

first - Int

The number of Ledger Accounts to return per page, when paginating forwards. Defaults to 20, maximum is 200.

last - Int

The number of Ledger Accounts to return per page, when paginating backwards. Defaults to 20, maximum is 200.
ledgerEntries - LedgerEntriesConnection! Query Ledger Entries in a Ledger. Ledger Entries are paginated and sorted in reverse-chronological order by posted date.
Arguments

after - String

Where to start paginating from, when paginating forwards. Send endCursor from a response to get its next page. Learn more about pagination.

before - String

Where to start paginating from, when paginating backwards. Send startCursor from a response to get the previous page. Learn more about pagination.

filter - LedgerEntriesFilterSet

Filter the Ledger Entries returned. Learn more about querying Ledger Entries.

first - Int

The number of Ledger Entries to return per page, when paginating forwards. Defaults to 20, maximum is 200.

last - Int

The number of Ledger Entries to return per page, when paginating backwards. Defaults to 20, maximum is 200.
ledgerEntryGroup - LedgerEntryGroup! Query a Ledger Entry Group for this Ledger given its key and value.
Arguments

ledgerEntryGroup - EntryGroupMatchInput!
ledgerEntryGroups - LedgerEntryGroupsConnection! Query LedgerEntryGroups in Ledger. Ledger Entry Groups are paginated and returned in order lexigraphically key then inverse chronologically by created.
Arguments

after - String

Where to start paginating from, when paginating forwards. Send endCursor from a response to get its next page. Learn more about pagination.

before - String

Where to start paginating from, when paginating backwards. Send startCursor from a response to get the previous page. Learn more about pagination.

filter - LedgerEntryGroupsFilterSet

Filter the Ledger Entry Groups returned.

first - Int

The number of Ledger Entry Groups to return per page, when paginating forwards. Defaults to 20, maximum is 200.

last - Int

The number of Ledger Entry Groups to return per page, when paginating backwards. Defaults to 20, maximum is 200.
migrations - LedgerMigrationConnection! Schema migrations affecting this Ledger.
name - String! The name of the Ledger. Can be updated with the updateLedger mutation.
schema - Schema Schema key associated with this Ledger.
type - LedgerTypes!
workspaceId - ID! Callers should not need to query or store this value.

LedgerAccount#

A ledger account is a container for money


Example
{
  "balance": "999999999999",
  "balanceChange": "999999999999",
  "balanceChanges": CurrencyAmountConnection,
  "balances": CurrencyAmountConnection,
  "childBalance": "999999999999",
  "childBalanceChange": "999999999999",
  "childBalanceChanges": CurrencyAmountConnection,
  "childBalances": CurrencyAmountConnection,
  "childLedgerAccounts": LedgerAccountsConnection,
  "consistencyConfig": LedgerAccountConsistencyConfig,
  "created": "2007-12-03T10:15:30Z",
  "currency": Currency,
  "currencyMode": "multi",
  "dashboardUrl": "abc123",
  "id": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
  "ik": "abc123",
  "ledger": Ledger,
  "ledgerId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
  "lines": LedgerLinesConnection,
  "link": Link,
  "linkedAccount": ExternalAccount,
  "name": "abc123",
  "ownBalance": "999999999999",
  "ownBalanceChange": "999999999999",
  "ownBalanceChanges": CurrencyAmountConnection,
  "ownBalances": CurrencyAmountConnection,
  "parentLedgerAccount": LedgerAccount,
  "parentLedgerAccountId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
  "path": "abc123",
  "type": "asset",
  "unreconciledTxs": TxsConnection,
  "workspaceId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1"
}

Field Name Description
balance - Int96! Total of all lines in this ledger account and child ledger accounts of the same currency as this ledger account
Arguments

at - LastMoment

Provide a timestamp to get this balance at a specific logical time. If not specified, the latest value will be returned e.g. 1969 or 1969-07 or 1969-07-03 or 1969-07-21T02

currency - CurrencyMatchInput

The currency of the balance to query. Required if the account is a multi-currency Ledger Account or if the the Ledger Account has child Ledger Accounts with different currencies.
balanceChange - Int96! How much did the this ledger account's balance change during the specified period. This query will include all child accounts in the same currency as this ledger account.
Arguments

currency - CurrencyMatchInput

The currency of the balance change to query. Required if the account is a multi-currency Ledger Account or if the the Ledger Account has child Ledger Accounts with different currencies.

period - Period!

Specifies the period of time over which this query will calculate the balance difference e.g. 1969 or 1969-Q3 or 1969-07 or 1969-07-21 or 1969-07-21T02
balanceChanges - CurrencyAmountConnection! How much did the this ledger account's balances change during the specified period. This query will include all child accounts of all currencies.
Arguments

period - Period!

Specifies the period of time over which this query will calculate the balance difference e.g. 1969 or 1969-Q3 or 1969-07 or 1969-07-21 or 1969-07-21T02
balances - CurrencyAmountConnection! Total of all lines in this ledger account and child ledger accounts in all currencies
Arguments

at - LastMoment

Provide a timestamp to get this balance at a specific logical time. If not specified, the latest value will be returned e.g. 1969 or 1969-07 or 1969-07-21 or 1969-07-21T02
childBalance - Int96! Total of all lines in child ledger accounts of the same currency as this ledger account
Arguments

at - LastMoment

Provide a timestamp to get this balance at a specific logical time. If not specified, the latest value will be returned e.g. 1969 or 1969-07 or 1969-07-21 or 1969-07-21T02

currency - CurrencyMatchInput

The currency of the balance to query. Required if the Ledger Account has child Ledger Accounts with different currencies.
childBalanceChange - Int96! How much did the this ledger account's childBalance change during the specified period. This query will only include child accounts which are in the same currency as this one. See childBalanceChanges to include children of different currencies.
Arguments

currency - CurrencyMatchInput

The currency of the balance change to query. Required if the Ledger Account has child Ledger Accounts with different currencies.

period - Period!

Specifies the period of time over which this query will calculate the balance difference e.g. 1969 or 1969-Q3 or 1969-07 or 1969-07-21 or 1969-07-21T02.
childBalanceChanges - CurrencyAmountConnection! How much did the this ledger account's child accounts' balances change during the specified period. This query will include all child accounts of all currencies.
Arguments

period - Period!

Specifies the period of time over which this query will calculate the balance difference e.g. 1969 or 1969-Q3 or 1969-07 or 1969-07-21 or 1969-07-21T02
childBalances - CurrencyAmountConnection! Total of all lines in child ledger accounts of this ledger in all currencies
Arguments

at - LastMoment

Provide a timestamp to get this balance at a specific logical time. If not specified, the latest value will be returned e.g. 1969 or 1969-07 or 1969-07-21 or 1969-07-21T02
childLedgerAccounts - LedgerAccountsConnection! The child Ledger Accounts of this Ledger Accountw
Arguments

after - String

Where to start paginating from, when paginating forwards. Send endCursor from a response to get its next page. Learn more about pagination.

before - String

Where to start paginating from, when paginating backwards. Send startCursor from a response to get the previous page. Learn more about pagination.

first - Int

The number of Child Ledger Accounts to return per page, when paginating forwards. Defaults to 20, maximum is 200.

last - Int

The number of Child Ledger Accounts to return per page, when paginating backwards. Defaults to 20, maximum is 200.
consistencyConfig - LedgerAccountConsistencyConfig! The consistency configuration for this Ledger Account. This defines how updates to this Ledger Account's ownBalance are handled.
created - DateTime!
currency - Currency Currency of this ledger account
currencyMode - CurrencyMode! Indicates if the account allows multiple currencies or is restricted to a single currency
dashboardUrl - String! URL to the FRAGMENT Dashboard for this Ledger Account.
id - ID!
ik - String! The idempotency key used to create this account
ledger - Ledger! Ledger this account is in
ledgerId - ID! ID of the ledger this account is in
lines - LedgerLinesConnection! List Ledger Lines in this account, sorted by posted in reverse chronological order. Does not include Ledger Lines from child Ledger Accounts.
Arguments

after - String

Where to start paginating from, when paginating forwards. Send endCursor from a response to get its next page. Learn more about pagination.

before - String

Where to start paginating from, when paginating backwards. Send startCursor from a response to get the previous page. Learn more about pagination.

filter - LedgerLinesFilterSet

Filter the Ledger Lines returned. Learn more about querying Ledger Lines.

first - Int

The number of Ledger Lines to return per page, when paginating forwards. Defaults to 20, maximum is 200.

last - Int

The number of Ledger Lines to return per page, when paginating backwards. Defaults to 20, maximum is 200.
link - Link The Link for the External Account that is linked to this ledger account
linkedAccount - ExternalAccount External Account that is linked to this ledger account
name - String The name of your Ledger Account
ownBalance - Int96! Total of all lines in this ledger account, excluding all child ledger accounts
Arguments

at - LastMoment

Provide a timestamp to get this balance at a specific logical time. If not specified, the latest value will be returned e.g. 1969 or 1969-07 or 1969-07-21 or 1969-07-21T02

consistencyMode - ReadBalanceConsistencyMode

* eventual: Returns an eventually consistent balance, even if the Ledger Account's ownBalanceUpdates in its consistencyConfig is strong (default).
* strong: Returns a strongly consistent balance or an error if the Ledger Account's ownBalanceUpdates in its consistencyConfig is eventual.
* use_account: Returns a strongly consistent balance if the Ledger Account's ownBalanceUpdates in its consistencyConfig is strong and an eventually consistent balance otherwise.

currency - CurrencyMatchInput

The currency of the balance to query. Required if the account is a multi-currency Ledger Account.
ownBalanceChange - Int96! How much did the this ledger account's ownBalance change during the specified period. This query will exclude all child accounts.
Arguments

currency - CurrencyMatchInput

The currency of the balance change to query. Required if the account is a multi-currency Ledger Account.

period - Period!

Specifies the period of time over which this query will calculate the balance difference e.g. 1969 or 1969-Q3 or 1969-07 or 1969-07-21 or 1969-07-21T02
ownBalanceChanges - CurrencyAmountConnection! How much did the this ledger account's ownBalance change during the specified period. This is the total of all lines in this ledger account, excluding all child ledger accounts
Arguments

period - Period!

Specifies the period of time over which this query will calculate the balance difference e.g. 1969 or 1969-Q3 or 1969-07 or 1969-07-21 or 1969-07-21T02
ownBalances - CurrencyAmountConnection! Total of all lines across all currencies in this ledger account, excluding all child ledger accounts
Arguments

at - LastMoment

Provide a timestamp to get this balance at a specific logical time. If not specified, the latest value will be returned e.g. 1969 or 1969-07 or 1969-07-21 or 1969-07-21T02

consistencyMode - ReadBalanceConsistencyMode

* eventual: Returns an eventually consistent balance, even if the Ledger Account's ownBalanceUpdates in its consistencyConfig is strong (default).
* strong: Returns a strongly consistent balance or an error if the Ledger Account's ownBalanceUpdates in its consistencyConfig is eventual.
* use_account: Returns a strongly consistent balance if the Ledger Account's ownBalanceUpdates in its consistencyConfig is strong and an eventually consistent balance otherwise.
parentLedgerAccount - LedgerAccount The parent ledger account of this ledger account
parentLedgerAccountId - ID ID of the parent ledger account of this ledger account
path - String! The unique Path of the ledger account. This is a slash-delimited string containing the location of an account in its chart of accounts. For accounts created with a schema, this will be composed of account keys. Else, for accounts created with the createLedgerAccounts API, this will be composed of the IKs of an account and its ancestors.
type - LedgerAccountTypes!
unreconciledTxs - TxsConnection! A list of external account transactions that haven't been reconciled to this ledger account yet. Only populated for linked ledger accounts. Transactions are sorted in reverse chronological order by posted date.
Arguments

after - String

Where to start paginating from, when paginating forwards. Send endCursor from a response to get its next page. Learn more about pagination.

before - String

Where to start paginating from, when paginating backwards. Send startCursor from a response to get the previous page. Learn more about pagination.

first - Int

The number of unreconciled transactions to return per page, when paginating forwards. Defaults to 20, maximum is 200.

last - Int

The number of unreconciled transactions to return per page, when paginating backwards. Defaults to 20, maximum is 200.
workspaceId - ID! Callers should not need to query or store this value.

LedgerEntry#

Example
{
  "conditions": [LedgerEntryCondition],
  "created": "2007-12-03T10:15:30Z",
  "dashboardUrl": "abc123",
  "date": "2022-03-28",
  "description": "abc123",
  "groups": [LedgerEntryGroup],
  "id": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
  "ik": "abc123",
  "ledger": Ledger,
  "ledgerId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
  "lines": LedgerLinesConnection,
  "parameters": {"bank_name": "bank-name", "deposit_amount": "10000"},
  "posted": "2007-12-03T10:15:30Z",
  "tags": [LedgerEntryTag],
  "type": "some-safe-string-ik",
  "workspaceId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1"
}

Field Name Description
conditions - [LedgerEntryCondition!]! The conditions that were satisfied by this Ledger Entry when it was posted.
created - DateTime! ISO-8601 timestamp this LedgerEntry was created in FRAGMENT .
dashboardUrl - String! URL to the FRAGMENT Dashboard for this Ledger Entry.
date - Date! Date this LedgerEntry posted to its Ledger e.g. "2021-01-01".
description - String Description posted for this Ledger Entry.
groups - [LedgerEntryGroup!]! The Ledger Entry Groups this Ledger Entry is in.
id - ID! The ID of this LedgerEntry.
ik - String! The idempotency key used to post this ledger entry
ledger - Ledger! The Ledger that this Ledger Entry is posted to.
ledgerId - ID! The ID of the Ledger this Ledger Entry is posted to.
lines - LedgerLinesConnection! Lines posted in this Ledger Entry.
parameters - Parameters The parameters used to post this Ledger Entry.
posted - DateTime! ISO-8601 timestamp this LedgerEntry posted to its Ledger.
tags - [LedgerEntryTag!]! The set of tags attached to this Ledger Entry.
type - SafeString The type of the Ledger Entry.
workspaceId - ID! Callers should not need to query or store this value.

LedgerLine#

Example
{
  "account": LedgerAccount,
  "accountId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
  "amount": "999999999999",
  "created": "2007-12-03T10:15:30Z",
  "currency": Currency,
  "date": "2022-03-28",
  "description": "abc123",
  "externalTransferId": "abc123",
  "externalTransferType": "ach",
  "externalTxId": "abc123",
  "id": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
  "key": "abc123",
  "ledger": Ledger,
  "ledgerEntry": LedgerEntry,
  "ledgerEntryId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
  "ledgerId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
  "otherTxExternalAccountExternalId": "abc123",
  "otherTxExternalAccountId": "abc123",
  "otherTxExternalId": "abc123",
  "otherTxId": "abc123",
  "posted": "2007-12-03T10:15:30Z",
  "tx": Tx,
  "txId": "abc123",
  "type": "credit",
  "workspaceId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1"
}

Field Name Description
account - LedgerAccount! LedgerAccount that contains this line
accountId - ID!
amount - Int96! How much this line's LedgerAccount's balance changed in integer cents (i.e. in USD 100 is 1 dollar, 100 cents)
Arguments

absolute - Boolean

If the absolute flag is passed, amount will always a positive integer in cents. Refer to type to see if this LedgerLine increased or decreased it's LedgerAccount's balance
created - DateTime ISO-8601 timestamp this LedgerLine was created in FRAGMENT
currency - Currency Currency of this LedgerLine
date - Date Date this LedgerLine posted to its LedgerAccount e.g. "2021-01-01"
description - String Description of this LedgerLine
externalTransferId - String ID in the external system of the payment or transfer that created the transaction linked to this LedgerLine
externalTransferType - ExternalTransferType Whether the transaction linked to this LedgerLine was a payment or transfer
externalTxId - String ID in the external system of the transaction linked to this LedgerLine
id - ID!
key - String
ledger - Ledger!
ledgerEntry - LedgerEntry LedgerEntry that contains this line
ledgerEntryId - ID ID of the LedgerEntry that contains this line
ledgerId - ID! Ledger that contains this line
otherTxExternalAccountExternalId - String ID in the external system of destination or source bank account for an internal bank transfer. Only for internal bank transfers - see otherTxId
otherTxExternalAccountId - String FRAGMENT ID of destination or source bank account. Only for internal bank transfers - see otherTxId
otherTxExternalId - String ID in the external system of transaction in the destination or source bank account. Only for internal bank transfers - see otherTxId
otherTxId - String FRAGMENT ID of the transaction in the destination account (if sending money from this account) or source account (if pulling money into this account). Only applicable if this line is linked to a transaction created through an internal transfer
posted - DateTime ISO-8601 timestamp this LedgerLine posted to its LedgerAccount
tx - Tx The transaction linked to this LedgerLine
txId - String FRAGMENT ID of the transaction linked to this LedgerLine
type - TxType! credit or debit
workspaceId - ID! Callers should not need to query or store this value.

LedgerMigration#

Represents a Schema being applied to a Ledger. It contains metadata about the Ledger, the Schema, and the status of the migration.


Example
{
  "ledger": Ledger,
  "schemaVersion": SchemaVersion,
  "status": "completed"
}

Field Name Description
ledger - Ledger! The Ledger that the migration is run on.
schemaVersion - SchemaVersion!
status - LedgerMigrationStatus! The status of the Ledger Migration.

Schema#

Example
{
  "key": "some-safe-string-ik",
  "ledgers": LedgersConnection,
  "name": "abc123",
  "version": SchemaVersion,
  "versions": SchemaVersionConnection
}

Field Name Description
key - SafeString! The identifier for a Schema. key is unique to a Workspace.
ledgers - LedgersConnection! The paginated list of ledgers the Schema has been applied to.
Arguments

after - String

Where to start paginating from, when paginating forwards. Send endCursor from a response to get its next page. Learn more about pagination.

before - String

Where to start paginating from, when paginating backwards. Send startCursor from a response to get the previous page. Learn more about pagination.

first - Int

The number of Ledgers to return per page, when paginating forwards. Defaults to 20, maximum is 200.

last - Int

The number of Ledgers to return per page, when paginating backwards. Defaults to 20, maximum is 200.
name - String! The name of a Schema. It defaults to the key if not provided in your SchemaInput.
version - SchemaVersion! The metadata for a specific SchemaVersion.
Arguments

version - Int

The version of the schema to retrieve. If this is not provided, the latest version will be returned.
versions - SchemaVersionConnection! A paginated list of SchemaVersions.
Arguments

after - String

Where to start paginating from, when paginating forwards. Send endCursor from a response to get its next page. Learn more about pagination.

before - String

Where to start paginating from, when paginating backwards. Send startCursor from a response to get the previous page. Learn more about pagination.

first - Int

The number of schema versions to return per page, when paginating forwards. Defaults to 20, maximum is 200.

last - Int

The number of schema versions to return per page, when paginating backwards. Defaults to 20, maximum is 200.

Tx#

Example
{
  "accountId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
  "amount": "999999999999",
  "currency": Currency,
  "date": "2022-03-28",
  "description": "abc123",
  "externalAccount": ExternalAccount,
  "externalAccountId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
  "externalId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
  "id": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
  "ledgerEntries": LedgerEntriesConnection,
  "ledgerEntryIds": ["3116551f-5efc-4c9e-84ac-5a36a51b09c1"],
  "ledgerLineIds": ["3116551f-5efc-4c9e-84ac-5a36a51b09c1"],
  "ledgerLines": LedgerLinesConnection,
  "link": Link,
  "linkId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
  "posted": "2007-12-03T10:15:30Z",
  "workspaceId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1"
}

Field Name Description
accountId - ID! FRAGMENT ID of this transaction's external account
amount - Int96! Integer amount in cents. Positive indicates money entering the external account, negative indicates money leaving
currency - Currency Currency of this Tx
date - Date! Date this Tx posted to the external account
description - String! Description at the external account (can be overridden within the FRAGMENT Dashboard)
externalAccount - ExternalAccount! The External Account that this transaction belongs to.
externalAccountId - ID! ID in the external system of this transaction's external account
externalId - ID! ID of this transaction in the external system
id - ID!
ledgerEntries - LedgerEntriesConnection! Returns ledger entries that are linked to this transaction. You can link the same external account to multiple ledgers, so there could be multipe entries associated with one transaction - one for each linked ledger account this transaction has been reconciled with
ledgerEntryIds - [ID!] Same as ledgerEntries, but returns an array of IDs instead
ledgerLineIds - [ID!] Same as ledgerLines, but returns an array of IDs instead
ledgerLines - LedgerLinesConnection! Returns ledger lines that are linked to this transaction. You can link the same external account to multiple ledgers, so there could be multipe lines associated with one transaction - one for each linked ledger account this transaction has been reconciled with
link - Link! This transaction's Link.
linkId - ID! FRAGMENT ID of this transaction's Link
posted - DateTime! ISO-8601 timestamp this Tx posted to the external account
workspaceId - ID! Callers should not need to query or store this value.

Workspace#

Example
{"id": "abc123", "name": "abc123"}

Field Name Description
id - String! The ID of the Workspace
name - String! The name of the Workspace

Scalars and Enums

#

BalanceUpdateConsistencyMode#

Used to configure the write-consistency of a Ledger Account's balance. See Configure consistency.


Example
"eventual"

Enum Value Description
eventual Eventually consistent balance updates.
strong Strongly consistent balance updates.

Boolean#

The Boolean scalar type represents true or false.


Example
true


Currency#

Example
{
  "code": "AAVE",
  "customCode": "abc123",
  "customCurrencyId": "some-safe-string-ik",
  "name": "abc123",
  "precision": 2277
}

Field Name Description
code - CurrencyCode! The currency code. This is an enum type .
customCode - String The currency code for custom currencies. This is only set if 'currency' is set to CUSTOM. It can be up to 32 characters long.
customCurrencyId - SafeString The ID for a custom currency. This is specified when creating the custom currency using the createCustomCurrency mutation.
name - String! A human readable name for the currency (e.g. United States Dollar). This is used for display purposes.
precision - Int! The number of decimal places this currency goes to. For example, United States Dollars have a precision of 2 (i.e. 100 cents in a dollar), whereas the Jordanian Dinar has a precision of 3. This is used for display purposes.

CurrencyCode#

Example
"AAVE"

Enum Value Description
AAVE
ADA
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
AWG
AZN
BAM
BBD
BCH
BDT
BGN
BHD
BIF
BMD
BND
BOB
BRL
BSD
BTC
BTN
BWP
BYR
BZD
CAD
CDF
CHF
CLP
CNY
COP
CRC
CUC
CUP
CUSTOM
CVE
CZK
DAI
DJF
DKK
DOP
DZD
EGP
ERN
ETB
ETH
EUR
FJD
FKP
GBP
GEL
GGP
GHS
GIP
GMD
GNF
GTQ
GYD
HKD
HNL
HRK
HTG
HUF
IDR
ILS
IMP
INR
IQD
IRR
ISK
JMD
JOD
JPY
KES
KGS
KHR
KMF
KPW
KRW
KWD
KYD
KZT
LAK
LBP
LINK
LKR
LOGICAL
LRD
LSL
LTC
LYD
MAD
MATIC
MDL
MGA
MKD
MMK
MNT
MOP
MUR
MVR
MWK
MXN
MYR
MZN
NAD
NGN
NIO
NOK
NPR
NZD
OMR
PAB
PEN
PGK
PHP
PKR
PLN
PTS
PYG
QAR
RON
RSD
RUB
RWF
SAR
SBD
SCR
SDG
SEK
SGD
SHP
SLL
SOL
SOS
SPL
SRD
STN
SVC
SYP
SZL
THB
TJS
TMT
TND
TOP
TRY
TTD
TVD
TWD
TZS
UAH
UGX
UNI
USD
USDC
USDT
UYU
UZS
VEF
VND
VUV
WST
XAF
XCD
XLM
XOF
XPF
YER
ZAR
ZMW

CurrencyMode#

Defines the currency handling of a LedgerAccount, which can either be restricted to a single currency or allow multiple currencies.


Example
"multi"

Enum Value Description
multi
single

Date#

ISO 8601 Date e.g. 1969-07-21


Example
"2022-03-28"


DateTime#

ISO 8601 DateTime e.g. 1969-07-16T13:32:00.000Z. You can also provide a date e.g. 1969-01-01 and it will be converted to 1969-01-01T00:00:00.000Z


Example
"2007-12-03T10:15:30Z"


ExternalTransferType#

Example
"ach"

Enum Value Description
ach
card
check
internal
wire

ID#

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "4") or integer (such as 4) input value will be accepted as an ID.


Example
"3116551f-5efc-4c9e-84ac-5a36a51b09c1"


IkReplay#

Example
{"ik": "some-safe-string-ik", "isIkReplay": true}

Field Name Description
ik - SafeString!
isIkReplay - Boolean!

Int#

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.


Example
2277


Int96#

A string representing integers as big as 2^96-1. The number is signed so the range is from -79,228,162,514,264,337,593,543,950,336 to 79,228,162,514,264,337,593,543,950,336.


Example
"999999999999"


JSON#

The JSON scalar type represents JSON values as specified by ECMA-404.


Example
"{"key":"value"}"


LastMoment#

The last moment of a specific year, month or day or hour e.g. 1969 or 1969-12 or 1969-12-31 or 1969-12-31T23. All of the previous examples are equivalent to 1969-12-31T23:59:59.999.


Example
"2021-07"


LedgerLinesConsistencyMode#

Example
"eventual"

Enum Value Description
eventual
strong

LedgerMigrationStatus#

The status of a ledger migration.


Example
"completed"

Enum Value Description
completed The Ledger Migration has been successfully completed. This is a terminal state.
failed The Ledger Migration has failed. This can happen either due to an invalid schema or an internal error. This is a terminal state.
queued The Ledger Migration has been queued.
skipped The Ledger Migration has been skipped because a newer version is available. This is a terminal state.
started The Ledger Migration has been started.

LedgerTypes#

Example
"double"

Enum Value Description
double

ParameterizedString#

A string of non-zero length that can contain parameterized values via handlebars syntax. ex: "Hello from {{country}}".


Example
"assets/bank:{{bank_name}}"


Parameters#

A mapping of parameter keys to values.


Example
{"bank_name": "bank-name", "deposit_amount": "10000"}


Period#

A specific year ("2021"), quarter ("2021-Q1"), month ("2021-02"), day ("2021-02-03") or hour ("2021-02-03T04")


Example
"2022-Q3"


ReadBalanceConsistencyMode#

The consistency configuration of a Ledger Account's balance queries. If not provided as an argument to a balance query, the default behavior is to read eventually consistent balances. See Configure consistency.


Example
"eventual"

Enum Value Description
eventual Balance queries will read eventually consistent balances. This is the default behavior if ReadBalanceConsistencyMode is not provided as an argument to the balance field. Both Ledger Accounts configured with strongly and eventually consistent balance updates support this enum.
strong Balance queries will read strongly consistent balances. This is only allowed if the Ledger Account's ownBalanceUpdates in its consistencyConfig is strong .
use_account Balance queries will use the value from the Ledger Account's ownBalanceUpdates in its consistencyConfig .

SafeString#

A string with delimiter characters /, #, and : disallowed, as well as parameters in {{handlebar}} syntax.


Example
"some-safe-string-ik"


SceneEventType#

Example
"entry"

Enum Value Description
entry

SchemaConsistencyMode#

The consistency modes available for entities created within this Schema.


Example
"eventual"

Enum Value Description
eventual Eventually consistent entity updates
strong Strongly consistent entity updates

String#

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.


Example
"abc123"


TxType#

Example
"credit"

Enum Value Description
credit
debit

UTCOffset#

All hour-aligned offsets from -11:00 to +12:00 are supported, e.g. "-08:00" (PT), "-05:00" (ET), "+00:00" (UTC)


Example
"-08:00"


Input Types

#

ChartOfAccountsInput#

The input for your Chart of Accounts in a Schema.


Example
{
  "accounts": [SchemaLedgerAccountInput],
  "defaultConsistencyConfig": LedgerAccountConsistencyConfigInput,
  "defaultCurrency": CurrencyMatchInput,
  "defaultCurrencyMode": "multi"
}

Input Field Description
accounts - [SchemaLedgerAccountInput!]! The Ledger Accounts modeled by your Schema. Ledger Accounts may be nested up to a maximum depth of 10.
defaultConsistencyConfig - LedgerAccountConsistencyConfigInput The default consistency configuration for all Ledger Accounts in this Schema. If a Ledger Account does not specify its own consistency configuration, it will use the default values provided here. See Configure consistency.
defaultCurrency - CurrencyMatchInput The default currency of each Ledger Account in the Chart Of Accounts. It must be provided if defaultCurrencyMode is set to single . Additionally, defaultCurrency must be omitted if defaultCurrencyMode is set to multi .
defaultCurrencyMode - CurrencyMode The default currency mode of each Ledger Account in the Chart Of Accounts.

CreateCustomCurrencyInput#

Example
{
  "customCode": "abc123",
  "customCurrencyId": "some-safe-string-ik",
  "name": "abc123",
  "precision": 2277
}

Input Field Description
customCode - String! The currency code for custom currencies. It can be up to 5 characters long. This is used for display purposes.
customCurrencyId - SafeString! The ID for a custom currency. This is specified when creating the custom currency using the createCustomCurrency mutation.
name - String! A human readable name for the currency (e.g. United States Dollar). This is used for display purposes.
precision - Int! The number of decimal places this currency goes to. For example, United States Dollars have a precision of 2 (i.e. 100 cents in a dollar), whereas the Jordanian Dinar has a precision of 3. This is used for display purposes.

CreateLedgerAccountInput#

Example
{
  "consistencyConfig": LedgerAccountConsistencyConfigInput,
  "currency": CurrencyMatchInput,
  "currencyMode": "multi",
  "linkedAccount": ExternalAccountMatchInput,
  "name": "abc123",
  "parent": LedgerAccountMatchInput,
  "type": "asset"
}

Input Field Description
consistencyConfig - LedgerAccountConsistencyConfigInput The consistency configuration for this Ledger Account. This defines how updates to this Ledger Account's balance are handled.
currency - CurrencyMatchInput The currency of this Ledger Account. If this is not set, and currencyMode is not set to multi , the workspace-level default is used.
currencyMode - CurrencyMode If set to multi , creates a multi-currency Ledger Account. If set to single , creates a single-currency Ledger Account.
linkedAccount - ExternalAccountMatchInput The External Account to link to this Ledger Account.
name - String! The human-readable name of this Ledger Account.
parent - LedgerAccountMatchInput The parent of this Ledger Account.
type - LedgerAccountTypes The type of ledger account to create. Required if this is a top-level Ledger Account. If not provided, the type will be inferred from the parent.

CreateLedgerAccountsInput#

Example
{
  "childLedgerAccounts": [CreateLedgerAccountsInput],
  "consistencyConfig": LedgerAccountConsistencyConfigInput,
  "currency": CurrencyMatchInput,
  "currencyMode": "multi",
  "ik": "some-safe-string-ik",
  "linkedAccount": ExternalAccountMatchInput,
  "name": "abc123",
  "parent": LedgerAccountMatchInput,
  "type": "asset"
}

Input Field Description
childLedgerAccounts - [CreateLedgerAccountsInput!] Ledger Accounts to create as children of this Ledger Account.
consistencyConfig - LedgerAccountConsistencyConfigInput The consistency configuration for this ledger account. See Configure consistency .
currency - CurrencyMatchInput The currency of this Ledger Account. If this is not set, the workspace level default is used.
currencyMode - CurrencyMode The currency mode of this Ledger Account. If this is not set, the workspace level default is used.
ik - SafeString! The idempotency key for creating this Ledger Account.
linkedAccount - ExternalAccountMatchInput The External Account to link to this Ledger Account. This can only be specified on leaf Ledger Accounts. See Reconcile transactions .
name - String! The name of the Ledger Account.
parent - LedgerAccountMatchInput The parent of this Ledger Account. This is only valid on the top level Ledger Account in the payload.
type - LedgerAccountTypes The type of this Ledger Account. This field is only required if this is a root Ledger Account. Otherwise, the type will get inherited from its parent.

CreateLedgerInput#

Example
{"balanceUTCOffset": "-08:00", "name": "abc123", "type": "double"}

Input Field Description
balanceUTCOffset - UTCOffset Use this field to specify a timezone for queries to your Ledger. When aggregating balances, all transactions within a 24 hour period starting at midnight UTC are included in each day. You can specify a different starting hour for balances. For example, use "-08:00" to align balances with Pacific Standard Time. Balance queries would then consider the start of each local day to be at 8am UTC the next day in UTC. The default timezone is UTC.
name - String!
type - LedgerTypes

CustomAccountInput#

Example
{
  "currency": CurrencyMatchInput,
  "currencyMode": "multi",
  "externalId": "some-safe-string-ik",
  "name": "abc123"
}

Input Field Description
currency - CurrencyMatchInput The currency of this external account. If this is not set, the workspace level default is used. 'currency' cannot be set if 'currencyMode' is 'multi'.
currencyMode - CurrencyMode The currency mode of this external account. If set to multi, creates a multi-currency account.
externalId - SafeString! The ID of this account at the external system. This is used as the idempotency key, within the scope of its Custom Link.
name - String! The name of the account at the external system.

CustomTxInput#

Example
{
  "account": ExternalAccountMatchInput,
  "amount": "999999999999",
  "currency": CurrencyMatchInput,
  "description": "abc123",
  "externalId": "some-safe-string-ik",
  "posted": "2007-12-03T10:15:30Z"
}

Input Field Description
account - ExternalAccountMatchInput!
amount - Int96!
currency - CurrencyMatchInput The currency of this tx. Should be set for multi-currency accounts.
description - String!
externalId - SafeString! The ID of this tx at the external system. This is used as the idempotency key, within the scope of its Custom Account.
posted - DateTime!

Int96ConditionInput#

A condition that must be met on an Int96 field.


Example
{"eq": "999999999999", "gte": "999999999999", "lte": "999999999999"}

Input Field Description
eq - Int96 Amount must exactly match this value. You may not specify this alongside gte or lte .
gte - Int96 Amount must be greater than or equal to this value.
lte - Int96 Amount must be less than or equal to this value.

LedgerAccountConditionInput#

A set of conditions that a Ledger Account must meet for an operation to succeed.


Example
{"ownBalance": Int96ConditionInput}

Input Field Description
ownBalance - Int96ConditionInput! A condition that the ownBalance field must satisfy. Note that this condition always applies to the latest balance, not to balances at a specific date or time. See Read balances for more on the different types of Ledger Account balances.

LedgerAccountConsistencyConfigInput#

The payload configuring the consistency for this Ledger Account. See Configure consistency.


Example
{
  "groups": [LedgerAccountGroupConsistencyConfigInput],
  "lines": "eventual",
  "ownBalanceUpdates": "eventual"
}

Input Field Description
groups - [LedgerAccountGroupConsistencyConfigInput!] The consistency configuration for Ledger Entry Groups affecting this account. See Configure consistency.
lines - LedgerLinesConsistencyMode If set to strong, then a Ledger Account's lines updates will be strongly consistent with the API response. This Ledger Account's balance will be updated and available for strongly consistent reads before you receive an API response. Otherwise if unset or set to eventual, lines updates are applied asynchronously and may not be immediately reflected in queries. See Configure consistency.
ownBalanceUpdates - BalanceUpdateConsistencyMode If set to strong, then a Ledger Account's ownBalance updates will be strongly consistent with the API response. This Ledger Account's balance will be updated and available for strongly consistent reads before you receive an API response. Otherwise if unset or set to eventual, ownBalance updates are applied asynchronously and may not be immediately reflected in queries. See Configure consistency.

LedgerAccountGroupConsistencyConfigInput#

The consistency configuration for a specific Ledger Entry Group in this account.


Example
{"key": "abc123", "ownBalanceUpdates": "eventual"}

Input Field Description
key - String! The group key for this configuration.
ownBalanceUpdates - BalanceUpdateConsistencyMode! If set to strong, then Ledger Entry Group ownBalances updates for this account will be strongly consistent with the API response. This Ledger Account's Ledger Entry Group balances will be updated and available for strongly consistent reads before you receive an API response. Otherwise if unset or set to eventual, Ledger Entry Group ownBalance updates are applied asynchronously and may not be immediately reflected in queries. See Configure consistency.

LedgerEntryConditionInput#

A set of pre-conditions and post-conditions that a Ledger Account balance must meet for an operation to succeed. You must specify at least one of precondition or postcondition for each condition.


Example
{
  "account": LedgerAccountMatchInput,
  "currency": CurrencyMatchInput,
  "postcondition": LedgerAccountConditionInput,
  "precondition": LedgerAccountConditionInput
}

Input Field Description
account - LedgerAccountMatchInput! The Ledger Account that must satisfy the provided conditions.
currency - CurrencyMatchInput For Ledger Accounts in the multi currency mode, you must specify the currency of the balance affected by the condition. You only need to specify this field for multi-currency accounts.
postcondition - LedgerAccountConditionInput The conditions that must hold after the operation.
precondition - LedgerAccountConditionInput The conditions that must hold prior to the operation.

LedgerEntryGroupInput#

Example
{"key": "some-safe-string-ik", "value": "some-safe-string-ik"}

Input Field Description
key - SafeString! The key of this group. Can be up to 128 characters long.
value - SafeString! The value associated with this group's key. Can be up to 128 characters long.

LedgerEntryInput#

Ledger Entries are limited to 30 Ledger Lines.


Example
{
  "conditions": [LedgerEntryConditionInput],
  "description": "abc123",
  "groups": [LedgerEntryGroupInput],
  "ledger": LedgerMatchInput,
  "lines": [LedgerLineInput],
  "parameters": "{"key":"value"}",
  "posted": "2007-12-03T10:15:30Z",
  "tags": [LedgerEntryTagInput],
  "type": "abc123",
  "version": 2277
}

Input Field Description
conditions - [LedgerEntryConditionInput!] Conditions that must be satisfied to post this Ledger Entry. The Ledger Entry will reject with a BadRequestError if any condition is not met. You can only add a condition on a Ledger Account containing a Line in this Ledger Entry.
description - String If specified, will also be used as the description for LedgerLines unless they specify their own description.
groups - [LedgerEntryGroupInput!] Adds this Ledger Entry to this set of Ledger Entry Groups
ledger - LedgerMatchInput The Ledger to which to post this Ledger Entry. Must be linked to a Schema that defines the provided Ledger Entry type.
lines - [LedgerLineInput!] The Ledger Lines to create as part of this Ledger Entry. This cannot be used with Ledger Entries that have a 'type' i.e. Ledger Entries defined in the Schema. This can be useful during non-routine operations such as an incident. It is not recommended to use 'lines' during routine operations.
parameters - JSON Parameters to be included in a templated Ledger Entry. All provided parameters must be present in the typed Ledger Entry within the Schema linked to the provided Ledger.
posted - DateTime ISO 8601 timestamp to post this Ledger Entry e.g. "2021-01-01" or "2021-01-01T16:45:00Z". Will error out if supplied to reconcileTx or createOrder since the transaction timestamp will be used instead
tags - [LedgerEntryTagInput!] A set of tags attached to this Ledger Entry.
type - String The type of the Ledger Entry. Must be defined in the Schema linked to the Ledger specified below.
version - Int Experimental: This field is reserved for an upcoming feature and is not yet supported.

LedgerEntryTagInput#

Example
{"key": "some-safe-string-ik", "value": "some-safe-string-ik"}

Input Field Description
key - SafeString! The key of this tag. Can be up to 128 characters long.
value - SafeString! The value associated with this tag's key. Can be up to 128 characters long.

LedgerLineInput#

Example
{
  "account": LedgerAccountMatchInput,
  "amount": "999999999999",
  "currency": CurrencyMatchInput,
  "description": "abc123",
  "key": "abc123",
  "tx": TxMatchInput
}

Input Field Description
account - LedgerAccountMatchInput! The LedgerAccount this line is being added to
amount - Int96 A positive amount increases the balance of its LedgerAccount, a negative amount reduces the balance of its LedgerAccount
currency - CurrencyMatchInput The currency the ledger line is in
description - String If not specified the description from the parent LedgerEntryInput will be used
key - String Optional identifier for Ledger Line. You can filter lines by key using LedgerLinesFilterSet .
tx - TxMatchInput Required for reconcileTx to specify the transaction being reconciled, you can specify either the FRAGMENT ID or external ID of the transaction

SceneEntryInput#

A simulated Ledger Entry posted as a part of a Scene.


Example
{"parameters": "{"key":"value"}", "type": "some-safe-string-ik"}

Input Field Description
parameters - JSON Any parameters to be used as inputs to this simulated Ledger Entry.
type - SafeString! The type of the simulated Ledger Entry. Must match one of the types provided in schema.ledgerEntries.types.

SceneEventInput#

Example
{"entry": SceneEntryInput, "eventType": "entry"}

Input Field Description
entry - SceneEntryInput! The simulated Ledger Entry.
eventType - SceneEventType! The type of the Scene Event. Currently, only entries are supported.

SceneInput#

Example
{"events": [SceneEventInput], "name": "abc123"}

Input Field Description
events - [SceneEventInput!]! A list of simulated ledger entries that make up the Scene.
name - String! The human-readable name of the Scene.

SchemaConditionInput#

A condition that must be met on a Ledger Account balance. The condition can be either a precondition or postcondition.


Example
{"ownBalance": SchemaInt96ConditionInput}

Input Field Description
ownBalance - SchemaInt96ConditionInput A condition on the ownBalance of the Ledger Account.

SchemaConsistencyConfigInput#

The consistency configuration for entities created within Ledgers created by this Schema.


Example
{"entries": "eventual"}

Input Field Description
entries - SchemaConsistencyMode The consistency mode for the Ledger Entries list query within Ledgers created by this Schema. See Configure consistency.

SchemaInput#

Input to the API for creating a Schema.


Example
{
  "chartOfAccounts": ChartOfAccountsInput,
  "consistencyConfig": SchemaConsistencyConfigInput,
  "key": "some-safe-string-ik",
  "ledgerEntries": SchemaLedgerEntriesInput,
  "name": "assets/bank:{{bank_name}}",
  "scenes": [SceneInput]
}

Input Field Description
chartOfAccounts - ChartOfAccountsInput! The Chart of Accounts for the Schema.
consistencyConfig - SchemaConsistencyConfigInput The consistency configuration for this Schema.
key - SafeString! The key of the Schema. This is a stable, unique identifier for the Schema. Uniqueness is enforced at the Workspace level.
ledgerEntries - SchemaLedgerEntriesInput The Ledger Entries to add to the Schema.
name - ParameterizedString The human-readable name of the Schema.
scenes - [SceneInput!] Any scenes associated with this Schema.

SchemaInt96ConditionInput#

A condition that must be met on a field.


Example
{
  "eq": "assets/bank:{{bank_name}}",
  "gte": "assets/bank:{{bank_name}}",
  "lte": "assets/bank:{{bank_name}}"
}

Input Field Description
eq - ParameterizedString Amount must be exactly equal to this value. You may not specify this alongside gte or lte .
gte - ParameterizedString Amount must be greater than or equal to this value.
lte - ParameterizedString Amount must be less than or equal to this value.

SchemaLedgerAccountInput#

Models a Ledger Account in a Schema. Upon successfully storing a Schema, a LedgerAccount will be created for each corresponding non-templated SchemaLedgerAccountInput in your Chart of Accounts.


Example
{
  "children": [SchemaLedgerAccountInput],
  "consistencyConfig": LedgerAccountConsistencyConfigInput,
  "currency": SchemaCurrencyMatchInput,
  "currencyMode": "multi",
  "key": "some-safe-string-ik",
  "linkedAccount": SchemaExternalAccountMatchInput,
  "name": "assets/bank:{{bank_name}}",
  "template": true,
  "type": "asset"
}

Input Field Description
children - [SchemaLedgerAccountInput!] Ledger Accounts to create as children of this Ledger Account. Ledger Accounts may be nested up to a maximum depth of 10.
consistencyConfig - LedgerAccountConsistencyConfigInput The consistency configuration for this ledger account. See Configure consistency .
currency - SchemaCurrencyMatchInput The currency of this Ledger Account. If this is not set, and currencyMode is not set to multi , it is derived from the Chart of Accounts' default.
currencyMode - CurrencyMode If set to multi , creates a multi-currency Ledger Account. If set to single , creates a single-currency Ledger Account.
key - SafeString! The key of this Ledger Account. Keys are used to formulate the unique path of the Ledger Account in your Chart of Accounts. Siblings must have unique keys.
linkedAccount - SchemaExternalAccountMatchInput The External Account to link to this Ledger Account. It must be provided of linked is true.
name - ParameterizedString The human-readable name of this Ledger Account.
template - Boolean Whether or not this Ledger Account should be templated.
type - LedgerAccountTypes The type of ledger account to create. Required if this is a top-level Ledger Account. If not provided, the type will be inferred from the parent.

SchemaLedgerEntriesInput#

The Ledger Entries in your Schema.


Example
{"types": [SchemaLedgerEntryInput]}

Input Field Description
types - [SchemaLedgerEntryInput!]! A list of Ledger Entry definitions.

SchemaLedgerEntryConditionInput#

A condition that must be met on a Ledger Account when a Ledger Entry is posted.


Example
{
  "account": SchemaLedgerAccountMatchInput,
  "currency": SchemaCurrencyMatchInput,
  "postcondition": SchemaConditionInput,
  "precondition": SchemaConditionInput
}

Input Field Description
account - SchemaLedgerAccountMatchInput! The Ledger Account to apply the condition to.
currency - SchemaCurrencyMatchInput The currency of the balance to apply the condition to. Required if the Ledger Account matched is a multi-currency Ledger Account. Otherwise, this field is defaults to the Ledger Account's currency.
postcondition - SchemaConditionInput A postcondition must be met after the Ledger Entry updates are applied.
precondition - SchemaConditionInput A precondition must be met before any Ledger Entry updates are applied.

SchemaLedgerEntryGroupInput#

A Ledger Entry Group associated with a Ledger Entry type.


Example
{"key": "some-safe-string-ik", "value": "assets/bank:{{bank_name}}"}

Input Field Description
key - SafeString! The key for this Ledger Entry Group.
value - ParameterizedString! The value associated with this Ledger Entry Group.

SchemaLedgerEntryInput#

A Ledger Entry in a Schema. All Ledger Entries defined in a Schema must have a unique type.


Example
{
  "conditions": [SchemaLedgerEntryConditionInput],
  "description": "assets/bank:{{bank_name}}",
  "groups": [SchemaLedgerEntryGroupInput],
  "lines": [SchemaLedgerLineInput],
  "parameters": "{"key":"value"}",
  "tags": [SchemaLedgerEntryTagInput],
  "type": "some-safe-string-ik",
  "version": 2277
}

Input Field Description
conditions - [SchemaLedgerEntryConditionInput!] Conditions that must be satisfied to post this Ledger Entry. The Ledger Entry will reject with a BadRequestError if any condition is not met. You can only add a condition on a Ledger Account containing a Line in this Ledger Entry.
description - ParameterizedString Human-readable description of the Ledger Entry.
groups - [SchemaLedgerEntryGroupInput!] Ledger Entries posted with this type will be in these Ledger Entry Groups.
lines - [SchemaLedgerLineInput!] The Ledger Lines in the Ledger Entry. If provided, when posting a Typed Entry, a LedgerEntry will be posted containing LedgerLines corresponding to the values you provide here. If your lines contain parameters, you must supply values for those parameters that balance out the Ledger Entry. If not provided, lines will be required when posting a Typed Entry.
parameters - JSON Fixed partial set of parameters to be included in a templated Ledger Entry.
tags - [SchemaLedgerEntryTagInput!] Ledger Entries posted with this type will be associated with these tags.
type - SafeString! The type of this Ledger Entry. This is a stable, unique identifier for this entry. Uniqueness is enforced at the Schema level. You can filter on this field when querying for Ledger Entries. See the docs on LedgerEntryFilterSet
version - Int Experimental: This field is not yet supported.

SchemaLedgerEntryTagInput#

A tag associated with a Ledger Entry type.


Example
{"key": "some-safe-string-ik", "value": "assets/bank:{{bank_name}}"}

Input Field Description
key - SafeString! The key for this tag.
value - ParameterizedString! The value associated with the given key for this tag.

SchemaLedgerLineInput#

A Ledger Line in a Ledger Entry.


Example
{
  "account": SchemaLedgerAccountMatchInput,
  "amount": "assets/bank:{{bank_name}}",
  "currency": SchemaCurrencyMatchInput,
  "description": "assets/bank:{{bank_name}}",
  "key": "some-safe-string-ik",
  "tx": SchemaTxMatchInput
}

Input Field Description
account - SchemaLedgerAccountMatchInput! The Ledger Account this Ledger Line will be posted to. It supports parameters in its attributes via handlebars syntax.
amount - ParameterizedString The amount of the Ledger Line. It supports parameters via the handlebars syntax and addition (+) and subtraction (-).
currency - SchemaCurrencyMatchInput The currency of the Ledger Line. This is required if the Ledger Account has currencyMode multi. It supports parameters in its attributes via handlebars syntax.
description - ParameterizedString Human-readable description of the line.
key - SafeString! The key for the Ledger Line. Ledger Line keys must be unique within a Ledger Entry. Key can be filtered on as part of the LedgerLinesFilterSet.
tx - SchemaTxMatchInput The external transaction to reconcile. This field is required if the Ledger Account being posted to is a Linked Ledger Account. Otherwise, this field is disallowed. It supports parameters in its attributes via handlebars syntax. See the docs on reconciliation and Linked Ledger Accounts.

UpdateLedgerAccountInput#

Example
{
  "consistencyConfig": LedgerAccountConsistencyConfigInput,
  "name": "abc123"
}

Input Field Description
consistencyConfig - LedgerAccountConsistencyConfigInput The consistency configuration for this ledger account. This defines how updates to this ledger account's balance are handled.
name - String The name to update the ledger account to

UpdateLedgerEntryInput#

Example
{
  "groups": [LedgerEntryGroupInput],
  "tags": [LedgerEntryTagInput]
}

Input Field Description
groups - [LedgerEntryGroupInput!] The list of Groups to add to this Ledger Entry.
tags - [LedgerEntryTagInput!] The list of Tags to add and/or update on this Ledger Entry.

UpdateLedgerInput#

Example
{"name": "abc123"}

Input Field Description
name - String The new Ledger name.

MatchInput Types

#

CurrencyMatchInput#

Example
{"code": "AAVE", "customCurrencyId": "some-safe-string-ik"}

Input Field Description
code - CurrencyCode! The currency code. This is an enum type .
customCurrencyId - SafeString The ID for a custom currency. This is specified when creating the custom currency using the createCustomCurrency mutation.

EntryGroupMatchInput#

Example
{"key": "some-safe-string-ik", "value": "some-safe-string-ik"}

Input Field Description
key - SafeString!
value - SafeString!

ExternalAccountMatchInput#

Specify an External Account by using id, or linkId and externalId.


Example
{
  "externalId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
  "id": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
  "linkId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1"
}

Input Field Description
externalId - ID The external system's ID of the External Account. If this is specified, linkId is required. id is optional, but will be validated if provided.
id - ID The FRAGMENT ID of the External Account. If this is specified, both linkId and externalId are optional, but will be validated if provided.
linkId - ID The FRAGMENT ID of the Link the External Account is in. If this is specified, externalId is required. id is optional, but will be validated if provided.

LedgerAccountMatchInput#

Specify a Ledger Account by using id or path.


Example
{
  "id": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
  "ledger": LedgerMatchInput,
  "path": "abc123"
}

Input Field Description
id - ID The FRAGMENT ID of the ledger account
ledger - LedgerMatchInput The Ledger to which this Ledger Account belongs. This is required if you are specifying the Ledger Account by path .
path - String The unique path of the ledger account. This is a slash-delimited string containing the keys of an account and all its direct ancestors.

LedgerEntryGroupMatchInput#

Example
{
  "key": "some-safe-string-ik",
  "ledger": LedgerMatchInput,
  "value": "some-safe-string-ik"
}

Input Field Description
key - SafeString!
ledger - LedgerMatchInput!
value - SafeString!

LedgerEntryMatchInput#

Specify a Ledger Entry by using id.


Example
{
  "id": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
  "ik": "some-safe-string-ik",
  "ledger": LedgerMatchInput
}

Input Field Description
id - ID The FRAGMENT ID of the Ledger Entry
ik - SafeString The IK provided to the addLedgerEntry mutation or the ik field returned from a reconcileTx mutation. This is required if you have not provided id .
ledger - LedgerMatchInput The FRAGMENT ID of the Ledger to which this Ledger Entry belongs. This is required if you have not provided id .

LedgerLineMatchInput#

Specify a Ledger Line by using id.


Example
{"id": "3116551f-5efc-4c9e-84ac-5a36a51b09c1"}

Input Field Description
id - ID! The FRAGMENT ID of the ledger line

LedgerMatchInput#

Specify a Ledger by using id or ik.


Example
{"id": "3116551f-5efc-4c9e-84ac-5a36a51b09c1", "ik": "some-safe-string-ik"}

Input Field Description
id - ID The FRAGMENT ID of the ledger
ik - SafeString The IK passed into the createLedger mutation. This is treated as a second unique identifier for this ledger.

LinkMatchInput#

Example
{"id": "3116551f-5efc-4c9e-84ac-5a36a51b09c1"}

Input Field Description
id - ID!

SchemaCurrencyMatchInput#

Matches a Currency. Can be a built-in CurrencyCode, custom Currency, or a parameterized string. If you supply a parameterized string, you must pass in a valid CurrencyCode as a parameter when posting a Ledger Entry.


Example
{
  "code": "assets/bank:{{bank_name}}",
  "customCurrencyId": "assets/bank:{{bank_name}}"
}

Input Field Description
code - ParameterizedString! The currency code. This must either be a CurrencyCode or a parameterized string that resolves to a CurrencyCode .
customCurrencyId - ParameterizedString The ID for a custom currency. This is specified when creating the custom currency using the createCustomCurrency mutation.

SchemaExternalAccountMatchInput#

Example
{
  "externalId": "assets/bank:{{bank_name}}",
  "id": "assets/bank:{{bank_name}}",
  "linkId": "assets/bank:{{bank_name}}"
}

Input Field Description
externalId - ParameterizedString The External systems's ID of the account
id - ParameterizedString The FRAGMENT ID of the external account
linkId - ParameterizedString The FRAGMENT ID of the link

SchemaLedgerAccountMatchInput#

Matches a Ledger Account in a Schema.


Example
{"path": "assets/bank:{{bank_name}}"}

Input Field Description
path - ParameterizedString! The unique path of the Ledger Account in the Schema. This is a slash-delimited string containing the keys of a Ledger Account and all its direct ancestors. ex: expense-root/subscriptions/netflix For Templated Ledger Accounts, you must supply a parameter in the path that will be used to name an instance of the template. ex: "expense-root/subscriptions/vendor:{{vendor_name}}"

SchemaMatchInput#

An object used to retrieve a Schema.


Example
{"key": "some-safe-string-ik", "version": 2277}

Input Field Description
key - SafeString! The key to retrieve a Schema by. key is unique to a Workspace.
version - Int Optional parameter to specify version of requested Schema. If not provided, it defaults to 0, representing the latest available version for the provided Schema key.

SchemaTxMatchInput#

Matches a transaction at an external system. This is used to specify the transaction being reconciled into a Linked Ledger Account


Example
{"externalId": "assets/bank:{{bank_name}}", "id": "assets/bank:{{bank_name}}"}

Input Field Description
externalId - ParameterizedString The external system's ID for the transaction.
id - ParameterizedString The FRAGMENT ID for the transaction.

TagMatchInput#

Specifies a single tag that an entity is expected to have. You must specify both the key and the value.


Example
{"key": "some-safe-string-ik", "value": "some-safe-string-ik"}

Input Field Description
key - SafeString! The key of this tag.
value - SafeString! The value associated with this tag's key.

TxMatchInput#

Specify a Tx by using id or externalId, the Link it belongs to by linkId, and the External Account it is a part of by accountId or externalAccountId.


Example
{
  "accountId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
  "externalAccountId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
  "externalId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
  "id": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
  "linkId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1"
}

Input Field Description
accountId - ID The FRAGMENT ID of the external account
externalAccountId - ID The external system's ID for the account
externalId - ID The external system's ID for the transaction
id - ID The FRAGMENT ID of the transaction
linkId - ID The FRAGMENT ID of the link

Response Types

#

AddLedgerEntryResponse#

Example
AddLedgerEntryResult


CreateCustomCurrencyResponse#

Example
BadRequestError


CreateCustomLinkResponse#

Example
BadRequestError


CreateLedgerAccountResponse#

Example
BadRequestError


CreateLedgerAccountsResponse#

Example
BadRequestError


CreateLedgerResponse#

Example
BadRequestError


ReconcileTxResponse#

Example
BadRequestError


StoreSchemaResponse#

Returned by the storeSchema mutation.


Example
BadRequestError


SyncCustomAccountsResponse#

Example
BadRequestError


SyncCustomTxsResponse#

Example
BadRequestError


UpdateLedgerAccountResponse#

Example
BadRequestError


UpdateLedgerEntryResponse#

Example
BadRequestError


UpdateLedgerResponse#

Example
BadRequestError


Result Types

#

AddLedgerEntryResult#

Example
{
  "entry": LedgerEntry,
  "isIkReplay": true,
  "lines": [LedgerLine]
}

Field Name Description
entry - LedgerEntry! The ledger entry that was posted
isIkReplay - Boolean! True if this request successfully completed before and the previous response is being returned
lines - [LedgerLine!]! The ledger lines that were created in that entry

CreateCustomCurrencyResult#

Example
{"customCurrency": Currency}

Field Name Description
customCurrency - Currency! The Currency that was created.

CreateCustomLinkResult#

Example
{"isIkReplay": true, "link": CustomLink}

Field Name Description
isIkReplay - Boolean!
link - CustomLink! The custom link that was created. Represents an instance of an external system.

CreateLedgerAccountResult#

Example
{"isIkReplay": true, "ledgerAccount": LedgerAccount}

Field Name Description
isIkReplay - Boolean! true if a previous request successfully created this ledger account
ledgerAccount - LedgerAccount! The ledger account that was created

CreateLedgerAccountsResult#

Example
{
  "ikReplays": [IkReplay],
  "ledgerAccounts": [LedgerAccount]
}

Field Name Description
ikReplays - [IkReplay!]! Whether the ledger accounts were successfully created by a previous request
ledgerAccounts - [LedgerAccount!]! The ledger accounts that were created

CreateLedgerResult#

Example
{"isIkReplay": true, "ledger": Ledger}

Field Name Description
isIkReplay - Boolean! true if this request successfully completed before and the previous response is being returned
ledger - Ledger! The Ledger that was created

ReconcileTxResult#

Example
{
  "entry": LedgerEntry,
  "isIkReplay": true,
  "lines": [LedgerLine]
}

Field Name Description
entry - LedgerEntry! The ledger entry that was posted
isIkReplay - Boolean! True if this request successfully completed before and the previous response is being returned
lines - [LedgerLine!]! The ledger lines that were created in that entry

StoreSchemaResult#

StoreSchemaResult represents a successful execution of storeSchema.


Example
{"schema": Schema}

Field Name Description
schema - Schema! The Schema that was stored as a result of calling storeSchema .

SyncCustomAccountsResult#

Example
{"accounts": [ExternalAccount]}

Field Name Description
accounts - [ExternalAccount!]! The external accounts that were synced.

SyncCustomTxsResult#

Example
{"txs": [Tx]}

Field Name Description
txs - [Tx!]!

UpdateLedgerAccountResult#

Example
{"ledgerAccount": LedgerAccount}

Field Name Description
ledgerAccount - LedgerAccount! The ledger account that was updated

UpdateLedgerEntryResult#

Example
{"entry": LedgerEntry}

Field Name Description
entry - LedgerEntry! The Ledger Entry that was updated.

UpdateLedgerResult#

Example
{"ledger": Ledger}

Field Name Description
ledger - Ledger! The updated Ledger.

Error Types

#

BadRequestError#

Equivalent to an HTTP 400 - request either has missing or incorrect data


Example
{"code": "abc123", "message": "abc123", "retryable": true}

Field Name Description
code - String! The HTTP status code corresponding to the error
message - String! The error message
retryable - Boolean! Whether or not the operation is retryable

Error#

Base error interface


Example
{"code": "abc123", "message": "abc123", "retryable": true}

Field Name Description
code - String! The HTTP status code corresponding to the error
message - String! The error message
retryable - Boolean! Whether or not the operation is retryable

InternalError#

Equivalent to an HTTP 5XX - something went wrong with our API.


Example
{"code": "abc123", "message": "abc123", "retryable": true}

Field Name Description
code - String! The HTTP status code corresponding to the error
message - String! The error message
retryable - Boolean! Whether or not the operation is retryable

Connection Types

#

CurrencyAmountConnection#

A paginated list of amounts with their currencies


Example
{
  "nodes": [CurrencyAmount],
  "pageInfo": PageInfo
}

Field Name Description
nodes - [CurrencyAmount!]! The current page of results
pageInfo - PageInfo! The pagination info for this list

CustomCurrenciesConnection#

A paginated list of Custom Currencies


Example
{
  "nodes": [Currency],
  "pageInfo": PageInfo
}

Field Name Description
nodes - [Currency!]! The current page of results
pageInfo - PageInfo! The pagination info for this list

ExternalAccountsConnection#

A paginated list of External Accounts


Example
{
  "nodes": [ExternalAccount],
  "pageInfo": PageInfo
}

Field Name Description
nodes - [ExternalAccount!]! The current page of results
pageInfo - PageInfo! The pagination info for this list

LedgerAccountsConnection#

A paginated list of Ledger Accounts


Example
{
  "nodes": [LedgerAccount],
  "pageInfo": PageInfo
}

Field Name Description
nodes - [LedgerAccount!]! The current page of results
pageInfo - PageInfo! The pagination info for this list

LedgerEntriesConnection#

A paginated list of Ledger Entries


Example
{
  "nodes": [LedgerEntry],
  "pageInfo": PageInfo
}

Field Name Description
nodes - [LedgerEntry!]! The current page of results
pageInfo - PageInfo! The pagination info for this list

LedgerEntryGroupBalanceConnection#

A set of balance changes for a specific Ledger Entry Group.


Example
{
  "nodes": [LedgerEntryGroupBalance],
  "pageInfo": PageInfo
}

Field Name Description
nodes - [LedgerEntryGroupBalance!]!
pageInfo - PageInfo!

LedgerEntryGroupsConnection#

A paginated list of Ledger Entry Groups


Example
{
  "nodes": [LedgerEntryGroup],
  "pageInfo": PageInfo
}

Field Name Description
nodes - [LedgerEntryGroup!]! The current page of results
pageInfo - PageInfo! Pagination info for this list.

LedgerLinesConnection#

A paginated list of Ledger Lines


Example
{
  "nodes": [LedgerLine],
  "pageInfo": PageInfo
}

Field Name Description
nodes - [LedgerLine!]! The current page of results
pageInfo - PageInfo! The pagination info for this list

LedgerMigrationConnection#

A paginated list of Ledger Migrations


Example
{
  "nodes": [LedgerMigration],
  "pageInfo": PageInfo
}

Field Name Description
nodes - [LedgerMigration!]! The current page of results
pageInfo - PageInfo! Pagination info for this list.

LedgersConnection#

A paginated list of Ledgers


Example
{
  "nodes": [Ledger],
  "pageInfo": PageInfo
}

Field Name Description
nodes - [Ledger!]! The current page of results
pageInfo - PageInfo! The pagination info for this list

LinksConnection#

A paginated list of Links


Example
{
  "nodes": [Link],
  "pageInfo": PageInfo
}

Field Name Description
nodes - [Link!]! The current page of results
pageInfo - PageInfo! The pagination info for this list

PageInfo#

An object containing pagination details.


Example
{
  "endCursor": "abc123",
  "hasNextPage": true,
  "hasPreviousPage": true,
  "startCursor": "abc123"
}

Field Name Description
endCursor - String
hasNextPage - Boolean!
hasPreviousPage - Boolean!
startCursor - String

SchemaConnection#

A paginated list of Schemas in a Workspace.


Example
{
  "nodes": [Schema],
  "pageInfo": PageInfo
}

Field Name Description
nodes - [Schema!]! The current page of results
pageInfo - PageInfo! Pagination info for this list.

SchemaVersionConnection#

A paginated list of SchemaVersions for a given Schema.


Example
{
  "nodes": [SchemaVersion],
  "pageInfo": PageInfo
}

Field Name Description
nodes - [SchemaVersion!]! The current page of results
pageInfo - PageInfo! Pagination info for this list.

TxsConnection#

A paginated list of Txs


Example
{
  "nodes": [Tx],
  "pageInfo": PageInfo
}

Field Name Description
nodes - [Tx!]! The current page of results
pageInfo - PageInfo! The pagination info for this list

Filter Types

#

CurrencyFilter#

Example
{
  "equalTo": CurrencyMatchInput,
  "in": [CurrencyMatchInput]
}

Input Field Description
equalTo - CurrencyMatchInput Must match the value provided
in - [CurrencyMatchInput!] Must match one of the values provided

DateFilter#

Example
{"equalTo": "2022-03-28", "in": ["2022-03-28"]}

Input Field Description
equalTo - Date
in - [Date!]

DateTimeFilter#

Filters a timestamp field between two moments in time


Example
{"after": "2007-12-03T10:15:30Z", "before": "2007-12-03T10:15:30Z"}

Input Field Description
after - DateTime The timestamp value must be after this moment. Specified in ISO 8601 format e.g "1968-01-01T16:45:00Z"
before - DateTime The timestamp value must be before this moment. Specified in ISO 8601 format e.g "1968-01-01T16:45:00Z"

ExternalAccountFilter#

Example
{
  "equalTo": ExternalAccountMatchInput,
  "in": [ExternalAccountMatchInput]
}

Input Field Description
equalTo - ExternalAccountMatchInput Ledger Account must linked to the the specified external account
in - [ExternalAccountMatchInput!] Ledger Account can be linked to any of the specified external accounts

GroupBalanceAccountFilter#

A filter to query balances of a specific subset of accounts


Example
{
  "id": StringFilter,
  "path": StringMatchFilter
}

Input Field Description
id - StringFilter A filter that must match the account ID
path - StringMatchFilter A filter that must match the account path. Wildcards ('*') may be used only for template variables, and will only match a single variable each.

Int96Filter#

Example
{
  "eq": "999999999999",
  "gte": "999999999999",
  "lte": "999999999999",
  "ne": "999999999999"
}

Input Field Description
eq - Int96 Must exactly equal this Int96 value
gte - Int96 Must be greater than or equal to this Int96 value
lte - Int96 Must be less than or equal to this Int96 value
ne - Int96 Must not equal this Int96 value

LedgerAccountFilter#

Example
{
  "equalTo": LedgerAccountMatchInput,
  "in": [LedgerAccountMatchInput]
}

Input Field Description
equalTo - LedgerAccountMatchInput Result must match the specified Ledger Account
in - [LedgerAccountMatchInput!] Results can match any of specified Ledger Accounts

LedgerAccountTypeFilter#

Example
{"equalTo": "asset", "in": ["asset"]}

Input Field Description
equalTo - LedgerAccountTypes Results must be of the specified Ledger Account type
in - [LedgerAccountTypes!] Results can have any of the specified Ledger Account types

LedgerAccountsFilterSet#

Example
{
  "hasParentLedgerAccount": true,
  "isLinkedAccount": true,
  "ledgerAccount": LedgerAccountFilter,
  "linkedAccount": ExternalAccountFilter,
  "parentLedgerAccount": LedgerAccountFilter,
  "path": StringMatchFilter,
  "type": LedgerAccountTypeFilter
}

Input Field Description
hasParentLedgerAccount - Boolean Use this to filter Ledger Accounts by their parent status
isLinkedAccount - Boolean Use this to filter Ledger Accounts by their linked status
ledgerAccount - LedgerAccountFilter Use this to filter Ledger Accounts by their ID or path
linkedAccount - ExternalAccountFilter Use this to filter Ledger Accounts by their external linked account ID
parentLedgerAccount - LedgerAccountFilter Use this to filter Ledger Accounts by their parent account IDs
path - StringMatchFilter A filter that must match the account path. Wildcards (' ') may be used only for template variables, and will only match a single variable each. For example: 'assets-root/accounts-receivable/merchant: ' would match: 'assets-root/accounts-receivable/merchant:1' and 'assets-root/accounts-receivable/merchant:1/child'. Wildcards may not be used outside of template variables. For example, passing in 'assets-root/*' as a filter is invalid and would raise a GraphQL error.
type - LedgerAccountTypeFilter Use this to filter Ledger Accounts by their type

LedgerEntriesFilterSet#

Example
{
  "date": DateFilter,
  "ledgerEntry": LedgerEntryFilter,
  "posted": DateTimeFilter,
  "tag": TagFilter,
  "type": StringFilter
}

Input Field Description
date - DateFilter
ledgerEntry - LedgerEntryFilter Use to filter Ledger Entries by their IDs or IKs.
posted - DateTimeFilter
tag - TagFilter Use this to filter Ledger Entries by tags. The response will include entries that contain tags matching the filter.
type - StringFilter Use this to filter Ledger Entries by type. Ledger Entry types are defined in Schemas.

LedgerEntryFilter#

Example
{
  "equalTo": LedgerEntryMatchInput,
  "in": [LedgerEntryMatchInput]
}

Input Field Description
equalTo - LedgerEntryMatchInput Result must be the specified Ledger Entry.
in - [LedgerEntryMatchInput!] Result can be any of the specified Ledger Entries.

LedgerEntryGroupBalanceFilterSet#

Optional filters for querying balances on a Ledger Entry Group.


Example
{
  "account": GroupBalanceAccountFilter,
  "currency": CurrencyFilter,
  "ownBalance": Int96Filter
}

Input Field Description
account - GroupBalanceAccountFilter Filter to a subset of accounts
currency - CurrencyFilter Filter to one or more currencies
ownBalance - Int96Filter Filter to only balances in a certain range

LedgerEntryGroupsFilterSet#

Example
{
  "created": DateTimeFilter,
  "key": StringFilter,
  "value": StringFilter
}

Input Field Description
created - DateTimeFilter Use to filter Ledger Entry Groups by their created timestamp
key - StringFilter Use to filter Ledger Entry Groups by their key
value - StringFilter Use to filter Ledger Entry Groups by their value

LedgerLinesFilterSet#

Example
{
  "created": DateTimeFilter,
  "date": DateFilter,
  "key": StringFilter,
  "posted": DateTimeFilter,
  "type": TxTypeFilter
}

Input Field Description
created - DateTimeFilter Filter by the created timestamp of the Ledger Line. This is the wall-clock time when the Ledger Line was created.
date - DateFilter Filter by the posted date of the Ledger Line. This is identical to using posted , but only supports day-level granularity.
key - StringFilter Use this to filter Ledger Lines by key. Ledger Line keys are defined in Schemas.
posted - DateTimeFilter Filter by the posted timestamp of the Ledger Line.
type - TxTypeFilter

LedgerTypeFilter#

Example
{"equalTo": "double", "in": ["double"]}

Input Field Description
equalTo - LedgerTypes
in - [LedgerTypes!]

LedgersFilterSet#

Example
{"hasSchema": true, "type": LedgerTypeFilter}

Input Field Description
hasSchema - Boolean
type - LedgerTypeFilter

StringFilter#

Example
{"equalTo": "abc123", "in": ["abc123"]}

Input Field Description
equalTo - String
in - [String!]

StringMatchFilter#

Example
{"equalTo": "abc123", "in": ["abc123"], "matches": "abc123"}

Input Field Description
equalTo - String Must exactly equal the provided value
in - [String!] Must exactly equal one of the provided values
matches - String Must match the provided pattern. Wildcards ("*") will match any substring

TagFilter#

Filters a result set based on the tags it contains.


Example
{
  "equalTo": TagMatchInput,
  "in": [TagMatchInput]
}

Input Field Description
equalTo - TagMatchInput
in - [TagMatchInput!]

TxTypeFilter#

Example
{"equalTo": "credit", "in": ["credit"]}

Input Field Description
equalTo - TxType
in - [TxType!]

Utility Types

#

CurrencyAmount#

A single amount accompanied by its currency


Example
{"amount": "999999999999", "currency": Currency}

Field Name Description
amount - Int96! Numerical integer value, serialized as a string
currency - Currency! The currency this amount is in

IncreaseEnv#

Example
"production"

Enum Value Description
production
sandbox

Int96Condition#

A condition that must be met on an Int96 field.


Example
{"eq": "999999999999", "gte": "999999999999", "lte": "999999999999"}

Field Name Description
eq - Int96 Amount must exactly match this value. You may not specify this alongside gte or lte .
gte - Int96 Amount must be greater than or equal to this value.
lte - Int96 Amount must be less than or equal to this value.

LedgerAccountCondition#

A set of conditions that a Ledger Account must meet for an operation to succeed.


Example
{"ownBalance": Int96Condition}

Field Name Description
ownBalance - Int96Condition A condition that the ownBalance field must satisfy. Note that this condition always applies to the latest balance, not to balances at a specific date or time. See Read balances for more on the different types of Ledger Account balances.

LedgerAccountConsistencyConfig#

The consistency configuration of a Ledger Account's balance updates. See Configure consistency.


Example
{"lines": "eventual", "ownBalanceUpdates": "eventual"}

Field Name Description
lines - LedgerLinesConsistencyMode!
ownBalanceUpdates - BalanceUpdateConsistencyMode! If set to strong, then a Ledger Account's ownBalance updates will be strongly consistent with the API response. This Ledger Account's balance will be updated and available for strongly consistent reads once you receive an API response. Otherwise if not set or set to eventual, ownBalance updates are applied asynchronously and may not be immediately reflected in queries. See Configure consistency.

LedgerAccountTypes#

Example
"asset"

Enum Value Description
asset
expense
income
liability

LedgerEntryCondition#

A set of pre-conditions and post-conditions that a Ledger Account must have satisfied. Each LedgerEntryCondition has at least one of precondition or postcondition.


Example
{
  "account": LedgerAccount,
  "currency": Currency,
  "postcondition": LedgerAccountCondition,
  "precondition": LedgerAccountCondition
}

Field Name Description
account - LedgerAccount! The Ledger Account that must satisfied the provided conditions.
currency - Currency! The currency of the balance associated with this LedgerEntryCondition .
postcondition - LedgerAccountCondition The conditions that must be satisfied after the operation.
precondition - LedgerAccountCondition The conditions that must be satisfied prior to the operation.

LedgerEntryGroup#

A group of Ledger Entries


Example
{
  "balances": LedgerEntryGroupBalanceConnection,
  "created": "2007-12-03T10:15:30Z",
  "dashboardUrl": "abc123",
  "key": "some-safe-string-ik",
  "ledger": Ledger,
  "ledgerEntries": LedgerEntriesConnection,
  "ledgerId": "3116551f-5efc-4c9e-84ac-5a36a51b09c1",
  "value": "some-safe-string-ik"
}

Field Name Description
balances - LedgerEntryGroupBalanceConnection!
Arguments

after - String

Where to start paginating from, when paginating forwards. Send endCursor from a response to get its next page. Learn more about pagination.

before - String

Where to start paginating from, when paginating backwards. Send startCursor from a response to get the previous page. Learn more about pagination.

filter - LedgerEntryGroupBalanceFilterSet

first - Int

The number of group balances to return per page, when paginating forwards. Defaults to 20, maximum is 200.

last - Int

The number of group balances to return per page, when paginating backwards. Defaults to 20, maximum is 200.
created - DateTime ISO-8601 timestamp this LedgerEntryGroup was created in FRAGMENT .
dashboardUrl - String! URL to the FRAGMENT Dashboard for this Ledger Entry Group.
key - SafeString! The key of this Ledger Entry Group.
ledger - Ledger! The Ledger that this Ledger Entry Group is within.
ledgerEntries - LedgerEntriesConnection!
Arguments

after - String

Where to start paginating from, when paginating forwards. Send endCursor from a response to get its next page. Learn more about pagination.

before - String

Where to start paginating from, when paginating backwards. Send startCursor from a response to get the previous page. Learn more about pagination.

filter - LedgerEntriesFilterSet

first - Int

The number of Ledger Entries to return per page, when paginating forwards. Defaults to 20, maximum is 200.

last - Int

The number of Ledger Entries to return per page, when paginating backwards. Defaults to 20, maximum is 200.
ledgerId - ID! The ID of the Ledger this Ledger Entry Group is within.
value - SafeString! The value associated with Ledger Entry Group.

LedgerEntryGroupBalance#

Represents the total effect of a Ledger Entry Group on a Ledger Account balance for a single currency.


Example
{
  "account": LedgerAccount,
  "currency": Currency,
  "ownBalance": "999999999999"
}

Field Name Description
account - LedgerAccount! The Ledger Account whose balance is affected.
currency - Currency! The currency of the affected balance.
ownBalance - Int96! The total balance change for this Ledger Account and currency.
Arguments

consistencyMode - ReadBalanceConsistencyMode

The consistency mode to use when fetching the balance. Use 'use_account' to match the configured consistency mode of the account.

LedgerEntryTag#

A tag attached to a Ledger Entry.


Example
{"key": "some-safe-string-ik", "value": "some-safe-string-ik"}

Field Name Description
key - SafeString! The key of this tag.
value - SafeString! The value associated with this tag's key.

SchemaVersion#

An instance of a Schema stored in a Workspace. A new SchemaVersion is created each time a Schema is stored. It stores the Chart of Accounts and list of Ledger Entries as well as a history of its Ledger migrations.


Example
{
  "created": "2007-12-03T10:15:30Z",
  "json": "{"key":"value"}",
  "migrations": LedgerMigrationConnection,
  "version": 2277
}

Field Name Description
created - DateTime!
json - JSON!
migrations - LedgerMigrationConnection!
version - Int! The version of the schema.

StripeEnv#

Example
"livemode"

Enum Value Description
livemode
testmode

UnitEnv#

Example
"production"

Enum Value Description
production
sandbox

E CLI Commands#

Use the CLI to:

  • Generate GraphQL queries specific to your Schema
  • Embed the CLI within your CI/CD process
  • Quickly store a Schema, create a Ledger, and start posting Ledger Entries

To install using Homebrew, run:

brew tap fragment-dev/tap &&\
  brew install fragment-dev/tap/fragment-cli

login

#

Authenticate with FRAGMENT.

Authentication is scoped to one FRAGMENT Workspace. If you want to authenticate with another Workspace, you must create another API Client and follow the authentication flow again.

Credentials will be written to ~/.fragment/auth.json.

Usage
fragment login \
  [--api-url=<api-url>] \
  [--client-id=<client-id>] \
  [--client-secret=<client-secret>] \
  [--oauth-scope=<oauth-scope>] \
  [--oauth-url=<oauth-url>] \
  [--test]

Optionally, run fragment login and the CLI will prompt you for the credentials.

Flags
--api-url=<api-url>The API URL for your FRAGMENT Workspace
--client-id=<client-id>The API Client ID
--client-secret=<client-secret>The API Client Secret
--oauth-scope=<oauth-scope>The OAuth Scope for your auth token
--oauth-url=<oauth-url>The OAuth URL from which to retrieve the auth token
--testIf set, tests stored credentials
Example
fragment login \
  --api-url="<api-url>" \
  --client-id="<client-id>" \
  --client-secret="<client-secret>" \
  --oauth-scope="<oauth-scope>" \
  --oauth-url="<oauth-url>"

To test the stored credentials, run:

fragment login --test

store-schema

#

Store a Schema within your FRAGMENT workspace.

Usage
fragment store-schema [-p <value>] [-v]
Flags
-p, --path=<value>[default: fragment.jsonc] Path for schema JSON file.
-v, --verboseEnable verbose mode (prints GraphQL commands)
Example
fragment store-schema \
  -p your-fragment-schema.jsonc

create-ledger

#

Create a Ledger within your FRAGMENT workspace.

Usage
fragment create-ledger \
  --ik=<ledger-ik> \
  --name=<ledger-name> \
  --schema=<schema-file>
Flags
-i, --ik=<ledger-ik>Idempotency key for createLedger
-n, --name=<ledger-name>Ledger name
-s, --schema=<schema-key>[default: fragment.jsonc] Path to the schema JSON file.
-v, --verboseEnable verbose mode (prints GraphQL commands)
Example
fragment create-ledger \
  --ik=test-ledger \
  --name="Test Ledger" \
  --schema=your-fragment-schema.jsonc

get-schema

#

Retrieve a Schema from the API for local use.

Usage
fragment get-schema \
  [--key=<schema-key>] \
  [--version=<version>] \
  [--output=<output-file>] \
  [-v]
Flags
-k, --key=<schema-key>(Optional) Key of the Schema (e.g. template-schema). If not provided, you'll be prompted to choose a Schema.
-o, --output=<output-file>Path to the JSONC schema file. Defaults to the schema key in the current directory.
--version=<version>Schema version to retrieve. Defaults to the latest version.
-v, --verboseEnable verbose mode (prints GraphQL commands)
Example

To choose the Schema from a list, run:

fragment get-schema

If providing the Schema key, run:

Providing a Schema key
fragment get-schema \
  --key=test-schema

add-ledger-entry

#

Post a Ledger Entry to your FRAGMENT Ledger.

Usage
fragment add-ledger-entry \
  --ik=<add-ledger-entry-ik> \
  --ledger.ik=<ledger-ik> \
  --type=<entry-type> \
  [--param=<parameter-value>] \
  [-v]
Flags
-i, --ik=<add-ledger-entry-ik>Idempotency key for addLedgerEntry
-l, --ledger.ik=<ledger-ik>Idempotency Key of the Ledger to post the Ledger Entry to
-t, --type=<entry-type>The type of Ledger Entry you want to post
-p, --param=<value>...The parameters for your Ledger Entry. You may specify multiple parameters by repeating the flag.
(ex: --param amount=100 --param currency=USD)
-v, --verboseEnable verbose mode (prints GraphQL commands)
Example
fragment add-ledger-entry \
  --ik=your-entry-ik \
  --ledger.ik=your-ledger-ik \
  --type=user_funds_account \
  --param='user_id="testing-user"' \
  --param='funding_amount="200"'

gen-graphql

#

Generate GraphQL queries to post Ledger Entries for a given Schema.

The generated GraphQL queries can be used to generate SDK code specific to your Schema. Read Install the SDK to learn more.

Usage
fragment gen-graphql \
  --path=<path-to-schema.jsonc> \
  --output=<output-filename.graphql>
Flags
-o, --output=<output-filename>The path for the generated file. Must end with .graphql or .gql
-p, --path=<schema-file-path>The path to your Schema file
--output-file-per-queryOutput a folder of queries, instead of a single file
--include-standard-queriesInclude the set of standard GraphQL queries in the output. This is required only if you are not using the FRAGMENT SDKs
Example
fragment gen-graphql \
  --path=your-fragment-schema.jsonc \
  --output=queries.graphql
fragment gen-graphql \
  --path=your-fragment-schema.jsonc \
  --output=generated/queries \
  --output-file-per-query

update

#

Update the FRAGMENT CLI.

Usage
fragment update [-y] [--dry-run]
Flags
-y, --yesUpdate without being prompted
--dry-runRun the update process without updating the CLI
Example
fragment update -y

token

#

Get a FRAGMENT Authentication Token.

This will print your auth token to standard output (stdout).

Usage
fragment token

help

#

Display help prompt for the CLI.

Usage
fragment help [COMMANDS]
Flags
COMMANDS...The Command (or Commands) to show help for. Ex: store-schema
Example
fragment help store-schema

workspace

#

Get the details of the Workspace this CLI is authenticated to.

Usage
fragment workspace