Skip to content
This repository has been archived by the owner. It is now read-only.


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Use the latest Wunderlist API version in your apps.

Latest Stable Version Total Downloads License Endpoint coverage

Wunderlist will be officially shut down on May 6th. Move your lists and tasks to Microsoft To Do before May 6th.

How to use?

Register your app

First of all, you need to register your app. To do that, go here, log in and click on the blue button that says 'CREATE APP'. Wunderlist will ask you about the name of the app, the description, an icon to represent the app, the URL where it is located and the callback URL for authorization.

If your app is not yet hosted on the Internet, set both the URL fields to http://localhost. You're only going to need a 'real' auth callback url when you need to set up authorization (more about this later).

Install the package

This package may be installed through Composer:

composer require johnrivs/wunderlist

If you're using a framework, everything in your vendor directory is most likely autoloaded for you. Otherwise, pull in the file yourself:


require_once __DIR__.'/path/to/vendor/autoload.php';
Build up the client

Go back to apps page and copy your app's 'CLIENT ID', 'CLIENT SECRET' and access token, which you can generate by clicking on 'CREATE ACCESS TOKEN':


use JohnRivs\Wunderlist\Wunderlist;

$clientId     = 'THE_CLIENT_ID';
$clientSecret = 'THE_CLIENT_SECRET';
$accessToken  = 'THE_ACCESS_TOKEN';

$w = new Wunderlist($clientId, $clientSecret, $accessToken);


You can optionally pass a boolean as the 4th parameter that decides whether or not the package should throw exceptions when a required parameter is missing. By default, it does.


For some methods (mostly the ones where you need to write, update or delete data), you're going to need a user access token. Up until this point you've only had the app access token, which you can use for yourself.

First, redirect the user to Wunderlist, where they need to grant access to your app. Wunderlist needs 2 things: a random string passed to it and the callback URL. Make sure you temporarily save said random string (in a file or session):

$state = md5(time());

// Store the $state to retrieve it later

// Redirect the user to:
$w->authUrl($state, '')

Note: the URL you provide must be the same you set as your app auth callback url.

If you're working locally, I recommend using ngrok:

  • Spin up an HTTP server. In PHP via terminal php -S localhost:8000
  • Create the tunnel: ngrok http localhost:8000. It'll tell you where your website is publicly available, something like
  • Go to the apps page and set the auth callback url to or whatever you got.
  • Use the same URL in your code: $w->authUrl($state, '')

Ngrok gives you a different URL everytime you create the tunnel, so you'll need to update the auth callback url for your app and the one you provide to authUrl().

Once the user grants access to your app, he's going to be redirected to the callback URL carrying a code and the state. It would look like Now retrieve the $state from earlier and compare it to $_GET['state']. If they're the same:

$accessToken = $w->getAuthToken($_GET['code']);

And that's the user's access token.


What exactly is this pacakage?

This package is a wrapper for each endpoint in the Wunderlist API. To know what attributes you need to provide to each method, the data it returns or what status code is set, head over to the official Wunderlist API documentation.

How flexible is this package?

Since this package doesn't perform validation or sanitization, you can provide any attribute to (almost) every method. However, it'll check if the attributes contain the fields required by the endpoint. If you provide unrecognized attribute fields, they will be ignored. Again, to know what fields should be present in the attributes for a Wunderlist API endpoint, have a look at the official Wunderlist API documentation.

What should I expect from the Wunderlist API?

Most of the time, the methods will return an array containing the results of what you just did. For example, if you createTask(), it will return the task that was just created. Some methods (such as deleteTask()) will return a status code. You can always use getStatusCode() regardless of what the method returned.

How does it look like?

Almost each method maps to a Wunderlist API endpoint:

// Get all tasks for a given list
$wunderlist->getTasks(['list_id' => 9876]);

// Get all lists
How do I provide data?

For most methods you'll need to provide an array of attributes, however, for certain ones you'll need to supply some value(s). Check the API Docs out to know what each method expects.

Why do some methods take more time than others?

Due to the nature of the service, Wunderlist requires to keep everything in sync by providing the entity's revision. To achieve this, methods responsible for updating entities (such as tasks, lists...) will fetch the entity first and then perform a request to apply the changes.

Why does it say Forbidden during authentication?

Make sure the auth callback URL you provide to authUrl() matches the one you have for your app.

What if something goes wrong?

Well.. at the time of this writing, the Wunderlist API isn't too helpful when it comes to error messages, so make sure you stick to the docs, use getStatusCode() and ask any questions in the docs comment section.


  • Reminder
    • Get all reminders
    • Create a reminder
    • Update a reminder
    • Delete a reminder
  • Some other endpoints (not started)
  • Laravel integration
  • Silex integration


  • Authorization
  • Avatar
  • File
  • Folder
  • Lists
  • Note
  • Subtask
  • Task
  • Comment
  • User (except restricting the list of users a user can access by list)
  • Webhook


SDK for the latest Wunderlist API version.








No packages published