TRACKVIA CLASSIC API

The API documentation on this page is for TrackVia Classic only. If you are looking for API docs for our new platform, please visit developer.trackvia.com.

New records can be created, retrieved, updated or deleted using HTTP GET and POST requests in XML, JSON, or CSV formats. SSL and a unique security key are required and can be optionally limited to specific IP addresses.

The TrackVia API allows customers to synchronize their data with any third-party application. Below you will find detailed documentation about our most current API. For customers using our legacy API (before February 2013), you can find documentation HERE. For additional information, we invite you to visit our SUPPORT COMMUNITY to learn more.

In addition to the documentation below, you can find sample client libraries on Github at:

API CONTENTS


AUTHENTICATION

Trackvia uses the OAuth2 protocol for API authentication. You need a valid Access Token before you can start using the API. Access Tokens are granted per user.

Client/App Setup

A “client” or app refers to the 3rd party app that is accessing the TrackVia API. An account admin must first add your app in ACCOUNT SETTINGS. Scroll to the “API” section and click “Add New App”. Type in the App name. If you are setting up the API for your own Trackvia account, you can simply type your own company name. Click the Save button, then scroll down to see your newly created Client ID and Secret Key. Copy and save these for later.

Access Token

Using the “User Credentials” flow (username/pass) you can easily get an Access Token for a user. Here is where you need to use the previously obtained client_id and secret. Use the following URL with a GET or POST request.

https://api.trackvia.com/oauth/v2/token?client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}&grant_type=password&username={USERNAME}&password={PASSWORD}

Response 200 OK

{

“access_token”: “MAN-O9BbkinUWabsRgUBMDckFgdSY-VtuoWBZqFZBg4″,

“expires_in”: 86400,

“token_type”: “bearer”,

“scope”: null,

“refresh_token”: “ZpQdQQ0v432kDw_AcwKnrVdqiFM8UCOCPPJplsgZtYc”

}

You will get a JSON object back with an “access_token”. You need to save this access token as you will need it for every subsequent API request. The “expires_in” parameter indicates how many seconds until that token expires. You are also given a “refresh_token”. See the Refresh Token section for more info.

Note: All authentication responses come back in JSON format as per the OAUTH2 SPEC.

REFRESH TOKEN

Your Access Token expires in 24 hours from when you first obtain one. A Refresh Token however is valid for 7 days. If you wish, you can request a new Access Token with your Refresh Token. With this approach, you do not have to pass along the user’s credentials in the request

https://api.trackvia.com/oauth/v2/token?client_id={CLIENT_ID}&client_secret={CLIENT_SECRECT}&grant_type=refresh_token&refresh_token={REFRESH_TOKEN}

Note: Using a refresh token is optional. The benefit here is you do not need to pass any user credentials with the request.

Response 200 OK

{

“access_token”: “Rz5tZ6lWh3WqWmLTdqzMB8Kw4H1ee4Nishdyl7_2V_k”,

“expires_in”: 86400,

“token_type”: “bearer”,

“scope”: null,

“refresh_token”: “l97ZM9vXQgDjGfRMIL7RGPTVqF2PTG2nR8BnXbTw7i8″

}

USING THE TRACKVIA REST API

Note: API data is available in different formats. Valid formats are .json (default), .xml, .csv, .jsonp. Just change the extension in the url request.

When requesting at the directory level:

JSON format:   https://api.trackvia.com/apps.json?access_token={ACCESS_TOKEN}

JSONP format: https://api.trackvia.com/apps.jsonp?access_token={ACCESS_TOKEN}

XML format:     https://api.trackvia.com/apps.xml?access_token={ACCESS_TOKEN}

CSV format:     https://api.trackvia.com/apps.csv?access_token={ACCESS_TOKEN}

When requesting specific entry by id:

JSON format:   https://api.trackvia.com/apps/{ID}.json?access_token={ACCESS_TOKEN}

JSONP format: https://api.trackvia.com/apps/{ID}.jsonp?access_token={ACCESS_TOKEN}

XML format:     https://api.trackvia.com/apps/{ID}.xml?access_token={ACCESS_TOKEN}

CSV format:     https://api.trackvia.com/apps/{ID}.csv?access_token={ACCESS_TOKEN}

DASHBOARDS

Now that you have an access token for that user, you can use the API. Get a list of dashboards created by the user associated with this access_token.

http://api.trackvia.com/dashboards?access_token={ACCESS_TOKEN}

Response 200 OK

[

{

“id”: “3088”,

“name”: “My Main Dashboard”

},

{

“id”: “3090”,

“name”: “Another Dashboard”

}

]

DASHBOARD

Get data for a specific dashboard by passing an ID.

HTTP://API.TRACKVIA.COM/DASHBOARDS/{DASHBOARD_ID}?access_token={ACCESS_TOKEN}

Response 200 OK

{

“id”: “3088″,

“name”: “My Main Dashboard”,

“created”: “2012-06-11T20:32:05-0600″,

“updated”: “2012-06-11T20:33:24-0600″,

“rows”: [

{

“id”: “6417”,

“name”: “”,

“description”: “”,

“columns”: [

{

“id”: “9810”,

“displayorder”: 0,

“fields”: [

{

“id”: “21429”,

“name”: “Tasks”,

“description_as_tooltip”: false,

“displayorder”: 0,

“reports”: [

{

“dashboardfieldid”: “21429”

}

]

},

{

“id”: “21430″,

“name”: “”,

“description_as_tooltip”: false,

“displayorder”: 1,

“reports”: [

{

“dashboardfieldid”: “21430”

}

]

}

]

}

]

}

]

}

APPS

Get a list of Apps available to that user.

https://api.trackvia.com/apps?access_token={ACCESS_TOKEN}

Response 200 OK

[

{

“id”: “1”,

“name”: “Employee Management App”

},

{

“id”: “2”,

“name”: “Sample App”

}

]

LIST TABLES FOR AN APP

Get App meta-data with a list of tables for that App, using an app_id

https://api.trackvia.com/apps/{APP_ID}?access_token={ACCESS_TOKEN}

Response 200 OK

{

“id”: “1″,

“name”: “Employee Management App”,

“tables”: [

{

“id”: “10”,

“name”: “Employees”,

“record_label”: “employee”,

“record_plural”: “employees”

},

{

“id”: “11”,

“name”: “Managers”,

“record_label”: “manager”,

“record_plural”: “managers”

},

]

}

TABLE

Get Table meta-data with a list of views, using a table_id

https://api.trackvia.com/tables/{TABLE_ID}?access_token={ACCESS_TOKEN}

Response 200 OK

{

“id”: “10″,

“name”: “Employees”,

“record_label”: “employee”,

“record_plural”: “employee”,

“views”: [

{

“id”: “100”,

“name”: “All employees, all fields”,

“description”: “View all Employees”,

“table_id”: “10”

},

{

“id”: “101”,

“name”: “Employees over 40”,

“description”: “List of employees over 40 yrs old”,

“table_id”: “10”

}

],

“coldefs”: [

{

“label”: “Name”,

“required”: true,

“display_order”: 1,

“type”: “short_answer”

},

{

“label”: “Job Title”,

“required”: true,

“display_order”: 2,

“type”: “short_answer”

},

{

“label”: “Manager”,

“required”: true,

“display_order”: 3,

“foreign_key_id”: 202,

“type”: “foreign_key”

}

]

}

This response gives you meta-data for the table – like its ID, name, and record labels. You also get a list of views for the table, and the column definitions (coldefs).

Coldefs:

Column definitions describe what fields are available in a table. You will also see what type of field it is such as short_answer, paragraph, drop_down, foreign_key, etc. See our KNOWLEDGE BASE for more info on fields types.

Foreign Keys:

A field that is a “foreign_key” type means that it links to a field in another table. In the TrackVia application, this will give you a dropdown list of values from the other table. If you need to get the values associated with that field, you must send another request using the foreign_key_id in the column definition:

https://api.trackvia.com/tables/{TABLE_ID}/foreign_keys/{FOREIGN_KEY_ID}?access_token={ACCESS_TOKEN}

The previous table response shows that the “Manager” field is a foreign_key type. To get a list of manager names you would make a request like this:

https://api.trackvia.com/tables/10/foreign_keys/202?access_token={ACCESS_TOKEN}

Response (list of manager names):

[

“Alan Schaefer”,

“George Dillon”,

“Anna Gonsalves”,

“Billy Sole”,

“Blain Cooper”

]

VIEW (LIST OF RECORDS)

Get View metadata with a list of records for that View, using a view_id

https://api.trackvia.com/views/{VIEW_ID}?access_token={ACCESS_TOKEN}

Response 200 OK

{

“id”: “100″,

“name”: “All employees, all fields”,

“description”: “View all Employees”,

“table_id”: “10″,

“records”: [

{

“id”: “75994649”,

“table_id”: “10”,

“created”: “2010-06-15T14:46:41-0600”,

“updated”: “2011-03-23T16:18:57-0600”,

“fields”: {

“Name”: “Frank Dillon”,

“Job Title”: “Marketing Supervisor”,

“Manager”: “Billy Sole”,

“Salary”: “$80,000”,

“Hire Date”: “2006-06-15T12:00:00-0000”

}

},

{

“id”: “75994650”,

“table_id”: “10”,

“created”: “2010-06-15T14:46:42-0600”,

“updated”: “2011-03-23T16:18:57-0600”,

“fields”: {

“Name”: “Justin Robinson”,

“Job Title”: “Software Engineer”,

“Manager”: “Billy Sole”,

“Salary”: “$90,000”,

“Hire Date”: “2007-05-15T12:00:00-0000”

}

}

]

}

Paginating results

Some of your views may have a large amount of records. By default we limit the amount of records returned to 500. Use the following parameters on the end of the query string to limit results and get different pages of results.

Optional parameters:

Parameter name: Type: Description:
page integer Select a page of results.e.g.  page=2
limit integer Limit the amount of records returned.e.g.  limit=50

Example:

https://api.trackvia.com/views/{VIEW_ID}?access_token={ACCESS_TOKEN}&limit=50&page=2

RECORDS

You have the ability to fetch data for a single record using a GET request.

https://api.trackvia.com/records/{RECORD_ID}?access_token={ACCESS_TOKEN}

Response 200 OK

{

“id”: “75994649″,

“table_id”: “10″,

“created”: “2010-06-15T14:46:41-0600″,

“updated”: “2011-03-23T16:18:57-0600″,

“fields”: {

“Name”: “Frank Dillon”,

“Job Title”: “Marketing Supervisor”,

“Manager”: “Billy Sole”,

“Salary”: “$80,000″,

“Hire Date”: “2006-06-15T12:00:00-0000″

}

}

Note: Date formats follow the ISO 8601 STANDARD

INSERTING RECORDS

You have the ability to insert one or more new records using a POST request.

https://api.trackvia.com/records?access_token={ACCESS_TOKEN}

Using a cURL library or similar:

Set the request header “Content-Type: application/json”

Set the request body content as a json formatted array of record data. This is the payload.

You can insert records on one table per request.

This following example would create 2 new records under the table_id 10:

Payload

{

“table_id”: “10″,

“records”: [

{

“Name”: “Craig Peters”,

“Job Title”: “Software Engineer”,

“Manager”: “Billy Sole”,

“Salary”: “$80,000”,

“Hire Date”: “2006-06-15T12:00:00-0000”

},

{

“Name”: “Kevin McGruber”,

“Job Title”: “UX Engineer”,

“Manager”: “Billy Sole”,

“Salary”: “$65,000”,

“Hire Date”: “2006-06-15T12:00:00-0000”

}

]

}

Response 200 OK

{

“code”: “success”,

“message”: “2 record(s) were added”

}

DELETE A RECORD

You can delete an existing record by sending a http DELETE request to the records uri with a record_id.

https://api.trackvia.com/records/{RECORD_ID}?access_token={ACCESS_TOKEN}

Response 200 OK

{

“code”: “success”,

“message”: “1 record was deleted”

}

BATCH DELETE RECORDS

Batch delete records by sending a http DELETE request to the records uri with a json array of record_ids

https://api.trackvia.com/records/{RECORD_ID}?access_token={ACCESS_TOKEN}

Example deleting 2 records using id’s:

Payload

{

“table_id”: 10,

“records”: [105973362,105973363,105973363,105973363,105973363,105973363]

}

Response 200 OK

{

“code”: “success”,

“message”: “2 record(s) were deleted”

}

UPDATE A RECORD

You can update a single record using a PUT request and specifying the record_id in the URL.

https://api.trackvia.com/records/{RECORD_ID}?access_token={ACCESS_TOKEN}

Using a cURL library or similar:

Set the request header “Content-Type” to “application/json”

Set the request body content as a json formatted array of record data. This is the “payload”.

Payload

{

“Name”: “Craig J. Peters”,

“Job Title”: “Director of Engineering”

}

Response 200 OK

{

“code”: “success”,

“message”: “Record was successfully updated”

}

BATCH UPDATE RECORDS

You can update multiple records at once using a PUT request

https://api.trackvia.com/records?access_token={ACCESS_TOKEN}

The payload is similar to inserting new records, except you need to specify the record id with each item and only provide the data fields that you want to change.

Using a cURL library or similar:

Set the request header “Content-Type” to “application/json”

Set the request body content as a json formatted array of record data. This is the “payload”.

Example payload to batch update 2 records, record ID’s are 75994649 and 75994650:

Payload

{

“table_id”: 62994,

“records”: [

{

“id”: 75994649,

“fields”: {

“Name”: “Craig J. Peters”,

“Job Title”: “Director of Engineering”

}

},

{

“id”: 75994650,

“fields”: {

“Job Title”: “Manager”,

“Salary”: “$70,000”

}

}

]

}

Response 200 OK

{

“code”: “success”,

“message”: “2 record(s) were successfully updated”

}

FORMS

To see what forms are available for a table, make a GET request to this url:

https://api.trackvia.com/tables/{TABLE_ID}/forms?access_token={ACCESS_TOKEN}

Response 200 OK

[

{

“id”: “3”,

“name”: “Add a new Employee”

},

{

“id”: “114”,

“name”: “Update an existing Employee”

}

]

SEARCH

You can search records in a table. You need the TABLE_ID and a SEARCH_TERM.

SEARCH_TERM should be properly url encoded. results will be an array of records.

https://api.trackvia.com/search/{TABLE_ID}/{SEARCH_TERM}?access_token={ACCESS_TOKEN}

For example:

Search your employee table for specific name.

https://api.trackvia.com/search/10/craig?access_token={ACCESS_TOKEN}

Response 200 OK

[

{

“id”: 76922034,

“table_id”: 10,

“created”: “2010-07-13T09:41:10-0600”,

“updated”: “2012-04-05T09:16:43-0600”,

“fields”: {

“Name”: “Craig Peters”,

“Job Title”: “Software Engineer”,

“Manager”: “Billy Sole”,

“Salary”: “$80,000”,

“Hire Date”: “2006-06-15T12:00:00-0000”

}

}

]

ERRATA AND NOTES

We recommend using the JSON interfaces unless there is a compelling reason to use an alternate format.

Date fields:

If a field is a “date only” field, the format is as follows 2013-01-15. (year-month-day)

Formula updates:

Formula calculations will be done asynchronously with the API request.  Expect a slight delay (seconds) in data being updated as a result.

User fields:

When submitting users via the API when dealing with link to parent, you must use the user id, not the text value of the name.