fairjungle (2.0.0)

You need an API Key or an OAuth Access Token associated to a user with admin role in order to authenticate API requests.

An API Key or an OAuth Access Token carry many privileges, so be sure to keep them secure! Do not share them in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication is performed via HTTP Authorization header. Example:

  Authorization: Bearer BdA5ijnMx8m7dqX0Fnl7NmB18etmVhFI

All API requests must be made over HTTPS.

Our custom REST API allows you to manage fairjungle resources.

A JSON object is at the root of every request and response containing data. This object defines a document’s “top level”.

A request document may contain the following top-level member:

• data: the document’s “primary data”

A successfull response document may contain the following top-level members:

• data: the document’s “primary data”
• meta: additional informations

Primary data is either:

• a single resource object for requests that target single resources
• an array of resource objects, or an empty array ([]), for requests that target resource collections

The resource attributes that have no value are not returned, except for booleans attributes that always have a false default value. It means that server nevers sends null values in resource data.

Data can be fetched by sending a GET request to an endpoint.

For example, the following request fetches a collection of users:

GET /api/users

The following request fetches a user:

GET /api/users/35c93884-5cca-4e72-98ff-eb52f611cb21

200 OK

The server responds to a successful request to fetch an individual resource or resource collection with a 200 OK response.

The server responds to a successful request to fetch a resource collection with an array of resource objects or an empty array ([]) as the response document’s primary data.

The server responds to a successful request to fetch an individual resource with a resource object provided as the response document’s primary data.

401 Unauthorized

The server responds with 401 Unauthorized when processing a request without authentication.

403 Forbidden

The server returns 403 Forbidden in response to an unsupported request to retrieve a resource.

404 Not Found

The server responds with 404 Not Found when processing a request to fetch a single resource that does not exist.

All endpoints that return resource collections are paginated. A default pagination is applied if no pagination parameter is provided by client.

There are two kinds of paginations:

• Offset based pagination
• Cursor based pagination

The offset based pagination is supported by all endpoints, and it is the default pagination. Additionally, some endpoints may support cursor based pagination. Please refer to each individual endpoint documentation for more info.

To use cursor based pagination with endpoints that support it, then you have to set the pageKind query parameter with cursor as value.

Offset based pagination

Offset based pagination query parameters are:

• pageKind: offset
• limit: maximum number of items to return (default: 10)
• offset: number of items to skip (default: 0)

The meta top-level member in the response document contains those fields:

• pageKind: offset
• limit: the query parameter value
• offset: the query parameter value
• total: the total number of items on the server

Cursor based pagination

Cursor based pagination query parameters are:

• pageKind: cursor
• limit: maximum number of items to return (default: 10)
• after: a cursor value that identifies the first item to retrieve
• before: a cursor value that identifies the last item to retrieve

The after and before parameters are mutually exclusive: only one of after or before may be used.

The meta top-level member in the response document contains those fields:

• pageKind: cursor
• limit: the query parameter value
• after: the query parameter value
• before: the query parameter value
• nextAfter: a cursor value that can be used to retrieve next items with after query parameter
• prevBefore: a cursor value that can be used to retrieve previous items with before query parameter

Endpoints that return resource collections accepts additional query parameters to control sorting of returned resources:

• order: sorting order (default: asc)
• sortBy: sorting field (default: createdAt)

The meta top-level member in the response document contains those fields:

• order: the query parameter value
• sortBy: the query parameter value

The allowed order values are asc and desc.

The allowed sortBy values are endpoint specific. Please refer to each individual endpoint documentation for more info.

A resource can be created by sending a POST request to a URL that represents a collection of resources. The request includes a single resource object as primary data.

Responses

201 Created

If the requested resource has been created successfully, the server returns a 201 Created status code.

The response also includes a document that contains the primary resource created.

401 Unauthorized

The server responds with 401 Unauthorized when processing a request without authentication.

403 Forbidden

The server returns 403 Forbidden in response to an unsupported request to create a resource.

422 Unprocessable Entity

The server returns 422 Unprocessable Entity when processing a POST request to create a resource if the resource validation failed.

A resource can be:

• partially updated by sending a PATCH request to the URL that represents the resource
• entirely replaced by sending a PUT request to the URL that represents the resource

The request includes a single resource object as primary data.

The patching mecanism follows the JSON merge patch specification:

• If a request does not include all of the attributes for a resource, the server interprets the missing attributes as if they were included with their current values.
• An attribute can be deleted by explicitly sending the null value.
• The server does not interpret missing attributes as null values.

If you use the PUT method, then:

• If a request does not include all of the attributes for a resource, the server interprets the missing attributes as if they were deleted.
• An attribute can still be deleted by explicitly sending the null value.

Responses

200 OK

The server returns a 200 OK status code if an update is successful. The response document includes a representation of the updated resource as if a GET request was made to the request URL.

401 Unauthorized

The server responds with 401 Unauthorized when processing a request without authentication.

403 Forbidden

The server returns 403 Forbidden in response to an unsupported request to update a resource.

404 Not Found

The server returns 404 Not Found when processing a request to modify a resource that does not exist.

422 Unprocessable Entity

The server returns 422 Unprocessable Entity when processing a PATCH request to update a resource if the resource validation failed.

An individual resource can be deleted by making a DELETE request to the resource’s URL.

Responses

200 OK

The server returns a 200 OK status code if a deletion request is successful. The response document includes a representation of the resource before deletion.

401 Unauthorized

The server responds with 401 Unauthorized when processing a request without authentication.

403 Forbidden

The server returns 403 Forbidden in response to an unsupported request to delete a resource.

404 Not Found

The server returns a 404 Not Found status code if a deletion request fails due to the resource not existing.

Fairjungle uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided. Codes in the 5xx range indicate a server error.

The error response provides additional information about problems encountered while performing an operation.

This is the error response schema:

The error response always have the following fields:

• code: an application-specific error code, expressed as a string value.
• message: a short, human-readable summary of the problem.

The error response may have the following field:

• invalid: if error code is validationFailed or invalidParam then that field contains an array of error details with associated invalid fields or parameters

Items in the invalid array have the following fields:

• field: field or parameter name
• value: invalid value received
• code: validation code
• message: validation message

Example for a 400 Bad Request error:

{
  "code": "badRequest",
  "message": "Top-level document 'data' member is missing"
}

Example for a 400 Bad Request error with invalid parameter:

{
  "code": "invalidParam",
  "invalid": [
    {
      "code": "paramValue",
      "field": "limit",
      "message": "limit parameter must be between 1 and 100",
      "value": 500
    }
  ],
  "message": "Invalid pagination parameter provided"
}

Example for a 422 Unprocessable Entity error:

{
  "code": "validationFailed",
  "invalid": [
    {
      "code": "country",
      "field": "address.country",
      "message": "The 'country' field is invalid",
      "value": "PLOP"
    },
    {
      "code": "email",
      "field": "email",
      "message": "The 'email' field is invalid",
      "value": "john @mycompany.com"
    },
    {
      "code": "required",
      "field": "name",
      "message": "The 'name' field is mandatory",
      "value": ""
    }
  ],
  "message": "Resource validation failed"
}

A billing operation represents the lowest billing granularity.

The transactionKind field:

A purchase billing operation is created:

• when fairjungle booked a trip on your behalf (a billing operation is created for each part of the trip)
• when your subscription invoice is emitted

A refund billing operation is created when a booking is canceled, or when a manual refund is issued. There are then two cases:

• if this is done before the corresponding invoice is emitted, then the invoice balance is adjusted and no refund resource is created (ie. the refundId attribute is null)
• if this is done after the corresponding invoice was emitted, then a money transfer is performed, a refund resource is created, and the refundId attributed is filled

A dispute billing operarion is created when our billing provider detects an issue with an already paid invoice, and automatically refunds back the invoice charge to your bank account. A dispute resource is created, and the refundId attributed is filled. This is a special case that must be regularized with our support team. Note that the dispute does not appear on the invoice, and no refund resource is created.

The operationType field:

An operation can be:

• a booking related operation, with either the generic booking value, or with one of the more specific values: car, flight, hotel, rail or seminar
• a subscription operation
• an other operation (performed by the support team)

In case of booking operation, the bookingSnapshot field contains the informations at the time of the booking, and if booking was performed via online channel then the tripProjectId field links to the corresponding trip project.

The status field:

This field value depends on transactionKind field:

• purchase: this is either the status of the corresponding invoice resource, or delayed if no invoice was emitted yet. Possible values: delayed, open, paid, uncollectible and void.
• refund: this is either the status of the corresponding refund resource if corresponding invoice status is paid, or delayed if refund is performed while the corresponding invoice status is still open, otherwise succeeded if no invoice was emitted yet. Possible values: delayed, waiting, pending, succeeded, failed and canceled.
• dispute: this is the status of the corresponding dispute resource.

This is the billingOperation resource schema:

Each billing profile has its own payment method and billing informations.

NOTE: you can't associate a payment method to a billing profile through the API.

This is the billingProfile resource schema:

Associating users to cost centers permit to tag emitted invoices with cost centers.

This is the costCenter resource schema:

Associate custom fields to resources.

This is the customField resource schema:

This is the customFieldOption resource schema: