About the Easysoft ODBC-FreeAgent Driver
The Easysoft ODBC-FreeAgent Driver provides real-time access to FreeAgent data from any application that supports ODBC.
ODBC API and scalar functions
API functions
Use this table to find out what ODBC API functions the Easysoft ODBC-FreeAgent Driver supports:
Function | Status |
---|---|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Not supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Not Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Supported |
|
Not supported |
|
Supported |
|
Supported |
Scalar functions
The Easysoft ODBC-FreeAgent Driver supports a number of scalar functions:
Use either the SQL-92 or ODBC syntax with scalar functions. For example:
SELECT
Invoice_Id,
Customer_Name,
EXTRACT(YEAR FROM Due_Date) as "Year"
FROM
Invoice
SELECT
Invoice_Id,
Customer_Name,
{fn EXTRACT(YEAR FROM Due_Date)} as "Year"
FROM
Invoice
String functions
The Easysoft ODBC-FreeAgent Driver supports these string functions:
-
ASCII(string_exp)
-
BIT_LENGTH(string_exp)
-
CHAR(code)
-
CHAR_LENGTH(string_exp)
-
CHARACTER_LENGTH
-
CONCAT(string_exp1, string_exp2)
-
DIFFERENCE(string_exp1, string_exp2)
-
INSERT(string_exp1, start, length, string_exp2)
-
LCASE(string_exp)
-
LEFT(string_exp, count)
-
LENGTH(string_exp)
-
LOCATE(string_exp1, string_exp2[,start])
-
LTRIM(string_exp)
-
OCTET_LENGTH(string_exp)
-
POSITION(char_exp IN char_exp)
-
REPEAT(string_exp, count)
-
REPLACE(string_exp1, string_exp2, string_exp3)
-
RIGHT(string_exp, count)
-
RTRIM(string_exp)
-
SOUNDEX(string_exp)
-
SPACE(count)
-
SUBSTRING(string_exp, start, length)
-
TRIM
-
UCASE(string_exp)
Numeric functions
The Easysoft ODBC-FreeAgent Driver supports these numeric functions:
-
ABS(numeric_exp)
-
ACOS(float_exp)
-
ASIN(float_exp)
-
ATAN(float_exp)
-
ATAN2(float_exp1, float_exp2)
-
CEILING(numeric_exp)
-
COS(float_exp)
-
COT(float_exp)
-
DEGREES(numeric_exp)
-
EXP(float_exp)
-
FLOOR(numeric_exp)
-
LOG(float_exp)
-
LOG10(float_exp)
-
MOD(integer_exp1, integer_exp2)
-
PI()
-
POWER(numeric_exp, integer_exp)
-
RADIANS(numeric_exp)
-
RAND([integer_exp])
-
ROUND(numeric_exp, integer_exp)
-
SIGN(numeric_exp)
-
SIN(float_exp)
-
SQRT(float_exp)
-
TAN(float_exp)
-
TRUNCATE(numeric_exp, integer_exp)
Time, date, and interval functions
The Easysoft ODBC-FreeAgent Driver supports these time, date, and interval functions:
-
CURRENT_DATE()
-
CURRENT_TIME[(time-precision)]
-
CURRENT_TIMESTAMP[(timestamp-precision)]
-
CURDATE()
-
CURTIME()
-
DAYNAME(date_exp)
-
DAYOFMONTH(date_exp)
-
DAYOFWEEK(date_exp)
-
DAYOFYEAR(date_exp)
-
EXTRACT(extract-field FROM extract-sourc)
-
HOUR(time_exp)
-
MINUTE(time_exp)
-
MONTH(date_exp)
-
MONTHNAME(date_exp)
-
NOW()
-
QUARTER(date_exp)
-
SECOND(time_exp)
-
TIMESTAMPADD(interval, integer_exp, timestamp_exp)
-
TIMESTAMPDIFF(interval, timestamp_exp1, timestamp_exp2)
-
WEEK(date_exp)
-
YEAR(date_exp)
System functions
The Easysoft ODBC-FreeAgent Driver supports these system functions:
-
DATABASE()
-
IFNULL(exp, value)
-
USER()
Conversion functions
The Easysoft ODBC-FreeAgent Driver supports supports both the SQL-92 CAST function and the ODBC CONVERT function for conversion between compatible data types.
Data type mapping
The Easysoft ODBC-FreeAgent Driver maps FreeAgent data types to ODBC data types in this way:
URI
FreeAgent data type | ODBC data type |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Finding out more about data types on Windows
If you need more information about a data types, for example, the precision and scale, use Microsoft’s ODBC Test to do this.
-
Download the version of ODBC Test that matches your application’s architecture from:
-
Copy both files to a folder on the machine where Easysoft ODBC-FreeAgent Driver is installed.
-
Double-click odbcte32.exe.
-
Select Con > Full Connect.
-
Choose your Easysoft ODBC-FreeAgent Driver data source from the list.
-
Choose Catalog > SQLGetTypeInfo.
-
Either choose SQL_ALL_TYPES=0 (1.0) or a specific data type from the DataType list.
-
Choose Results > Get Data All.
SQL support
The Easysoft ODBC-FreeAgent Driver supports these SQL statements, clauses, and operators:
-
SELECT
-
SELECT DISTINCT
-
WHERE
-
ORDER BY
-
AND
-
OR
-
NOT
-
INSERT INTO
-
NULL
-
UPDATE
-
DELETE
-
TOP
-
MIN
-
MAX
-
COUNT
-
SUM
-
AVG
-
LIKE
-
WILDCARDS
-
IN
-
BETWEEN
-
ALIASES
-
JOINS
-
UNION
-
GROUP BY
-
HAVING
-
EXISTS
-
CASE
Example queries
-
To fetch all records from a table, use the asterisk symbol (
*
) in your queries. For example:SELECT * FROM Invoices
-
To only fetch records whose values are different, use
DISTINCT
. For example:-- Which different customers do we invoice? SELECT DISTINCT Contact_Name AS Different_Contact_Name FROM Invoices -- How many different customers do we invoice? SELECT COUNT(DISTINCT Contact_Name) AS Different_Contact_Total FROM Invoices
-
To filter records, use
WHERE
. For example:SELECT Id, Contact_Name, Total_Value FROM Invoice WHERE Currency = 'USD' SELECT Id, Contact_Name, Total_Value FROM Invoices WHERE Currency = 'USD' OR Currency = 'EUR' SELECT Id, Contact_Name, Total_Value FROM Invoices WHERE Currency = 'USD' AND Total_Value < 1000
You can also supply a
WHERE
clause value as a parameter. For example, to do this in Python:cursor.execute("SELECT Id, Contact_Name, Total_Value FROM Invoices WHERE Currency = ?", ['USD'])
-
To fetch records that don’t match the
WHERE
clause pattern useNOT
. For example:SELECT Id, Contact_Name, Total_Value FROM Invoices WHERE NOT Currency = 'USD'
-
To sort the result set in either ascending or descending order, use
ORDER BY
. For example:SELECT Id, Contact_Name, Net_Value FROM Invoices ORDER BY Net_Value ASC SELECT * FROM Contacts ORDER BY ( CASE WHEN Last_Name IS NULL THEN Organisation_Name ELSE Last_Name END );
-
To group a result set into summary rows, use
GROUP BY
. For example:SELECT COUNT(Id) As "Number", Currency FROM Invoices GROUP BY Currency SELECT COUNT(Id) As "Number", Currency FROM Invoices GROUP BY Currency HAVING COUNT(Id) > 10;
-
To do calculations based on result set vales, use the SQL aggregate functions
MIN()
,MAX()
,COUNT()
,SUM()
, andAVG()
. For example:SELECT Max(Total_Value) FROM Invoices SELECT Sum(Total_Value) FROM Invoices
In addition, you can use these scalar funtions.
-
To convert between compatible data types, use
CAST
orCONVERT
. For example:SELECT CAST(Total_Value AS Char(100))FROM Invoices SELECT {fn CONVERT(Total_Value, SQL_CHAR)} FROM Invoices
-
To fetch records that contain column values between a given range, use
BETWEEN
For example:SELECT Id, Contact_Name FROM Invoices WHERE Total_Value BETWEEN 10 AND 20
-
To combine the result set of two or more
SELECT
statements, useUNION
. For example:SELECT Group_Description, Description, Id, Url, Nominal_Code, Allowable_For_Tax, Tax_Reporting_Name, Auto_Sales_Tax_Rate FROM Categories_Admin_Expenses UNION ALL SELECT Group_Description, Description, Id, Url, Nominal_Code, Allowable_For_Tax, Tax_Reporting_Name, Auto_Sales_Tax_Rate FROM Categories_Cost_Of_Sales UNION ALL SELECT REPLACE (Url, Url, 'General') AS Group_Description, Description, Id, Url, Nominal_Code, CAST(NULL AS bit) AS Allowable_For_Tax, Tax_Reporting_Name, CAST(NULL AS double) AS Auto_Sales_Tax_Rate FROM Categories_General UNION ALL SELECT Group_Description, Description, Id, Url, Nominal_Code, CAST(NULL AS bit) AS Allowable_For_Tax, REPLACE (Url, Url, 'N/A') AS Tax_Reporting_Name, Auto_Sales_Tax_Rate FROM Categories_Income
-
To combine rows from two or more tables, use
JOIN
. For example:SELECT a.Name, bt.* FROM Bank_accounts a LEFT JOIN Bank_Transactions bt ON bt.Bank_Account = a.URL
-
To fetch records that contain column values matching a search pattern, use
LIKE
. For example:SELECT Id FROM Invoices WHERE Contact_Name LIKE 'E%' SELECT Id FROM Invoices WHERE Contact_Name LIKE '_asysoft'
-
To search for columns without a value (
NULL
) or with a value (nonNULL
), use eitherIS NULL
orIS NOT NULL
. For example:SELECT Id, Contact_Name, Total_Value FROM Invoices WHERE Include_Estimates IS NULL
-
To specify multiple values in a
WHERE
clause, you can useIN
as an alternative toOR
. For example:SELECT Id, Contact_Name, Total_Value FROM Invoices WHERE Currency = 'USD' OR Currency = 'EUR' OR Currency = 'GBP'
can be replaced with:
SELECT Id, Contact_Name, Total_Value FROM Invoices WHERE Currency IN ('USD', 'EUR', 'GBP');
-
To set the maximum number of records to return, use
TOP
. For example:SELECT TOP 10 Id, Contact_Name FROM Invoices
-
To test for the existence of records in a subquery, use
EXISTS
. For example:SELECT Contact_Name FROM Invoices WHERE EXISTS ( SELECT First_Name, Last_Name FROM Contacts WHERE Invoices.Contact_Id = Contacts.Id AND Currency = 'USD' )
Example inserts, updates, and deletes
-
To insert a FreeAgent record, use
INSERT INTO
. For example:INSERT INTO Bills ( Contact, Reference, Dated_On, Due_On, Bill_Items ) VALUES ( 'https://api.freeagent.com/v2/contacts/18727314', 'YEB021', '2025-01-16', '2025-01-16', '[{"category":"https://api.freeagent.com/v2/categories/291","description":"YEB-line-2-standing-charge","sales_tax_rate":"20","total_value_ex_tax":6.99}]' )
-
Here’s a SQL Server linked server example:
EXEC ('INSERT INTO Bills (Contact, Reference, Dated_On, Due_On, Bill_Items) VALUES (''https://api.freeagent.com/v2/contacts/18727314'' , ''YEB021'' , ''2025-01-16'' , ''2025-01-16'' , ''[{"category":"https://api.freeagent.com/v2/categories/291","description":"YEB-line-2-standing-charge","sales_tax_rate":"20","total_value_ex_tax":6.99}]'')')
-
Here’s an Oracle linked table example:
DECLARE num_rows integer; BEGIN num_rows:=DBMS_HS_PASSTHROUGH.EXECUTE_IMMEDIATE@FreeAgentLink ('INSERT INTO Bills (Contact, Reference, Dated_On, Due_On, Bill_Items) VALUES (''https://api.freeagent.com/v2/contacts/18727314'', ''YEB021'', ''2025-01-16'', ''2025-01-16'', ''[{"category":"https://api.freeagent.com/v2/categories/291","description":"YEB-line-2-standing-charge","sales_tax_rate":"20","total_value_ex_tax":6.99}]'')'); END; /
-
The Easysoft ODBC-FreeAgent Driver also supports parameterized inserts. Here’s an example of doing this in PHP:
$stmt = odbc_prepare($cnx, "INSERT INTO Bills (Contact, Reference, Dated_On, Due_On, Bill_Items) VALUES (?, ?, ?, ?, ?)"); $success = odbc_execute($stmt, array('https://api.freeagent.com/v2/contacts/18727314', 'YEB021', '2025-01-16', '2025-01-16', '[{"category":"https://api.freeagent.com/v2/categories/291","description":"YEB-line-2-standing-charge","sales_tax_rate":"20","total_value_ex_tax":6.99}]'));
-
To update a FreeAgent record, use
UPDATE
. For example:UPDATE Bills SET Contact = 'Standing charges for second line.' WHERE Account_Id = '31962267'
The Easysoft ODBC-FreeAgent Driver also supports parameterized updates. Here’s an example of doing this in Perl:
my $sth = $dbh->prepare('UPDATE Bills SET Contact = \'Standing charges for second line.\' WHERE Id = ?') or die "Can't prepare statement: $DBI::errstr"; $sth->execute('31962267');
-
To delete a FreeAgent record, use
DELETE
. For example:-- Delete (mark inactive) a bank account DELETE FROM Bills WHERE Id = '31962267'
The Easysoft ODBC-FreeAgent Driver also supports parameterized deletes. Here’s an example of doing this in Python:
sql = "DELETE FROM Bills WHERE Id = ?" cursor.execute(sql, '31962267')