ACMC GraphQL Queries and Mutations

Queries and Mutations Overview

In GraphQL, operations are divided into two primary types: Queries and Mutations. Queries are used to retrieve data from the API, while Mutations allow for creating, updating, or deleting data. Both types provide powerful capabilities for interacting with the ACMC API, enabling developers to manage financial data with precision and flexibility.

Core Capabilities:

  • Queries: Efficiently fetch data such as accounts, transactions, and other entities. GraphQL allows you to request only the specific data fields you need, reducing unnecessary data transfer.

  • Mutations: Manage data by creating, updating, or deleting entities such as payments, account details, or transaction entries, ensuring real-time updates and accuracy.

Queries

Queries are the read operation of GraphQL. They allow you to retrieve data from the server without modifying it. In ACMC’s API, the bank and node fields offer access to essential financial data such as account balances, approvals, payments, and more. Each query starts at the root Query type and can fetch both simple scalar fields and complex, nested objects.

Key Features of Queries:

  • Field Selection: Only request the fields you need, minimizing response size.

  • Nested Queries: Retrieve related data, such as transactions related to an account, within a single request.

  • Pagination: Handle large datasets by requesting results in smaller chunks using the first, last, before, and after arguments.

  • Filtering: Refine the results of queries based on specific conditions, such as retrieving only active accounts or transactions within a certain date range.

List of ACMC Queriable Objects

Query Description
bank The bank field is the primary entry point for accessing a wide range of financial data. It includes connections that allow you to query for information on accounts, approvals, payments, and more. Each of these connections supports pagination, filtering, and ordering.
  • Accounts: Retrieve details of bank accounts with pagination and filtering options, such as account status, balance, or account type. You can also order the results.
  • Customers: Retrieve detailed customer information using the customers field.
  • Business Processes, Payments, Products: Query business processes, payments, and financial products with similar filtering, pagination, and ordering features to retrieve relevant financial data efficiently.
  • Reports and Receipts: Access report and receipt data using pagination and filtering mechanisms to narrow down the results to specific business needs.
heartbeat The heartbeat field provides basic system health information. It is used to confirm the current operational status of the ACMC API. The response typically includes uptime or simple diagnostic information, useful for monitoring the APIs availability.
node The node field provides a powerful way to query any entity by its unique identifier (ID). This field allows you to:
  • Fetch any object by its ID: Retrieve specific entities, such as accounts or transactions, based on their globally unique ID. This is useful when you know the exact entity you're looking for and want to retrieve it directly.
Arguments:
  • id: (ID!): The unique identifier for the entity you are querying. This is required to fetch the specific entity.

Mutations

Mutations allow developers to modify data within the ACMC platform. This includes operations like creating new accounts, updating transaction statuses, or initiating payments. Unlike queries, which are read-only, mutations change the underlying data and can return the affected objects, enabling developers to confirm successful updates in real-time.

Key Features of Mutations:

  • Create, Update, Delete: Perform various operations on entities such as creating payments, updating client details, or deleting transactions.

  • Input Fields: Mutations often require input data, such as account information or payment details, which are passed via input types.

  • Immediate Feedback: Mutations return the updated or created data, allowing developers to verify the changes made in real-time.

For example, when initiating a new payment, a mutation allows you to specify the recipient, amount, and payment method. The mutation will return a confirmation with the payment details, including the transaction ID and status.

List of ACMC Mutation Operations

  • Allocate: Allocates an unallocated transaction to a client account.
  • Approve Request: Sends an approval for a command awaiting approval.
  • Close Account: Closes a client account.
  • Create Party Company: Creates a new company party.
  • Create Party Individual: Creates a new individual party.
  • Delete Party: Deletes a party from the system.
  • Do Encrypted: Processes an encrypted payload, typically used for sensitive operations.
  • Execute Aggregate Payment: Executes an aggregate payment consisting of multiple instructions.
  • Make Internal Transfer: Executes an internal transfer between two accounts within the same pool.
  • Move Account: Moves an account to a different product.
  • Move Unallocated To CLA: Moves an unallocated payment or receipt to a Customer Linked Account.
  • Open Account: Opens a new account for a customer.
  • Request Payment From Customer Linked Account: Initiates a payment request from a customer linked account to a CCM account.
  • Request Withholding Tax Refund: Requests a withholding tax refund for a single account.
  • Unallocate: Unallocates a previously allocated transaction.
  • Update Account: Updates the details of an existing account.
  • Update Account Restraint: Updates the customer level account restraint.

Usage Considerations

  • Field Selection: Whether you are performing a query or mutation, always request only the fields you need to optimise performance.

  • Error Handling: Mutations provide real-time feedback. Make sure to handle errors appropriately by checking the mutation response for any issues, such as validation errors or failed operations.

  • Security: Queries and mutations both require OAuth 2.0 authentication. Ensure your tokens are valid and refreshed as needed to maintain continuous access to the ACMC API.

Performance Optimisation:

  • Queries: Limit the depth and size of your queries to avoid large responses that may affect performance.

  • Mutations: Use input types to pass structured data efficiently and avoid sending unnecessary fields.

  • Pagination: Use pagination to handle large datasets, requesting results in smaller chunks using the first, last, before, and after arguments.

  • Filtering: Refine the results of queries and mutations based on specific conditions, such as retrieving only active accounts or transactions within a certain date range.