Using API v2

Last Updated -

Please Note: We recommend only using Full-Time Agents when making API calls, as Flex-Agents will be billed for their usage, which may run up additional costs.

At Desk.com, we believe in the API-first development philosophy. With API v2, you have access to the same API that powers Desk.com itself, including Business Insights and the Next Gen Agent experience. With over 115 endpoints, API v2 offers developers the possibility to build extremely rich integrations and applications.

 

Technical Overview

Desk.com API v2 is a RESTful, JSON, HAL-based API with support for linking, embedding, and pagination which makes extensive use of HTTP status codes, HTTP headers, ETags, and validation codes.

Changes in V2

  • Support for Basic Authentication (over SSL/TLS) and OAuth 1.0a
  • Increased API rate limit (number of agents * 60 with a max of 300)
  • Rate limit info included in response headers for better rate limit management
  • Consistent HTTP status codes (Reference)
  • ETag Caching (Read More)
  • 422 Unprocessable Entity validation codes for better error handling (Read More)
  • Consistent object hierarchy and field names
  • Option to embed related resources via HAL specification (Read More)
  • Custom fields now returned as objects
  • Dynamic pagination: Previous and next page endpoints included in response (Read More)
  • Field selection: You can now optionally restrict which data fields are returned (Read More)
  • Consolodated endpoints for creating and updating customer-related fields (Read More)

Use the API from your browser

Getting started with API v2 is as simple as going to a URL within your browser. For example, visit https://mysite.desk.com/api/v2/filters to view a list of all your Desk.com filters. You can perform API v2 requests directly in your browser.

Upgrading from v1 to v2

Depending on the complexity of your existing API v1 application, upgrading to API v2 may take as little as a few minutes to as much as a few hours. The amount of effort involved ultimately depends on which API calls your application is making and how complex the logic is that handles the API responses.

Generally, the process of upgrading to v2 is a three phase process:

  1. Updating the API request endpoints.
  2. Adjusting how parameters are sent.
  3. Adjusting how your code logic processes the responses.

Example 1: Verifying credentials

API v1
response = client.get('/api/v1/account/verify_credentials.json')
puts "Your user level is #{response["user"]["user_level"]}."
API v2
response = client.get('/api/v2/users/me')
puts "Your user level is #{response["level"]}."


Example 2: Creating a customer

API v1
params = '{
  "name": "George Washington",
  "company": "U.S. Government",
  "custom_member_status": "Pro",
  "custom_vip_support": true
}'
create_customer = client.post('/api/v1/customers.json', params)
params = '{
  "email": "george@whitehouse.gov"
}'
add_email = client.post('/api/v1/customers/#{create_customer["results"]["customer"]["id"]}/emails.json', params)
puts "Created record for #{create_customer["results"]["customer"]["first_name"]}."
API v2
params = '{
  "first_name": "George",
  "last_name": "Washington",
  "company": "U.S. Government",
  "emails": [{
  	"type": "work", 
  	"value": "george@whitehouse.gov"
  }],
  "custom_fields": {
    "member_status": "Pro",
    "vip_support": true
  }
}'
response = client.post('/api/v2/customers', params)
puts "Created record for #{response["first_name"]}."


Pagination Limitation

There is currently a max pagination limit of 500. A request exceeding this limit will result in a 403 forbidden error. If your search has more than 500 pages, you can keep using the pagination links up to the max page size and then make a new "since_updated_at" call, allowing you to start back at page 1 again. To demonstrate this, here is an example: 

Example request #1:

{{base_url}}/api/v2/cases/search?email=jeremy@desk.com&sort_field=updated_at&per_page=100&since_updated_at=1383332580

Example response #1: 

You'll notice the last item in the result set has an updated at of "2013-12-13T20:24:12Z".  To retrieve the results since this item, you could issue the following request where the since_updated_at is the time since epoch of "2013-12-13T20:24:12Z" which is 1386966252. Note this will include the item in this page since you want to make sure that other items retrieved within the same second aren't lost from page to page.

Example request #2:

{{base_url}}/api/v2/cases/search?email=jeremy@desk.com&sort_field=updated_at&per_page=100&since_updated_at=1386966252

Example response #2: 

To view our full API v2 documentation, visit http://dev.desk.com. If you get stuck, send us an email and we'll be glad to help.