Our new API is in beta. It’s possible that things can go wrong. We’ve been testing it—and we’ll be revealing some interesting integration news soon—but it’s not perfect yet.

This probably won’t make a difference for most folks. Rule of thumb: if you don’t know what API stands for, it’s probably not an interesting feature for you. (Yet!)

If you’re savvy and would like to try it out, keep reading!

h3. Getting Your API Token

First, to get the API token for your account, log in, click Settings and then Integration.

It’ll look like this: refet7vjpj01elltewf2fbqd9znkbh9

h3. Fetching Your List of Projects

Fetching a list of projects is dead simple. You just have to pick whether you want XML or JSON.

Using a GET request, access one of the following URLs:

XML
http://yourfreckle.letsfreckle.com/api/projects.xml?token=your-api-token

JSON
http://yourfreckle.letsfreckle.com/api/projects.json?token=your-api-token

h3. Logging a Time Entry

To log a time entry, you’ll use the following URL (be sure to enter your account’s domain name and your real API token):

http://yourfreckle.letsfreckle.com/api/entries.json?token=your-api-token

Submit, via POST, an entry with the following JSON syntax (be sure to use your real username):

{
  "entry": {
    "date":"2009-01-08",
    "user":"yourusername",
    "minutes":"2h",
    "project":"Test Project",
    "description":"tag1, tag2, sample description"
  }
}

Note: We work on project names, not IDs.

Supply the full, exact name of an existing project (no autocomplete here!), or a new one (and the project will get created for you).

All of the time formatting types that work in the Quick Entry time box work here, and all the little tricks: 2h will be 2 hours, 15 will be 15 minutes, 15h will be 15 hours, and so on. Increment rounding works, too.

There’s also an optional “url” parameter, which will be shown as a link (in shortened form) next to the entry in freckle. You can use this to link back to the application the data is from (for example if you’ve a bug ticket tracker, you could link back to a specific bug that was worked on).

h3. Bulk entry import

We also have a special API call if you want to import many entries at once:

HTTP POST to http://yourfreckle.letsfreckle.com/api/entries/import.json?token=your-api-token.

Here’s how the JSON data should look like (note, for bulk import, you can use new project names and those projects will be automatically created for you. Mind your account project limit, if you have one!).

{
  :entries => [
    {
      :user => 'dieter@komendera.com',
      :description => 'api import, testing out bulk import',
      :minutes => '2h',
      :date => '2009-01-15',
      :project_name => 'Freckle App'
    },
    {
      :user => 'dieter@komendera.com',
      :description => 'a bulk import entry with a link!',
      :minutes => '12 minutes',
      :date => '2009-01-16',
      :project_name => 'New Project',
      :url => 'http://letsfreckle.com/'
    }
  ]
}