Zapier Destination

Introduction

Connect Finicom to thousands of other applications using Zapier. This integration allows you to automate workflows based on your bank transaction events in Finicom, such as creating tasks, sending notifications, or updating spreadsheets whenever new transactions are added, modified, or deleted.

The setup process is primarily done within Zapier, and Finicom will automatically create the necessary connections on your behalf.

Prerequisites

• A Finicom account with at least one bank account source connected.
• A Zapier account (a free or paid plan, depending on your needs).

Setup Guide

Follow these steps to connect Finicom to Zapier:

1. Get Your Finicom API Key

You'll need a Finicom API key to allow Zapier to securely access your Finicom data.

1. Log in to your Finicom dashboard.

2. Navigate to Settings from the dashboard menu.

3. Scroll to the API Keys section, at the bottom of settings.

4. If you don't have an API key, click Create API Key. Give it a descriptive name (e.g., "Zapier Integration").

5. Copy the generated API key - it will only be shown this one time. You will need this in Zapier.

   Treat your API key like a password. Do not share it publicly.

2. Create a New Zap in Zapier

1. Log in to your Zapier account and click Create Zap or Make a Zap.
2. Trigger Setup:
   • Choose App: Search for and select Finicom as the trigger app.
   • Choose Trigger Event: Select the event that will start your Zap. Currently, the primary trigger is:
     • Bank Account Transactions Updated: Triggers when a transaction is added, modified, or deleted in a selected bank account source. (More specific triggers might be available or added in the future).
   • Connect Account:
     • Click Sign in or Connect a new account.
     • Zapier will prompt you for your Finicom API Key. Paste the key you copied in Step 1.
     • Follow the prompts to authorize the connection.
   • Set up trigger:
     • Source Account: Select the specific Finicom bank account source you want this Zap to monitor.
     • Sync Historical Data (Optional): Choose whether to sync transactions that already exist in the source (True) or only new transactions created after the Zap is activated (False). The default is usually to sync only new transactions.
   • Test trigger: Zapier will attempt to pull in sample transaction data from your selected Finicom source to confirm the setup. Ensure this test is successful.

3. Add Action Step(s) in Zapier

After setting up the trigger, configure what you want your Zap to do:

1. Click the + button to add an Action step.
2. Choose the app you want to send data to (e.g., Google Sheets, Slack, Trello).
3. Configure the action, mapping data fields from the Finicom trigger (see "Data Payload" section below) to the fields in your chosen action app.
4. Test your action step.

4. Name and Turn On Your Zap

1. Give your Zap a descriptive name.
2. Turn on your Zap.

Now, whenever the trigger event occurs in your selected Finicom source, the Zap will run and perform the actions you've configured.

5. Finicom Destination (Automatic)

Once you successfully set up and created the Finicom zap in Zapier:

• Zapier communicates with Finicom using the API key and the details you provided (like the source account).
• Finicom automatically creates a new "Zapier" destination within your Finicom organization. This destination is specifically linked to this Zap.
• You can view this automatically created destination under the Destinations page in your Finicom dashboard. It will typically be named based on the Zap or trigger.
• You may modify this destination in Finicom to apply filtering or other settings, on the Finicom side, before updates reach Zapier.

Data Payload Sent to Zapier

When a transaction event occurs, Finicom sends a JSON payload to Zapier. Your Zap will use this data. Here's what the payload typically includes:

Common Fields for All Events:

• id (string): The unique Finicom ID of the transaction.
• accountId (string): The Finicom ID of the bank account this transaction belongs to.
• updateType (string): Indicates the type of change. Values can be:
  • "ADD": A new transaction was added.
  • "MODIFY": An existing transaction was updated (e.g., status change from pending to posted, description updated).
  • "DELETE": A transaction was removed (e.g., a pending transaction that was voided).
• status (string): The transaction's status (e.g., "pending", "posted", "void").
• createdAt (string): ISO 8601 timestamp of when the transaction was created or the event occurred.
• merchant (string, optional): The merchant name.
• description (string, optional): The transaction description.
• amount (number): The transaction amount (negative for debits, positive for credits).
• currency (string): The ISO 4217 currency code (e.g., "USD").
• institutionName (string, optional): Name of the financial institution.
• accountName (string, optional): Name of the bank account in Finicom.
• category (string, optional): Transaction category.

Example Payload (Transaction Added/Modified)

{
  "id": "txn_123abc",
  "accountId": "acc_456def",
  "updateType": "Add",
  "status": "posted",
  "createdAt": "2024-05-15T10:30:00.000Z",
  "merchant": "Coffee Shop",
  "description": "Morning Latte",
  "amount": -4.5,
  "currency": "USD",
  "institutionName": "My Bank",
  "accountName": "Checking",
  "category": "Food & Drink"
}

Example Payload (Transaction Deleted)

For DELETE events, the payload will still contain the id and accountId, with updateType: "DELETE" and status: "void". Other fields might be present with their last known values or be null.

{
  "id": "txn_789ghi",
  "accountId": "acc_456def",
  "updateType": "Delete",
  "status": "void",
  "createdAt": "2024-05-16T11:00:00.000Z"
  // Other fields might be null or reflect last known state
}

Important Considerations

• One Zap, One Finicom Destination: Each Zap you create using a Finicom trigger will result in a new, automatically managed destination in your Finicom account.
• Modifying Zaps: If you change the Finicom trigger configuration in an existing Zap (e.g., change the source account), these changes should reflect in how Finicom sends data.
• Deleting Zaps: If you delete a Zap in Zapier, Finicom may not be automatically notified. The associated destination in Finicom might start showing errors if Finicom attempts to send data to a Zapier webhook URL that no longer exists (Zapier typically returns a 410 Gone status). You may want to manually delete the corresponding destination in Finicom to keep things tidy.
• Paused Zaps: If you pause a Zap in Zapier, Finicom will continue to try sending data for triggered events. These attempts will likely queue up or fail in Zapier until the Zap is resumed.

Error Handling & Troubleshooting

• Check Zap History: Zapier provides a detailed history for each Zap run, showing successes, failures, and the data processed. This is the first place to look if a Zap isn't working as expected.
• Finicom Destination Status: In Finicom, under Destinations, you can see the status of the automatically created Zapier destinations. If Finicom encounters persistent errors sending data to Zapier (e.g., Zapier's webhook URL returns errors like 4xx or 5xx), the destination status will reflect this.
  • 410 Gone: If Zapier returns a 410 status, it means the Zap or trigger is no longer active. Finicom will mark the destination with an error.
• API Key: Ensure your Finicom API key used in Zapier is valid and has not been revoked.
• Source Account: Double-check that the correct source account is selected in the Zapier trigger settings.

By following this guide, you can effectively leverage Zapier to extend the power of your Finicom financial data across your favorite applications.