This document covers the methods and techniques required to access and modify user content in Wrike through the API.

Authorization

Wrike’s API uses the OAuth 2.0 protocol for authorization. Every API request must contain the Authorization header (preferred option) or the access_token parameter with the OAuth 2.0 access token. Access scopes may be requested during the authorization process. See the OAuth 2.0 authorization description for details.

Overview

The API methods are organized in the RESTful way and support GET, POST, PUT and DELETE requests. If a client is not able to execute all kinds of requests, then only GET requests can be used with an additional method parameter, which is set to the required request type (e.g., ...&method=POST).

To access a specific API method, the request token should have at least one of the scopes required by this method. Supported scopes: Default, wsReadOnly, wsReadWrite, amReadOnlyWorkflow, amReadWriteWorkflow, amReadOnlyInvitation, amReadWriteInvitation, amReadOnlyGroup, amReadWriteGroup, amReadOnlyUser, amReadWriteUser.

Each API method operates on a certain type of resource with a defined model (for details, see the Methods section below) and produces a JSON response that contains the entity type in the kind field and an array of entities in the data field. Client can pass an additional state parameter in the request, which also will be included in the response.

Response example:

HTTP codeerrordetails
400invalid_requestRequest HTTP type is invalid, request critical data is absent or malformed (e.g., no attachment body)
400invalid_parameterRequest parameter name or value is invalid
400parameter_requiredRequired parameter is absent
401not_authorizedUser is not authorized (authorization is invalid, malformed or expired)
403access_forbiddenAccess to requested entity is denied for user
403not_allowedRequested action is not allowed due to license/quota limitations, e.t.c.
404resource_not_foundRequested entity is not found
404method_not_foundRequested API method does not exist
500server_errorServer side error

OAuth 2.0 authorization

APIv3 uses the OAuth 2.0 protocol for authorization. The OAuth 2.0 Authorization Framework protocol is described in http://tools.ietf.org/html/rfc6749. At the moment, APIv3 supports authorization code flow. This documentation contains a brief description of the OAuth 2.0 authorization process. For details, please see [RFC6749, 4.1.].

Obtaining client credentials

In order to use OAuth 2.0 authorization in the application, you should register it in Wrike. After registration, you can obtain your client credentials by filling out the form at https://developers.wrike.com/getting-started/.

OAuth 2.0 authorization steps

1. Requesting authorization code [RFC6749, 4.1.1.]

To start the authorization process, the user should click on the link that will direct the user-client to the following URL:

Copy to clipboard
https://www.wrike.com/oauth2/authorize?client_id=<client_id>&response_type=code

The authorize URL can also contain the optional parameters redirect_uri, state, and scope. The value of the scope parameter is expressed as a list of comma-delimited, case-sensitive strings. Supported scopes: Default, wsReadOnly, wsReadWrite, amReadOnlyWorkflow, amReadWriteWorkflow, amReadOnlyInvitation, amReadWriteInvitation, amReadOnlyGroup, amReadWriteGroup, amReadOnlyUser, amReadWriteUser. If scope parameter value is absent, Default is assumed.

After clicking on the URL, the user is redirected to the login page (if he or she is not already logged in) and then to a consent page to get confirmation approval.
The consent page redirects the client to the redirect_uri with the code parameter set to the authorization code.

Copy to clipboard
Redirect example:
GET https://www.myapp.com/oauth2_uri?code=<authorization_code>

2. Exchanging authorization code for access credentials [RFC6749, 4.1.3.]

Access credentials are requested by executing POST request to a token URL with an authorization code.

Copy to clipboard
POST https://www.wrike.com/oauth2/token
Parameters:
client_id=<client_id>
client_secret=<client_secret>
grant_type=authorization_code
code=<authorization_code>
Copy to clipboard
CURL example:
curl -X POST -d "client_id=<client_id>&client_secret=<client_secret>&grant_type=authorization_code&code=<authorization_code>" https://www.wrike.com/oauth2/token

Response example:

  • {
  •    "access_token": "2YotnFZFEjr1zCsicMWpAA",
  •    "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
  •    "token_type": "bearer",
  •    "expires_in": 3600
  • }

3. Using access credentials

Every request to the API should be done using HTTPS protocol with the access token, which should be passed in the authorization header (preferred option) or the access_token parameter.

Copy to clipboard
CURL example:
curl -X GET -H "Authorization: bearer <access_token>" https://www.wrike.com/api/v3/accounts

If the access_token is expired, the application should refresh the access token to continue.
The server response for an expired access token will be as follows:

  • {
  •    "error": "not_authorized",
  •    "errorDescription": "Access token is unknown or expired"
  • }

4. Refreshing access token [RFC6749, 6.]

The access token is refreshed by a POST request to a token URL with a refresh token:

Copy to clipboard
POST https://www.wrike.com/oauth2/token
Parameters:
client_id=<client_id>
client_secret=<client_secret>
grant_type=refresh_token
refresh_token=<refresh_token>
Copy to clipboard
CURL example:
curl -X POST -d "client_id=<client_id>&client_secret=<client_secret>&grant_type=refresh_token&refresh_token=<refresh_token>" https://www.wrike.com/oauth2/token

Web-hooks (Beta)

Webhooks allow you to subscribe to notifications about changes in Wrike instead of having to rely on periodic polling. When webhooks are in place, a small package of information (‘payload’) is sent to your HTTP endpoint when specific changes occur.

We support the following scopes for webhooks:

  1. Folder webhooks - fire notifications about changes to tasks within a single Folder or Project. You must subscribe to Folders/Projects individually — subscribing to a Folder/Project does not subscribe you to its Subfolders/Subprojects.
  2. Account webhooks - fire notifications about changes to any tasks in the Account. Includes changes to all tasks (which are shared with you) in the account.

API Methods

REST-style API methods allow you to create webhooks, get lists of your webhooks and their states, update webhook states, and delete webhooks.

Create Webhooks

  • [POST] /folders/{folderId}/webhooks — Creates a webhook for a target Folder / Project.
    • Parameters: hookUrl - URL of the server which will receive the payload.
  • [POST] /accounts/{accountId}/webhooks — Creates a webhook for a particular account.
    • Parameters: hookUrl - URL of the server which will receive the payload.

Get Webhook(s) State

  • [GET] /webhooks — Returns a list of all existing webhooks
  • [GET] /accounts/{accountId}/webhooks — Returns a list of webhooks in a specified account.
  • [GET] /webhooks/{webhookId},{webhookId},... [up to 100 IDs] — Returns information for the specified webhooks.
  • The response model for these methods includes the following data for each hook:
       webhook ID, account ID, Folder ID (optional), your server's URL and status (Active | Suspended).

Update Webhook State

  • [PUT] /webhooks/{webhookId} — Modifies the webhooks state to suspend or resume. Suspended webhooks do not send notifications.
    • Parameters: status = Active | Suspended

Delete Webhooks

  • [DELETE] /webhooks/{webhookId} — Deletes webhook by ID.

Sample Payloads

Below is an example of the most basic payload which can be received. This payload is sent when a new task is created (note the “eventType”):

  • [{
  •        "webhookId": "IEAADQQLKQAKAOPB",
  •        "eventAuthorId": "KQAKAOPB",
  •        "eventType": "TaskCreated",
  •        "taskId": "IEAADQQLKQAKAOPB",
  •        "lastUpdatedDate": "2016-10-10T11:33:28Z"
  • }]

Note, even single notifications are sent as JSON-array. For simplicity, we’ll write payloads as single JSON-objects in the text below.

Some payloads can contain values which designate what the data was before the change, i.e. for the TaskTitleChanged event you see the old and new task title:

  • {
  •    "oldValue": "Old task title",
  •    "title": "New task title",
  •    "taskId": "IEAADQQLKQAKOFAB",
  •    "webhookId": "IEAADQQLJAAAAULL",
  •    "eventAuthorId": "KUAALDRX",
  •    "eventType": "TaskTitleChanged",
  •    "lastUpdatedDate": "2016-11-22T10:25:50Z"
  • }

Another example with old/new values is TaskStatusChanged:

  • {
  •    "oldStatus": "Active",
  •    "status": "Completed",
  •    "taskId": "IEAADQQLKQAKOFAB",
  •    "webhookId": "IEAADQQLJAAAAULN",
  •    "eventAuthorId": "KUAALDRX",
  •    "eventType": "TaskStatusChanged",
  •    "lastUpdatedDate": "2016-11-22T11:09:58Z"
  • }

Task statuses mentioned in “oldStatus” and “status” fields are described for “status” param of “query-tasks” API method.

For events related to task child entities, i.e. attachments, payload will contain corresponding entity ID. Example is AttachmentAdded event:

  • {
  •    "webhookId": "IEAADQQLKQAKAOPB",
  •    "eventAuthorId": "KQAKAOPB",
  •    "lastUpdatedDate": "2016-10-10T11:33:28Z",
  •    "eventType": "AttachmentAdded",
  •    "taskId": "IEAADQQLKQAKAOPB",
  •    "attachmentId": "IEAADQQLKQAKAOPD"
  • }

To get detailed information about the attachment you'll need to use Get Attachments method - with the ID you'd received.

Event Types

Currently we support only events related to tasks, not to Folders/Projects (i.e. webhook won’t fire if comment is added to the Folder itself).

Show supported events
Event Description Includes Old Value
TaskCreated Fired when user creates a new task
TaskDeleted

Per-account hooks: Fired when a user deletes a task

Per-Folder hooks: Not fired

TaskTitleChanged Fired when task title changed +
TaskImportanceChanged Fired when task importance changed +
TaskStatusChanged Fired when task status changed +
TaskDatesChanged Fired when start, finish dates, duration, or the “Work on weekends” flag is changed +
TaskParentsAdded Fired when a task is added to a Folder
TaskParentsRemoved Fired when a task is removed from a Folder
TaskResponsiblesAdded Fired when a new assignee is added to a task, including all Wrike users (and Collaborators) and users with pending invitations.
TaskResponsiblesRemoved Fired when someone is unassigned from a task
TaskSharedsAdded Fired when a task is shared
TaskSharedsRemoved Fired when a task is unshared
TaskDescriptionChanged Fired when a task’s description is changed. Note: Notifications related to description field changes are fired with a 5 min delay (approximately)
AttachmentAdded Fired when a new attachment is added to a task
AttachmentDeleted Fired when attachment was deleted from task or comment with attachment was deleted
CommentAdded Fired when a new comment is added. Not fired for comments without text, i.e. comments with attachments only
CommentDeleted Fired when a comment is deleted
TimelogChanged Fired when a Timelog record is added, updated, or removed
The following events are not yet supported (and do not trigger notifications):

Example of Usage

Use Case Example

Let’s assume a task is related to the development process and a “Completed” status means that all code was committed/pushed to the source repository. You could have this change trigger a CI build via some CI REST endpoint.

Step 1

Create an account-wide webhook.

Get your accountId using the following CURL command:
Copy to clipboard

curl -g -X GET -H 'Authorization: bearer <access_token>' 'https://www.wrike.com/api/v3/accounts'

The response contains a list of your accounts:

  • {
  •    "kind": "accounts",
  •    "data": [
  •        {
  •            "id": "IEAADQQL",
  •            "name": "My Personal Account",
  •            "dateFormat": "MM/dd/yyyy",
  •            "firstDayOfWeek": "Mon",
  •            "workDays":
  •            [
  •                "Sun",
  •                "Mon",
  •                "Tue",
  •                "Wed",
  •                "Thu",
  •                "Fri",
  •                "Sat"
  •            ],
  •            "rootFolderId": "IEAAAOVII7777777",
  •            "recycleBinId": "IEAAAOVII7777776",
  •            "createdDate": "2013-12-30T12:17:24Z",
  •            "joinedDate": "2015-08-04T13:56:13Z"
  •        }
  •    ]
  • }

You will need “id” field for future requests (“IEAADQQL” in the example above).

Step 2

Execute the following CURL command to create a new account-wide webhook and subscribe your endpoint (https://yourwebhookserver.com/event-handler) to notifications.

Get your accountId using the following CURL command:
Copy to clipboard

curl -g -X POST -H 'Authorization: bearer <access_token>' -d 'hookUrl=https://yourwebhookserver.com/event-handler' 'https://www.wrike.com/api/v3/accounts/IEAADQQL/webhooks'

You’ll see the following response:

  • {
  •    "kind": "webhooks",
  •    "data": [
  •        {
  •            "id": "IEAADQQLJAAAAULN",
  •            "accountId": "IEAADQQL",
  •            "hookUrl": "https://yourwebhookserver.com/event-handler",
  •            "status": "Active"
  •        }
  •    ]
  • }

Step 3

Next, change a task in the account, i.e. change a task’s status from Active to Completed. You’ll receive the following payload on your endpoint:

  • {
  •    "oldStatus": "Active",
  •    "status": "Completed",
  •    "taskId": "IEAADQQLKQAKOFAB",
  •    "webhookId": "IEAADQQLJAAAAULN",
  •    "eventAuthorId": "KUAALDRX",
  •    "eventType": "TaskStatusChanged",
  •    "lastUpdatedDate": "2016-11-22T11:09:58Z"
  • }

Suspended Webhooks

If you shut down your endpoint or it is not accessible via the internet, then we automatically suspend the webhook after three retries. In this case, the following request by given webhook ID returns the Suspended state for webhook:
Copy to clipboard

curl -g -X POST -H 'Authorization: bearer <access_token>' 'https://www.wrike.com/api/v3/webhooks/IEAADQQLJAAAAULN'

Response reflecting suspended state:

  • {
  •    "kind": "webhooks",
  •    "data": [
  •        {
  •            "id": "IEAADQQLJAAAAULN",
  •            "accountId": "IEAADQQL",
  •            "hookUrl": "https://yourwebhookserver.com/event-handler",
  •            "status": "Suspended"
  •        }
  •    ]
  • }

Restart Webhooks

Restart the webhook using the following PUT request:
Copy to clipboard

curl -g -X POST -H 'Authorization: bearer <access_token>' 'https://www.wrike.com/api/v3/webhooks/IEAADQQLJAAAAULN'

Response:

  • {
  •    "kind": "webhooks",
  •    "data": [
  •        {
  •            "id": "IEAADQQLJAAAAULN",
  •            "accountId": "IEAADQQL",
  •            "hookUrl": "https://yourwebhookserver.com/event-handler",
  •            "status": "Active"
  •        }
  •    ]
  • }

You can get a list of your webhooks (and their states) at any time:
Copy to clipboard

curl -g -X POST -H 'Authorization: bearer <access_token>' 'https://www.wrike.com/api/v3/accounts/IEAADQQL/webhooks'

Response will contain JSON with all of webhooks created by you. Similar to:

  • {
  •    "kind": "webhooks",
  •    "data": [
  •        {
  •            "id": "IEAADQQLJAAAAULN",
  •            "accountId": "IEAADQQL",
  •            "hookUrl": "https://yourwebhookserver.com/event-handler",
  •            "status": "Active"
  •        }
  •    ]
  • }