> ## Documentation Index
> Fetch the complete documentation index at: https://agenticbanking.backbase.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Reference

> Configuration properties, operations, events, and field mappings for the Plaid Connector

export const VendorApiVersionTag = ({versions, label = "Supports"}) => {
  useEffect(() => {
    if (!versions || versions.length === 0) {
      return undefined;
    }
    const findAndSegmentStart = (reference, target) => {
      let i = 0;
      while (i < reference.length && i < target.length && reference[i] === target[i]) {
        i += 1;
      }
      let start = i;
      while (start > 0 && (/[0-9.vR]/).test(target[start - 1])) {
        start -= 1;
      }
      return start;
    };
    const formatText = () => {
      const suffix = " operations";
      if (versions.length === 1) {
        return `${label} ${versions[0]}${suffix}`;
      }
      const [first, ...rest] = versions;
      const last = rest[rest.length - 1];
      const andStart = findAndSegmentStart(first, last);
      const lead = first.slice(0, andStart);
      if (versions.length === 2) {
        return `${label} ${first} and ${last.slice(andStart)}${suffix}`;
      }
      const stems = versions.map(version => version.slice(andStart));
      return `${label} ${lead}${stems.slice(0, -1).join(", ")}, and ${stems[stems.length - 1]}${suffix}`;
    };
    const text = formatText();
    const mountCallout = () => {
      const title = document.querySelector("#page-title");
      const header = title?.closest("header") ?? document.querySelector("#header");
      if (!title || !header || !header.contains(title)) {
        return null;
      }
      let titleBlock = title;
      while (titleBlock.parentElement && titleBlock.parentElement !== header) {
        titleBlock = titleBlock.parentElement;
      }
      let callout = header.querySelector("[data-vendor-api-version-callout='true']");
      if (!callout) {
        callout = document.createElement("div");
        callout.dataset.vendorApiVersionCallout = "true";
        callout.className = "vendor-api-version-callout";
        titleBlock.insertAdjacentElement("afterend", callout);
      }
      callout.replaceChildren();
      const textEl = document.createElement("span");
      textEl.className = "vendor-api-version-text";
      textEl.textContent = text;
      callout.appendChild(textEl);
      return callout;
    };
    let callout = mountCallout();
    if (callout) {
      return () => {
        callout?.remove();
      };
    }
    const observer = new MutationObserver(() => {
      callout = mountCallout();
      if (callout) {
        observer.disconnect();
      }
    });
    observer.observe(document.body, {
      childList: true,
      subtree: true
    });
    return () => {
      observer.disconnect();
      callout?.remove();
    };
  }, [versions, label]);
  return null;
};

export const vendorApiVersions = ["Plaid Enrich API"];

<VendorApiVersionTag versions={vendorApiVersions} />

The Plaid Connector calls Plaid Enrich synchronously and publishes enrichment results to Sync Hub. For setup steps, see [Get started](/connectors/financial-data-aggregation/plaid-transaction-enrichment/get-started).

## Configuration properties

### Values to obtain from the vendor

Obtain the following values from Plaid and set them in the connector values files for your runtime. The following table lists each property and its purpose.

| Property             | Description                                                                                                                                |
| :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- |
| `api.plaid.url`      | Plaid Enrich API URL for your environment (sandbox or production).                                                                         |
| `api.plaid.clientId` | Plaid client ID. Resolves from the `PLAID_CLIENT_ID` environment variable. Grand Central sends this value as the `PLAID-CLIENT-ID` header. |
| `api.plaid.secret`   | Plaid secret. Resolves from the `PLAID_SECRET` environment variable. Grand Central sends this value as the `PLAID-SECRET` header.          |

### gc-plaid-transaction-enrichment-connector

The following table lists Azure Service Bus (ASB) producer properties that `gc-plaid-transaction-enrichment-connector` uses in the `gc-applications-live` repository:

| Property              | Description                                                                        | Default                                   |
| :-------------------- | :--------------------------------------------------------------------------------- | :---------------------------------------- |
| `asb.producer.apiUri` | Callback URI of the Sync Hub ASB producer that receives outgoing events.           | No default. Set this value at deployment. |
| `asb.event.topic`     | Topic for enrichment result events.                                                | No default. Set this value at deployment. |
| `asb.event.source`    | Source identifier for outgoing messages.                                           | No default. Set this value at deployment. |
| `asb.event.type`      | Event type for outgoing messages. Use `transactionsEnriched` for the success path. | No default. Set this value at deployment. |
| `asb.event.version`   | Schema version of the published event.                                             | No default. Set this value at deployment. |

## SOPS secrets

The connector reads Plaid credentials from `PLAID_CLIENT_ID` and `PLAID_SECRET`. Store those environment variables in a SOPS secret. For more information, see [How to create SOPS](/platform/developer-guides/build/configure-connector).

## Supported operations

For the full contract, see [API playground](/connectors/reference/unified-api-playground).

| Method                                         | Endpoint                            | Purpose                                                                          |
| :--------------------------------------------- | :---------------------------------- | :------------------------------------------------------------------------------- |
| <span className="http-method-post">POST</span> | `/internal/transactions/enrichment` | Accept a batch of transactions for enrichment. Returns `202` with an empty body. |

An enrichment request must include a UUID `enrichmentRequestId`, a `partyInformation` array, and an `accounts` array. A request can contain a maximum of 50 accounts and 100 transactions in total.

## Events

The connector publishes the following Sync Hub events when Plaid Enrich completes.

| Event                  | When emitted                                                                 |
| :--------------------- | :--------------------------------------------------------------------------- |
| `transactionsEnriched` | Plaid Enrich succeeds, including partial per-item outcomes where applicable. |

Published events use the standard Grand Central envelope. The `data` payload includes per-transaction category, merchant, and location fields.

Downstream services can also align with the `transactionsEnrichmentRequested` Sync Hub payload shape when they initiate enrichment through internal position-keeping or event-driven flows. For more information about event schemas, see [API playground](/connectors/reference/unified-api-playground).

## Requirements and restrictions

The following table lists request limits and connector behavior:

| Requirement or restriction | Detail                                                                                                                                                                                                                                                                                                                                            |
| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Batch size                 | Maximum of **100** transactions per request across all accounts. This limit is fixed in the connector.                                                                                                                                                                                                                                            |
| Account count              | Maximum of **50** accounts per request.                                                                                                                                                                                                                                                                                                           |
| Synchronous vendor call    | The connector calls Plaid `POST /transactions/enrich` before publishing to Sync Hub. There is no webhook callback for completion.                                                                                                                                                                                                                 |
| Learn and unlearn          | Plaid Enrich does not support learn or unlearn category feedback flows. Use SaltEdge if you need those capabilities.                                                                                                                                                                                                                              |
| Category taxonomy          | Grand Central preserves Plaid native personal finance categories. It does not remap Plaid categories to other vendor taxonomies.                                                                                                                                                                                                                  |
| Mandatory request fields   | Each enrichment request requires a UUID `enrichmentRequestId`, a `partyInformation` array, and at least one account with at least one transaction. Confirm remaining transaction fields in the [Plaid field mapping sheet](https://docs.google.com/spreadsheets/d/1nfj_V-AEArcRhvS60wu8zGU2yIpxwjaO_4EYfNagtEo/edit?gid=759261116#gid=759261116). |

## Field mapping

Grand Central maps Plaid Enrich request and response fields to the unified transaction enrichment model. The mapping sheet lists mandatory and optional fields and canonical target paths such as `merchantInformation` and category fields.

For the authoritative mapping reference, see the [Plaid field mapping sheet](https://docs.google.com/spreadsheets/d/1nfj_V-AEArcRhvS60wu8zGU2yIpxwjaO_4EYfNagtEo/edit?gid=759261116#gid=759261116).

## Error mapping

The connector maps Plaid error responses to Grand Central status codes. For the full list of Grand Central codes, see [Error codes](/connectors/reference/error-codes). The following table shows Plaid `error_code` values and the corresponding Grand Central codes:

| Plaid code                    | Grand Central code |
| :---------------------------- | :----------------- |
| `MISSING_FIELDS`              | `GC439`            |
| `INVALID_FIELD`               | `GC025`            |
| `INVALID_BODY`                | `GC024`            |
| `INVALID_HEADERS`             | `GC025`            |
| `UNKNOWN_FIELDS`              | `GC025`            |
| `INCOMPATIBLE_API_VERSION`    | `GC025`            |
| `NOT_FOUND`                   | `GC054`            |
| `NO_LONGER_AVAILABLE`         | `GC054`            |
| `INVALID_API_KEYS`            | `GC001`            |
| `UNAUTHORIZED_ROUTE_ACCESS`   | `GC004`            |
| `UNAUTHORIZED_ENVIRONMENT`    | `GC004`            |
| `INVALID_PRODUCT`             | `GC004`            |
| `INTERNAL_SERVER_ERROR`       | `GC028`            |
| `PLANNED_MAINTENANCE`         | `GC064`            |
| `RATE_LIMIT`                  | `GC031`            |
| `RATE_LIMIT_EXCEEDED`         | `GC031`            |
| `INVALID_SANDBOX_TRANSACTION` | `GC415`            |

The following table shows Plaid `error_type` fallbacks when a more specific `error_code` mapping does not apply:

| Plaid error type  | Grand Central code |
| :---------------- | :----------------- |
| `INVALID_REQUEST` | `GC025`            |
| `ENRICH_ERROR`    | `GC415`            |

## Dependencies

* [Sync Hub](/platform/sync-hub/overview)
* [Grand Central unified transaction enrichment API](/connectors/reference/unified-api-playground)
* [Plaid Enrich](https://plaid.com/products/enrich/)