Skip to main content

Introduction

Welcome to the documentation for the Journyx API!

Journyx is the premier employee time entry and cost and profitability tracking solution for companies of all sizes. The Journyx API allows you to interact with the Journyx application server and database programmatically, enabling you to integrate Journyx with other applications and enterprise systems.

Important links

Overview​

This website contains the documentation for the Journyx (JX) web application programming interface (API). This is the same API that is used by the Journyx web application user interface (UI), as well as the JX mobile apps (Android and iOS), to interact with the Journyx application server and database.

You can use the APIs provided by Journyx to integrate the Journyx app with other applications, such as your company's HR system, accounting system, data warehouse or reporting system.

If you want to jump right in and start making API requests, check out the Tutorial section for a step-by-step guide to making your first API request to the Journyx API.

OpenAPI Specification file

The API Reference section is generated from the OpenAPI Specification file for the Journyx REST API. You can also access the OpenAPI Specification file directly here:

The OpenAPI spec file can be useful for generating client libraries, and for importing into a tool like Postman for interactive API exploration and documentation. Here's how to import an OpenAPI file into Postman.

A word about URLs...

The OpenAPI spec file linked above, and used throughout the rest of this site, is set up to use a placeholder base URL of https://example.apps.journyx.com. Before making real API calls to your actual Journyx site, you will need to replace example with your actual site name.

This includes the interactive examples in the API Reference section, which will not work until you replace the base URL with your own site name. It also includes use of the OpenAPI specification file. Before you import the OpenAPI spec file into a tool like Postman, you may need to update the base URL there as well.

Resources available here​

This documentation consists of the following major sections:

  • General information about working with the Journyx APIs, including topics like authentication, working with custom fields and collections, and a tutorial.

  • Reference documentation for the Journyx REST API, including detailed information about the available endpoints, request and response formats with examples. This information is compiled from an OpenAPI specification file, which can be downloaded here.

  • Documentation for the legacy SOAP API, which is still available for use but is considered deprecated in favor of the REST API.

  • Documentation for other legacy or miscellaneous APIs, such as the Reportlink API.

Types of APIs​

The term API encompasses a wide range of functionality available from multiple endpoints or URLs using a variety of programming styles. This documentation may refer to the following types of APIs:

  • REST APIs

    • The REST or "RESTful" API is a web service that uses standard HTTP methods (GET, POST, PUT, DELETE) to interact with the Journyx application server using the "REST" principles, or Representational State Transfer, which attempts to provide a consistent and predictable way to interact with the application.

      REST API status

      Currently, the REST API is under active development and not all object types and operations are available yet. We are working diligently to add new endpoints and improve the developer experience.

    • This is the recommended API for most integrations with Journyx where possible. This documentation mainly covers the REST API, particularly the API Reference section.

    • A summary of working with the REST API can be found on the Core Concepts page, and a detailed tutorial is available as well.

  • SOAP or WSDL APIs

    • This is a legacy API that uses the SOAP (Simple Object Access Protocol) and WSDL (web services description language) standards to interact with the Journyx application server.

    • It uses an older programming style that can be more complicated and difficult to interact with, and is less performant because it does not support paginated responses or other modern features.

    • However, this API has relatively complete coverage of product features and is still available for use.

    • The SOAP API documentation is available here.

  • Reportlink API

    • This is a special endpoint /jtcgi/delimited.pyc that can be used to retrieve data from the Journyx database in a CSV (comma separated values) or tab-delimited format.

    • Among other things, it can pull data from Standard Report configurations in the Journyx UI.

    • TODO: This API is not yet documented here, but we plan to add documentation for it in the future.

  • Other ad-hoc APIs

    • These are internal-use APIs that are not generally available for use by customers or end-users.

    • Many of these are in the process of being replaced by the REST API.

Working with the API​

The Journyx (JX) application is delivered as a Software as a Service (SaaS) product, and each customer gets a dedicated site with a unique URL to serve as their product instance. All API access is done through this URL, which will be referred to as the "base URL" in this documentation, for example:

https://example.apps.journyx.com

Where example represents the customer's unique site name.

This documentation website is set up to use the base URL https://example.apps.journyx.com, including in the interactive examples, but this is not a real site. You will need to replace example with your own site name when working with the API.

A word about labels and feature names

It's important to understand that names (labels) of many things can be customized in Journyx, but this documentation will use the default names for consistency and clarity. For example, in Journyx the primary organizing time entry column is called "Project" by default, but in your company's deployment it may be called "Job", or "Cost Center", or some other term.

Programming languages​

The Journyx API is a web service that can be accessed from any programming language that can make HTTP requests. This includes but is not limited to:

  • JavaScript (Node.js, browser)
  • Python
  • C / C++
  • Java / Kotlin
  • C# / .NET

A simple example of interacting with the REST API in Python and JavaScript is provided in the programming tutorial section.

Other parts of the tutorial show how to use the API with tools that support making direct HTTP requests, such as Postman, or in this case, the "REST Client" extension available for the free Visual Studio Code editor.

This will allow us to directly compose HTTP requests and see the responses without worrying about the details of how to code the request in any particular programming language.

Getting Started​

To get started with the Journyx API, you will need to:

  1. Make sure you know the base URL for your Journyx instance as mentioned above. This is the URL that you use to access the Journyx web application in your web browser, such as https://example.apps.journyx.com.

  2. Create an API key in the Journyx application UI. It is also possible to use Basic Authentication with a regular username and password, but this is only recommended for development or testing purposes; for live production use, an API key is recommended. See the Authentication section for more information.

  3. Using a tool like Postman, or the REST Client extension in VS Code, or the programming language of your choice, you can start making requests to the Journyx API using the base URL and API key as shown in this Tutorial section.

Next steps​

Be sure to check out the following pages:

  • The Core Concepts page for a general overview of interacting with the Journyx REST API.

  • See About REST APIs for background information on the REST philosophy and how it applies to the Journyx API and contrasts with the legacy SOAP API.

  • The Tutorial section should be your next destination for a step-by-step guide to making your first API request to the Journyx API.

  • The Collections page is a good place to learn about pagination, sorting, and filtering in the Journyx API.

API Topics​

Aside from the Tutorial and API Reference sections, the following general topics are covered in this documentation:

Unfinished content

Many of these pages are still under construction and may not be complete or fully accurate.