Skip to main content

FreeAgent Data Source

The FreeAgent connector enables you to ingest accounting and financial data from your FreeAgent account, including contacts, invoices, bills, expenses, bank transactions, timeslips, projects, and more. Follow the instructions below to create a new data flow that ingests data from a FreeAgent source in Nexla.
free_agent_api.png

FreeAgent

Create a New Data Flow​

  1. To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Then, select the desired flow type from the list, and click the Create button.

  2. Select the FreeAgent connector tile from the list of available connectors. Then, select the credential that will be used to connect to the FreeAgent instance, and click Next; or, create a new FreeAgent credential for use in this flow.

  3. In Nexla, FreeAgent data sources can be created using pre-built endpoint templates, which expedite source setup for common FreeAgent endpoints. Each template is designed specifically for the corresponding FreeAgent endpoint, making data source setup easy and efficient.
    • To configure this source using a template, follow the instructions in Configure Using a Template.

    FreeAgent sources can also be configured manually, allowing you to ingest data from FreeAgent endpoints not included in the pre-built templates or apply further customizations to exactly suit your needs.
    • To configure this source manually, follow the instructions in Configure Manually.

Configure Using a Template​

Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common FreeAgent endpoints. Each template is designed specifically for the corresponding FreeAgent endpoint, making data source setup easy and efficient.

Endpoint Settings​

  • Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below. Click on an endpoint to see more information about it and how to configure your data source for this endpoint.

    List Users

    Returns a list of all users in the FreeAgent account. Use this endpoint to retrieve user profiles, roles, and contact details for everyone who has access to the account.

    • Sends a GET request to /users; returns user records as an array at $.users[*].
    • Each record includes the user's name, email, role, and account permissions.

    This endpoint requires an OAuth access token with appropriate scope for the FreeAgent account. Only users with admin-level access can view all account users.

    Get Balance Sheet

    Returns the balance sheet accounting report for the FreeAgent account. Use this endpoint to retrieve a point-in-time snapshot of assets, liabilities, and equity.

    • Sends a GET request to /accounting/balance_sheet; returns the full balance sheet object at $.
    • The response is a single JSON object containing categorized account balances rather than an array of records.

    The balance sheet reflects the state of the account at the time the request is made. For historical balance sheet data, use FreeAgent's date query parameters if supported for your account type.

    List Bank Accounts

    Returns a list of all bank accounts connected to the FreeAgent account. Use this endpoint to retrieve bank account details including account names, types, and balances.

    • Sends a GET request to /bank_accounts; returns bank account records as an array at $.bank_accounts[*].
    • Each record includes the account name, currency, opening balance, and current balance.

    Bank accounts returned include both manually managed accounts and accounts connected via Open Banking. Use the bank account URL from each record as a reference when fetching bank transactions for a specific account.

    List Bank Transactions

    Returns a list of all bank transactions in the FreeAgent account. Use this endpoint to retrieve transaction history across all connected bank accounts.

    • Sends a GET request to /bank_transactions; returns transaction records as an array at $.bank_transactions[*].
    • Each record includes the transaction date, amount, description, and reconciliation status.

    FreeAgent paginates bank transaction results — by default 25 records are returned per page. Use the page and per_page query parameters to retrieve additional pages. Use date range parameters (from_date, to_date) combined with Nexla date/time macros for incremental ingestion.

    List Bills

    Returns a list of all bills (supplier invoices) in the FreeAgent account. Use this endpoint to track outstanding and paid supplier bills.

    • Sends a GET request to /bills; returns bill records as an array at $.bills[*].
    • Each record includes the bill reference, supplier contact, due date, total amount, and payment status.

    Bills are the FreeAgent term for supplier invoices / purchase invoices. Use filter parameters such as view to narrow results to unpaid, overdue, or recently updated bills.

    List Contacts

    Returns a list of all contacts in the FreeAgent account. Use this endpoint to retrieve customer and supplier records including names, addresses, and contact details.

    • Sends a GET request to /contacts; returns contact records as an array at $.contacts[*].
    • Each record includes the contact name, email, phone, billing address, and contact type (customer or supplier).

    FreeAgent supports filtering contacts by type using the view query parameter (e.g., ?view=clients or ?view=suppliers). Results are paginated — use page and per_page parameters for large contact lists.

    List Credit Note Reconciliations

    Returns a list of credit note reconciliations in the FreeAgent account. Use this endpoint to track how credit notes have been applied against invoices or other transactions.

    • Sends a GET request to /credit_note_reconciliations; returns reconciliation records as an array at $.credit_note_reconciliations[*].
    • Each record includes the credit note reference, the invoice it was applied to, and the reconciled amount.

    This endpoint is useful for reconciliation reporting and auditing credit note applications across your accounts receivable ledger.

    List Credit Notes

    Returns a list of all credit notes in the FreeAgent account. Use this endpoint to retrieve credit note records issued to customers.

    • Sends a GET request to /credit_notes; returns credit note records as an array at $.credit_notes[*].
    • Each record includes the credit note reference, associated contact, issue date, total amount, and status.

    Credit notes can be filtered by status and date range using FreeAgent's query parameters. Results are paginated — use page and per_page to retrieve additional pages.

    List Estimates

    Returns a list of all estimates (quotes) created in the FreeAgent account. Use this endpoint to track the status of outstanding estimates and their conversion to invoices.

    • Sends a GET request to /estimates; returns estimate records as an array at $.estimates[*].
    • Each record includes the estimate reference, associated contact, issue date, expiry date, total amount, and status.

    Estimates can be filtered by status (e.g., draft, sent, accepted) using the view query parameter. Results are paginated.

    List Expenses

    Returns a list of all expenses recorded in the FreeAgent account. Use this endpoint to retrieve employee expense claims including amounts, categories, and reimbursement status.

    • Sends a GET request to /expenses; returns expense records as an array at $.expenses[*].
    • Each record includes the expense date, category, amount, currency, associated user, and reimbursement status.

    Expenses can be filtered by date range using the from_date and to_date query parameters — combine these with Nexla date/time macros for incremental ingestion of newly submitted expenses.

    List Invoices

    Returns a list of all invoices in the FreeAgent account. Use this endpoint to retrieve sales invoice records including amounts, due dates, and payment status.

    • Sends a GET request to /invoices; returns invoice records as an array at $.invoices[*].
    • Each record includes the invoice reference, associated contact, issue date, due date, total amount, and payment status.

    Invoices support filtering by status, date range, and contact using query parameters such as view, from_date, to_date, and contact. Results are paginated — the default is 25 per page, with a maximum of 100.

    Get Company

    Returns details about the company associated with the FreeAgent account. Use this endpoint to retrieve company profile information such as name, registration number, address, and VAT details.

    • Sends a GET request to /company; returns the company object at $.company.
    • The response is a single company object — not an array — containing all company profile fields.

    The company record is a singleton — there is only one company per FreeAgent account. This endpoint is useful for enriching other FreeAgent data with the account owner's company details.

    Get Profit & Loss Summary

    Returns a profit and loss summary report for the company in FreeAgent. Use this endpoint to retrieve income, expenses, and net profit figures for reporting and financial analysis.

    • Sends a GET request to /accounting/profit_and_loss/summary; returns the profit and loss summary object at $.profit_and_loss.
    • The response is a single object containing categorized income and expense totals — not an array of records.

    Use the from_date and to_date query parameters to retrieve the profit and loss summary for a specific period. FreeAgent expects dates in YYYY-MM-DD format — combine with Nexla date/time macros for rolling period reports.

    List Projects

    Returns a list of projects in the FreeAgent account. Use this endpoint to retrieve project details including budgets, timelines, and associated contacts.

    • Sends a GET request to /projects; returns project records as an array at $.projects[*].
    • Each record includes the project name, associated contact, status, budget, and timeline dates.

    Projects can be filtered by status (active, completed, or cancelled) using the view query parameter. Project URLs returned in the response can be used to fetch related tasks or timeslips.

    List Tasks

    Returns a list of tasks in the FreeAgent account. Use this endpoint to retrieve task definitions including billing rates and associated projects.

    • Sends a GET request to /tasks; returns task records as an array at $.tasks[*].
    • Each record includes the task name, associated project, billing type, and hourly rate.

    Tasks are linked to projects in FreeAgent and are used to categorize timeslips. Use the project URL as a filter parameter to retrieve tasks for a specific project.

    List Timeslips

    Returns a list of all timeslips (time entries) in the FreeAgent account. Use this endpoint to retrieve time tracking data for billing, payroll, and project management purposes.

    • Sends a GET request to /timeslips; returns timeslip records as an array at $.timeslips[*].
    • Each record includes the date, user, task, project, duration in hours, and billing status.

    Timeslips support filtering by date range (from_date, to_date), user, task, and project. Use Nexla date/time macros with from_date/to_date to perform incremental ingestion of newly logged time entries. Results are paginated.

Endpoint Testing​

Once the selected endpoint template has been configured, Nexla can retrieve a sample of the data that will be fetched according to the current settings. This allows users to verify that the source is configured correctly before saving.

  • To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

  • If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Configure Manually​

FreeAgent sources can also be configured manually, allowing you to ingest data from any valid FreeAgent API endpoint. Configuration options available for FreeAgent sources allow them to be fully customized to suit any use case — including using chained API calls to fetch data from multiple endpoints or sources that require custom authentication headers or request parameters.

First, select the method that will be used for calls to the FreeAgent API from the Method pulldown menu. The most common methods are:

  • GET: For retrieving data from the API (used for listing and reading resources such as invoices, contacts, bank transactions, and expenses)

  • POST: For sending data to the API or triggering actions

  • PUT: For replacing existing resource data

  • PATCH: For partial updates to existing data

  • DELETE: For removing data

Most FreeAgent data retrieval operations use the GET method. The FreeAgent API base URL for production is https://api.freeagent.com/v2. For sandbox testing, use https://api.sandbox.freeagent.com/v2. See the FreeAgent API documentation for the full list of available endpoints and their HTTP methods.

API Endpoint URL​

  1. Enter the URL of the FreeAgent API endpoint from which this source will fetch data in the Set API URL field. This should be the complete URL including the protocol (https://) and the resource path.

    Common FreeAgent API endpoint URL patterns include:

    • Contacts: https://api.freeagent.com/v2/contacts

    • Invoices: https://api.freeagent.com/v2/invoices

    • Bills: https://api.freeagent.com/v2/bills

    • Expenses: https://api.freeagent.com/v2/expenses

    • Bank Transactions: https://api.freeagent.com/v2/bank_transactions

    • Timeslips: https://api.freeagent.com/v2/timeslips

    • Projects: https://api.freeagent.com/v2/projects

    • Users: https://api.freeagent.com/v2/users

    • Company: https://api.freeagent.com/v2/company

    The FreeAgent API uses pagination for endpoints that return multiple items — by default, 25 items are returned per page. You can control pagination using the page and per_page query parameters (maximum 100 items per page). For example: https://api.freeagent.com/v2/invoices?page=1&per_page=100. For the full list of available endpoints and their parameters, refer to the FreeAgent API reference.

Date/Time Macros (API URL)​

Optional

Optionally, the API URL can be customized using macros — all macros added to the API URL will be converted into values when Nexla executes the API call. Macros are dynamic placeholders that allow you to create flexible API endpoints that can adapt to different time periods or data requirements.

Date/time macros are particularly useful for FreeAgent endpoints that support date filtering. For example, FreeAgent's invoices endpoint supports from_date and to_date query parameters (format: YYYY-MM-DD), making it straightforward to configure incremental ingestion of invoices created or updated within a rolling time window.

  1. To add a macro, type { at the appropriate position in the API URL (within the Set API URL field), and select the desired macro from the dropdown list.

    • {now} – The current datetime
    • {now-1} – The datetime one time unit before the current datetime
    • {now+1} – The datetime one time unit after the current datetime
    • custom – Datetime macros can reference any number of time units before or after the current datetime — for example, enter (now-4) to indicate the datetime four time units before the current datetime

  2. Select the format that will be applied to datetime macros from the Date Format for Date/Time Macro pulldown menu. This format will be applied to the base datetime value of the macro — i.e., the value of {now} in {now-1}.

  3. Select the datetime unit that will be used to perform mathematical operations in the included macro(s) from the Time Unit for Operations pulldown menu — for example, for the macro {now-1}, when Day is selected, {now-1} will be converted to the datetime one day before the current datetime.

Lookup-Based Macros (API URL)​

Optional

Column values from existing lookups can also be included as macros in the API URL. Lookup-based macros allow you to reference data from previously configured data sources or lookups, enabling dynamic API endpoints that can adapt based on existing data.

Lookup-based macros are useful when you need to create FreeAgent API endpoints that reference specific IDs, values, or parameters from other data sources in your Nexla environment. For example, you could reference a project ID from a lookup to dynamically fetch timeslips for a specific FreeAgent project.

  1. To include a lookup column value macro, select the relevant lookup from the Add Lookups to Supported Macros pulldown menu.

  2. Type { at the appropriate position in the API URL, and select the lookup column-based macro from the dropdown list. Lookup-based macros are automatically populated into the macro list when a lookup is selected in the Add Lookups to Supported Macros pulldown menu.

Path to Data​

Optional

If only a subset of the data returned by the API endpoint is needed, you can designate the part(s) of the response that should be included in the Nexset(s) produced from this source by specifying the path to the relevant data within the response. This is particularly useful when API responses contain metadata, pagination information, or other data that you don't need for your analysis.

For example, FreeAgent API list responses typically wrap the resource array within a named JSON object. When fetching invoices, the response has the structure {"invoices": [...]}, and when fetching contacts, the structure is {"contacts": [...]}. By entering the path to the relevant data array, you can configure Nexla to treat each element of the returned array as a record.

Path to Data is essential when API responses have nested structures. Without specifying the correct path, Nexla might not be able to properly parse and organize your data into usable records.

  • To specify which data should be treated as relevant in responses from this source, enter the path to the relevant data in the Set Path to Data in Response field.

    • For responses in JSON format, enter the JSON path that points to the object or array that should be treated as relevant data. JSON paths use dot notation (e.g., $.invoices[*] to access an array of invoices, or $.contacts[*] to access an array of contacts).

    • For responses in XML format, enter the XPath that points to the object/array containing relevant data.

    FreeAgent Path to Data Examples:
    • For the invoices endpoint (/v2/invoices), the path is $.invoices[*]
    • For the contacts endpoint (/v2/contacts), the path is $.contacts[*]
    • For the bank_transactions endpoint (/v2/bank_transactions), the path is $.bank_transactions[*]
    • For the expenses endpoint (/v2/expenses), the path is $.expenses[*]
    • For the timeslips endpoint (/v2/timeslips), the path is $.timeslips[*]
Autogenerate Path Suggestions​

Nexla can also autogenerate data path suggestions based on the response from the API endpoint. These suggested paths can be used as-is or modified to exactly suit your needs.

  • To use this feature, click the Test button next to the Set API URL field to fetch a sample response from the API endpoint. Suggested data paths generated based on the content & format of the response will be displayed in the Suggestions box below the Set Path to Data in Response field.

  • Click on a suggestion to automatically populate the Set Path to Data in Response field with the corresponding path. The populated path can be modified directly within the field if further customization is needed.

    PathSuggestions.png

Metadata​

If metadata is included in the response but is located outside of the defined path to relevant data, you can configure Nexla to include this data as common metadata in each record. This is useful when you want to preserve important contextual information that applies to all records but isn't part of the main data array.

For example, FreeAgent list API responses include the array of resource objects alongside pagination information. If you have specified the path to the relevant data array but want to preserve the total count or other top-level metadata, you can specify a path to this metadata to include it with each record in the generated Nexset(s).

Metadata paths are particularly useful for preserving API response context like request IDs, timestamps, or summary statistics that apply to all records in the response.

  • To specify the location of metadata that should be included with each record, enter the path to the relevant metadata in the Path to Metadata in Response field.

    • For responses in JSON format, enter the JSON path to the object or array that contains the metadata, and for responses in XML format, enter the XPath.

Request Headers​

Optional

  • If Nexla should include any additional request headers in API calls to this source, enter the headers & corresponding values as comma-separated pairs in the Request Headers field (e.g., header1:value1,header2:value2). Additional headers are sometimes required for API versioning or content type specifications.

    You do not need to include the OAuth Authorization header — Nexla automatically includes the access token from your FreeAgent credential. The FreeAgent API accepts responses in both JSON and XML formats; Nexla defaults to JSON. If your integration requires a specific format, you can specify it by adding an Accept header (e.g., Accept:application/json).

Endpoint Testing​

After configuring all settings for the selected endpoint, Nexla can retrieve a sample of the data that will be fetched according to the current configuration. This allows users to verify that the source is configured correctly before saving.

  • To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

  • If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Save & Activate the Source​

  1. Once all of the relevant steps in the above sections have been completed, click the Create button in the upper right corner of the screen to save and create the new FreeAgent data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.