About TrackVia Core Concepts # Anatomy of a TrackVia App TrackVia is a cloud-based solution for building custom, secure business applications. The platform places a significant emphasis on low-code development strategies, meaning that everyday citizen developers are given the tools to build powerful applications with minimal effort. TrackVia offers a comprehensive suite of features, including an intuitive user interface, drag-and-drop form builders, custom reports, user management, and enterprise security. The platform is designed to be extensible, allowing professional developers to customize their application with more complex logic and integrations as needed. ![TrackVia Tenant Architecture](https://developer.trackvia.com/_next/static/media/TenantArchitecture.2004d8e8.png) ## Apps [Permalink for this section](https://developer.trackvia.com/about-trackvia/anatomy\#apps) TrackVia apps can be seen as relational databases, allowing users to store and access data from their computers, tablets, and phones. Apps are composed of tables, views, forms, and other components. They can be customized with features such as workflow automation, role-based access management, custom dashboards, and integrations. An organization may have multiple apps within their TrackVia tenant, allowing them to organize data and information into logical, manageable areas. ## Tables [Permalink for this section](https://developer.trackvia.com/about-trackvia/anatomy\#tables) Tables are the foundation of all TrackVia apps. They are used to store and organize data in a structured format. Tables can be customized with fields, relationships, validation rules, and more. Tables can also be used to store documents and images. As with all relational database systems, tables should be normalized to ensure data integrity and performance. A well-designed table structure will ensure that data is stored efficiently and accurately, and that the app can grow naturally with the organization's needs. ## Views [Permalink for this section](https://developer.trackvia.com/about-trackvia/anatomy\#views) Views are used to visualize data stored in tables. They are composed of fields, filters, and sorting. Views can also be customized with charts, pivot tables, and other visualizations. There is no limit to the number of views that can be created in a TrackVia app. This allows users to quickly access the data they need. They can also give users the ability to drill down into the data and discover new insights. ## Forms [Permalink for this section](https://developer.trackvia.com/about-trackvia/anatomy\#forms) Forms are used to capture data from users. They are composed of fields, focused validation rules, and conditional logic. Views can also be added inside a form to naturally filter children records. These special views help users visualized related data with no extra configuration required. ## Dashboards [Permalink for this section](https://developer.trackvia.com/about-trackvia/anatomy\#dashboards) Dashboards are used to present data in a central screen. They are composed of multiple views and forms, and can contain special widgets such as embedded websites and shortcut panels. A single TrackVia app can have many dashboards, and only certain users or business groups can be assigned access to each dashboard. This allows organizations to customize the application's security to meet their specific needs. ## Flows [Permalink for this section](https://developer.trackvia.com/about-trackvia/anatomy\#flows) Flows are used to automate business processes. They are composed of actions, conditions, and triggers. Flows can be used to standardize data entry, streamline approval processes, and more. ## Users [Permalink for this section](https://developer.trackvia.com/about-trackvia/anatomy\#users) Users play an important role in TrackVia. They are used to manage access to the application, assign tasks, and generate notifications. Users can be organized into groups and assigned specific roles and permissions on an app basis. [Welcome](https://developer.trackvia.com/ "Welcome") [Data Types](https://developer.trackvia.com/about-trackvia/types "Data Types") ; --- About TrackVia What can you do with the API? # What can you do with the API? The API can be used to access and/or manipulate data within a TrackVia account, without the need to use the web interface to do so. It can only interact with the following elements: - Users - Applications - Views - Records - Integrations - Files Check out the [API Reference](https://developer.trackvia.com/api-development/swagger) page to see a complete list of all actions that the API can perform. The API cannot interact with the following elements: - Forms - Dashboards - Filters - Flows - Tables - Table Relationships - Account settings Last updated on June 2, 2023 [Data Types](https://developer.trackvia.com/about-trackvia/types "Data Types") [What are the integration options?](https://developer.trackvia.com/about-trackvia/integration-options "What are the integration options?") ; --- About TrackVia Application Scripts # Application Scripts Application Scripts (App Scripts) are self contained blocks of code written in Groovy. These scripts can be used to tailor the business logic layer of a TrackVia application when unique needs surrounding record actions arise. App Scripts are created and managed through the integrated Groovy editor within the edit table screen. Learn more about app scripts [here (opens in a new tab)](https://help.trackvia.com/hc/en-us/sections/15814055277083-App-Scripts) Last updated on June 2, 2023 [What are the integration options?](https://developer.trackvia.com/about-trackvia/integration-options "What are the integration options?") [Low Code Tools](https://developer.trackvia.com/about-trackvia/low-code-tools "Low Code Tools") ; --- About TrackVia What are the integration options? # Integration Options There are 4 primary ways that you can interact with the API. The right choice will depend on several factors, including but not limited to: what you're trying to accomplish, your security sensitivities, your proficiency with software development, and budget. Below are a list of considerations for each option. ## 1\. The Integration Platform [Permalink for this section](https://developer.trackvia.com/about-trackvia/integration-options\#1-the-integration-platform) The integration platform (powered by Workato) is a low-code option for building integrations. It allows you to connect to TrackVia, and hundreds of other systems, through a drag and drop interface. This is typically the best option for integrations. **Pros** - Speed to solution - Most integrations can be created in a matter of minutes. - Ease of use - Most integrations can be created by someone with little to no coding experience. - Accessibility - The integration platform is accessed directly through your TrackVia account. - Robust feature set - The integration platform manages hosting, logging, versioning, and analytics for your integrations. **Considerations** - Cost - Accessing the Integration platform is an additional cost to your base TrackVia subscription. Contact your Account Manager or Customer Success Manager for more information. - Workato is a third party software provider so you may have additional security considerations. ## 2\. Zapier [Permalink for this section](https://developer.trackvia.com/about-trackvia/integration-options\#2-zapier) Zapier is another low-code option for building integrations. Similar to Workato, it allows you to connect to TrackVia and hundreds of other applications through a drag and drop interface. **Pros** - Speed to solution - Most integrations can be created in a matter of minutes. - Ease of use - Most integrations can be created by someone with little to no coding experience. **Considerations** - Cost - Accessing the Integration platform is an additional cost to your base TrackVia package. Contact your Account Manager or Customer Success Manager for more information. - Accessibility - You will need to sign up for a subscription to Zapier, a third party software provider. In order to use the tool, you will need to log into their software. - Security - Zapier is a third party software provider so you may have additional security considerations. ## 3\. Microservices [Permalink for this section](https://developer.trackvia.com/about-trackvia/integration-options\#3-microservices) Microservices are small, individual, interconnected services written in Node.js that are uploaded directly to TrackVia and executed as a result of record actions. These services greatly expand the capabilities of TrackVia by executing code in a self contained environment. **Pros** - Hosting - Because the Code is uploaded to TrackVia, you don't need to worry about all the hassles that come with hosting (ensuring uptime, running servers, logging errors, etc.) - Invoking - Easily attach the microservice to any table in your TrackVia account and specify when the integration will run. All microservices are also assigned a custom API endpoint so they can be invoked externally. - User experience - Microservices are the the only integration option that allow you to configure the process to run synchronously with the end user's action. - Development - Node.js, comes with access to the worlds largest software repository npm (Node Package Manager). This includes many packages that can be used to create a microservice rather than starting completely from scratch. **Considerations** - Must be written using Node. - High code - Must have software development experience to use this option. ## 4\. Custom API [Permalink for this section](https://developer.trackvia.com/about-trackvia/integration-options\#4-custom-api) Partial to doing things on your own? Feel free to use our [OpenAPI documentation](https://developer.trackvia.com/api-development/swagger) to build your own client to interact directly with our API. **Pros** - Cost - API access is free. - Control - You own everything from the code to hosting to logging. - Flexibility - Write the code your own way. **Considerations** - High code - Must have software development experience to use this option. - Maintenance - custom API integrations can be more difficult to make updates to and troubleshoot than the low-code options. - Limited support - TrackVia support will not be able to review and debug your code. Last updated on June 2, 2023 [What can you do with the API?](https://developer.trackvia.com/about-trackvia/api-abilities "What can you do with the API?") [Application Scripts](https://developer.trackvia.com/about-trackvia/app-scripts "Application Scripts") ; --- About TrackVia Low Code Tools # Low Code Tools ## Workato [Permalink for this section](https://developer.trackvia.com/about-trackvia/low-code-tools\#workato) A robust automation tool with a wide variety of triggers and actions that can be composed into complex automations to suppliment your TrackVia workflow. Learn more about Workato [here (opens in a new tab)](https://help.trackvia.com/hc/en-us/articles/15945151254299-Workato) ## Zapier [Permalink for this section](https://developer.trackvia.com/about-trackvia/low-code-tools\#zapier) Zapier is a popular online automation tool that enables users to connect over 5,000 business apps without writing code. It offers an intuitive drag and drop workflow builder that allows users to quickly create automated processes. Learn more about Zapier [here (opens in a new tab)](https://help.trackvia.com/hc/en-us/articles/15945180888987-Zapier) Last updated on June 2, 2023 [Application Scripts](https://developer.trackvia.com/about-trackvia/app-scripts "Application Scripts") [API Users](https://developer.trackvia.com/getting-started-with-the-api/api-users "API Users") ; --- About TrackVia Data Types # Data Types ## List of Data Types [Permalink for this section](https://developer.trackvia.com/about-trackvia/types\#list-of-data-types) The following field types are available to be added to a TrackVia table: | 🛠 Field Type | 📃 Description | | :-- | :-- | | Single Line | Short, one-line text box for entering words, letter, or numbers. Limit of ~250 characters. | | Paragraph | Multi-line text box for entering longer amounts of text, namely sentences and paragraphs. Limit of ~65,000 characters (less when using multi-byte UTF-8 character sets). | | Number | Decimals, positive numbers, and negative numbers. For example, valid entries include: 175, -175, 1.75, -1.75. | | Percentage | Accept the same values as Number. Adhere to decimal formatting and display a percent symbol, i.e, entering 0.05 results in 5%; entering 5 results in 500%. | | Currency | Accept the same values as Number. Adhere to decimal formatting and display a currency symbol, i.e, entering 1.00 results in $1.00 in U.S.-based locales. | | Auto Counter | Sequentially increment by 1 for each new record with configurable starting value. | | Drop Down | Single-selection from list of options. | | Checkbox | Multiple-selection from list of options. | | Date | Day, month, and year. | | Date Time | Day, month, year, hour, and minute. Automatically reformatted in the user's selected timezone. | | Location | Latitude and longitude coordinates of a custom location, or user's current location when saving a record. | | Email | String-validated email field input. Limit of ~250 characters. | | Link | String-validated URL field input. | | Image | Attach photo or image file to a record. Supported file types: `.jpeg`, `.jpg`, `.png`, and `.gif`. Maximum file size: `40MB` | | Document | Attach file or document to a record. Maximum file size: `40MB` | | Calculated Fields | Input formulas that automatically calculate a resulting value in each record. Options: Calculated Text, Calculated Number, Calculated Percentage, Calculated Currency, Calculated Date, Calculated Date Time, Calculated Email | | User | Single-select from list of TrackVia users in the app. | | User Group | Single-select from list of TrackVia user groups in the app. | | Relationship | Single-select from list of related records in the app or cross-app. | Read [our knowledge base article on field types (opens in a new tab)](https://help.trackvia.com/hc/en-us/articles/8811398834971) for more on each type. ## Selecting the Right Data Types [Permalink for this section](https://developer.trackvia.com/about-trackvia/types\#selecting-the-right-data-types) Novice TrackVia developers may feel overwhelmed by the number of data type options available. Choosing the right data type is important; not only will it make it easier to use the app, but it will also ensure that data is input correctly. In general, it's best to use the most specific data type for a given field. For example, if a field is intended to store a date, use the 'Date' field type instead of 'Single Line'. This will ensure that users are only able to input valid dates and not arbitrary text. When selecting the data type for a field, consider the following questions: - What kind of data will this field store? - How precise does the data need to be? - How many characters/bytes can this field hold? - Are any special formatting requirements needed (e.g. currency symbols, percent signs, etc.)? Once a field is saved in a table, and users begin to enter data, it becomes extremely difficult to convert a field's data type. The longievity of a table and the accuracy of its data depend on the correct selection of data types. [Core Concepts](https://developer.trackvia.com/about-trackvia/anatomy "Core Concepts") [What can you do with the API?](https://developer.trackvia.com/about-trackvia/api-abilities "What can you do with the API?") ; --- API Development Best Practices # Best Practices Here are some best practices and tips you can use when developing against the API: - **Avoid making API calls against the default view.** These views often take the longest amount of time to load, and therefore will have longer response times. - **Build a custom view to make API calls against.** The view should contain the minimum number of fields necessary for your API requests. Avoid field sorting, including complex or large number of calculated fields, and complex view filters where possible. All these will slow down the response times of the view. Learn more about building views [here. (opens in a new tab)](https://help.trackvia.com/hc/en-us/articles/8811299454875-How-to-create-views) - **Use indexing to improve response times.** If you have an API call that will be searching a table regularly for the same field, you can reduce the load on the search and make it easier to find the item with table indexing. Indexing a field, especially with the “Identical to” search type, helps the find function locate the right record faster. Only put one indexed field on a view to optimize call performance. Learn more [here. (opens in a new tab)](https://help.trackvia.com/hc/en-us/articles/8782629983899-How-to-setup-Table-Level-Indexing) - **Follow the principle of least privilege.** When setting up the permissions for the API User, only give the role access to the views and permissions needed to run the integration actions. This will ensure better data security and integrity. Learn more about roles and permissions [here. (opens in a new tab)](https://help.trackvia.com/hc/en-us/articles/8727728717595-How-to-create-a-role-to-assign-permissions) - **Test in a sandbox environment before releasing to production.** Build your API connections with your sandbox ID, production API Key and auth token, and you can utilize your sandbox to test your API calls to check performance and test delete or post actions. This ensures that your data will remain safe while you test your processes and ensure they are working seamlessly before implementing a new process that could alter or delete important data. Learn more about sandboxes [here. (opens in a new tab)](https://help.trackvia.com/hc/en-us/sections/9169976872731-Sandboxes-Account-Backup) - **Make the fewest number of API calls possible.** If you think that you'll need to make the same API call more than one time, consider storing the response in memory after the first request. This way you can reference the response in memory rather than making the call again. Referencing the data in memory is faster and it will reduce the number of API calls that you need to make (keep you below the rate limits). ## Building Views for API use [Permalink for this section](https://developer.trackvia.com/api-development/best-practices\#building-views-for-api-use) When building a view for your API, a best practice is to follow the principle of the least privilege and only include the minimum number of fields and records necessary for your Integration. You'll be ensuring better data security and integrity and keeping your API call returns quick. Four key reminders, make sure to avoid default views, column sorting, filters, and unnecessary calculated fields in these views they can each be resource intensive and slow down your return. A default view will contain all the records and fields, and calculated fields must run every time the view is accessed, making both items less performant for API calls. To ensure your API has access, ensure you've shared the appropriate views with your API user specific to your integration. You can use our API to GET a list of views, a list of records, or a list of filtered records from a view. You can also use our API to POST, DELETE, or GET a record from a view. Make a note of your view IDs in the request URL (i.e. go.trackvia.com/apps/#/tables/#/views/ID #), and you can use [Swagger](https://developer.trackvia.com/api-development/swagger) or [Postman](https://developer.trackvia.com/api-development/postman) to test, learn more about different IDs and options with our API, and plan out the build for your API actions. ## Indexing Fields for API Calls [Permalink for this section](https://developer.trackvia.com/api-development/best-practices\#indexing-fields-for-api-calls) If you have an API call that will be searching a table regularly for the same field, you can reduce the load on the search and make it easier to find the item with table indexing. Indexing a field, especially with the “Identical to” search type, helps the find function locate the right record faster. Only put one indexed field on a view to optimize call performance. To learn more about applying table-level indexing, check out our [how-to article (opens in a new tab)](https://help.trackvia.com/hc/en-us/articles/8782629983899-How-to-setup-Table-Level-Indexing) for more details and best practices. ## Sandboxes & Your API [Permalink for this section](https://developer.trackvia.com/api-development/best-practices\#sandboxes--your-api) Utilizing sandboxes to test your API connection and results is a great way to check your system and setup before impacting your current data. Build your API connections with your sandbox ID, production API Key and auth token, and you can utilize your sandbox to test your API calls to check performance and test delete or post actions. This ensures that your data will remain safe while you test your processes and ensure they are working seamlessly before implementing a new process that could alter or delete important data. Last updated on June 2, 2023 [Postman](https://developer.trackvia.com/api-development/postman "Postman") [Limitations](https://developer.trackvia.com/api-development/limitations "Limitations") ; --- API Development FAQ # API Frequently Asked Questions ### How can I keep up with changes to the TrackVia API? [Permalink for this section](https://developer.trackvia.com/api-development/faq\#how-can-i-keep-up-with-changes-to-the-trackvia-api) There are a few great ways to follow the changes we make to TrackVia: - Register on our Developer Community Forum - Read the latest documentation & release notes ### How do I enable API Access? [Permalink for this section](https://developer.trackvia.com/api-development/faq\#how-do-i-enable-api-access) It's easy, just visit your “API Access” page and you can create an API Key and Access Tokens there. Once you have your key, visit our developer website for documentation and code samples. ### How do I keep from running into the rate limit? [Permalink for this section](https://developer.trackvia.com/api-development/faq\#how-do-i-keep-from-running-into-the-rate-limit) We recommend that you cache API responses in your application or on your site if you expect high-volume usage. For example, don't try to call the TrackVia API on every page load of your hugely popular website. Instead, call our API once a minute and save the response to your local server, displaying your cached version on your site. Request only what you need, and only when you need it. For example, frequent polling of the REST API looking for new data is inefficient for both your application, and the TrackVia API. If you are using the TrackVia API to monitor for specific transactions, consider using a Microservice instead of an API pooler. ### What can you do with the API? [Permalink for this section](https://developer.trackvia.com/api-development/faq\#what-can-you-do-with-the-api) The API can be used to access and/or manipulate data within a TrackVia account, without the need to use the web interface to do so. It can only interact with the following elements: - Users - Applications - Views - Records - Integrations - Files Check out the [API Reference](https://developer.trackvia.com/api-development/swagger) page to see a complete list of all actions that the API can perform. The API cannot interact with the following elements: - Forms - Dashboards - Filters - Flows - Tables - Table Relationships - Account settings Last updated on June 2, 2023 [Limitations](https://developer.trackvia.com/api-development/limitations "Limitations") [Writing Code](https://developer.trackvia.com/microservices/write-code "Writing Code") ; --- API Development Limitations # Limitations ## API Rate Limits [Permalink for this section](https://developer.trackvia.com/api-development/limitations\#api-rate-limits) TrackVia has API rate limits in place to ensure system stability. There are two rate limits; per minute and per month. The rate limit per minute is 1,200 API calls. The per month rate limit is 11M API calls. Please refer to the API Best Practices page and the API TrackVia University course for best practices on staying under these limits. ## Account Elements that the API Cannot Interact with: [Permalink for this section](https://developer.trackvia.com/api-development/limitations\#account-elements-that-the-api-cannot-interact-with) - Forms - Dashboards - Filters - Flows - Tables - Table relationships - Account settings ## Search Limitations [Permalink for this section](https://developer.trackvia.com/api-development/limitations\#search-limitations) You can use the `GET/views/{viewId}/find` endpoint to retrieve a subset of records from a view. This endpoint allows you to provide an optional search parameter in the query. You can only provide one search term, and a "contains" search will be performed on all records in the specified view. Please refer to [Knowledge Base (opens in a new tab)](https://help.trackvia.com/hc/en-us) for more information on search behavior. [Best Practices](https://developer.trackvia.com/api-development/best-practices "Best Practices") [FAQ](https://developer.trackvia.com/api-development/faq "FAQ") ; --- API Development Postman # Postman ## Overview [Permalink for this section](https://developer.trackvia.com/api-development/postman\#overview) ![Postman](https://developer.trackvia.com/_next/static/media/postman_logo.5984a073.png) For testing your data and integration with the TrackVia API, we suggest using the industry standard tool, [Postman (opens in a new tab)](https://www.postman.com/). The Postman API client is the foundational tool of Postman, enabling you to easily explore, debug, and test againt the TrackVia API. ## Install Postman [Permalink for this section](https://developer.trackvia.com/api-development/postman\#install-postman) [Download the Postman app (opens in a new tab)](https://www.postman.com/downloads/) to get started. ## Install the TrackVia API Postman Collection [Permalink for this section](https://developer.trackvia.com/api-development/postman\#install-the-trackvia-api-postman-collection) All TrackVia API endpoints are defined for you in a Postman Collection. This eliminates your need to recreate the requests yourself and instead dive head first into your integration. First, [download the TrackVia API Postman Collection](https://developer.trackvia.com/TrackViaOpenApi.postman_collection.json) where we publish the latest available version. Second, [import the collection into Postman following this guide (opens in a new tab)](https://learning.postman.com/docs/getting-started/importing-and-exporting-data/#importing-data-into-postman). ## Configure Your TrackVia API [Permalink for this section](https://developer.trackvia.com/api-development/postman\#configure-your-trackvia-api) Once imported, you will want to update the provided template variables: - `TrackViaHost` - `UserKey` - `AccessToken` ![TrackVia Postman Collection Screenshot](https://developer.trackvia.com/_next/static/media/postman-trackvia-collection-1024x663.5d5bf17c.png) ## Run API Tests [Permalink for this section](https://developer.trackvia.com/api-development/postman\#run-api-tests) You should now be configured to call any endpoint against the TrackVia API in Postman! This includes querying records, creating/updating/deleting records, uploading files, downloading images, and much more. Last updated on July 18, 2023 [OpenAPI Documentation](https://developer.trackvia.com/api-development/swagger "OpenAPI Documentation") [Best Practices](https://developer.trackvia.com/api-development/best-practices "Best Practices") ; --- API Development SDK # SDKs ![Getting Started](https://developer.trackvia.com/_next/static/media/Vector_Graphics_Data_Manipulation_1.61c07bd9.svg) TrackVia offers official SDKs for popular programming languages, which can be used at no cost to rapidly integrate and extend TrackVia applications. The Node SDK is the preferred SDK for developing applications with the TrackVia API. It provides a simple, lightweight interface for making API requests and accessing the response objects. The SDK also includes utilities for authentication and for building and executing queries. This SDK can be packaged in Microservices or deployed as part of a larger application. ## Official SDKs [Permalink for this section](https://developer.trackvia.com/api-development/sdk\#official-sdks) - [Node SDK (opens in a new tab)](https://www.npmjs.com/package/trackvia-api) Last updated on June 2, 2023 [Auth Tokens](https://developer.trackvia.com/getting-started-with-the-api/tokens "Auth Tokens") [OpenAPI Documentation](https://developer.trackvia.com/api-development/swagger "OpenAPI Documentation") ; --- API Development OpenAPI Documentation # OpenAPI Documentation ## TrackVia OpenAPI ``` 1.0.0 ``` ``` OAS3 ``` [/openapi.yaml](https://developer.trackvia.com/openapi.yaml) This is the OpenAPI specification for the TrackVia open api. [Terms of service](https://trackvia.com/general-terms/) [Contact the developer](mailto:integrations@trackvia.com) [Apache 2.0](http://www.apache.org/licenses/LICENSE-2.0.html) Servers https://{domain}/openapi Computed URL: `https://go.trackvia.com/openapi` #### Server variables | | | | --- | --- | | domain | | Authorize ### Users User operations ### Apps Application operations ### Views View operations ### Integrations Microservice operations ### Records Record operations ### Files File operations #### Schemas [SDK](https://developer.trackvia.com/api-development/sdk "SDK") [Postman](https://developer.trackvia.com/api-development/postman "Postman") ; --- Developer Community # Developer Community ![Welcome](https://developer.trackvia.com/_next/static/media/Vector_Graphics_Chart_Graphs2_1.feeb2b32.svg) As a member of our developer community, you'll have access to a wealth of resources and support to help you build custom applications and automate business processes using the TrackVia platform. Our community is a place where you can share tips and tricks, post code snippets, and get answers to your questions from other developers. The TrackVia team also regularly shares updates about new features and improvements to the platform, and is available to provide support and guidance. To help you expand your skills and stay up-to-date with the latest trends, we also organize a variety of events, including webinars, hackathons, meet-ups, and training sessions. Our goal is to make the TrackVia Developer Community a valuable resource for developers at all levels, from beginners to experts. We encourage you to participate in the discussions, share your own knowledge and experiences, and help others in the community. Last updated on June 2, 2023 [Common Error Response Code Examples](https://developer.trackvia.com/troubleshooting/common-errors "Common Error Response Code Examples") ; --- Getting started with the API API Key # API Key The `API Key` is unique to your **TrackVia** account and is a required component for accessing the **TrackVia API**. Once generated, it cannot be changed or deleted. It can be copied for use in an integration using the clipboard icon. This `API Key` should be used as the value of the `user_key` `query string parameter` in the of API requests. To create an `API Key` navigate to `API Access` from inside of your `Account Settings`. ![Create API Key](https://developer.trackvia.com/_next/static/media/create-api-key.e710f3de.png) [API Users](https://developer.trackvia.com/getting-started-with-the-api/api-users "API Users") [Auth Tokens](https://developer.trackvia.com/getting-started-with-the-api/tokens "Auth Tokens") ; --- Getting started with the API API Users # API Users ![Using the API](https://developer.trackvia.com/_next/static/media/Vector_Graphics_Charts_Graphsv2.3f9c9986.svg) `API Users` are able to be assigned access tokens which allow you to authenticate with the API. **TrackVia** uses access tokens to verify a user's identity and permission level when accessing the API. Tokens ensure account security by limiting API access and enforcing permissions. A **TrackVia** `Super Admin` has the ability to create up to 100 unique access tokens, each with its own expiration date and set of permissions. Actions that use the access token will be performed by and that user will be displayed in the appropriate `Created` and `Updated` fields of **TrackVia**. `API Users` are a special kind of user and are used only for API connections and integrations. Designating a user as an `API user` means that user will: - **Restrict Web and Mobile access.** `API Users` are unable to use either the TrackVia web or mobile applications. - **Bypass Single Sign On (SSO).** `API Users` bypass SSO login in order to prevent their access tokens from inadvertently expiring due to SSO policies. - **Ignore password expiration policies.** `API Users` are exempt from **TrackVia** password expiration policies. - **Be eligible for access token creation.** Only **API Users** may be used to create access tokens. - **Have permissions managed like any other user.** `API Users` will still need to be put in a properly configured role in order to have read, write, or delete permissions in an account. ## Create an API User [Permalink for this section](https://developer.trackvia.com/getting-started-with-the-api/api-users\#create-an-api-user) To designate a user as an `API User`, navigate to `Manage Users` and select the user you want to assign to a token. Check the `Set As API User` box on that user. Users in `Unverified` status may not be designated as `API Users`. ![Create API User](https://developer.trackvia.com/_next/static/media/create-api-user.c3faed25.png) Last updated on June 2, 2023 [Low Code Tools](https://developer.trackvia.com/about-trackvia/low-code-tools "Low Code Tools") [API Key](https://developer.trackvia.com/getting-started-with-the-api/api-keys "API Key") ; --- Getting started with the API Auth Tokens # Auth Tokens After creating at least one `API User`, `Super Admins` will be able to create auth tokens by clicking `Create Auth Token`. A window will open for the `Super Admin` to set the token's name, `API User`, and expiration date. Once created, these values cannot be changed. Only active users, designated as an `API User`, will be shown in this window. The expiration date can be any date in the future and will expire at `midnight UTC` on the date selected. Once created, auth tokens can be copied using the clipboard icon and used in `Microservices`. They can be turned off by clicking the gear icon and selecting `Deactivate`. ![Create Auth Token](https://developer.trackvia.com/_next/static/media/create-auth-token.256b23cc.png) ![View Auth Token](https://developer.trackvia.com/_next/static/media/auth-token.82e591d8.png) [API Key](https://developer.trackvia.com/getting-started-with-the-api/api-keys "API Key") [SDK](https://developer.trackvia.com/api-development/sdk "SDK") ; --- Welcome # Welcome, developers! ![Welcome](https://developer.trackvia.com/_next/static/media/Vector_Graphics_Integrations_Implementation_1.abda5f00.svg) Create, automate, and solve problems for your team on TrackVia. TrackVia offers endless ways to build standalone solutions or complex integrations to your existing software. Before you get started, learn [about what makes a TrackVia app](https://developer.trackvia.com/about-trackvia/anatomy). Then review our [integration options](https://developer.trackvia.com/about-trackvia/integration-options) or dive into [our developer toolkit](https://developer.trackvia.com/api-development/sdk) to start integrating. Visit [our developer community](https://developer.trackvia.com/dx) to collaborate with others on your solution. Happy building! Last updated on June 2, 2023 [Core Concepts](https://developer.trackvia.com/about-trackvia/anatomy "Core Concepts") ; --- Microservices Attaching to tables # Attaching to tables In order for the microservice to run, it needs to be attached to one or more tables. To set up the trigger, go to the table builder for the table where records should trigger the service. Click the "Microservices" link near the top of the screen (next to app scripts). Click "Attach Microservice". Choose a previously uploaded microservice and a trigger type. ![Attach microservice](https://developer.trackvia.com/_next/static/media/view-microservice.62674143.png) Once saved, the microservice will run anytime the event occurs. A microservice can be detached from a table by clicking the Trash Can icon next to the service from this screen. [Uploading](https://developer.trackvia.com/microservices/uploading "Uploading") [Event Types](https://developer.trackvia.com/microservices/event-types "Event Types") ; --- Microservices Best Practices # Best practices For writing microservices, we recommend: 1. Refer to the API best practices for making API calls [here](https://developer.trackvia.com/api-development/best-practices). These all apply to microservices as well. 2. Use a code editor with language extensions installed (like VS Code). 3. Use the debugger built into your code editor to confirm what is happening during execution. 4. Leave detailed comments in your code. 5. Plan out what the service will do step by step before writing code. 6. Read up on general JavaScript best practices before you start. 7. Once your code is confirmed to work, go back over it and look for ways you can simplify it and remove any code left over from earlier iterations. 8. Write tests for each function using Jest. 9. If you have experience with code, we also recommend using Typescript for microservices. Last updated on June 1, 2023 [Downloading](https://developer.trackvia.com/microservices/downloading "Downloading") [Limitations](https://developer.trackvia.com/microservices/limitations "Limitations") ; --- Microservices Downloading # Downloading Once uploaded, the microservice can be re-downloaded by clicking the download button next to the microservice name. ![Download microservice](https://developer.trackvia.com/_next/static/media/download-microservice.fd84fee1.png) [Who can access?](https://developer.trackvia.com/microservices/who-can-access "Who can access?") [Best Practices](https://developer.trackvia.com/microservices/best-practices "Best Practices") ; --- Microservices Event Types # Event types Similar to App scripts, the following event types may be used to trigger the execution of a microservice: 1. After record insert 2. After record update 3. After record delete [Attaching to tables](https://developer.trackvia.com/microservices/attaching-to-tables "Attaching to tables") [Logs](https://developer.trackvia.com/microservices/logs "Logs") ; --- Microservices Examples # Examples Microservices are best used to make calls to outside APIs based on triggers in a TrackVia app, but can also be used for data manipulation within TrackVia itself. Here are some examples: - A service that gathers information from a TrackVia record, sends a request to the Formstack Documents API to create a PDF of the record data, then uploads the resulting PDF to a TrackVia document field on the same record (see below). - A service that calls the Outlook 365 API to create calendar invites for an event created in TrackVia. - A service that posts Slack/Teams messages to a shared channel whenever a project is marked completed in TrackVia. - A service that runs whenever a user uploads an image to a record in TrackVia. The service would download the image, resize and rename it according to a set convention, then re-upload it to the TrackVia record. ## Formstack Merge Microservice [Permalink for this section](https://developer.trackvia.com/microservices/examples\#formstack-merge-microservice) The Formstack Merge Microservice allows a user to send a TrackVia record to a template in their Formstack account for merging. The merged document is then attached to a preconfigured destination record. For instructions on usage, see the `README.md`. ## Download Microservice [Permalink for this section](https://developer.trackvia.com/microservices/examples\#download-microservice) [Download the latest version of the FormStack Merge Microservice](https://developer.trackvia.com/formstackMerge.zip). [Limitations](https://developer.trackvia.com/microservices/limitations "Limitations") [FAQ](https://developer.trackvia.com/microservices/faq "FAQ") ; --- Microservices FAQ # Microservice Frequently Asked Questions ## What environment do Microservices run in? [Permalink for this section](https://developer.trackvia.com/microservices/faq\#what-environment-do-microservices-run-in) TrackVia Microservices are executed as Amazon Web Service Lambda, configured with an x86 Node 16.x runtime or x86 Python 3.9 runtime. Each microservice is provisioned with 1024 MB of memory. ## What are the limitations of a Microservice? [Permalink for this section](https://developer.trackvia.com/microservices/faq\#what-are-the-limitations-of-a-microservice) - Microservices are limited to a total runtime of 15 minutes. - Microservices do not have access to IAM or other AWS services. - Microservices packages (ZIP) may only be 40MB in size. - Microservices are standalone - there is no access to layers. - All microservices are subject to TrackVia's Terms of Service and security policies. Check out our [getting started guides](https://developer.trackvia.com/getting-started-with-the-api/api-users) or read our [FAQs](https://developer.trackvia.com/api-development/faq) for best practices and common questions to start extending your app! Last updated on July 18, 2023 [Examples](https://developer.trackvia.com/microservices/examples "Examples") [Swagger issues](https://developer.trackvia.com/troubleshooting/swagger-issues "Swagger issues") ; --- Microservices Limitations # Limitations - Microservices can be written in Node or Python - Microservices run on a serverless implementation of Node.js. - 512 MB of memory available to the microservice - Execution timeout of 1 minute [Best Practices](https://developer.trackvia.com/microservices/best-practices "Best Practices") [Examples](https://developer.trackvia.com/microservices/examples "Examples") ; --- Microservices Logs # Logs Any logging that you've written into the microservice will be available in the "Log" tab of the account microservices page. Only super admin users will be able to see the logs. ![Microservice logs](https://developer.trackvia.com/_next/static/media/microservice-logs.ebdbd4e4.png) [Event Types](https://developer.trackvia.com/microservices/event-types "Event Types") [Who can access?](https://developer.trackvia.com/microservices/who-can-access "Who can access?") ; --- Microservices Uploading # Uploading To prepare your microservice, put all files into a single zip file. The default JS file needs to be named `index.js` and must be at the top level of the zip. Once prepared, go to the "Microservices" tab in the user profile menu and click "Add New Microservice" on the left sidebar. Give your microservice a name and follow the instructions on screen to upload the zip. ![Add microservice](https://developer.trackvia.com/_next/static/media/add-microservice.2ac8c7c5.png) The "Run Asynchronously" checkbox will allow the microservice to run asynchronously, meaning the user who saves the record that triggers the microservice will not need to wait for it to complete, it will run in the background on its own. This does mean, however, that it's possible for the microservice to change fields that the user has not seen. If it's important for the user to see the results of the microservice right away, leave this box unchecked. [Writing Code](https://developer.trackvia.com/microservices/write-code "Writing Code") [Attaching to tables](https://developer.trackvia.com/microservices/attaching-to-tables "Attaching to tables") ; --- Microservices Who can access? # Who can access Super Admin permissions are required to work with microservices. Any Super Admin on your account can create, delete, and make changes to your microservices. Last updated on June 2, 2023 [Logs](https://developer.trackvia.com/microservices/logs "Logs") [Downloading](https://developer.trackvia.com/microservices/downloading "Downloading") ; --- Microservices Writing Code # Writing Code ![Writing Code](https://developer.trackvia.com/_next/static/media/Vector_Images_Account_settings_tile_1.058139ba.svg) ## Example Microservice Function [Permalink for this section](https://developer.trackvia.com/microservices/write-code\#example-microservice-function) ```nx-border-black nx-border-opacity-[0.04] nx-bg-opacity-[0.03] nx-bg-black nx-break-words nx-rounded-md nx-border nx-py-0.5 nx-px-[.25em] nx-text-[.9em] dark:nx-border-white/10 dark:nx-bg-white/10 export const handler = async (event, context) => { // event object contains any data passed into the microservice // context object contains information about the invocation and execution environment try { console.log('Hello, World'); // use the "await" keyword to wait for data returned from asynchronous functions const data = await someAsynchronousFunction(); // a successful response object // ends the microservice return { statusCode: 200, message: 'success', }; } catch (error) { // an error response object // ends the microservice return { statusCode: 500, message: error.message }; } } ``` Last updated on September 27, 2023 [FAQ](https://developer.trackvia.com/api-development/faq "FAQ") [Uploading](https://developer.trackvia.com/microservices/uploading "Uploading") ; --- Troubleshooting Common Error Response Code Examples # Error Response Code Examples ## 400: Bad Request [Permalink for this section](https://developer.trackvia.com/troubleshooting/common-errors\#400-bad-request) **Error Response Body:** ```nx-border-black nx-border-opacity-[0.04] nx-bg-opacity-[0.03] nx-bg-black nx-break-words nx-rounded-md nx-border nx-py-0.5 nx-px-[.25em] nx-text-[.9em] dark:nx-border-white/10 dark:nx-bg-white/10 { "errors": [], "message": "Invalid request submitted. One or more value conversions failed: Could not convert \"Baseball\" to Long", "name": "invalidRequest", "code": "400" } ``` **Reason:** Trying to set a relationship name by name rather than underlying id of the parent record **Solution:** Relationship fields are set using the parent's primary key (underlying ID). If you navigate to the parent record in TrackVia and click on it, the URL will display that record's ID after `view/` (e.g. go.trackvia.com/#/apps/56/tables/322/views/607/records/view/ `93`/form/1162). **Error Response Body:** ```nx-border-black nx-border-opacity-[0.04] nx-bg-opacity-[0.03] nx-bg-black nx-break-words nx-rounded-md nx-border nx-py-0.5 nx-px-[.25em] nx-text-[.9em] dark:nx-border-white/10 dark:nx-bg-white/10 { "errors": [], "message": "Invalid request submitted. The value \"Yes\" is not a valid DATETIME for field \"Last Grandparent Update\".", "name": "invalidRequest", "code": "400" } ``` **Reason:** Trying to update a field with an incorrect data type **Solution:** Check the field's data type from the Table editor in TrackVia and ensure the value you are trying to set on that field matches the data type shown for that field. In the example above, “Yes” was the payload value that was used to set a `Date and Time` field in TrackVia, resulting in this error. **Error Response Body:** ```nx-border-black nx-border-opacity-[0.04] nx-bg-opacity-[0.03] nx-bg-black nx-break-words nx-rounded-md nx-border nx-py-0.5 nx-px-[.25em] nx-text-[.9em] dark:nx-border-white/10 dark:nx-bg-white/10 { "errors": [], "message": "Invalid request submitted. The value \"\" is not a valid DATETIME for field \"Last Grandparent Update\".", "name": "invalidRequest", "code": "400" } ``` **Reason:** Trying to null out a field using `“”` instead of `null` **Solution:** If trying to update a record's field value to be null, use the test of `null` (without quotes), as the value. ## 401: Unauthorized [Permalink for this section](https://developer.trackvia.com/troubleshooting/common-errors\#401-unauthorized) **Error Response Body:** ```nx-border-black nx-border-opacity-[0.04] nx-bg-opacity-[0.03] nx-bg-black nx-break-words nx-rounded-md nx-border nx-py-0.5 nx-px-[.25em] nx-text-[.9em] dark:nx-border-white/10 dark:nx-bg-white/10 { "errors": [], "message": "DENIED!!! - View: 5000 either does not exist or you do not have access to it.", "name": "accessDenied", "code": "401" } ``` **Reason:** View/Record doesn't exist or is not permissioned to the API user **Solution:** Ensure that the view/recordId does exist in TrackVia. If it does and this error is still being thrown, check the API User (that's attached to the Auth Token being used) to see that user's role/permissions. If the API User is NOT a super admin, find the role it has been assigned to and either update that role to give access to this resource or assign/edit that user's role to one that does have access to this resource. **Error Response Body:** ```nx-border-black nx-border-opacity-[0.04] nx-bg-opacity-[0.03] nx-bg-black nx-break-words nx-rounded-md nx-border nx-py-0.5 nx-px-[.25em] nx-text-[.9em] dark:nx-border-white/10 dark:nx-bg-white/10 { "error": "3Scale: unauthorized metric \"openapi/views/N/records/Third/GET\" is invalid" } ``` **Reason:** Inputting the recordId text value instead of the underlying ID when getting a record **Solution:** Find the underlying ID of a record by navigating to the record in TrackVia and clicking on it. The URL will display that record's ID after `view/` (e.g. go.trackvia.com/#/apps/56/tables/322/views/607/records/view/ `93`/form/1162). **Error Response Body:** ```nx-border-black nx-border-opacity-[0.04] nx-bg-opacity-[0.03] nx-bg-black nx-break-words nx-rounded-md nx-border nx-py-0.5 nx-px-[.25em] nx-text-[.9em] dark:nx-border-white/10 dark:nx-bg-white/10 { "errors": [], "message": "DENIED!!! - field \"book Title\" either does not exist or you do not have access to it.", "name": "accessDenied", "code": "401" } ``` **Reason:** Setting a field name incorrectly in the payload **Solution:** Ensure that the field names in the payload are an exact match to the field names in TrackVia. These are also case sensitive. ## 403: Forbidden [Permalink for this section](https://developer.trackvia.com/troubleshooting/common-errors\#403-forbidden) ## 404: Not Found [Permalink for this section](https://developer.trackvia.com/troubleshooting/common-errors\#404-not-found) ## 500: Internal Server Error [Permalink for this section](https://developer.trackvia.com/troubleshooting/common-errors\#500-internal-server-error) **Error Response Body:** ```nx-border-black nx-border-opacity-[0.04] nx-bg-opacity-[0.03] nx-bg-black nx-break-words nx-rounded-md nx-border nx-py-0.5 nx-px-[.25em] nx-text-[.9em] dark:nx-border-white/10 dark:nx-bg-white/10 { "errors": [], "message": "We're sorry, there's been an error. Please contact support@trackvia.com for troubleshooting", "name": "exception", "code": "500" } ``` **Reason:** Incorrect payload structure **Solution:** Depending on the request being made, different payload structures could be used. Review the Swagger and/or Postman documentation for the expected payload structures based on the request. Last updated on June 2, 2023 [Postman issues](https://developer.trackvia.com/troubleshooting/postman-issues "Postman issues") [Developer Community](https://developer.trackvia.com/dx "Developer Community") ; --- Troubleshooting Postman issues # Common Postman Errors And How To Resolve Them When testing API actions, the most common errors are caused by: - incorrectly inputting information such as using the wrong URL for the domain - not authorizing properly using the API Key and Auth Token - not assigning the necessary TrackVia resources to the API user The sections below identify the most common errors you may encounter while using Postman for testing and the steps to take to resolve them. ## Common Errors While Using Postman [Permalink for this section](https://developer.trackvia.com/troubleshooting/postman-issues\#common-errors-while-using-postman) The most common issues people encounter while using Postman are very similar to those described above when using Swagger. One difference between using Postman and Swagger is that with Postman you can add the domain, API Key, and Auth Token credentials as variables. This allows for better security as the variable does not show the access credentials, and once the credentials are saved as variables, you do not have to re-enter them each time you want to authenticate. ### 1\. Incorrect Domain [Permalink for this section](https://developer.trackvia.com/troubleshooting/postman-issues\#1-incorrect-domain) After you've imported the TrackVia Postman collection to Postman, you can click on "Collections" on the left side of the screen to choose an API call. ![Postman Collections](https://developer.trackvia.com/_next/static/media/postman1a.0de74ce5.png) After selecting the action, you can add the domain URL as the `{{TrackViaHost}}` variable to the right of the API call dropdown menu (see below). First, click on `{TrackViaHost}}`, and in the message that opens, click the "Add new variable" button to enter your URL. ![dd Variables](https://developer.trackvia.com/_next/static/media/postman1b.51b86685.png) Just as with Swagger, `go.trackvia.com` should work for most cases if your account is on the standard PRODUCTION environment. If your account is on the GOV or HIPAA environments, you will need to enter the corresponding URL for your environment (e.g. [https://hipaa.trackvia.com (opens in a new tab)](https://hipaa.trackvia.com/)). If your account uses a custom subdomain, you can use the default go.trackvia.com, or enter your custom subdomain here, but note that it will not work if the custom subdomain is not entered exactly as it appears in your account. If you try to send the API call without adding the correct URL as the `{{TrackViaHost}}` variable, or you've entered the incorrect URL, you will receive a "Could not send request" error message as seen below. ![TrackVia Host not found error](https://developer.trackvia.com/_next/static/media/postman1c.eaaca536.png) To resolve this, make sure you are using the correct URL for your account's environment, and it's highly recommended to add it as the `{{TrackViaHost}}` variable. ### 2\. Incorrectly Entering Authorization Information [Permalink for this section](https://developer.trackvia.com/troubleshooting/postman-issues\#2-incorrectly-entering-authorization-information) Just as you would with Swagger, you should create an API user, the API Key, and a valid Auth Token before you begin working in Postman. You can read more about how to set these up in [this Help Center article (opens in a new tab)](https://help.trackvia.com/hc/en-us/articles/8700168754843-API-Authentication-and-Access). As mentioned above, it is recommended that you add your URL, API Key, and Auth Token as variables. Once you've added these variables, you will not need to re-enter their details and re-authenticate each time you test something in Postman. After you've selected an API call from the TrackVia collection, click on the "Params" tab, then click on the `{{UserKey}}` variable (see screenshot below) to add your API Key information as the variable in the same way as described above for adding the URL as the `{{TrackViaHost}}` variable. ![User Key param](https://developer.trackvia.com/_next/static/media/postman2a.bc0fc248.png) To enter your Auth Token information, click on the "Authorization" tab, and in the "Type" dropdown, select "Bearer Token". Then, click on the `{{AccessToken}}` variable to add your auth token details as a variable (see below). ![Authorization access token](https://developer.trackvia.com/_next/static/media/postman2b.ab651ec7.png) ### 3\. API User Does Not Have Access to Necessary TrackVia Resources [Permalink for this section](https://developer.trackvia.com/troubleshooting/postman-issues\#3-api-user-does-not-have-access-to-necessary-trackvia-resources) When working with Postman, error messages will appear in the “Body” section below where you entered the information such as your View ID for a "Get Record" call. **Keep in mind that whichever Auth Token you used for this call is connected to an API User, and you will only be able to access resources (such as Views) that have been assigned to the API User's role.** If the API User is set as a Super Admin, they will have access to all resources in the account. If you only want to access specific resources via the API, you will need to create a Role within each application in your account, assign the API User to the role, and assign whichever resources to that role that you want to access. For example, if you are using the "Get Record" call, you would enter a view ID and record ID in the corresponding "Value" fields as shown below. ![Path variables](https://developer.trackvia.com/_next/static/media/postman3a.70cde25c.png) After clicking the blue “Send” button, if you see a 401 error message in the "Body" section saying `“DENIED!!! - Record: XXXX either does not exist or you do not have access to it.”` (See screenshot below) ![Denied access error](https://developer.trackvia.com/_next/static/media/postman3b.aa743d97.png) That means that either: **a)** you incorrectly entered the Record ID and there are no records with that ID in the View you chose, or **b)** the API User associated with the Auth Token you used does not have the View in question assigned to their role, and so it cannot be accessed. To resolve this, make sure that the view you are referencing is assigned to whichever role the API User is assigned to. ### 4\. Other Systems Require Authentication Details to Be Entered Differently [Permalink for this section](https://developer.trackvia.com/troubleshooting/postman-issues\#4-other-systems-require-authentication-details-to-be-entered-differently) Note that if you are integrating with systems besides TrackVia, they may require you to enter your API Key and Auth Token details in different fields than we described above in section 2. For example, we entered our API Key information under the "Params" tab in the "Value" field next to "user\_Key". If you are integrating with another system, they may require you to enter your API Key under the "Headers" tab instead of the "Params" tab. And just as mentioned in the Swagger section above, keep in mind that other systems may have different definitions for what each API call does. If you are integrating with other systems, **be sure to refer to their API documentation as they may not have the same requirements as TrackVia, or use the API calls in the same way that TrackVia does.** Last updated on June 2, 2023 [Swagger issues](https://developer.trackvia.com/troubleshooting/swagger-issues "Swagger issues") [Common Error Response Code Examples](https://developer.trackvia.com/troubleshooting/common-errors "Common Error Response Code Examples") ; --- Troubleshooting Swagger issues # Common Swagger Errors And How To Resolve Them ![Troubleshooting](https://developer.trackvia.com/_next/static/media/Vector_Images_Scoping_tile_1.1b53eb44.svg) When testing API actions, the most common errors are caused by: - incorrectly inputting information such as using the wrong URL for the domain - not authorizing properly using the API Key and Auth Token - not assigning the necessary TrackVia resources to the API user The sections below identify the most common errors you may encounter while using Swagger and the steps to take to resolve them. ## Common Errors While Using Swagger [Permalink for this section](https://developer.trackvia.com/troubleshooting/swagger-issues\#common-errors-while-using-swagger) ### 1\. Incorrect Domain [Permalink for this section](https://developer.trackvia.com/troubleshooting/swagger-issues\#1-incorrect-domain) On the Swagger page, make sure to check the “domain” field at the top of the page. Note that it defaults to go.trackvia.com, which should work for most cases if your account is on the standard PRODUCTION environment. If your account is on the GOV or HIPAA environments, you will need to edit the domain field accordingly. If your account uses a custom subdomain, you can use the default go.trackvia.com, or enter your custom subdomain here, but note that it will not work if the custom subdomain is not entered exactly as it appears in your account. If you input the incorrect URL in the domain field and try to execute an action, you will receive an error message as seen below: ![Swagger Incorrect Domain](https://developer.trackvia.com/_next/static/media/swagger1.2a8a6a43.png) ### 2\. Incorrectly Entering Authorization Information [Permalink for this section](https://developer.trackvia.com/troubleshooting/swagger-issues\#2-incorrectly-entering-authorization-information) Before you start working with Swagger or Postman, make sure you've created an API user, the API Key, and a valid Auth Token. You can read more about how to set these up in [this Help Center article (opens in a new tab)](https://help.trackvia.com/hc/en-us/articles/8700168754843-API-Authentication-and-Access). In Swagger, once all of those have been created, note that you will need to click the “Authorize” button at the top of the page. If you have not authorized, the lock icon next to the Authorize button will be unlocked, and if you try to enter information such as a View ID, it will be grayed out and not allow you to click into the field as shown in the screenshots below. ![Authorize](https://developer.trackvia.com/_next/static/media/swagger2a.a95bf31c.png) ![Get/views](https://developer.trackvia.com/_next/static/media/swagger2b.22dbb2ec.png) When you click on the Authorize button at the top of the page, you will need to go to your TrackVia application, click on the person icon in the top right corner, open “My Account” and click on the “API Access” section where you can copy your API key and Auth Token, paste them into the fields shown below, and click “Authorize” next to each one. ![Available auths](https://developer.trackvia.com/_next/static/media/swagger2c.b37990ca.png) Once you've entered the API Key and Auth Token values as above and clicked “Authorize”, you'll notice that the lock icon now appears locked. Now, when you find the action you want to try on the page, click the “Try it out” button and you can now enter values in the fields on the page. Finally, click “Execute” to get your results. ### 3\. API User Does Not Have Access to Necessary TrackVia Resources [Permalink for this section](https://developer.trackvia.com/troubleshooting/swagger-issues\#3-api-user-does-not-have-access-to-necessary-trackvia-resources) When working with Swagger, error messages will appear in the “Response body” section. **Keep in mind that whichever Auth Token you used to authorize on the Swagger page is connected to an API User, and you will only be able to access resources (such as Views) that have been assigned to the API User's role.** If the API User is set as a Super Admin, they will have access to all resources in the account. If you only want to access specific resources via the API, you will need to create a Role within each application in your account, assign the API User to the role, and assign whichever resources to that role that you want to access. For example, you are using the `GET /views/{viewID}` to return a list of records in a view, you enter a view ID, and after clicking “Execute” you see a 401 error message in the Response body saying `“DENIED!!! - View XXXX either does not exist or you do not have access to it.”` (See screenshot below) ![Denied Error](https://developer.trackvia.com/_next/static/media/swagger3.cd5203e6.png) That means that either **a)** you incorrectly entered the View ID and it does not correspond to any views in your account, or **b)** the API User associated with the Auth Token you used to authorize the Swagger page does not have the View in question assigned to their role, and so it cannot be accessed. ### 4\. Not Using the Correct API Call While Integrating With Other Systems [Permalink for this section](https://developer.trackvia.com/troubleshooting/swagger-issues\#4-not-using-the-correct-api-call-while-integrating-with-other-systems) In TrackVia, the API calls are detailed below. Note that the example below is for the "Records" section: - POST = Create Record - DEL = Delete Records in a View - GET = Get Record - PUT = Update Record If you are integrating with other systems, **be sure to refer to their API documentation as they may not use the API actions in the same way as TrackVia**, which can be confusing and cause errors. Last updated on June 5, 2023 [FAQ](https://developer.trackvia.com/microservices/faq "FAQ") [Postman issues](https://developer.trackvia.com/troubleshooting/postman-issues "Postman issues") ;