Walkthrough: Using the DocuPhase Pro Web API

Getting started

This documentation is designed for people who are familiar with making REST-based API calls using JSON data. It provides a simple overview of the DocuPhase Pro Web API, along with code samples written in C#. Detail documentation of the calls you can make with the DocuPhase Pro Web API can be found here.

Additional information
  • The BASE_URL of the API is: api.treenosoftware.com/api
  • Every API request returns an HTTP status of 200 as long as the URL is valid and you are authenticated correctly.
  • Each request contains hasError and errorMessage fields in addition to any other data provided by the API.
  • If hasError is true, an more detailed explanation of the error that occurred can be found in the errorMessage field.
  • The response content type of most requests is application/json.

Prerequisites

A DocuPhase Pro license is required to use this API. If you don’t own a license, contact DocuPhase Sales.

You will also need to have a DocuPhase Pro username and password to send requests to the DocuPhase Pro Web API.

A valid JWT access token must be passed in the HTTP headers of each API call (except during the initial authentication process).

Authentication

  • Request type: POST
  • Request url: BASE_URL/authentication/login

According to our api documentation of login we must provide username and password in request body. After a successful request a valid token will be given along with its expiration time. The hasError property will be true and detail error message will be in errorMessage if the login fails.


string loginUrl = "https://api.treenosoftware.com/api/authentication/login";

User userInfo = new User
{
    Username = "Username",
    Password = "Password"
};

StringContent postBody = new StringContent(JsonConvert.SerializeObject(userInfo), Encoding.UTF8, "application/json");

HttpClient client = new HttpClient();
HttpResponseMessage response = await client.PostAsync(loginUrl, postBody);

if (response.IsSuccessStatusCode)
{
    string responseContent = await response.Content.ReadAsStringAsync();
    ReturnAuthentication responseData = JsonConvert.DeserializeObject<ReturnAuthentication>(responseContent);

    if (!responseData.HasError)
    {
        string token = responseData.Authentication.Token; // Authentication token
        string email = responseData.Authentication.User.Email; // User email
    }
    else
    {
        string errorMessage = responseData.ErrorMessage; // Error message
    }
}

GET Request

  • Request type: GET
  • Request url: BASE_URL/folders/{dept}/{cab}
  • Additional header: Authorization: Bearer <TOKEN>

This sample request fetches the folder list for a specific cabinet in a department. The detail response is described in the api documentation section. In this particular url, department real name and cabinet real name must be provided. The authentication token needs to be passed in the request header as well.


string requestUrl = "<Request URL>";
string bearerToken = "Bearer " + token;

HttpClient client = new HttpClient();
client.DefaultRequestHeaders.Clear();
client.DefaultRequestHeaders.Add("Authorization", bearerToken);
HttpResponseMessage response = await client.GetAsync(requestUrl);

if (response.IsSuccessStatusCode)
{
    string responseContent = await response.Content.ReadAsStringAsync();
    ReturnFolderList responseData = JsonConvert.DeserializeObject<ReturnFolderList>(responseContent);
    if (!responseData.HasError)
    {
        List<Folder> folders = responseData.Folders; // Folder list
    }
    else
    {
        string errorMessage = responseData.ErrorMessage; // Error message
    }
}

POST Request

  • Request type: POST
  • Request url:BASE_URL/versions/change
  • Additional header: Authorization: Bearer <TOKEN>, ContentType: application/json

This particular api changes the version number to a new version. The detail response object and the necessary body object information is described in api documentation section. In this api some information about the file must be provided in the request body as a JSON. The authentication token needs to be passed in the request header as well.


string requestUrl = "<Request URL>";
string bearerToken = "Bearer " + token;

ChangeVersion postInfo = new ChangeVersion
{
    Department = "<Deparment real name>",
    Cabinet = "<Cabinet real name>",
    DocId = <Doc Id>,
    Subfolder = "<Subfolder (optional)>",
    Filename = "<Filename>",
    OldVersion = "<Old version>",
    NewVersion = "<New version>"
};

StringContent postBody = new StringContent(JsonConvert.SerializeObject(postInfo), Encoding.UTF8,    "application/json");

HttpClient client = new HttpClient();
client.DefaultRequestHeaders.Clear();
client.DefaultRequestHeaders.Add("Authorization", bearerToken);
HttpResponseMessage response = await client.PostAsync(requestUrl, postBody);

if (response.IsSuccessStatusCode)
{
    string responseContent = await response.Content.ReadAsStringAsync();
    ReturnChangeVersion responseData = JsonConvert.DeserializeObject<ReturnChangeVersion>(responseContent);

    if (!responseData.HasError)
    {
        bool isChanged = responseData.IsChanged; // Is changed or not
    }
    else
    {
        string errorMessage = responseData.ErrorMessage; // Error message
    }
}

Refresh TOKEN

Every authentication token has an expiration time that is given along with a valid login response and additional value with the key refreshToken is also given. Once the expiration time has reached instead of getting a 200 response, 401 (Unauthorized) response will be received. In this scenario refreshToken api can be used to acquire new access token.

A request to BASE_URL/authentication/refreshtoken/<REFRESH_TOKEN> will give another token that can be used for further requests.