Filtered by Id

Why filter by Id with “where”?

In the Sage Active Public API V2, to fetch a single record by its identifier you use the list query with an Id filter.
There is generally no dedicated <object>ById query in the schema.

<object>(where: { id: { eq: $id }})

One operation serves both lists and single-record lookup. The API does not expose a separate ById entry point per resource (except a few special cases below).

Why not a ById query?

A dedicated ById operation might look simpler for a single record, but the Id-filtered list approach is intentional:

• One <object> query for list and single-record fetch: fewer operations and types in the schema.
• Same GraphQL list + filter model as every other filtered query.
• Better performance for Id lookup in this API.
• One response shape everywhere: edges → node, so clients parse list and single-record results the same way.

Illustrative contrast (ById is not available)

The ById samples below are not part of the API. They only show what a ById-style call and response would look like, so you can see why the Id-filtered list query (and its edges/node payload) is used instead.

query ($id: ID!) {
  accountingAccountById(id: $id) {
    id
    accountLevel
    accountType
    code
    subAccountType
    description
    taxTreatmentId
  }
}

{
  "id": "{currentId}"
}

query ($id: UUID!) {
  accountingAccounts(where: { id: { eq: $id }}) {
    edges {
      node {
        id
        accountLevel
        accountType
        code
        subAccountType
        description
        taxTreatmentId
      }
    }
  }
}

{
  "id": "{currentId}"
}

Response format

A ById-style result would put the object directly under data. That shape is not what the API returns for a single-record read.

{
    "data": {
        "accountingAccountById": {
            // ... fields ...
        }
    }
}

let accountId = response.data.accountingAccountById.id;

With filtered by Id, the record is nested under edges, then node (same structure as any other list query).

{
    "data": {
        "accountingAccounts": {
            "edges": [
                {
                    "node": {
                        // ... fields ...
                    }
                }
            ]
        }
    }
}

let accountId = response.data.accountingAccounts.edges[0].node.id;

Exceptions

Almost all resources use the Id-filtered list pattern. A few operations expose a real ById query because they only make sense for a single Id.

• Actions related to the Id of an object
  For example, ProductPrice only offers productPriceById. API resources / ⚙️Product Price service
  These queries are tailored for direct access by Id and do not use the generalized list + where format.