# Docketwise Api v1 Documentation

## Getting Started

To start using Docketwise's API please email <dev@docketwise.com> with subject: **API integration**. Please include the redirect uris you'll be using for the OAuth 2.0 authorization.

### Base url

This is the base url you'll be using for all requests:

```bash
https://app.docketwise.com/api/v1/
```

### **Authorization**

We use OAuth 2.0 flow to obtain proper authorization and access to the API.  Here are the urls you'll be using for the authorization flow:

* Authorization url: [`https://app.docketwise.com/oauth/authorize`](https://app.docketwise.com/oauth/authorize)
* Token url: [`https://app.docketwise.com/oauth/token`](https://app.docketwise.com/oauth/token)

Remember to include the redirect uri and response type in the request. Here's an example request authorization request:

```bash
GET /oauth/authorize?response_type=code&client_id=your_client_id&redirect_uri=http%3A%2F%2Fyourapp.com%2Fcallback&scope=public%20write
```

After obtaining your authorization code, you'll be able to request a token by doing a POST request to the token url above. Here's an example request:

```bash
POST /oauth/token
Content-Type: application/x-www-form-urlencoded
client_id=your_client_id&client_secret=your_client_secret&grant_type=authorization_code&code=code_obtained_from_authorize&redirect_uri=http%3A%2F%2Fyourapp.com%2Fcallback
```

And that's it, you should obtain an `access_token` string, an `expires_in` integer and a `refresh_token` string. You should add the Bearer Token&#x20;

You need to include the access\_token as an `Authorization` header with value `Bearer <your_access_token>`

### Refreshing Token

The access tokens obtained through the OAuth 2.0 flow, have an expiration of 180 days. Once this time passes, you'll have to request a new access token using the refresh token provided by the OAuth 2.0 flow as well. To do this you'll have to do a `POST` request to the `/oauth/token` url, but with a `gran_type` of `refresh_token`

### Pagination

Index actions return a maximum of 200 records per page. Information about pagination is returned in a X-Pagination header where you can find the total amount of records, next page, previous page and total pages. By default the first page of the records is returned. Subsequent pages can be requested by adding a page parameter in the request. I.e.:<br>

```bash
GET /contacts?page=2
```

### Rate Limit

Requests are limited on a per token basis to a 120 requests per minute. When a request gets throttled it responds with a 429 status. If this happens, you can use the Retry-Header to know how many seconds you have to wait before issuing new requests.&#x20;