A Java based client for FreeAgent that allows simple access to the API utilising the awesome Retrofit.
Authentication is required before the client can be used and is performing using OAuth 2.0.
FreeAgentClient freeAgentClient = FreeAgentClient.authorise("OAuth Key here",
"OAuth Secret Here");
Once you have an authenticated instance you can use it to access the various entities and rich information that FreeAgent provides for the specified account.
To obtain information about the company associated with the account
FreeAgentCompany company = freeAgentClient.getCompany();
NOTE: The FreeAgent API only allows read access to the Company information and therefore so does this client.
To list all the contacts attached to an account
List<FreeAgentContact> contacts = freeAgentClient.getContacts();
To obtain a specific contact (by known identifier)
String contactId = "Set your valid contact identifier here";
FreeAgentContact contact = freeAgentClient.getContact(contactId);
To show only contacts who are attached to active projects
List<FreeAgentContact> contacts = freeAgentClient.getContacts(ContactViewType.ActiveProjects);
To show only contacts that have been hidden and sort by their creation dates in ascending order
List<FreeAgentContact> contacts = freeAgentClient.getContacts(ContactViewType.Hidden,
ContactSortOrderType.CreatedAtAscending);
or to sort by descending order
List<FreeAgentContact> contacts = freeAgentClient.getContacts(ContactViewType.Hidden,
ContactSortOrderType.CreatedAtDescending);
FreeAgentContact contact = new FreeAgentContact();
contact.setFirstName("Bob");
contact.setLastName("Tester");
contact.setEmail("bob.tester@bobstesting.com");
// a new contact instance is returned with the identifier url and created_at timestamp set or null
// returned if creation failed.
FreeAgentContact contact = freeAgentClient.createContact(contact);
contact.setEmail("bob@bobstesting.com");
contact.setBillingEmail("billing@bobstesting.com");
boolean updateSuccessful = freeAgentClient.updateContact(contact);
boolean deleteSuccessful = freeAgentClient.deleteContact(contact);
To list all the projects attached to an account
List<FreeAgentProject> project = freeAgentClient.getProjects();
To obtain a specific project (by known identifier)
String projectId = "Set your valid project identifier here";
FreeAgentProject project = freeAgentClient.getProject(projectId);
To show only projects which are currently active
List<FreeAgentProject> projects = freeAgentClient.getProjects(ProjectStatusType.Active);
To show only projects which are currently completed
List<FreeAgentProject> projects = freeAgentClient.getProjects(ProjectStatusType.Completed);
To obtain the contact for a specific project
String projectId = "Set your valid project identifier here";
FreeAgentProject project = freeAgentClient.getProject(projectId);
FreeAgentContact projectContact = freeAgentClient.getContact(project);
To obtain the projects for a specific contact
String contactId = "Set your valid contact identifier here";
FreeAgentContact contact = freeAgentClient.getContact(contactId);
List<FreeAgentProject> projects = freeAgentClient.getProjects(contact);
FreeAgentProject project = new FreeAgentProject();
project.setName("Test Project");
project.setStatus("Active");
project.setBudgetUnits("Days");
project.setCurrency("GBP");
// Associate an existing contact
project.setContact(contact.getUrl());
// a new project instance is returned with the identifier url and created_at timestamp set or null
// returned if creation failed.
FreeAgentProject createdProject = freeAgentClient.createProject(project);
project.setBudgetUnits("Hours");
project.setCurrency("EUR");
boolean updateSuccessful = freeAgentClient.updateProject(project);
boolean deleteSuccessful = freeAgentClient.deleteProject(project);
If you have data thats in FreeAgent API V2 compliant JSON then you can build and/or import most entities via the client.
For example, to build a new FreeAgentContact instance from JSON
String loadedContactJSON = "...";
FreeAgentContact contact = freeAgentClient.buildContact(loadedContactJSON);
To build and automatically import a new FreeAgentContact
String loadedContactJSON = "...";
FreeAgentContact contact = freeAgentClient.importContact(loadedContactJSON);
Or to do the same with projects
String loadedProjectJSON = "..."
FreeAgentProject project = freeAgentClient.buildProject(loadedProjectJSON);
String loadedProjectJSON = "..."
FreeAgentProject project = freeAgentClient.importProject(loadedProjectJSON);