Information for developers wanting to use the TIA survey API

You MUST have an account before activating an API key. Please register if you have not already.

Registrations must be approved by TIA administrators, so please wait for approval before accessing the system.

Getting started using the TIA API

The TIA survey site is designed as a data collection effort by TIA. Each data collection effort is referred to as a "survey" for purposes of this website. Members are able to login and complete the survey online manually or utilize the API in order to allow their in-house software to automatically communicate the data back to the TIA survey system.

The API is a RESTful API designed to allow developers to implement the survey features found on this site into their own applications without having a significant amount of code or rework to add. Because it uses standardized HTTP access, any program that can access the internet should be able to submit data.

The API was developed using REST web services. This essentially means that the server will quietly wait to be contacted by a "client" before responding. The client program/server/computer contacts the TIA API through HTTP (web URLs) and sends both their authentication information and the request they would like. The server then responds in a predictable and documented way as below. The following information is provided so that you (the client) will know what you can ask for and how that information will be provided back to you via your program.


View the Getting Started Guide to complete your account setup and/or get an API key (with screenshots).


API Keys

To use any of the API functions you must provide a valid API Key with each request. Valid API keys can only be generated by active and approved users.

All API request are made over HTTP request. The data returned by calling these functions will be in JSON format.


HTTP Methods


This API exclusively uses GET and POST methods. Deleting and updating records are not necessary. Users can call these two methods by using HTTP request with the given parameters along with an api key. All available GET and POST methods are shown below.

Response codes

Since all methods calls are made by an HTTP request there will be associating status code generated with each request. A few of these include:

  • 200 - OK
  • 201 - CREATED | Data has been saved
  • 400 - BAD REQUEST | Returned if the request is invalid (i.e. invalid API call or parameters)
  • 401 - NOT AUTHORIZED | Returned primarily if the API key is invalid
  • 404 - NOT FOUND | Returned if the requested resources is not found (i.e. an incorrect survey is selected)

These status codes let the user know what actions their input has triggered in the system. As per REST specifications, a response code is always returned. If you are not receiving some sort of HTTP code, you have not made a successful connection to the system.

GET Functions

GET functions are queries where the client is asking for information but not accessing or entering data into the system.

/get/survey_list/(API_KEY)

Description Gets a list of surveys the current user is authorized to access
Response Lists names and descriptions of surveys that can be accessed
Called by Query
Member of GET
Data in Authorization (API) Key
JSON Response
        {
            "status" : "Returned list of surveys.",
            "data" : [
                {
                    "name" : "Surveyname1",
                    "ID" : "1",
                    "description" : "Description1."
                },
                {
                    "name" : "Surveyname2",
                    "ID" : "2",
                    "description" : "Description2."
                }
            ]
        }
HTTP Responses
Response code Additional Information
200 OK JSON List
401 Not Authorized None
404 Not Found No surveys are open to that user

Example Request

The below request is for demonstration purposes only. The components may differ (i.e. the base URL, API Key, etc.).

Request: https://tiasurvey.com/get/survey_list/DEMO-15205479412463-46ccfa91fdcf

Response: 

            {
                "status" : "Returned list of surveys.",
                "data" : [
                    {
                        "name" : "TIA Benchmarking Report",
                        "ID" : "30",
                        "description" : "The TIA Benchmarking Market Report is produced from monthly real operating data supplied by TIA members."
                    }
                ]
            }

NOTE: The integer value contained in the "ID" field (e.g. "30" in this case) is used to identify a particular survey you are trying to reference in various API request. The "ID" will be needed for the "surveyID" when you go to retrieve a list of fields for a particular survey (i.e. survey_fields). The "ID" value is also used to close (i.e. close_survey) a survey.The integer value contained in the "ID" field will also be needed for the "surveyID" when you go to make a submit request for a particular survey.

/get/survey_fields/(API_KEY)/(surveyID)

Description Given a survey ID, show the fields necessary to complete that collection.
Response Lists names, item codes, data types, descriptions, and required status of survey items to be submitted.
Called by Query
Member of GET
Data in Authorization (API) Key / (int) id of survey to lookup
JSON Response
        {
            "status" : "Returned list of survey fields.",
            "data" : [
                {
                    "name" : "Fieldname1",
                    "code" : "Fieldcode1",
                    "type" : "Date",
                    "description" : "A description of this field",
                    "required" : "Y"
                },
                {
                    "name" : "Fieldname2",
                    "code" : "Fieldcode2",
                    "type" : "Integer",
                    "description" : "A description of this field",
                    "required" : "Y"
                },
                {
                    "name" : "Fieldname3",
                    "code" : "Fieldcode3",
                    "type" : "Decimal",
                    "description" : "Description3",
                    "required" : "N"
                },
                {
                    "name" : "Fieldname4",
                    "code" : "Fieldcode4",
                    "type" : "Text",
                    "description" : "Description4",
                    "required" : "N"
                }
            ]
        }
HTTP Responses
Response code Additional Information
200 OK JSON List
401 Not Authorized None
404 Not Found Cannot find the requested survey
Definitions:

A type is returned with each field. This specifies the type of data that can be submitted to that field.

Type Definition Acceptable Value Examples Unacceptable Value Examples
Integer Integer value consisting of positive digits only from 0-9. No commas or punctuation. 35677 $12, -4, 5.6, or 4,356
Decimal Decimal values consisting of positive numbers only with a decimal point. No other symbols allowed. 8.642 or 8 5%, n/a, or $75.23
Date Date/time field using ISO 8601 formatting which is YYYY-MM-DDTHH:MM:SS-GMT_OFFSET. 2017-06-28T06:05:32-05:00 July 2, 2015 or 1/7/16 or 2017-08-01
Text Text value consisting of a sequence of characters "Hello World!" N/A

Example Request

The below request is for demonstration purposes only. The components may differ (i.e. the base URL, API Key, etc.).

Request: https://tiasurvey.com/get/survey_fields/DEMO-15205479412463-46ccfa91fdcf/30

Response: 

                {
                    "status" : "Returned list of survey fields.",
                    "data" : [
                        {
                            "name" : "Reporting Period Start",
                            "code" : "Reporting Period Start",
                            "type" : "Date",
                            "description" : "MM/DD/YYYY of START of reporting period",
                            "required" : "Y"
                        },
                        {
                            "name" : "Reporting Period End",
                            "code" : "Reporting Period End",
                            "type" : "Date",
                            "description" : "MM/DD/YYYY of END of reporting period",
                            "required" : "Y"
                        },
                        {
                            "name" : "Truck Load Billing Dollars - Van",
                            "code" : "TLVD",
                            "type" : "Integer",
                            "description" : "The sum of billings/invoices (revenue) to all customers for Van Truckload Over the road shipments during the applicable reporting period.",
                            "required" : "N"
                        },
                        {
                            "name" : "LTL Shipment Count",
                            "code" : "LTLC",
                            "type" : "Integer",
                            "description" : "The count of all LTL shipments during the applicable reporting period.",
                            "required" : "N"
                        },
                        {
                            "name" : "Rail Intermodal Shipment Count - 53ft",
                            "code" : "I53S",
                            "type" : "Integer",
                            "description" : "The count of all 53' intermodal shipments during the applicable reporting period.",
                            "required" : "N"
                        },
                        {
                            "name" : "Air Billing Dollars",
                            "code" : "AIRD",
                            "type" : "Decimal",
                            "description" : "The count of all air shipments during the applicable reporting period.",
                            "required" : "N"
                        }
                    ]
                }

NOTE: The text value contained in the "code" fields (e.g. "TLVD", "LTLC", "I53S", & "AIRD" in this case) will be needed for the "code" when you go to make a submit request for this particular survey. The "input" (i.e. the data you are submitting to a survey) values in the submit request will be mapped to the corresponding fields via the "code".

/get/token_expiry/(API_KEY)

Description Provides the user with a date/time of the expiration of their API key.
Response Date/Time of expiration of authentication information.
Called by Query
Member of GET
Data in Authorization (API) Key.
JSON Response
        {
            "status" : "Returned the expiration date for a valid token.",
            "data" : {
                "date" : "2018-07-14T15:00:03-05:00"
            }
        }
HTTP Responses
Response code Additional Information
200 OK Date/TimeStamp in ISO 8601 format
401 Not Authorized Your API key is invalid

Example Request

The below request is for demonstration purposes only. The components may differ (i.e. the base URL, API Key, etc.).

Request: https://tiasurvey.com/get/token_expiry/DEMO-15205479412463-46ccfa91fdcf

Response: 

                {
                    "status" : "Returned the expiration date for a valid token.",
                    "data" : {
                        "date" : "2018-07-14T15:00:03-05:00"
                    }
                }

NOTE: The "date" value is the date upon which your API Key will expire in ISO 8601 format.

/get/latest_closed_survey/(API_KEY)

Description Provides the user with information about the last survey they completed.
Response Date/Time and data submitted last.
Called by Query
Member of GET
Data in Authorization (API) Key.
JSON Response
        {
            "status" : "Returned the latest submission.",
            "data" : {
                    "timestamp" : "2017-07-28T08:30:44-05:00",
                    "survey" : "TIA Benchmarking Report",
                    "fields" : [
                    {
                        "name" : "Truck Load Billing Dollars - Van",
                        "code" : "TLVD",
                        "response" : "12594",
                        "received" : "2017-07-28T08:30:44-05:00"
                    },
                    {
                        "name" : "Truck Load Shipment Count - Van",
                        "code" : "TLVS",
                        "response" : "1000",
                        "timestamp" : "2017-07-28T08:30:44-05:00"
                    }
                ]
            }
        }
HTTP Responses
Response code Additional Information
200 OK JSON encoded response of submission specifics and responses
401 Not Authorized Your API key is invalid
404 Not Found No surveys have been submitted

Example Request

The below request is for demonstration purposes only. The components may differ (i.e. the base URL, API Key, etc.).

Request: https://tiasurvey.com/get/latest_closed_survey/DEMO-15205479412463-46ccfa91fdcf

Response: 

                {
                    "status" : "Returned the latest submission.",
                    "data" : {
                            "timestamp" : "2017-07-28T08:30:44-05:00",
                            "survey" : "TIA Benchmarking Report",
                            "fields" : [
                            {
                                "name" : "Truck Load Billing Dollars - Van",
                                "code" : "TLVD",
                                "response" : "12594",
                                "received" : "2017-07-28T08:30:44-05:00"
                            },
                            {
                                "name" : "Truck Load Shipment Count - Van",
                                "code" : "TLVS",
                                "response" : "1000",
                                "timestamp" : "2017-07-28T08:30:44-05:00"
                            }
                        ]
                    }
                }

NOTE: The "survey" field is the name of the latest closed survey for which the "fields" correspond to. The "response" field is the latest response (i.e. the latest value) for the field that you have submitted.

/get/submit_history/(API_KEY)

Description Provides the user with information about, at most, the last 3 submission that the user has made via the API. Submission history is to allow you, the user, the ability to view when and to what submission a particular response was submitted. During a reporting period you may submit to a survey as many times as you would like. However once a submission is closed that submission will no longer accept new data. Instead a new submission will be opened to receive data until it (the newly opened submission) has been closed.
Response Date/Time and data submitted last.
Called by Query
Member of GET
Data in Authorization (API) Key.
JSON Response
        {
            "status" : "Returned the submission history.",
            "data" : [
                {
                    "timestamp" : "2017-07-28T08:30:44-05:00",
                    "survey" : "My Survey 1",
                    "fields" : [
                        {
                            "name" : "Truck Load Shipment Count - Van",
                            "code" : "TLVS",
                            "response" : "8",
                            "received" : "2017-07-28T08:30:44-05:00"
                        },
                        {
                            "name" : "Truck Load Miles - Van",
                            "code" : "TLVM",
                            "response" : "844444",
                            "received" : "2017-07-28T08:30:44-05:00"
                        }
                    ]
                },
                {
                    "timestamp" : "2017-06-28T06:05:32-05:00",
                    "name" : "Example Survey",
                    "fields" : [
                        {
                            "name" : "Survey Field Example 1",
                            "code" : "SFE1",
                            "response" : "Our response goes here",
                            "received" : "2017-07-28T08:30:44-05:00"
                        },
                        {
                            "name" : "Question 2",
                            "code" : "EX2",
                            "response" : "Response 2",
                            "received" : "2017-07-28T08:30:44-05:00"
                        }
                    ]
                },
                {
                    "timestamp" : "2017-05-01T12:14:04-05:00",
                    "name" : "My Survey 1",
                    "fields" : [
                        {
                            "name" : "Truck Load Profit Margin - Van",
                            "code" : "TLVPM",
                            "response" : "12",
                            "received" : "2017-07-28T08:30:44-05:00"
                        },
                        {
                            "name" : "Truck Load Miles - Van",
                            "code" : "TLVM",
                            "response" : "123",
                            "received" : "2017-07-28T08:30:44-05:00"
                        }
                    ]
                }
            ]
        }
HTTP Responses
Response code Additional Information
200 OK JSON encoded response of submission specifics and responses
401 Not Authorized Your key is invalid or you are not authorized for any surveys
404 Not Found No surveys have been submitted

Example Request

The below request is for demonstration purposes only. The components may differ (i.e. the base URL, API Key, etc.).

Request: https://tiasurvey.com/get/submit_history/DEMO-15205479412463-46ccfa91fdcf

Response: 

                {
                    "status" : "Returned the latest submission.",
                    "data" : {
                            "timestamp" : "2017-07-28T08:30:44-05:00",
                            "survey" : "TIA Benchmarking Report",
                            "fields" : [
                            {
                                "name" : "Truck Load Billing Dollars - Van",
                                "code" : "TLVD",
                                "response" : "12594",
                                "received" : "2017-07-28T08:30:44-05:00"
                            },
                            {
                                "name" : "Truck Load Shipment Count - Van",
                                "code" : "TLVS",
                                "response" : "1000",
                                "timestamp" : "2017-07-28T08:30:44-05:00"
                            }
                        ]
                    }
                }

NOTE: The "survey" field is the name of the survey for which the following "fields" list correspond to. submit_history returns, at most, the last 3 submits. If you have not made any submits then only the "status" field with the message "There are no submissions for your account." will be returned.

/get/open_survey/(API_KEY)/(surveyID)

Description Provides the survey answers that have been submitted so far, on the open survey.
Response All survey fields that have been submitted for the open survey.
Called by Query
Member of GET
Data in Authorization (API) Key / (int) id of survey to lookup
JSON Response
        {
            "status" : "Returned responses for currently open survey.",
            "data" : {
                {
                    "timestamp": "2017-07-28T12:32:16-05:00",
                    "code" : "QUESTION1",
                    "response" : "23465"
                },
                {
                    "timestamp" : "2017-07-28T12:32:16-05:00",
                    "code" : "EXAMPLE2",
                    "response" : "Response to Example 2"
                }
            }
        }
HTTP Responses
Response code Additional Information
200 OK JSON encoded response of submission specifics and responses
401 Not Authorized Your key is invalid or you are not authorized for any surveys
404 Not Found No fields have been submitted for this open survey

Example Request

The below request is for demonstration purposes only. The components may differ (i.e. the base URL, API Key, etc.).

Request: https://tiasurvey.com/get/open_survey/DEMO-15205479412463-46ccfa91fdcf/30

Response: 

                {
                    "status" : "Returned responses for currently open survey.",
                    "data" : {
                        {
                            "timestamp": "2017-07-28T12:32:16-05:00",
                            "code" : "TLVD",
                            "response" : "23465"
                        },
                        {
                            "timestamp" : "2017-07-28T12:32:16-05:00",
                            "code" : "TLVS",
                            "response" : "20"
                        }
                    }
                }

NOTE: The response is the currently open survey with the current "response" values contained in the "data" section for the particular fields (i.e. the "code"). This request requires a "surveyID" that can be retrieved from the survey_list GET function call. The "timestamp" is the time at which the response was received in ISO 8601 format (i.e. the last response you submitted for the field).

POST Functions

POST functions are used when submitting data to the system. The data, when received, is recorded in the appropriate database.

/post/submit/(API_KEY)

Description Submits survey question responses in a JSON string. It requires that you submit the ID of a survey for which you want to submit data. This will open a new survey submission OR submit to an already open survey submission. You can submit data as often as you like to a survey submission and new data will automatically overwrite old fields. Surveys should be closed when all data has been submitted. During a reporting period you may submit to a survey as many times as you would like.
Response 201 Data Received
Called by Query
Member of POST
Data in

surveyID (int) - id of survey you want to submit
{"surveyID":100}

data (object) - JSON object containing the field code and the response to that field. Applicable data includes name,value pairs of the "code" for the field and the "input" for the response.
"data": [ {"code":"Field1","input":155}, {"code":"Field2","input":"My Input for Field2"} ]

Data In

(HTTP 201 Created): Data format is very strict. Any formatting problems will cause the submission to fail. Formatting problems include trailing or leading whitespace, inappropriate symbols, including negative integers, invalid date format, etc. Below is an example of a valid JSON data string. NOTE: The example below is for demonstration purposes only, prior to formatting a JSON string a User should retrieve a list of survey fields for a given survey and format the data appropriately. 

        {
            "surveyID" : "30",
            "data" : [
                {
                    "code" : "TLVS",
                    "input" : "15"
                },
                {
                    "code" : "TLVD",
                    "input" : "10000"
                },
                {
                    "code" : "TLVM",
                    "input" : "2004-02-12T15:19:21+00:00"
                },
                {
                    "code" : "TLFD",
                    "input" : "5.25"
                },
                {
                    "code" : "TLVPM",
                    "input" : "600"
                },
                {
                    "code" : "WSPM",
                    "input" : "1000"
                }
            ]
        }
JSON Response
        {
            "status" : "Save Successful"
        }
JSON Response (if there is an error in submission)

(HTTP 400 Error): Data format is very strict. Any formatting problems will cause the submission to fail. Formatting problems include trailing or leading whitespace, inappropriate symbols, including negative integers, invalid date format, etc. The API will send back an HTTP 400 error with a JSON object outlining the problematic fields. No data will be saved until these issues are resolved. 

        {
            "status" : "8 errors occurred in your submission.",
            "data" : [
                "Improper format, expected a positive Integer.",
                {
                    "code" : "TLVS",
                    "input" : "-15"
                },
                "Improper format, expected a positive Integer.",
                {
                    "code" : "TLVD",
                    "input" : "$10000"
                },
                "Improper format, expected a positive Integer.",
                {
                    "code" : "TLVS",
                    "input" : "222$2222"
                },
                "Improper 'date' format, expected ISO 8601 format.",
                {
                    "code" : "TLFM",
                    "input" : "2004-02-12T115:19:21+00:00"
                },
                "Improper format, expected a positive real number.",
                {
                    "code" : "TLFD",
                    "input" : "-5"
                },
                "Improper format, expected a positive real number.",
                {
                    "code" : "TLFD",
                    "input" : "-4"
                },
                "The Survey code Does Not Exist in this survey.",
                {
                    "code" : "some text",
                    "input" : "6"
                },
                "The Survey code Does Not Exist in this survey.",
                {
                    "code" : "invalid",
                    "input" : "0"
                }
            ]
        }
HTTP Responses
Response code Additional Information
201 Created Save successful
400 Bad request There is a problem with the data you submitted
401 Not Authorized API key is invalid or you do not have permissions to submit for that survey
404 Not Found The survey ID you submitted is not valid

Example Request

The below request is for demonstration purposes only. The components may differ (i.e. the base URL, API Key, etc.).

Request: https://tiasurvey.com/post/submit/DEMO_APIKey-15aaf45ab35349b9f-0eb345340f97
Post Data (example): {"surveyID":"100","data":[{"code":"TLFD","input":"10.5"},{"code":"TLVS","input":"50"}]}

Response: 

                {
                    "status" : "Save Successful"
                }

NOTE: The "status" field is the lone return field that indicates the success/failure of the post request. The "surveyID" and "code" fields to build your JSON post data with are retrievable from the aforementioned survey_list and survey_fields GET functions.

/post/close_survey/(API_KEY)/(surveyID)

Description Given a survey ID, this will close the last/latest open progress. For example when the user has filled in all of the information and is ready to complete and finalize that survey submission. Note, you cannot submit additional data for a survey that has been closed.
NOTE: Some data maybe required for a given survey. If data is not submitted to required fields then a response containing all of the required fields will be returned and the survey will not be closed. You will have to submit to all required fields before being able to close a survey.
Response 201 Success
Called by Query
Member of POST
Data in Authorization (API) Key / (int) id of survey to close via HTTP POST
JSON Response
        {
            "status" : "Survey Closed."
        }
JSON Response (if there are missing required fields in the submission)

(HTTP 400 Error): The API will send back an HTTP 400 error with a JSON object outlining the missing required fields. The survey WILL NOT be closed until these fields have been submitted to. 

        {
            "status" : "The following fields are required. Please submit a response for each and try again.",
            "data" : [
                {
                    "type" : "date",
                    "name" : "Reporting Period Start",
                    "code" : "Reporting Period Start"
                },
                {
                    "type" : "date",
                    "name" : "Reporting Period End",
                    "code" : "Reporting Period End"
                }
            ]
        }
HTTP Responses
Response code Additional Information
200 OK Survey submission closed
401 Not Authorized None
404 Not Found Cannot find the requested survey

Example Request

The below request is for demonstration purposes only. The components may differ (i.e. the base URL, API Key, etc.).

Request: https://tiasurvey.com/post/close_survey/DEMO_APIKey-15aaf45ab35349b9f-0eb345340f97/100

Response: 

                {
                    "status" : "Survey Closed."
                }

NOTE: The "status" field is the lone return field that indicates the success/failure of the post request. The "surveyID" indicates which survey you would like to close and is retrievable from the aforementioned survey_list GET function.

Example API Process

Overview
  1. User should generate an API key. For more information on that process, see Getting Started which contains information on how to get an API key.
  2. Key should be used to setup an HTTP connection within the 3rd party program.
  3. The 3rd party program should then interact with the API through the HTTP connection by way of HTTP request (GET/POST).
    • HTTP GET request example: https://developer.tiasurvey.com/get/survey_list/(API_Key)
    • HTTP POST request example: https://developer.tiasurvey.com/post/close_survey/(API_Key)/(surveyID)
  4. The 3rd party program will then receive a JSON string for processing.
  5. For more details, including (Java) code examples and 3rd party client demo, on how to use the API click the "API Integration" link below.

Example API Integration

We have provided a basic example in the JAVA environment for your developers to reference. While you may not be working in JAVA, this should give developers some indication of how to integrate a RESTful API with your platform.
  1. Put together an API request. Show JAVA code Example.
    code example for putting together an API 'GET' request.
  2. Communicate the request to the API. Show JAVA code Example.
    Example API 'GET' request.
  3. Get a list and description of the available surveys. Use the API key to get a list of the surveys using the "survey_list" function. Show Demo Example.
    Example of get survey list function.
  4. Once you have found the survey you wish to submit to, use the survey ID for that survey (ID field of the survey_list) to retrieve the list of submittable fields for the survey using the "survey_fields" function. Show Demo Example.
    Example of get survey fields function.
  5. Now that you know the survey ID and fields for the survey you wish to submit to, you are ready for submitting.
  6. To submit, format the submit data in the appropriate JSON format and include it at the end of the URL. Show JAVA code Example.
    • https://developer.tiasurvey.com/post/submit/(API_Key)/{JSON data}
    • If there was a submission already opened for the survey then the data will be submitted to the open survey.
    • If there is not an open submission for the survey then a submission will be opened for you.
    Example API 'POST' request.
  7. You can submit as much and as often as necessary while the survey is opened. New submissions to an open survey will overwrite the existing fields. Show code/Demo Example.
    code example for submit function, API 'POST' request. Example of submit function.
  8. To view the fields and data you have submitted to the current (open) survey use the "open_survey" function. Show code/Demo Example.
    code example for 'get_open_survey'. Example of get open survey client demo.
  9. Once you are finished submitting to a particular survey you can close it by using the "close_survey" function and start anew.
  10. Using the "latest_closed_survey" and "submit_history" you can view either your lastest closed or the last 3 survey submission respectively. Show Demo Example.
    Example of get latest closed survey function.
  11. All data received from the API will be a JSON string. Examples of the JSON output are depicted in the above client application demo and the function definitions.

Diagnostics and Logging

In order to keep records for security and diagnostic reasons, Unconfusing Technology will log all activities made by users. The information in these logs will include but is not limited to: user identification, timestamps, status codes, IP address, and the action performed. All of this data will be kept internally is not available to other users. To access the tracking logs for your particular account, you may login and go to My Account > View API Usage.