Getting started

This section shows you how to install the Easysoft ODBC-FreeAgent Driver and configure the ODBC data source that stores the connection details for your FreeAgent organization. You’re then ready to work with FreeAgent data in your application.

Installing the Easysoft ODBC-FreeAgent Driver

Install the Easysoft ODBC-FreeAgent Driver on the computer where the application you want to connect to FreeAgent is running.

Installing on Windows

The Windows installation can be done by anyone with local administrator privileges.

  1. Download the Easysoft ODBC-FreeAgent Driver installer.

  2. Follow the onscreen instructions to progress through the installation wizard.

Updating files that are in use

To avoid rebooting your computer, the Easysoft ODBC-FreeAgent Driver installer prompts you when files that it needs to update are in use by another application or service. This frees the locked files and allows the installation to complete without a system restart. The installer uses the Restart Manager to locate the applications that are using files that need updating. These applications are displayed in the Files in Use dialog box. To avoid a system restart, choose Automatically close applications and attempt to restart them after setup is complete. The Easysoft ODBC-FreeAgent Driver installer then uses Restart Manager to try to stop and restart each application or service in the list. If possible, Restart Manager restores applications to the same state that they were in before it shut them down.

Licensing

By default, the installer starts the Easysoft License Manager, because you can’t use the Easysoft ODBC-FreeAgent Driver until you have a license. If you choose not to run Easysoft License Manager as part of the installation process, run License Manager from the Easysoft group in the Windows Start menu when you’re ready to license the Easysoft ODBC-FreeAgent Driver. These types of license are available:

  • A free time-limited trial license which gives you free and unrestricted use of the product for a limited period (usually 14 days).

  • A full license if you have purchased the product. On purchasing the product you are given an authorization code, which you use to obtain a license.

To license the Easysoft ODBC-FreeAgent Driver:

  1. In License Manager, enter your contact details.

    You must complete the Name, E-Mail Address, and Company fields.

    The e-mail address must be the same as the one used to register at the Easysoft web site. Otherwise, you won’t be able to obtain a trial license.

  2. Choose Request License.

    You’re prompted to choose a license type.

  3. Do one of the following:

    • For a trial license, choose Time Limited Trial, and then choose Next.
      -Or-

    • For a purchased license, choose Non-expiring License, and then choose Next.

  4. Choose your product from the drop-down list when prompted, and then choose Next.

  5. For a purchased license, enter your authorization code when prompted, and then choose Next.

  6. Choose how to get your license when prompted.

  7. Do one of the following:

    • Choose On-line Request if your machine is connected to the internet and can make outgoing connections to port 8884.
      With this method, License Manager automatically requests and then applies your license.
      -Or-

    • Choose View Request. Then open a web browser and go to https://www.easysoft.com/support/licensing/trial_license.html or https://www.easysoft.com/support/licensing/full_license.html, as appropriate. In the web page, enter your machine number (labelled Number in the license request). For purchased licenses, you also need to enter your authorization code (labelled Ref in the license request).
      We’ll automatically email your license to the email address you supplied in License Manager.
      -Or-

    • Choose Email Request to email your license request to our licensing team.
      Once we’ve processed you request, we’ll email your license to the email address you supplied in License Manager.

  8. Close the License Manager windows and then choose Finish.

If you chose either View Request or Email Request, apply your license by double-clicking the email attachment when you get the license email from us. Alternatively, start License Manager from the Easysoft folder in the Windows Start menu. Then choose Enter License and paste the license in the space provided.

Once you’ve licensed the Easysoft ODBC-FreeAgent Driver, the installation is complete.

Repairing the installation

The installer can repair a broken Easysoft ODBC-FreeAgent Driver installation. For example, you can use the installer to restore missing Easysoft ODBC-FreeAgent Driver files or registry keys. To do this:

  1. In the Windows taskbar, enter Add or remove programs in the Windows search box.

  2. Select Easysoft ODBC-FreeAgent Driver in the list, and then choose Repair.

Uninstalling on Windows

This section explains how to remove the Easysoft ODBC-FreeAgent Driver from your system.

Removing Easysoft ODBC-FreeAgent Driver data sources

Easysoft ODBC-FreeAgent Driver data sources are not removed when you uninstall the Easysoft ODBC-FreeAgent Driver. You don’t therefore need to recreate your Easysoft ODBC-FreeAgent Driver data sources if you reinstall or upgrade. If you don’t want to keep your Easysoft ODBC-FreeAgent Driver data sources, use Microsoft ODBC Data Source Administrator to remove them, before uninstalling the Easysoft ODBC-FreeAgent Driver:

  1. In the Windows taskbar, enter Run in the Windows search box.

  2. In the Windows Run dialog box, enter:

    odbcad32.exe
  3. Locate your data source in either the User or System tab.

  4. Select the data source from the list, and then choose Remove.

    If the Remove button isn’t available, close ODBC Data Source Administrator, and then, in the Windows Run dialog box, enter:

    %windir%\syswow64\odbcad32.exe

    Repeat the previous two steps.

Removing the Easysoft ODBC-FreeAgent Driver

  1. In the Windows taskbar, enter Add or remove programs in the Windows search box.

  2. Select Easysoft ODBC-FreeAgent Driver in the list, and then choose Uninstall.

Easysoft product licenses are stored in the Windows registry. When you uninstall, your licenses are not removed, so you do not need to relicense the product if you reinstall or upgrade.

Connecting to FreeAgent

Applications that support ODBC interface with an ODBC Driver Manager, which is included with the operating system, and also the Easysoft ODBC driver distribution on some platforms. One of the jobs that the ODBC Driver Manager does is to manage ODBC data sources. A data source specifies which ODBC driver to load, which data store to connect to, and how to connect to it.

Before setting up a data source, you must have successfully installed the Easysoft ODBC-FreeAgent Driver.

Connecting from Windows

Creating an ODBC data source

  1. In the Windows taskbar search box, enter “Run”.

  2. Do one of the following:

    • If your application is 64-bit, in the Run dialog box, enter:

      odbcad32.exe

      -Or-

    • If your application is 32-bit, in the Run dialog box, enter:

      %windir%\syswow64\odbcad32.exe
      If your not sure whether your application is 32-bit or 64-bit, start your application, then in Windows Task Manager check whether your application’s process name contains (32-bit). For example, the process name for the 32-bit version of Excel is Microsoft Excel (32-bit); the process name for the 64-bit version of Excel is Microsoft Excel. On older versions of Windows, 32-bit applications contain *32 in the process name rather than (32-bit).
      For applications such as Oracle or SQL Server that run as a service, check the *Background processes* list rather than the Apps list in Task Manager.
      If you’re running a programming language from within a Windows command-line shell (for example, Command or PowerShell), in your shell, run the .exe file for the programming language. For example, run perl, php, python, or node. In Task Manager, expand the process list for Windows Command Processor or Windows PowerShell, as appropriate, and check whether the process for your programming language contains (32-bit).
  3. Do one of the following:

    • To create a data source that only the user you’re currently logged in as can access, choose the User tab.
      If your application is a Windows service (for example, SQL Server or Oracle) creating a user data source won’t work, unless the service is running as the same user you’re logged in as.

    • To create a data source that all users on this computer can access, choose the System tab.

  4. Choose Add.

  5. In the list of ODBC drivers, select Easysoft ODBC-FreeAgent Driver, and then choose Finish.

  6. Complete the Easysoft ODBC-FreeAgent Driver configuration dialog box.
    To find out how to do this, refer to the Connection attributes section.

  7. To test the connection to FreeAgent, choose Test.
    Note that this doesn’t test that the Easysoft ODBC-FreeAgent Driver is licensed. If you haven’t yet licensed the Easysoft ODBC-FreeAgent Driver, this ODBC data source won’t work with your application, even if the Test button succeeds.

Authentication

FreeAgent uses the OAuth security standard to authorise users.

To use the Easysoft ODBC-FreeAgent Driver, you need to obtain a refresh token, which enables the driver to get the access tokens it needs to make FreeAgent API requests.

By default, the Easysoft ODBC-FreeAgent Driver uses an app that we have registered with FreeAgent to supply an OAuth client ID and secret. If you want to use your own FreeAgent OAuth app, specify its client ID and secret in your Easysoft ODBC-FreeAgent Driver data source.

The reasons for using your own OAuth app are:

  • You want to replace our text with your own text in the web page that prompts users to grant access to their FreeAgent data. This page displays when users initially authenticate and obtain a FreeAgent refresh token. This is done as when configuring an Easysoft ODBC-FreeAgent Driver data source.

To create an OAuth app:

  1. In the FreeAgent Developer Dashboard, choose My Apps.

  2. Choose Create New App page, enter a name, description, and home page URL.

  3. In the Create a new app page, enter a name.

    This name is displayed to users in the web page that prompts them to allow access to their FreeAgent data.

  4. In the OAuth Redirect URIs box, enter http://localhost:port. For example, http://localhost:8090.

  5. Choose Create App.

The page that displays next contains the client id (OAuth identifier) and client secret (OAuth secret) that you need to supply in the Easysoft ODBC-FreeAgent Driver DSN configuration dialog box.

To obtain a refresh token on Windows, choose the Authenticate and obtain token button in the configuration dialog box when setting up your data source. This launches your default browser. Sign into your FreeAgent account and grant the permissions the Easysoft ODBC-FreeAgent Driver needs when prompted. Close the web browser window or tab when prompted.

You now have a refresh token. The Easysoft ODBC-FreeAgent Driver uses this to request the access tokens it needs to access your FreeAgent data.

Connection attributes

Name Value

DSN

The name of the data source. You’ll need to specify this in your application. For example, your application may prompt you to choose this from a list of DSNs.

Description

Some applications display this to help users identify a particular data source.

Refresh Token

The FreeAgent refresh token that enables the Easysoft ODBC-FreeAgent Driver to work with your FreeAgent data.

Local Filtering

When turned on, the Easysoft ODBC-FreeAgent Driver increases its preferred batch size for queries, which alters the number of FreeAgent API calls it makes. FreeAgent may create batches that are larger or smaller than the requested size to maximise performance.

There is no one correct setting for Local Filtering, it depends on how your application executes its queries. You may find that this attribute increases query performance for one application and decreases performance for another.

By default, Local Filtering is turned off.

Proxy

If you use a proxy server connect to FreeAgent, use this attribute to specify this server’s details. Use this format:

http://address:port

where address is the host name or IP address of the proxy server and port is the proxy server port. For example:

http://squid.example.com:8080

Proxy User

If your proxy server has authentication turned on, use this attribute to supply a user name that can connect to the proxy server.

The Easysoft ODBC-FreeAgent Driver supports the Basic and Digest proxy authentication schemes.

Proxy Password

The password for the proxy user.

Driver Logging

Whether to turn on Easysoft ODBC-FreeAgent Driver logging. Normally, you’ll only do this if so directed by the Easysoft support team.

Log File

The file name and path of the file you want the driver to write log information to. For example:

C:\Windows\Temp\Easysoft.log

If the file doesn’t exist, the Easysoft ODBC-FreeAgent Driver creates it.

Flush On Update

Whether the Easysoft ODBC-FreeAgent Driver flushes its cache when it is used to update or delete FreeAgent data. When this setting is turned on, the effect of your changes will apply in your current session. For example, you turn on this setting and delete a record. If you then do a select in the same session, the record will no longer be present in the result set, If you do the same with Flush On Update turned off, the result set contains the deleted record until the Easysoft ODBC-FreeAgent Driver cache expires or you reconnect your application (for example, you restart your SQL Server instance).

Sandbox

Turn on this option if you’re connecting to the FreeAgent sandbox.

Max Num

The maximum number of records to return for each FreeAgent API request the Easysoft ODBC-FreeAgent Driver makes.

Cache Timeout

The time in seconds that Easysoft ODBC-FreeAgent Driver stores records in its cache. If you set the timeout to 0, the Easysoft ODBC-FreeAgent Driver always caches records. The default value for Cache Timeout is 0.

The Easysoft ODBC-FreeAgent Driver flushes the cache when you close the connection to FreeAgent. (For example, you quit your application or restart your application’s service.)

To reduce FreeAgent API usage and reduce the amount of data retrieved over the network, the Easysoft ODBC-FreeAgent Driver caches FreeAgent records. By default, a record remains in the cache until the timeout elapses.

Note that any changes to the record that happen at the FreeAgent end aren’t reflected in the cached copy until the cache is refreshed (that is, the timeout expires and the record is fetched again.) If a cached record is changed by the Easysoft ODBC-FreeAgent Driver, the cache is refreshed to reflect this change.

Client Id

If you have created your own FreeAgent OAuth client app, enter the app’s client id here. Otherwise, leave this field blank.

Client Secret

The client secret for your FreeAgent OAuth client app.

DSN-less connections

Some applications allow you to make an ODBC connection without configuring a data source. To do this, you supply a connection string that contains the ODBC driver name and other driver-specific attribute-value pairs. Connection string attributes have different names to the ones shown in the Easysoft ODBC-FreeAgent Driver data source configuration dialog box. Use these attribute names in a connection string:

  • Cache_Timeout

  • Description

  • Filter_Local

  • Flush_On_Update

  • Logfile

  • Logging

  • Max_Num

  • Proxy_Pass

  • Proxy_User

  • Proxy

  • Refresh_Token

  • Sandbox

Here’s an example connection string for the Windows version of the Easysoft ODBC-FreeAgent Driver:

Driver={Easysoft FreeAgent ODBC Driver};Refresh_Token=2000.d2927da21cff612e6818f832a47c256e.379428ee4a4abc3040799dff191f8620;LogFile=C:\\Temp\\FA.log;

Logging

If you report an issue to us, we may ask you to turn on ODBC Driver Manager or Easysoft ODBC-FreeAgent Driver logging, to help us diagnose the cause of the issue.

To turn on logging, refer to the following sections.

If your application is a service (for example, Oracle or SQL Server), you may need to restart the service before enabling logging takes effect. To do this on Linux or UNIX, use service, systemctl, or a vendor-supplied script. To do this on Windows, use the Windows Services app.

ODBC Driver Manager logging on Windows

  1. In the Windows taskbar search box, enter “Run”.

  2. Do one of the following:

    • If your application is 64-bit, in the Run dialog box, enter:

      odbcad32.exe

      -Or-

    • If your application is 32-bit, in the Run dialog box, enter:

      %windir%\syswow64\odbcad32.exe
      If your not sure whether your application is 32-bit or 64-bit, start your application, then in Windows Task Manager check whether your application’s process name contains (32-bit). For example, the process name for the 32-bit version of Excel is Microsoft Excel (32-bit); the process name for the 64-bit version of Excel is Microsoft Excel. On older versions of Windows, 32-bit applications contain *32 in the process name rather than (32-bit).
      For applications such as Oracle or SQL Server that run as a service, check the *Background processes* list rather than the Apps list in Task Manager.
      If you’re running a programming language from within a Windows command-line shell (for example, Command or PowerShell), in your shell, run the .exe file for the programming language. For example, run perl, php, python, or node. In Task Manager, expand the process list for Windows Command Processor or Windows PowerShell, as appropriate, and check whether the process for your programming language contains (32-bit).
  3. Choose the Tracing tab.

  4. Select Machine-Wide tracing for all identities.

  5. Enter a log file name and path in the space provided. For example:

    C:\Windows\Temp\SQL.log
  6. Choose Start Tracing Now.

With SQL Server, you may get two Driver Manager log files, we need both. The first log file is in the folder that you specify in ODBC Data Source Administrator. The second file’s location is defined by SQL Server. Two possible locations are the top-level folder (for example, C:\SQL.log) or the SQL Server temporary folder (for example, C:\Users\MSSQL$SQLEXPRESS\AppData\Local\Temp\SQL.log). If the Driver Manager log file isn’t in these folders, search for it on the drive where SQL Server is installed.

Easysoft ODBC-FreeAgent Driver logging on Windows

  1. In the Windows taskbar search box, enter “Run”.

  2. Do one of the following:

    • If your application is 64-bit, in the Run dialog box, enter:

      odbcad32.exe

      -Or-

    • If your application is 32-bit, in the Run dialog box, enter:

      %windir%\syswow64\odbcad32.exe
      If your not sure whether your application is 32-bit or 64-bit, start your application, then in Windows Task Manager check whether your application’s process name contains (32-bit). For example, the process name for the 32-bit version of Excel is Microsoft Excel (32-bit); the process name for the 64-bit version of Excel is Microsoft Excel. On older versions of Windows, 32-bit applications contain *32 in the process name rather than (32-bit).
      For applications such as Oracle or SQL Server that run as a service, check the *Background processes* list rather than the Apps list in Task Manager.
      If you’re running a programming language from within a Windows command-line shell (for example, Command or PowerShell), in your shell, run the .exe file for the programming language. For example, run perl, php, python, or node. In Task Manager, expand the process list for Windows Command Processor or Windows PowerShell, as appropriate, and check whether the process for your programming language contains (32-bit).
  3. Do one of the following:

    • If you configured a system data source, choose the System DSN tab.
      -Or-

    • If you configured a system data source, choose the System DSN tab.

  4. Choose your Easysoft ODBC-FreeAgent Driver data source from the list, and then choose Configure.

  5. In the Easysoft ODBC-FreeAgent Driver data source configuration dialog box, turn on Driver Logging.

  6. Enter a log file name and path in the space provided. For example:

    C:\Windows\Temp\Easysoft.log

Finding out what product version you have on Windows

If you have an issue with the Easysoft ODBC-FreeAgent Driver, we may ask you to tell us what your product version is. To find this out:

  1. In the Windows taskbar, enter “Add or remove programs” in the Windows search box.

  2. Select Easysoft ODBC-FreeAgent Driver in the list.

    The product version displays below.

Working with FreeAgent data

The Easysoft ODBC-FreeAgent Driver lets you use SQL to work with FreeAgent data. Your application might build the SQL for you or you might have to specify the SQL statements yourself.

SELECT statements

Use either a FreeAgent table or the API view in your queries. For example, both these statements fetch the comments for a particular bill:

SELECT
    *
FROM
    Bank_Accounts
WHERE
    Id = '1580844'

=Or-

SELECT
  *
FROM
  API
WHERE
  URL = '/v2/bank_accounts/1580844'
  AND Method = 'GET'

Example select queries

SELECT
    *
FROM
    Bills
WHERE
    Status = 'Open'

SELECT
    *
FROM
    Credit_Notes
WHERE
    Status <> 'Refunded'

SELECT
    *
FROM
    Estimates
WHERE
    Estimate_Type = 'Quote'

SELECT
    *
FROM
    Sales_Tax_Periods
WHERE
    Is_Locked = FALSE

INSERT statements

When inserting a record that has one or more line items, specify the line items with a JSON array. For example, this line item is for a recurring expense

[
  {
    "item_type": "Days",
    "quantity": "5",
    "price": "1249.99",
    "description": "CON001 : Consultancy"
  },
  {
    "item_type": "Stock",
    "quantity": "7",
    "price": "199.99",
    "description": "WD 1TB 3.5 : Western Digital 1TB 3.5 hard disk drive",
    "stock_item": "https://api.freeagent.com/v2/stock_items/236156"
  }
]

In the INSERT statement, specify the JSON as a single line. For example:

INSERT INTO
    Invoices (
        Contact,
        Dated_On,
        Due_On,
        Currency,
        Exchange_Rate,
        Payment_Terms_In_Days,
        Net_Value,
        Invoice_Items
    )
VALUES
    (
        'https://api.freeagent.com/v2/contacts/18494140',
        '2024-11-27',
        '2024-11-27',
        'USD',
        '0.7263561',
        '30',
        '7649.88',
        '[{"item_type":"Days","quantity":"5","price":"1249.99","description":"CON001 : Consultancy"},{"item_type":"Stock","quantity":"7","price":"199.99","description":"WD 1TB 3.5 : Western Digital 1TB 3.5 hard disk drive","stock_item":"https://api.freeagent.com/v2/stock_items/236156"}]'
    )

Example inserts

Bill

Create a new bill:

INSERT INTO
    Bills (Contact, Reference, Dated_On, Due_On, Bill_Items)
VALUES
    (
        'https://api.freeagent.com/v2/contacts/18541472',
        'YEB002',
        '2024-11-28',
        '2024-12-28',
        '[{"category":"https://api.freeagent.com/v2/categories/291","description":"YEB Line 2 standing charge","sales_tax_rate":"20","total_value_ex_tax":49.99}]'
    )

The JSON for the line items is:

[
  {
    "category": "https://api.freeagent.com/v2/categories/291",
    "description": "YEB Line 2 standing charge",
    "sales_tax_rate": "20",
    "total_value_ex_tax": 49.99
  }
]
Contact

Create a new contact:

INSERT INTO
    Contacts (
        First_Name,
        Last_Name,
        Email,
        Billing_Email,
        Phone_Number,
        Mobile,
        Address1,
        Address2,
        Address3,
        Town,
        Region,
        Postcode,
        Country,
        Uses_Contact_Invoice_Sequence,
        Contact_Name_On_Invoices,
        Charge_Sales_Tax,
        Sales_Tax_Registration_Number,
        [Status],
        Default_Payment_Terms_In_Days,
        Locale
    )
VALUES
    (
        'Thomas, ' Axen ', ' ta@example.com ', ' bills@example.com ', ' (123) 555 -0101 ', ' (321) 555 -0101 ', ' 123 Third Street ', '', '', ' Los Angeles ', ' CA ', ' 99999 ', USA',
        'false',
        'true',
        'Always',
        'US123456789',
        'Active',
        '30',
        'en'
    )
Credit note

Create a new credit note:

INSERT INTO
    Credit_Notes (Contact, Dated_On, Currency, Credit_Note_Items)
VALUES
    (
        'https://api.freeagent.com/v2/contacts/18494140',
        '2024-11-27',
        'GBP',
        '[{"item_type":"Days","quantity":"1","price":"-999.99","description":"Consultancy Days"}]'
    )

The JSON for the line items is:

[
  {
    "item_type": "Days",
    "quantity": "1",
    "price": "-999.99",
    "description": "Consultancy Days"
  }
]
Estimate

Create a new estimate:

INSERT INTO
    Estimates (
        Contact,
        Dated_On,
        [Status],
        Estimate_Type,
        Currency,
        Reference,
        Estimate_Items
    )
VALUES
    (
        'https://api.freeagent.com/v2/contacts/18494140',
        '2024-11-27',
        'Draft',
        'Quote',
        'USD',
        'Customer Ref 2',
        '[{"item_type":"Days","quantity":"2","price":"999.99","description":"Consultancy Days"}]'
    )

The JSON for the line items is:

[
  {
    "item_type": "Days",
    "quantity": "2",
    "price": "999.99",
    "description": "Consultancy Days"
  }
]
Expense

Submit a new expense:

INSERT INTO
    Expenses (
        User,
        Category,
        Dated_On,
        Currency,
        Gross_Value,
        Sales_Tax_Rate,
        Sales_Tax_Status,
        [Description]
    )
VALUES
    (
        'https://api.freeagent.com/v2/users/1861284',
        'https://api.freeagent.com/v2/categories/287',
        '2024-12-03',
        'GBP',
        '-200',
        '20',
        'TAXABLE',
        'Overnight stay'
    )
Journal

Create a new journal:

INSERT INTO
    Journal_Sets (Dated_On, [Description], Journal_Entries)
VALUES
    (
        '2024-12-03',
        'Sample Journal Created',
        '[{"category":"https://api.freeagent.com/v2/categories/363","description":"Sample journal line 1","debit_value":"10"},{"category":"https://api.freeagent.com/v2/categories/001","description":"Sample journal line 2","debit_value":"-10"}]'
    )

The JSON data for the line items is:

[
  {
    "category": "https://api.freeagent.com/v2/categories/363",
    "description": "Sample journal line 1",
    "debit_value": "10"
  },
  {
    "category": "https://api.freeagent.com/v2/categories/001",
    "description": "Sample journal line 2",
    "debit_value": "-10"
  }
]

UPDATE statements

To update records with JSON columns (for example, line items columns), you first need to retrieve the existing JSON. Then change the existing values, or add new JSON to the existing JSON. For example:

SELECT Estimate_Items FROM Estimates WHERE Id = '1580844'

returns the following (formatted for readability):

  {
    "item_type": "Days",
    "quantity": "4",
    "price": "999.99",
    "description": "Consultancy Days"
  },

Add a new line item to the JSON:

  {
    "item_type": "Days",
    "quantity": "4",
    "price": "999.99",
    "description": "Consultancy Days"
  },
  {
    "item_type": "Hours",
    "quantity": "32",
    "price": "172.22",
    "description": "Developer Hours"
  }

and include the revised JSON in an UPDATE statement. Enclose the JSON in square brackets. For example:

UPDATE Estimates
SET
    Estimate_Items = '[{"item_type":"Days","quantity":"4","price":"999.99","description":"Consultancy Days"},{"item_type":"Hours","quantity":"32","price":"172.22","description":"Developer Hours"}]'
WHERE
    Id = '5771094'

You can also us the API view to make updates to your FreeAgent data. Use PUT as the method in your SELECT statement. For example:

SELECT
    *
FROM
    API
WHERE
    Url = '/v2/invoices/default_additional_text'
    AND Method = 'PUT'
    AND RequestBody = '{"default_additional_text":"Please pay promptly."}'

Example updates

Bank transaction explanation

Change the description of a transaction:

UPDATE Bank_Transaction_Explanations
SET
    Description = 'New FEE description text.'
WHERE
    Id = '532804092'
Bills

Update a bill’s comment:

UPDATE Bills
SET
    Comments = 'Standing charge for second line.'
WHERE
    Id = '31467166'
Contact

Update a contact’s contact details:

UPDATE Contacts
SET
    Mobile = '(321)555-0101'
WHERE
    Email = 'ta@example.com'
DELETE FROM Contacts
WHERE
    Id = '18482080'
Credit note

Add credit note line items:

UPDATE Credit_Notes
SET
    Credit_Note_Items = '[{"item_type":"Days","quantity":"4","price":"-999.99","description":"Consultancy Days"},{"item_type":"Hours","quantity":"32","price":"-172.22","description":"Developer Hours"}]'
WHERE
    Id = '73934615'

The JSON data for the line items is:

[
  {
    "item_type": "Days",
    "quantity": "4",
    "price": "-999.99",
    "description": "Consultancy Days"
  },
  {
    "item_type": "Hours",
    "quantity": "32",
    "price": "-172.22",
    "description": "Developer Hours"
  }
]
Expense

Change the description of an expense:

UPDATE Expenses
SET
    Description = 'Hotel Stay'
WHERE
    Id = '53063365'
Price list

Update a price:

UPDATE Price_List_Items
SET
    Price = 10.99
WHERE
    Code = 'CS001'
Users

Update a name:

UPDATE Users
SET
    Last_Name = 'Jones'
WHERE
    Id = '1853395'

DELETE statements

The Easysoft ODBC-FreeAgent Driver provides two ways to delete records. Either specify a table in your DELETE statement:

DELETE FROM Bank_Accounts
WHERE
    AccountId = '1558819'

or use the API view instead:

SELECT
    *
FROM
    API
WHERE
    Url = 'bank_accounts/1558819'
    AND Method = 'DELETE'

API view

The API view lets you use SQL to make FreeAgent API calls. The view has these columns:

Column Description

URL

A FreeAgent API endpoint.

Method

GET, PUT, POST, or DELETE.

Code

HTTP status code.

Code Description

200

OK

201

Created

400

Bad request

401

Unauthorized (Invalid AuthToken)

404

Error

405

Method Not Allowed (Method you have called is not supported for the invoked API)

429

Rate Limit Exceeded (API usage limit exceeded)

500

Internal Error

RequestType

If NULL, JSON is expected in RequestBody.

RequestBody

Data sent to the FreeAgent API.

ResponseType

The type of data in the response. For example, application/json;charset=UTF-8.

ResponseBody

Data returned from the FreeAgent API.

Use SELECT statements with the API view. To select data set Method to GET. To insert data set Method to POST. To insert data set Method to PUT. To delete data set Method to DELETE.

Use a WHERE clause to specify the URL, Method, and, if updating or inserting data, RequestBody. For example:

-- Fetch the additional text for an invoice
SELECT
    *
FROM
    API
WHERE
    Url = '/v2/invoices/default_additional_text'
    AND Method = 'GET'

-- Remove a bank account
SELECT
    *
FROM
    API
WHERE
    Url = 'bank_accounts/1558819'
    AND Method = 'DELETE'

-- Add a bank transaction
SELECT
    *
FROM
    API
WHERE
    Url = '/v2/bank_transactions/statement?bank_account=1555435'
    AND Method = 'POST'
    AND RequestBody = '[{"statement":[{"dated_on":"2024-11-26","description":"CREDIT line test","amount":"298","fitid":"031AE5B1-FC68-4889-935E-327897E31B67","transaction_type":"CREDIT"},{"dated_on":"2024-11-26","description":"DEBIT line test","amount":"130","fitid":"93845D69-7CB3-491E-B16B-2D186F0A0241","transaction_type":"DEBIT"}]}]'

-- Update an invoice status
SELECT
    *
FROM
    API
WHERE
    Url = '/v2/invoices/73959649/transitions/mark_as_sent'
    AND Method = 'PUT'

For more information, consult the FreeAgent API documentation.

JSON columns

Columns that can contain multiple values are in JSON format. For example, a bill’s line items (Bill table’s Line_Items column):

To update records with JSON columns (for example, line items columns), you first need to retrieve the existing JSON. Then change the existing values, or add new JSON to the existing JSON. For example:

SELECT Estimate_Items FROM Estimates WHERE Id = '1580844'

returns the following (formatted for readability):

{
  "item_type": "Days",
  "quantity": "4",
  "price": "999.99",
  "description": "Consultancy Days"
},

Add a new line item to the JSON:

{
  "item_type": "Days",
  "quantity": "4",
  "price": "-999.99",
  "description": "Consultancy Days"
},
{
  "item_type": "Hours",
  "quantity": "32",
  "price": "-172.22",
  "description": "Developer Hours"
}

and include the revised JSON in an UPDATE statement. Enclose the JSON in square brackets. For example:

UPDATE Credit_Note_Items
SET
    Estimate_Items = '[{"item_type":"Days","quantity":"4","price":"-999.99","description":"Consultancy Days"},{"item_type":"Hours","quantity":"32","price":"-172.22","description":"Developer Hours"}]'
WHERE
    Id = '1580844'

In the FreeAgent API, JSON has this format:

  • Data is in name/value pairs.

  • Data is separated by commas.

  • Curly braces ({}) hold objects.

  • Square brackets ([]) hold arrays.

All the data names in the FreeAgent API are in lower case. JSON is case sensitive.

In the API we connect to, JSON values must be one of the following data types:

  • Array

  • Boolean

  • Date

  • Datetime

  • Decimal

  • Object

  • String

  • Timestamp

  • URI

In some of the JSON returned, you may get something like:

"tags":[]

This denotes an empty array.

String data needs to be escaped:

  • Backslash becomes \\

  • Backspace becomes \b

  • Form feed becomes \f

  • Newline becomes \n

  • Carriage return becomes \r

  • Tab becomes \t

  • Double quote becomes \"