You are viewing the Resources for the older version of JourneyApps (V3). JourneyApps V4 is the new default for all new apps since July 1, 2016.
V1

The JourneyApps API (V1) → 1. Getting Started

Enabling the API

The API is configured on an App Instance level, which means that each instance of your app that is deployed to an environment (for example, Testing, Staging or Production) has its own API credentials.

To obtain the API credentials for a specific App Instance, go to the Deploy page for the app in the JourneyApps Editor and click on Manage API for the appropriate environment.

On the page that opens next, you'll see the API credentials for the App Instance which consist of a username and password. Please keep this information private and record it in a secure place.

HTTP Endpoints

An endpoint is the base URL that you connect to when using the API.

Base URL and Relative URL

Throughout the rest of the documentation, we'll indicate the URL that you need to use relative to the base URL to perform a particular function (e.g. Retrieve Objects, Create an Object, Update an Object, etc). For example, in the section Creating New Objects, we indicate that you need to send an HTTP POST request to the relative URL /api/v1/object-type.format in order to create an object. In other words, let's say you want to create a new 'car' object in the "Testing" environment of your app with a JSON response data format, and you're using the United States region, you'll send an HTTP request to:
https://run-testing.journeyapps.com/api/v1/car.json

The endpoints for the various regions and environments are shown below:

Region Environment Endpoint
United States Testing https://run-testing-us.journeyapps.com/api/v1
Staging https://run-staging-us.journeyapps.com/api/v1
Production https://run-us.journeyapps.com/api/v1
European Union Testing https://run-testing-eu.journeyapps.com/api/v1
Staging https://run-staging-eu.journeyapps.com/api/v1
Production https://run-eu.journeyapps.com/api/v1
Australia Testing https://run-testing-au.journeyapps.com/api/v1
Staging https://run-staging-au.journeyapps.com/api/v1
Production https://run-au.journeyapps.com/api/v1
South Africa Testing https://run-testing.journeyapps.com/api/v1
Staging https://run-staging.journeyapps.com/api/v1
Production https://run.journeyapps.com/api/v1

Authentication

The API uses HTTP Basic Authentication.

Your API username and password (refer to the Enabling the API section above) must be specified for each request.

All requests to the API must occur via HTTPS.

Request Parameter Formats

Parameters supplied to API functions may be in any of the following formats. It may be necessary to set the Content-Type HTTP header as shown.

Format Content-Type Header Example
JSON application/json {"client":{"address":"123 South"}}
URL-encoded
key-value pairs 		application/x-www-form-urlencoded
This is the default for POST requests and usually does not have to be specified explicitly 		client[address]=123%20South
XML application/xml

How do I format the attributes?

For details on how to format the object attributes that you send to the API, please see the Attribute Representation section.

Response Data Formats

API responses may be requested in either XML or JSON data formats. The format may be specified either:

  • Using the Accept HTTP header (in Internet media type format)
  • By appending the format to the end of the URL (for example: https://run.journeyapps.com/api/v1/assets.json where json is the format)

Valid values for the format are shown below:

Format Accept Header format argument
JSON (Default) application/json json
XML application/xml xml

In what format will my attributes be returned?

For details on how your object attributes received from the API will be formatted, please see the Attribute Representation section.

Error Handling

Response Codes

The API uses standard HTTP status codes to indicate the outcome of an API request.

  • A status code of 200 indicates that the operation completed successfully.
  • Any other status code indicates that the operation has failed:
    • A status code in the 4xx range indicates that invalid input from your side is responsible for the error.
    • A status code in the 5xx range indicates that an internal server error on the JourneyApps side is responsible for the error.

Specific examples of status codes are shown below.

Status Code Meaning
200 OK - The request completed successfully.
400 Bad request, usually a missing required parameter.
401 Authentication failed: Check your username, password and whether the API is enabled for your app instance.
404 Not found: The supplied object ID does not exist, or the path / URL does not exist.
Please Note: Don't confuse a 404 returned by the API for a URL that does not exist. A 404 means that the object that you tried to retrieve does not exist (in accordance with the REST convention).
500 Internal server error: Something went wrong on the JourneyApps side. Please contact JourneyApps Support.

Response Data

The response body will contain a list of all errors.

Examples

XML

JSON

Next Section: 2. Retrieving All Objects
Next Section