IMPORTANT NOTE ABOUT THIS API DOCUMENTATION:

The API documentation has been moved to http://www.dovico.com/developer/API_doc/index.htm.

The Content of this wiki will be deleted on Friday July 20th, 2018.



PLEASE UPDATE YOUR BOOKMARKS AS REQUIRED



API Architecture
DOVICO Hosted Services API is based on the REST Architecture for web services. REST is an architecture modeled off the web. It uses a set of constraints that eases development complexity and encourages scalable designs. To learn more about the the REST architecture please see REST.

Security
Access and data security was a top priority during the development of the API. Below are the some of the security mechanisms implemented in the API:

  • Encryption - We require all API communication to be sent and received using SSL encrypted HTTP. This keeps your data safe in transit.
  • Authentication - The API needs to have 2 tokens sent to its authentication engine for data to be accessed. One token is a consumer secret key that is required to identify the program and the other is a User token to identify the user. This Authentication engine is based on the OAuth WRAP specification. This keeps unauthorized entities from accessing your data.
  • Data Access - After the the API has authenticated a request, it will enforce the limited access security that has been setup in the DOVICO Services application for the user. This keeps your authorized entities from accessing data they should not have access to.
  • Enable/Disable API - We have also built in the option to disable API access to your company data. This can be set by a DOVICO administrator in the Database Options screen of the DOVICO application.

Request Limits
By default API requests will be limited to 5 calls per second and 1000 results returned per call. This means 5000 records per second are returned for GET calls. Paging is implemented for methods that return more than 100 results so that the developer can request additional pages of information. When the page results are returned they will include the Previous Page URI and Next Page URI. If the Next Page URI returns the value of “N/A” then that’s the last page. There is a limit of 5MB of data per POST call. If you have more than 5MB of data to post you will need to make additional POST calls in 5MB increments.

Service URL
The service URL for the API is:

https://api.dovico.com/?version=6
Sending a properly formatted request to this URL will return a list of API calls available. Please note that all API communication requires sending the request to HTTPS. We require all requests to the API to be secured using SSL.

Representation Formats
API requests are sent to a resource URI. Included in the header of the HTTP request is the Consumer secret and User Access tokens. In addition to the header information you are required to include the API version as a querystring variable in the URI. Below is a sample request syntax using win32 cURL.

curl -H "Authorization: WRAP access_token=""client=c97727ec3838427bbec992a043db2408.555&user_token=8f540ff34f0c48baa80868fbc72bcc58.555""" -k https://api.dovico.com/employees/?version=6


The current version of this API supports accepting data as XML or JSON and returning data as XML or JSON. By default the API returns data as XML. To have the API return data as JSON, specify the Accept header: Accept: application/json
Use the Content-Type header to indicate what type of data you are passing. For XML use either 'application/xml' or 'text/xml' and for JSON use 'application/json'. The following is an example of the Content-Type header when passing the API JSON data: Content-Type: application/json

Below is a sample successful request response made to the Employee URI:
<Result xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <Employees>
    <Employee>
      <ID>187</ID>
      <LastName>2</LastName>
      <FirstName>2</FirstName>
      <Wage />
      <WageCurrencyID />
      <WageChangedDate />
      <Charge />
      <ChargeCurrencyID />
      <ChargeChangedDate />
      <StartDate>2011-05-12</StartDate>
      <EndDate>2100-12-31</EndDate>
      <Number />
      <Email />
      <WorkDays>.MTWTF.</WorkDays>
      <Hours>8</Hours>
      <AltApproval>F</AltApproval>
      <NotificationTime>F</NotificationTime>
      <NotificationExpense>F</NotificationExpense>
      <NotificationRejected>F</NotificationRejected>
      <Archive>F</Archive>
      <Integrate />
      <CustomFields>
        <CustomField>
          <ID>2029</ID>
          <TemplateID>105</TemplateID>
          <Name>Custom Field</Name>
          <Values>
            <Value>Easily add user defined fields</Value>
          </Values>
          <GetCustomTemplateURI>https://api.dovico.com/API/CustomFieldTemplates/105/?version=6</GetCustomTemplateURI>
        </CustomField>
      </CustomFields>
    </Employee>
All unsuccessful responses will return a description of the error in the response where applicable:

This was a response from a request that had an incorrect Data Access Token.
<string xmlns="http://schemas.microsoft.com/2003/10/Serialization/">The server failed to authenticate the request.</string>
HTTP Status Codes
All request responses will include HTTP status codes. Below is a list of status codes used:

Get Requests:
  • 200 OK: A successful request. The response includes the representation.
  • 302 FOUND: A redirect response. Possibly a moved resource and you can get the representation from the redirected link.
  • 401 UNAUTHORIZED: The Authorization header was not specified. The Authorization header was not formatted correctly. The Consumer Secret or Data Access Token are incorrect.
  • 404 NOT FOUND: URI not found. Either the URI does not exist or has been removed.
  • 500 SERVER ERROR: This represents an internal server error. DOVICO Support should be contacted any time this error is received.
  • 503 SERVICE UNAVAILABLE: The service is temporarily down or request limits have been reached. Please wait and try again.

Put or Post requests:
  • 200 OK: A successful request. The resource was updated and the response includes the representation.
  • 201 CREATED: A successful request. The resource was created and the response includes the representation.
  • 400 BAD REQUEST: The request failed data validation. Check the format of the URI.
  • 401 UNAUTHORIZED: The Authorization header was not specified. The Authorization header was not formatted correctly. The Consumer Secret or Data Access Token are incorrect.
  • 404 NOT FOUND: URI not found. Either the URI does not exist or has been removed.
  • 500 SERVER ERROR: This represents an internal server error. DOVICO Support should be contacted any time this error is received,

Delete requests:
  • 200 OK: A successful request. The resource was deleted.
  • 401 UNAUTHORIZED: URI not found. Either the URI does not exist or has been removed.
  • 404 NOT FOUND: URI not found. Either the URI does not exist or has been removed.
  • 500 SERVER ERROR:This represents an internal server error. DOVICO Support should be contacted any time this error is received,