Introduction
An introduction to the PTLINKED API
At PTLINKED, we develop engaging exercise content that is flexible to be customized and packaged specifically for the companies and organizations we work with. We provide a secure private REST API built upon pragmatic RESTful design principles. With a REST API, we are able to provide a powerful, convenient, and simple Web services API for integrating our high-quality exercise content into your apps and platforms.
The PTLINKED API uses resource-oriented URLs that leverage built-in features of HTTP like verbs and response codes. All request and response bodies are JSON encoded, including error responses. Any off-the-shelf HTTP client (and active authentication credentials) can be used to communicate with the API.
This documentation will outline the various API end-points available to authorized developers. In addition, the documentation will guide any developer who is developing with the PTLINKED API and show source code examples.
Changes
Stay up to date on changes to the PTLINKED API
We continuously update our API as we add more exercise content, features, and end-points. This page will provide you a complete chronological list of all changes, bug fixes, new features, and updated content. You can also add your email address to our API Developer list and get notified every time a new version is released.
Sign up for the PTLINKED API Developer mailing list
Version 1.1.3 (January 12, 2021) - Custom integration branch release. We refactored the API to now support multiple customers identified by API Keys.
- Customers can now customize various aspects of their PTLINKED integration, fully supported by the API.
- In addition, customers can now track their user usage metrics by supplying a UID (unique identifier) and User Type (Patient, Physician).
Version 1.1.2 (October 14, 2020) - Bug fix release. Additional bugs were identified and corrected with this release.
- There was an encoding issue with one of the end-points.
- One of the end-point private methods was extremely slow and timing out on occasion.
- There was an issue with the API logging system, where the logs were not being recycled causing disk space to be eaten up quickly.
Version 1.1.1 (July 2, 2020) - Bug fix release. Due to the new API framework, we identified several compatibility bugs.
- We had to update the authentication middleware to utilize the SLIM framework middleware mechanics.
- There was an issue with the end-point authentication pass thru, where some public end-points were failing because they were expecting the authentication header.
Version 1.1.0 (April 16, 2020) - We switched the API micro-framework to utilize the popular SLIM framework. This will allow us to scale the API much more efficiently and provide more features and support.
Version 1.0.5 (January 11, 2020) - We updated the exercise program search end-point.
- Our engineers redesigned the exercise program search algorithm and database structure to provide natural language searching capabilities. The search end-point had to be completely updated to take advantage of the new capabilities.
Version 1.0.4 (November 21, 2019) - Added a new end-point.
- We restructured the exercise library organization, so we needed to add an end-point to pull the new filter types.
Version 1.0.3 (September 7, 2019) - Bug fix release.
- There was an issue with the JSON response body of one of the end-points.
- Fixed a couple of spelling/grammar issues with the response code messages.
Version 1.0.1 (August 14, 2019) - Bug fix release. Several bugs were corrected for our first minor patch update.
- Fixed an API end-point routing issue.
- Fixed an issue with an HTTP Method (PUT) getting routed to incorrect route.
- Fixed several incorrect error codes getting returned in various end-points.
Version 1.0.0 (June 20, 2019) - First Release. The PTLINKED API was launched with a primary focus to use it for internal application development.
Authentication
You must be authorized with correct credentials to use the API
The PTLINKED API is a closed service available only to authorized companies. Because of this, you will be required to register the domain you wish to use the PTLINKED API with. Once the domain has been accepted, PTLINKED will provide you with an API Key.
Every request to the PTLINKED API will require the API Key to be attached to the HTTP request header. An example of accomplishing this with cURL and PHP are displayed below.
Setting the API KEY using cURL
$ curl -H "token-authorization-x: {API KEY}" https://api-v1.ptlinked.com/exerciseprogram/resolve_name
Setting the API KEY using jQuery (AJAX)
$.ajax({
type: "GET",
url: "https://api-v1.ptlinked.com/exerciseprogram/resolve_name",
crossDomain: true,
headers: { 'token-authorization-x': '{API KEY}' },
dataType: "json",
error: function( jqXHR, textStatus, errorThrown ) {
},
success: function( data, textStatus, jqXHR ) {
}
});
Requests
Learn how to make requests for data from the API
The base URL of the PTLINKED API may vary depending on the version you are using, or if you have a customized branch of the API. For demonstration purposes, we will assume the following as the API base URL https://api-v1.ptlinked.com
.
The Request Method
Every HTTP request has a method that is typically one of:
GET
- Used to retrieve a resource or a collection of resources.POST
- Used to create a new resource.PUT
- Used to update or modify a resource.DELETE
- Used to delete a resource.HEAD
- Used to request the headers of a GET request.PATCH
- Used to update of modify a resource.OPTIONS
- Used to request information about the communication options from the API.
JSON Bodies
All POST
, PUT
, PATCH
requests are JSON encoded and must have a content type of application/json
, or the API will return a 415 Unsupported Media Type
status code. The following example shows a jQuery AJAX call to create a new exercise program. The example illustrates the HTTP request type (POST
), the API Key header, and JSON formatted data being sent to the server (data
).
$.ajax({
type: "POST",
url: "https://api-v1.ptlinked.com/exerciseprogram/create_new",
crossDomain: true,
headers: { 'token-authorization-x': '{API KEY}' },
data: { 'title': 'Some exercise title' },
dataType: "json",
error: function( jqXHR, textStatus, errorThrown ) {
},
success: function( data, textStatus, jqXHR ) {
}
});
Responses
Learn what to expect back from the API
Every HTTP response has a numeric status code. The status code identified the type of HTTP response. These codes allow the client end to handle the responses accordingly. For example, a successful response will have a status code 200 (OK)
or the invoked end-point doesn't exist in which case you will receive a response code of 400 (Invalid Request)
.
HTTP Status Response Codes
200 (OK)
- Request was successful.400 (Invalid Request)
- The requested end-point does not exist, or the required request conditions have not been met.401 (Unauthorized)
- The PTLINKED API server is unable to authorize the request, the API Key may be incorrect.403 (Forbidden)
- Request is authenticated but does not have access to the requested end-point.404 (Not Found)
- The requested resource cannot be located.415 (Unsupported Media Type)
- APOST
,PUT
, orPATCH
request does not have the correct content type set.422 (Unprocessed Entry)
- A request to create, updated, or modify a resource failed due to validation errors.429 (Too Many Requests)
- Request was rejected due to rate limiting implemented for the supplied API KEY.500 series
- An internal server error occurred.
Error Responses
All error responses from the API server will contain vital information useful for handling the issues on the client side. A typical error response will look similar to:
{
"statusCode": "400",
"statusMessage": "Invalid Request"
}
JSON Response Bodies
All API responses are JSON encoded. A single resource is represented as a singular JSON object, while a collection of resources is represented as an array of JSON objects.
Below is an example of a single resource response:
{
"field1": "value",
"field2": true,
"field3": []
}
Below is an example of a response containing a collection of resources:
[
{
"field1": "value",
"field2": true,
"field3": []
},
{
"field1": "another value",
"field2": false,
"field3": [],
"field4": 1234.23
}
}
Rate Limiting
API protection for high quality service
Rate limiting is not enabled for everyone. In fact, rate limiting is turned off by default and typically only used in situations where public requests may be needed.
When enabled, an API Key will be limited to 100 requests per minute across all end-points. The current state of the rate limiting is included in all response headers describing the current rate limit status:
Rate-Limit-Limit: 100
Rate-Limit-Remaining: 99
Rate-Limit-Used: 1
Rate-Limit-Reset: 20
Rate-Limit-Limit
- Total requests for the current period.Rate-Limit-Remaining
- Remaining number of requests for the current period.Rate-Limit-Used
- The number of "credits" used for the current request (typically 1).Rate-Limit-Reset
- The number of seconds until the limit is reset again.
If the rate limit is hit, the API will respond with a 429 (Too Many Requests)
status code. In this situation, you will not be able to make a successful request to the API until the Rate-Limit-Reset
seconds have elapsed.
Exercise Program Library End-Points
Access hundreds of pre-designed exercise programs
PTLINKED has a growing library of hundreds of exercise programs for fitness and injury prevention as well as condition-specific exercise recommendations for each phase of the injury recovery process for over 150 surgical and non-surgical musculoskeletal conditions.
Each exercise program contains several pieces of metadata to help organize and allow users to find what they are looking for using various categories, filters, and search tags.
The following is a list of available exercise library end-points. The API is continuously being updated, so this list of end-points will grow over time.
End-Point Path | Method | Description |
---|---|---|
/predesigned/bodyregions/ | GET | Queries the server for a list of Body Regions/Categories. |
/predesigned/filters/ | GET | Queries the server for a list of available library filters. |
/predesigned/autocomplete/ | GET | Queries the server for a list of predictive search queries the user may be trying to search for. |
/predesigned/ | GET | Queries the server for a list of exercise program objects. |
Exercise Program Body Regions/Categories
Request a list of body regions/categories from the server
This end-point will request a list of available body regions and categories that PTLINKED uses to group the exercise programs in the library. If your integration includes custom categories, these will also be returned.
URI
GET /predesigned/bodyregions/{return_type}
FORMAT
JSON
HTTP METHOD
GET
AUTHENTICATION
token-authorization-x: {API KEY}
HEADER PARAMS
token-uid-x: {UNIQUE USER ID}
token-utype-x: {USER TYPE}
PARAMETERS
Parameter | Type | Description |
---|---|---|
{return_type} | String (raw | html) | This parameter will dictate what form the body region/categories are returned as. RAW will return the data as an array of JSON objects. HTML will return the data as formatted HTML unordered list. |
RESPONSE BODY
Key | Type | Description |
---|---|---|
oid | Unsigned Integer | This is the object identifier for each body region/category. This value is used to reference the element for other API requests. |
title | String | The name of the body region/category. |
order | Unsigned Integer | The recommended display order for the element. |
Example Request
$.ajax({
type: "GET",
url: api_uri_root + "/predesigned/bodyregions/raw",
crossDomain: true,
headers: { 'token-authorization-x': options["api_key"], 'token-uid-x': options["user_uid"], 'token-utype-x': options["user_type"] },
dataType: "json",
error: function( jqXHR, textStatus, errorThrown ) {
},
success: function( data, textStatus, jqXHR ) {
}
});
Example Response
[
{
"oid" : "1",
"title" : "Abdominal",
"order" : "1"
},
{
"oid" : "2",
"title" : "Ankle",
"order" : "2"
},
{
"oid" : "3",
"title" : "Calf",
"order" : "3"
},
{
"oid" : "4",
"title" : "Chest",
"order" : "4"
},
]
Exercise Program Filters
Request a list of available exercise program filters
This end-point will request a list of available filters that PTLINKED uses to group the exercise programs in the library. There are five (5) groups of filters: Condition, Equipment, Type, Difficulty, and Duration.
URI
GET /predesigned/filters/{return_type}
FORMAT
JSON
HTTP METHOD
GET
AUTHENTICATION
token-authorization-x: {API KEY}
HEADER PARAMS
token-uid-x: {UNIQUE USER ID}
token-utype-x: {USER TYPE}
PARAMETERS
Parameter | Type | Description |
---|---|---|
{return_type} | String (raw | html) | This parameter will dictate what form the filters are returned as. RAW will return the data as an array of JSON objects. HTML will return the data as formatted HTML unordered list. |
RESPONSE BODY
Key | Type | Description |
---|---|---|
oid | Unsigned Integer | This is the object identifier for each item. This value is used to reference the element for other API requests. |
title | String | The name of the filter item. |
order | Unsigned Integer | The recommended display order for the element. |
Example Request
$.ajax({
type: "GET",
url: api_uri_root + "/predesigned/filters/raw",
crossDomain: true,
headers: { 'token-authorization-x': options["api_key"], 'token-uid-x': options["user_uid"], 'token-utype-x': options["user_type"] },
dataType: "json",
error: function( jqXHR, textStatus, errorThrown ) {
},
success: function( data, textStatus, jqXHR ) {
}
});
Example Response
[
"conditions" : [
{
"oid" : "1",
"title" : "Abdominal Strain",
"order" : "1"
},
{
"oid" : "2",
"title" : "AC Joint Sprain / Separation",
"order" : "2"
},
{
"oid" : "3",
"title" : "AC Joint Surgery",
"order" : "3"
},
{
"oid" : "4",
"title" : "Achilles Tendon Repair",
"order" : "4"
}
],
"equipment": [
{
"oid" : "1",
"title" : "None",
"order" : "1"
},
{
"oid" : "2",
"title" : "Home Equipment",
"order" : "2"
},
{
"oid" : "3",
"title" : "Machines / Gym",
"order" : "3"
}
]
]
Autocomplete
Request a list predictive search queries based on what the user has entered.
This end-point will provide a list of predictive search queries based on what the user has entered into a search field. For example, if a user types "Knee" this end-point will return a list of search queries (which have been previously searched for) that are relevant to "knee" (i.e. "Knee Replacement Surgery").
URI
GET /predesigned/autocomplete/?term={user_entered_search_term}
FORMAT
JSON
HTTP METHOD
GET
AUTHENTICATION
token-authorization-x: {API KEY}
HEADER PARAMS
token-uid-x: {UNIQUE USER ID}
token-utype-x: {USER TYPE}
PARAMETERS
Parameter | Type | Description |
---|---|---|
term | String | This parameter is passed as a URL parameter (i.e. ?term={value} ). |
RESPONSE BODY
Key | Type | Description |
---|---|---|
oid | Unsigned Integer | This is the object identifier for each item. This value is used to reference the element for other API requests. |
value | String | A predictive string that has been searched for in the past, but is relevant to the term the user has entered. |
Example Request
$.ajax({
type: "GET",
url: api_uri_root + "/predesigned/autocomplete?term=knee",
crossDomain: true,
headers: { 'token-authorization-x': options["api_key"], 'token-uid-x': options["user_uid"], 'token-utype-x': options["user_type"] },
dataType: "json",
error: function( jqXHR, textStatus, errorThrown ) {
},
success: function( data, textStatus, jqXHR ) {
}
});
Example Response
[
{
"oid" : "1",
"value" : "Total Knee Replacement",
},
{
"oid" : "2",
"value" : "Patello-Femoral Knee Pain",
},
{
"oid" : "3",
"value" : "Stretching the Knee",
},
{
"oid" : "4",
"value" : "Knee Strengthening Exercises",
}
]
Search
Use the search engine to find the right exercise programs
The PTLINKED search API end-point utilizes a search algorithm that takes advantage of natural English queries, filters, tags, and popularity to produce search results that will ensure high quality and relevant exercise programs are returned.
URI
GET /predesigned/
FORMAT
JSON
HTTP METHOD
GET
AUTHENTICATION
token-authorization-x: {API KEY}
HEADER PARAMS
token-uid-x: {UNIQUE USER ID}
token-utype-x: {USER TYPE}
PARAMETERS
Parameter | Type | Description |
---|---|---|
v | String | Textual search query. |
c | Integer | The selected category ID. |
f1 | Integer | The exercise program type filter. |
f2 | Integer | The exercise program difficulty filter. |
f3 | Integer | The exercise program duration filter. |
f4 | Integer | The exercise program condition filter. |
f5 | Integer | The exercise program equipment filter. |
i | Integer | The current search results starting index. |
m | Integer | The total number of results to return. |
RESPONSE BODY
Key | Type | Description |
---|---|---|
predesigned_program_id | Unsigned Integer | This is the object identifier for each item. This value is used to reference the element for other API requests. |
exercise_program_id | Unsigned Integer | The unique identifier for the exercise program object. |
title | String | The title of the exercise program. |
description | String | A brief description of the exercise program. |
views | Integer | An active count of how many times the exercise program has been viewed. |
likes | Integer | The number of times a user has "liked" this exercise program. |
num_exercises | Integer | The number of exercises in this exercise program. |
selected_thumbnail | String | The thumbnail that was selected to visually represent this exercise program. |
card_image | String | The complete URL to the exercise image that is displayed on the exercise program card. |
card_video | String | The complete URL to the SD video version of the selected exercise used to represent the exercise program. |
Example Request
$.ajax({
type: "GET",
url: api_uri_root + "/predesigned/?c=1&f1=0&f2=0&f3=0$f4=0$f5=0&i=0&m=5",
crossDomain: true,
headers: { 'token-authorization-x': options["api_key"], 'token-uid-x': options["user_uid"], 'token-utype-x': options["user_type"] },
dataType: "json",
error: function( jqXHR, textStatus, errorThrown ) {
},
success: function( data, textStatus, jqXHR ) {
}
});
Example Response
[
{
"predesigned_program_id" : "1",
"exercise_program_id" : "2",
"title" : "Exercises to Manage Low Back Pain",
"description" : "Walking regularly, combined with some simple stretching and strengthening exercises will certainly help improve the health of your low back. Do not perform exercises that increase pain.",
"views": "147",
"likes": "78",
num_exercises: "7",
"selected_thumbnail": "0037_FC_R_SD_W.png",
"card_image": "https://86562b62996fa2a503ce-846bc247abc74e9a3c74db9bd9092660.ssl.cf2.rackcdn.com/images/IMAGES-ICO-W/0037_FC_R_SD_W.png",
"card_video": "https://86562b62996fa2a503ce-846bc247abc74e9a3c74db9bd9092660.ssl.cf2.rackcdn.com/videos/MP4-SD-WHITE/0037_FC_R_SD_W.mp4"
}
]
Exercise Program End-Points
Access thousands of exercises and supporting Content
Over the past 15 years, PTLINKED’s team has built a robust library of over 3000 exercise animations. Each exercise object contains several pieces of supportive content including textual technique reminders and various media elements. An exercise program is composed of an array of exercise objects, typically used to display a complete exercise program to the end-user.
The following is a list of available exercise program object end-points. The API is continuously being updated, so this list of end-points will grow over time.
End-Point Path | Method | Description |
---|---|---|
/exerciseprogram/resolve_name/ | GET | Each exercise program in the PTLINKED library is linked to a human-readable vanity URL. This end-point will resolve the vanity URL to the appropriate exercise program. |
/exerciseprogram/resolve_code/ | GET | Each exercise program is also linked to a unique alpha-numeric code. These codes are a shorthand way of providing a direct link to an exercise program. |
/exerciseprogram/print/ | GET | PTLINKED has developed a print system that will generate a clean, easy to understand printed handout of the exercise program. This end-point will request the PDF for the specified exercise program. |
/exerciseprogram/ | GET | This end-point will return all the data and media for an exercise program. |
Resolve Exercise Program Vanity URL
How to load an exercise program by its vanity URL
This end-point will resolve an exercise programs vanity URL instead of using just the exercise programs unique numerical identifier.
URI
GET /exerciseprogram/resolve_name/{exercise_program_name}
FORMAT
JSON
HTTP METHOD
GET
AUTHENTICATION
token-authorization-x: {API KEY}
HEADER PARAMS
token-uid-x: {UNIQUE USER ID}
token-utype-x: {USER TYPE}
PARAMETERS
Parameter | Type | Description |
---|---|---|
exercise_program_name | String | This is the vanity URL that represents this exercise program. |
RESPONSE BODY
Key | Type | Description |
---|---|---|
id | Unsigned Integer | This is the exercise program unique identifier. This value is used to reference the element for other API requests. |
Example Request
$.ajax({
type: "GET",
url: api_uri_root + "/exerciseprogram/resolve_name/exercises-to-manage-low-back-pain",
crossDomain: true,
headers: { 'token-authorization-x': options["api_key"], 'token-uid-x': options["user_uid"], 'token-utype-x': options["user_type"] },
dataType: "json",
error: function( jqXHR, textStatus, errorThrown ) {
},
success: function( data, textStatus, jqXHR ) {
}
});
Example Response
[
{
"id" : "1"
}
]
Resolve Exercise Program Code
How to load an exercise program by its unique code
This end-point will resolve an exercise programs Code instead of using just the exercise programs unique numerical identifier.
URI
GET /exerciseprogram/resolve_code/{exercise_program_code}
FORMAT
JSON
HTTP METHOD
GET
AUTHENTICATION
token-authorization-x: {API KEY}
HEADER PARAMS
token-uid-x: {UNIQUE USER ID}
token-utype-x: {USER TYPE}
PARAMETERS
Parameter | Type | Description |
---|---|---|
exercise_program_code | String | This is the alpha-numeric code that represents this exercise program. |
RESPONSE BODY
Key | Type | Description |
---|---|---|
id | Unsigned Integer | This is the exercise program unique identifier. This value is used to reference the element for other API requests. |
Example Request
$.ajax({
type: "GET",
url: api_uri_root + "/exerciseprogram/resolve_code/QDG081",
crossDomain: true,
headers: { 'token-authorization-x': options["api_key"], 'token-uid-x': options["user_uid"], 'token-utype-x': options["user_type"] },
dataType: "json",
error: function( jqXHR, textStatus, errorThrown ) {
},
success: function( data, textStatus, jqXHR ) {
}
});
Example Response
[
{
"id" : "1"
}
]
Print Exercise Program (PDF)
Generate a PDF handout for the exercise program
This end-point will generate a PDF handout, optimized for printing. The logo on the handout can be customized upon request.
URI
GET /exerciseprogram/print/{exercise_program_id}
FORMAT
JSON
HTTP METHOD
GET
AUTHENTICATION
token-authorization-x: {API KEY}
HEADER PARAMS
token-uid-x: {UNIQUE USER ID}
token-utype-x: {USER TYPE}
PARAMETERS
Parameter | Type | Description |
---|---|---|
exercise_program_id | Unsigned Integer | This is the unique identifier that represents this exercise program. |
RESPONSE BODY
Key | Type | Description |
---|---|---|
id | Unsigned Integer | This is the exercise program unique identifier. This value is used to reference the element for other API requests. |
Example Request
$.ajax({
type: "GET",
url: api_uri_root + "/exerciseprogram/print/1",
crossDomain: true,
headers: { 'token-authorization-x': options["api_key"], 'token-uid-x': options["user_uid"], 'token-utype-x': options["user_type"] },
dataType: "json",
error: function( jqXHR, textStatus, errorThrown ) {
},
success: function( data, textStatus, jqXHR ) {
}
});
Example Response
[
{
"pdf_filename" : "PTLINKED--Exercise_Program.pdf"
}
]
Load Exercise Program
Load an exercise program to display to the end-user
This end-point will request all the required data for an exercise program to display to the end-user.
URI
GET /predesigned/print/{exercise_program_id}
FORMAT
JSON
HTTP METHOD
GET
AUTHENTICATION
token-authorization-x: {API KEY}
HEADER PARAMS
token-uid-x: {UNIQUE USER ID}
token-utype-x: {USER TYPE}
token-videobg-x: {VIDEO BG VERSION}
PARAMETERS
Parameter | Type | Description |
---|---|---|
exercise_program_id | Unsigned Integer | This is the unique identifier that represents this exercise program. |
RESPONSE BODY (Exercise Program)
Key | Type | Description |
---|---|---|
exercise_program_id | Unsigned Integer | This is the exercise program unique identifier. This value is used to reference the element for other API requests. |
program_title | String | The title of the exercise program being requested. |
program_description | String | A brief description of the exercise program. |
code | String | An alpha-numeric code that represents the exercise program. |
views | Integer | The number of times this exercise program has been viewed. |
likes | Integer | The number of times this exercise program has been liked. |
dislikes | Integer | The number of times this exercise program has been disliked. |
num_exercises | Integer | The number of exercises that make up this exercise program. |
exercises | Array | An array of exercise objects that make up the exercise program. |
RESPONSE BODY (Exercise Object)
Key | Type | Description |
---|---|---|
oid | Unsigned Integer | This is the exercise unique identifier for this exercise program. This value is used to reference the element for other API requests. |
asset_number | Unsigned Integer | This is the exercise unique identifier for the entire library. This value is used to reference the element for other API requests. |
title | String | The title of the exercise. |
media_prefix | String | The filename prefix for all of this exercises media files. |
orientation | String | The orientation (Right side vs Left side) of the exercise in this exercise program. |
instructions | Integer | Technical instructions on how to perform the exercise correctly. |
parameters | Array | An array of exercise parameter objects that define the exercises parameters (sets, reps, etc.). |
RESPONSE BODY (Parameter Object)
Key | Type | Description |
---|---|---|
id | Unsigned Integer | This is the exercise parameter set unique identifier for this exercise program. This value is used to reference the element for other API requests. |
label | Unsigned Integer | The label/title of the parameter. |
input_mask | String | The input field mask to ensure proper formatting of the values entered. |
suffix | String | The suffix of the parameter, added into the input field (i.e. sec, min, x) |
alt_input_mask | String | An alternate input mask for the parameter (used only if the parameter has alternate units). |
alt_suffix | Integer | An alternate suffix for the parameter (used only if the parameter has alternate units). |
has_alt | Boolean | A flag indicating if the parameter has alternate units. |
width | Integer | The suggested width (in pixels) that the input field should be. |
value | String | The default value for the parameter. |
use_alt | Boolean | A flag indicating if the parameter should use the alternate units instead of the default. |
Example Request
$.ajax({
type: "GET",
url: api_uri_root + "/exerciseprogram/1",
crossDomain: true,
headers: { 'token-authorization-x': options["api_key"], 'token-uid-x': options["user_uid"], 'token-utype-x': options["user_type"], 'token-videobg-x': options["video_bg"] },
dataType: "json",
error: function( jqXHR, textStatus, errorThrown ) {
},
success: function( data, textStatus, jqXHR ) {
}
});
Example Response
[
"exercise_program_id": "1",
"program_title": "Exercises to Manage Low Back Pain",
"program_description": "Walking regularly, combined with some simple stretching and strengthening exercises will certainly help improve the health of your low back. Do not perform exercises that increase pain.",
"code": "QDG081",
"views": "147",
"likes": "75",
"dislikes": "10",
"num_exercises": "7",
"exercises":
{
"oid": "4565",
"asset_number": "53",
"title": Prone Press Ups",
"media_prefix": "0053_FC_S_",
"orientation": "0",
"instructions": "Lie on your stomach with your hands positioned below your shoulders. Look up toward the ceiling and push your torso upwards by extending your arms. Maintain your pelvis in contact with the floor. Perform an abdominal sag at the top to increase the intensity. Hold the recommended time at end range, then slowly lower to complete each repetition.",
"parameters":
{
"id": "1",
"label": "Repeat",
"input_mask": "z?zzzz",
"suffix": "x",
"alt_input_mask": "",
"alt_suffix": "",
"has_alt": "",
"width": "100",
"value": "10-15",
"use_alt": ""
},
{
"id": "2",
"label": "Hold",
"input_mask": "z?zzzz",
"suffix": "sec",
"alt_input_mask": "z?zzzz",
"alt_suffix": "min",
"has_alt": "true",
"width": "100",
"value": "3",
"use_alt": "false"
},
},
{
"oid": "4566",
"asset_number": "37",
"title": Single Knee to Chest",
"media_prefix": "0037_FC_R_",
"orientation": "1",
"instructions": "Lie on your back with your legs straight. Pull a single knee to your chest. Hold the recommended time at end range, then slowly release stretch.",
"parameters":
{
"id": "1",
"label": "Repeat",
"input_mask": "z?zzzz",
"suffix": "x",
"alt_input_mask": "",
"alt_suffix": "",
"has_alt": "",
"width": "100",
"value": "10-15",
"use_alt": ""
},
{
"id": "2",
"label": "Hold",
"input_mask": "z?zzzz",
"suffix": "sec",
"alt_input_mask": "z?zzzz",
"alt_suffix": "min",
"has_alt": "true",
"width": "100",
"value": "3",
"use_alt": "false"
},
},
]
User Specific End-Points
Add user specific functionality to your apps
These end-points are not available to everyone. When used, these end-points allow you to provide additional user specific functionality to your applications. Users can save their favorite exercise programs in their own My Favorites folder. Additional features and functionality will be added in future versions of the API.
End-Point Path | Method | Description |
---|---|---|
/users/register_plugin/ | POST | This end-point is used to register a user with the PTLINKED system. If the user already exists, it will simply ensure the data is accurate. A unique user identifier must be supplied (identifier can be anything as long as its unique from other user identifiers within your organization). |
/users/save_favorite/ | POST | This end-point is used to save an exercise program to a users My Favorites folder. |
/users/remove_favorite/ | POST | When a user wants to remove an exercise program from their "My Favorites" folder, this is the end-point that will accomplish it. |
Register a User with PTLINKED
Enhance your applications by providing user specific functionality
This end-point attempt to register the user with the PTLINKED system. This is accomplished by registering a unique identifier for the user in the PTLINKED database. No personal or identifying data is required or stored by PTLINKED.
URI
POST /users/register_plugin/
FORMAT
JSON
HTTP METHOD
POST
AUTHENTICATION
token-authorization-x: {API KEY}
HEADER PARAMS
token-uid-x: {UNIQUE USER ID}
token-utype-x: {USER TYPE}
PARAMETERS
Parameter | Type | Description |
---|---|---|
user_id | Unsigned Integer | This is the unique identifier that represents the user. The ID must be unique to any other user within your organization. |
RESPONSE BODY
Key | Type | Description |
---|---|---|
Status Code | String | The end-point will respond with either "success" or "failed". |
Example Request
$.ajax({
type: "POST",
url: api_uri_root + "/users/register_plugin/",
crossDomain: true,
headers: { 'token-authorization-x': options["api_key"], 'token-uid-x': options["user_uid"], 'token-utype-x': options["user_type"] },
dataType: "json",
error: function( jqXHR, textStatus, errorThrown ) {
},
success: function( data, textStatus, jqXHR ) {
}
});
Example Response
[
"success"
]
Saved Exercise Program as a Favorite
Enhance your users experience by allowing them to save their favorite programs
This end-point will save the specified exercise program to the specified users My Favorites folder for quick and easy access in the future.
URI
POST /users/save_favorite/
FORMAT
JSON
HTTP METHOD
POST
AUTHENTICATION
token-authorization-x: {API KEY}
HEADER PARAMS
token-uid-x: {UNIQUE USER ID}
token-utype-x: {USER TYPE}
PARAMETERS
Parameter | Type | Description |
---|---|---|
exercise_program_id | Unsigned Integer | This is the unique identifier that represents the exercise program that will be saved to the users My Favorites folder. |
RESPONSE BODY
Key | Type | Description |
---|---|---|
Status Code | String | The end-point will respond with either "success" or "failed". |
Example Request
$.ajax({
type: "POST",
url: api_uri_root + "/users/save_favorite/",
data: { "exercise_program_id": "53" },
crossDomain: true,
headers: { 'token-authorization-x': options["api_key"], 'token-uid-x': options["user_uid"], 'token-utype-x': options["user_type"] },
dataType: "json",
error: function( jqXHR, textStatus, errorThrown ) {
},
success: function( data, textStatus, jqXHR ) {
}
});
Example Response
[
"success"
]
Remove Exercise Program from My Favorites
Enhance your users experience by allowing them to remove a favorite program
This end-point will remove the specified exercise program from the specified users My Favorites folder.
URI
POST /users/remove_favorite/
FORMAT
JSON
HTTP METHOD
POST
AUTHENTICATION
token-authorization-x: {API KEY}
HEADER PARAMS
token-uid-x: {UNIQUE USER ID}
token-utype-x: {USER TYPE}
PARAMETERS
Parameter | Type | Description |
---|---|---|
exercise_program_id | Unsigned Integer | This is the unique identifier that represents the exercise program that will be removed from the users My Favorites folder. |
RESPONSE BODY
Key | Type | Description |
---|---|---|
Status Code | String | The end-point will respond with either "success" or "failed". |
Example Request
$.ajax({
type: "POST",
url: api_uri_root + "/users/remove_favorite/",
data: { "exercise_program_id": "53" },
crossDomain: true,
headers: { 'token-authorization-x': options["api_key"], 'token-uid-x': options["user_uid"], 'token-utype-x': options["user_type"] },
dataType: "json",
error: function( jqXHR, textStatus, errorThrown ) {
},
success: function( data, textStatus, jqXHR ) {
}
});
Example Response
[
"success"
]
Analytics and Reporting
Track how your users are using PTLINKED
These end-points are not available to everyone. When used, these end-points allow you to pull various analytics based on your integration setup.
End-Point Path | Method | Description |
---|---|---|
/metrics/summary/ | GET | This end-point will query the PTLINKED system and provide a high level summary of the API usage specific to your integration/apps. |
/metrics/users/ | GET | If you are using the user specific API features, this end-point will produce usage data for your users. |
/metrics/programs/ | GET | This end-point will query the PTLINKED system and return the analytics for each exercise program you are accessing from the API. |
Usage Summary
View high level analytics summary of the PTLINKED API usage
This end-point will query the PTLINKED system, specific to your integration/application and return a high level set of metrics between the dates you provide.
URI
GET /metrics/summary/{start_date}/{end_date}
FORMAT
JSON
HTTP METHOD
GET
AUTHENTICATION
token-authorization-x: {API KEY}
PARAMETERS
Parameter | Type | Description |
---|---|---|
start_date | String | The starting date you want the analytics for. This must be in the formate of YYYY-MM-DD (ie. 2021-01-21). If omitted, the start date will be set to the "beginning of time". |
end_date | String | The ending date you want the analytics for. This must be in the formate of YYYY-MM-DD (ie. 2021-01-21). If omitted, the end date will be set for the current date. |
RESPONSE BODY
Key | Type | Description |
---|---|---|
num_active_users | Integer | The number for active users (if applicable) between the start and end date. |
num_active_physicians | Integer | The number for active users (if applicable) identified as "Physician" between the start and end date. |
num_active_patients | Integer | The number for active users (if applicable) identified as "Patient" between the start and end date. |
num_active_other | Integer | The number for active users (if applicable) identified as something other than "Physician" or "Patient" between the start and end date. |
num_viewed_programs | Integer | The number of exercise programs viewed between the start and end date. |
num_saved_programs | Integer | The number of exercise programs saved (favorited) by users between start and end date. |
num_printed_programs | Integer | The number of printed exercise programs between the start and end date. |
num_sent_programs | Integer | The number of exercises programs sent/shared between the start and end date. |
top_5_viewed_programs | Array | An array of the top 5 most viewed exercise programs between the start and end date. |
top_5_printed_programs | Array | An array of the top 5 most printed exercise programs between the start and end date. |
top_5_saved_programs | Array | An array of the top 5 most saved/favorited exercise programs between the start and end date. |
top_5_sent_programs | Array | An array of the top 5 most sent/shared exercise programs between the start and end date. |
Example Request
$.ajax({
type: "GET",
url: api_uri_root + "/metrics/summary/2020-01-01/2021-01-27",
crossDomain: true,
headers: { 'token-authorization-x': options["api_key"] },
dataType: "json",
error: function( jqXHR, textStatus, errorThrown ) {
},
success: function( data, textStatus, jqXHR ) {
}
});
Example Response
[
"num_active_users": "54",
"num_active_physicians": "22",
"num_active_patients": "25",
"num_active_other": "7",
"num_viewed_programs": "165",
"num_saved_programs": "54",
"num_printed_programs": "23",
"num_sent_programs": "12",
"top_5_viewed_programs":
[
{
"id": "1",
"title": "Exercises to Manage Low Back Pain",
"cnt": "34"
},
{
"id": "16",
"title": "An Upper Body Strengthening Workout for Home",
"cnt": "22"
}
],
"top_5_saved_programs":
[
{
"id": "1",
"title": "Exercises to Manage Low Back Pain",
"cnt": "5"
},
{
"id": "16",
"title": "An Upper Body Strengthening Workout for Home",
"cnt": "3"
}
],
"top_5_printed_programs":
[
{
"id": "7",
"title": "The Best Stretches for Tight IT Bands",
"cnt": "42"
},
{
"id": "22",
"title": "Thumb Strengthening Exercises with Elastic Resistance",
"cnt": "21"
}
],
"top_5_sent_programs":
[
{
"id": "7",
"title": "The Best Stretches for Tight IT Bands",
"cnt": "3"
},
{
"id": "22",
"title": "Thumb Strengthening Exercises with Elastic Resistance",
"cnt": "2"
}
]
]
User Usage Analytics
View user specific usage analytics
If you are utilizing the user end-points, this end-point will query the PTLINKED system specific to your integration/application and return the analytics for users between the dates you provide.
URI
GET /metrics/users/{user_type}/{start_date}/{end_date}
FORMAT
JSON
HTTP METHOD
GET
AUTHENTICATION
token-authorization-x: {API KEY}
PARAMETERS
Parameter | Type | Description |
---|---|---|
user_type | String | Use this optional parameter to pull analytics for a specific user group (i.e. Physicians vs. Patients). To query analytics for all users, simply set this parameter to ALL . |
start_date | String | The starting date you want the analytics for. This must be in the formate of YYYY-MM-DD (ie. 2021-01-21). If omitted, the start date will be set to the "beginning of time". |
end_date | String | The ending date you want the analytics for. This must be in the formate of YYYY-MM-DD (ie. 2021-01-21). If omitted, the end date will be set for the current date. |
RESPONSE BODY
Key | Type | Description |
---|---|---|
customer_uid | Integer | The users unique identifier. |
creation_date | String | The date the user was first registered with the PTLINKED API (Format: YYYY-MM-DD) |
metrics | Array | An array containing the metrics for the user calculated between start and end date. |
RESPONSE BODY (Metrics Array)
Key | Type | Description |
---|---|---|
views | Integer | How many exercise programs did the user view between the start and end dates. |
saves | Integer | How many exercise programs did the user save between the start and end dates. |
prints | Integer | How many exercise programs did the user print between the start and end dates. |
sends | Integer | How many exercise programs did the user send/share between the start and end dates. |
Example Request
$.ajax({
type: "GET",
url: api_uri_root + "/metrics/users/physicians/2020-01-01/2021-01-27",
crossDomain: true,
headers: { 'token-authorization-x': options["api_key"] },
dataType: "json",
error: function( jqXHR, textStatus, errorThrown ) {
},
success: function( data, textStatus, jqXHR ) {
}
});
Example Response
[
{
"customer_uid": "77125",
"creation_date": "2021-01-21",
"metrics":
[
"views": "123",
"saves": "23",
"prints": "6",
"sends": "14"
]
},
{
"customer_uid": "32677",
"creation_date": "2020-12-16",
"metrics":
[
"views": "453",
"saves": "123",
"prints": "64",
"sends": "11"
]
},
]
Exercise Program Analytics
View the analytics of exercise programs specific to your integration/app.
This end-point will return the exercise program analytics for all the exercise programs available for your company/organization.
URI
GET /metrics/programs/{start_date}/{end_date}
FORMAT
JSON
HTTP METHOD
GET
AUTHENTICATION
token-authorization-x: {API KEY}
PARAMETERS
Parameter | Type | Description |
---|---|---|
start_date | String | The starting date you want the analytics for. This must be in the formate of YYYY-MM-DD (ie. 2021-01-21). If omitted, the start date will be set to the "beginning of time". |
end_date | String | The ending date you want the analytics for. This must be in the formate of YYYY-MM-DD (ie. 2021-01-21). If omitted, the end date will be set for the current date. |
RESPONSE BODY
Key | Type | Description |
---|---|---|
program_title | String | The title of the exercise program. |
eid | Integer | The unique ID of the exercise program. |
impressions | Integer | The number of times the exercise program was displayed to a user from the API search end-point. |
views | Integer | The number of times the exercise program was opened and viewed by a user. |
prints | Integer | The number of times the exercise program was printed. |
saves | Integer | The number of times the exercise program was saved/favorited by a user. |
sends | Integer | The number of times the exercise program was sent/shared by a user. |
Example Request
$.ajax({
type: "GET",
url: api_uri_root + "/metrics/programs/2020-01-01/2021-01-27",
crossDomain: true,
headers: { 'token-authorization-x': options["api_key"] },
dataType: "json",
error: function( jqXHR, textStatus, errorThrown ) {
},
success: function( data, textStatus, jqXHR ) {
}
});
Example Response
[
{
"program_title": "Ankle Strengthening with Elastic Resistance",
"eid": "74",
"impressions": "3,123",
"views": "323",
"saves": "105",
"prints": "110",
"sends": "54"
},
{
"program_title": "My Abdominals are Tight - What Should I Do?",
"eid": "87",
"impressions": "4,123",
"views": "523",
"saves": "125",
"prints": "90",
"sends": "104"
},
...
]
Getting Started
Learn how to get started with using the PTLINKED API.
The PTLINKED API is a closed API service, meaning you will need authorization to access the documented API end-points. This section of the document will take you through the prerequisites and provide you with some simple examples to get you started.
Section | Description |
---|---|
Prerequisites | This section will outline what the prerequisites are for accessing the API end-points. |
Obtaining an API Key | This section will explain how you can obtain an API Key and get your domain registered with the PTLINKED system. |
Making a Request | In this section, we will guide you through making a request to a PTLINKED API end-point. |
Handling a Response | In this section, we will guide you through how to handle responses from the PTLINKED API. |
Prerequisites
What you need to start using the PTLINKED API.
In order to start using the PTLINKED API, you will need the following:
- Register Your Domain. - You will need to register the domain with PTLINKED that will be accessing the API. If you try to access the API, even with a valid API Key, the server will respond with
"403 Forbidden"
status code for unrecognized domains. - A valid API Key from PTLINKED. - Once your domain is registered with PTLINKED, a valid API Key will be generated and provided to you. This API Key will need to be sent in the request headers for every request to the API.
- cURL or jQuery. - A strong knowledge of cURL or jQuery (specifically how to make AJAX requests).
- JSON - You should be familiar with JSON, or be able to translate samples from JSON to the standard you use.
Obtaining an API Key
How to obtain an API Key to access the PTLINKED API.
Currently, the only way to obtain an API Key is for PTLINKED to provide you with one. This will automatically be done once your domain is registered with our system. Please use the form below to request access to the API. A PTLINKED representative will reach out to you to help get you started.
Request API Access
Making a Request
Learn how to make a request to the PTLINKED API.
Once your domain has been registered, and you have received your API Key, you can now begin to make requests to the API server. In the following examples, we will show you how to accomplish a successful request using jQuery AJAX.
jQuery AJAX Example
$.ajax({
type: "GET", // The method as outlined in the end-point documentation (GET, POST, PUT, DELETE, etc.)
url: api_uri_root + "/predesigned/bodyregions/raw", // The URI to the end-point you are requesting.
crossDomain: true, // Must be set to true to allow crossDomain requests
headers: { 'token-authorization-x': options["api_key"] }, // Set your API Key in the request header.
dataType: "json", // The type of data you are expecting back. Should always be JSON.
error: function( jqXHR, textStatus, errorThrown ) { // Callback function to handle any errors returned by the API
},
success: function( data, textStatus, jqXHR ) { // Callback function to handle a successful response back from the API
}
});
Handling a Response
Learn how to handle a response back from the PTLINKED API.
You should be able to make a successful API request from the previous section. In this section, we will demonstrate how to handle both an error and success response back from the API. Again, for this example we will be using jQuery AJAX like in the previous section.
jQuery AJAX Example
$.ajax({
type: "GET", // The method as outlined in the end-point documentation (GET, POST, PUT, DELETE, etc.)
url: api_uri_root + "/predesigned/bodyregions/raw", // The URI to the end-point you are requesting.
crossDomain: true, // Must be set to true to allow crossDomain requests
headers: { 'token-authorization-x': options["api_key"] }, // Set your API Key in the request header.
dataType: "json", // The type of data you are expecting back. Should always be JSON.
error: function( jqXHR, textStatus, errorThrown ) { // Callback function to handle any errors returned by the API
console.log( "::::: Register User AJAX :::::" ) ;
console.log( "Request Error or Timeout" ) ;
console.log( "Status Code: " + jqXHR["status"] ) ; // The status code returned by the API (i.e. 403 Forbidden)
console.log( "Status Msg: " + jqXHR["statusText"] ) ; // The status message returned by the API (i.e. You do not have permission to access this end-point)
console.log( "Response Msg: " + jqXHR["responseText"] ) ; // Additional explanation of the error
console.log( "::::: ===== ===== ===== ===== :::::" ) ;
},
success: function( data, textStatus, jqXHR ) { // Callback function to handle a successful response back from the API
if( status == 200 ) { // Request was successful and data has been returned
console.dir( data ) ; // Output the JSON encoded data to the console.
} else if( status == 201 ) { // Request was successful, but no data has been returned (i.e. requesting more records, but there aren't anymore).
console.log( "No data returned" ) ;
}
}
});