REST API

Use the REST API addon to integrate with web services and unleash the power of JReviews beyond your website.

Demo

Below you can see a little directory app that uses the API with our JReviews demo site. The app was developed using Ionic Vue.

We've made the source code available for free on Github. → Get the code. We are not providing support for building or integrating with existing mobile apps. The code is shared as is to be used as a reference.

Our demo refreshes periodically so if the app doesn't load, try waiting a bit and then re-load the page.

To sign-in to the app use:

Getting Started

The first step to get started with the JReviews REST API is to create the JReviews REST API menu. This will be used as the base URL for all endpoints. For example, if the slug for the REST API menu is directory-api and you want to get a list of listings via the /jreviews/listings endpoint, the URL would be:

https://jreviews.com/directory-api/jreviews/listings

Authentication

The API uses Bearer tokens to authenticate existing site users. API requests that create or modify data must include the Bearer token in the Authorization header.

Once you have a token, using it in the Authorization header for read-only requests allows obtaining user-specific information. For example:

  • Permissions letting you know if the user can update, delete, or add media to an object.
  • Information about whether a listing is in the user's favorites.

This is useful when building an app because it allows you to incorporate this information into the UI/UX without having to perform additional requests.

Endpoints
post
post
get

Create User Account

Register a new user account. This endpoint uses basic core Joomla and WordPress functionality for user registration.

Payload Parameters

name

required

User's Full Name

username

required

User's username

email

required

Account email

password

required

Account password

device

optional

Allows specifying a string identifier for the device used to register which can be associated with the generated user token on successful regisration.

Returns

If user accounts are automatically activated, the request returns a user object with Bearer token to use in Authorization header in sub-sequent requests. Otherwise a `pending-activation` status is returned.

In WordPress all accounts are automatically activated. In Joomla it depends on the site's configuration.

request
post /jreviews/auth/register
response 
// Automatic activation

{
    "id": 100,
    "avatar": "",
    "email": "",
    "name": "",
    "token": ""
}

// Pending activation

{
    "status": "pending_activation",
    "token": "User successfully registered. Needs to be activated using email activation link."
}

Connect User

Retrieve the user token to use in requests requiring authentication, and also non-authenticated requests that will provide more user-specific information like permissions.

Payload Parameters

email

required

User account email

password

required

User account password

device

optional

Allows specifying a string identifier for the device used to login which can be associated with the generated user token.

Returns

User object with Bearer token to use in Authorization header in sub-sequent requests.

request
post /jreviews/auth/email
response 
{
    "id": 100,
    "avatar": "",
    "email": "",
    "name": "",
    "token": ""
}

Logout User

Log out the user by invaliding the token.

Parameters

No parameters

Returns

Returns a successful message if the call succeeded.

request
Header Authorization: Bearer USER_TOKEN_HERE required
get /jreviews/auth/logout
response 
{
    "message" => "User was logged out."
}

Listings

Listings can be pretty much anything you want (products, news, services, businesses, people, etc.) and they each belong to one category.
Endpoints
post
get
patch
get
delete

Create Listing

Create a listing.

Payload Parameters

cat

required

A category ID to which the listing will be assigned.

title

required

The title for the listing.

summary

configuration dependent

The listing's summary, shown in list and detail pages. When a lisitng summary is not provided, the a truncated version of the listing description will be used in list pages.

description

configuration dependent

The listing's description, shown in detail pages.

metakey

optional

The content for listing's meta description tag.

metadesc

optional

The content for the listing's meta keywords tag.

fields

optional

An array of custom field name/value pairs to store with the listing. For example: 

"fields" => [
    "jr_state" => "california"
]

For fields with pre-defined options, use the reference option `value` (i.e. california rather of California). For multiple option fields, specify the values as an array 

"fields" => [
    "jr_amenities" => [
        "wifi", 
        "breakfeast"
    ]
]

Returns

A listing object.

request
Header Authorization: Bearer USER_TOKEN_HERE required
post /jreviews/listings
response 
{
    "id": 123,
    "link": "https://jreviews.com/directory-api/jreviews/listings/123",
    "web": "https://jreviews.com/businesses/acme-inc",
    "title": "Acme Inc",
    "alias": "acme-inc",
    "created": "2022-08-04 15:59:54",
    "featured": false,
    "category": {
        "id": 10,
        "title": "Businesses"
    },
    "summary": "",
    "description": "",
    "metadesc": "",
    "metakey": "",
    "user": {}
    "fields": [
        { 
            "name": "jr_state",
            "label": "State",
            "type": "select",
            "selected_values": [
                "california"
            ]
            "selected_text": [
                "California"
            ]
        }
    ],
    "photos": [],
    "attachments": [],
    "aggregates": [],
    "permissions": {}
}

Get Listing

Get a single listing.

URL Parameters

id

required

The listing ID

Query String Parameters

layout

optional

Specify the type of page making the request to automatically exclude custom fields not visible for that layout. Supported values are: list, detail,

exclude

optional

Exclude one or more relations from the object response. The parameter allows multiple comma separated values: user, fields, photos, attachments, aggregates. The fields relation also supports excluding specific fields: fields[jr_latitude,jr_longitude]

include

optional

The include parameter allows specifying which relations to include in the response. At this time it only allows including specific custom fields, while excluding all others. The supported format is: fields[jr_state,jr_city]

Returns

A listing object.

request
Header Authorization: Bearer USER_TOKEN_HERE optional
get /jreviews/listings/123
response 
{
    "id": 123,
    "link": "https://jreviews.com/directory-api/jreviews/listings/123",
    "web": "https://jreviews.com/businesses/acme-inc",
    "title": "Acme Inc",
    "alias": "acme-inc",
    "created": "2022-08-04 15:59:54",
    "featured": false,
    "category": {
        "id": 10,
        "title": "Businesses"
    },
    "summary": "",
    "description": "",
    "metadesc": "",
    "metakey": "",
    "user": {}
    "fields": [
        { 
            "name": "jr_state",
            "label": "State",
            "type": "select",
            "selected_values": [
                "california"
            ]
            "selected_text": [
                "California"
            ]
        }
    ],
    "photos": [],
    "attachments": [],
    "aggregates": [],
    "permissions": {}
}

Update Listing

Update a listing.

URL Parameters

id

required

ID of the listing that is being updated.

Payload Parameters

title

optional

The title for the listing.

summary

optional

The listing's summary, shown in list and detail pages. When a lisitng summary is not provided, the a truncated version of the listing description will be used in list pages.

description

optional

The listing's description, shown in detail pages.

metakey

optional

The content for listing's meta description tag.

metadesc

optional

The content for the listing's meta keywords tag.

fields

optional

An array of custom field name/value pairs to store with the listing. For example: 

"fields" => [
    "jr_state" => "california"
]

For fields with pre-defined options, use the reference option `value` (i.e. california rather of California). For multiple option fields, specify the values as an array 

"fields" => [
    "jr_amenities" => [
        "wifi", 
        "breakfeast"
    ]
]

Returns

A listing object.

request
Header Authorization: Bearer USER_TOKEN_HERE required
patch /jreviews/listings/:id
response 
{
    "id": 123,
    "link": "https://jreviews.com/directory-api/jreviews/listings/123",
    "web": "https://jreviews.com/businesses/acme-inc",
    "title": "Acme Inc",
    "alias": "acme-inc",
    "created": "2022-08-04 15:59:54",
    "featured": false,
    "category": {
        "id": 10,
        "title": "Businesses"
    },
    "summary": "",
    "description": "",
    "metadesc": "",
    "metakey": "",
    "user": {}
    "fields": [
        { 
            "name": "jr_state",
            "label": "State",
            "type": "select",
            "selected_values": [
                "california"
            ]
            "selected_text": [
                "California"
            ]
        }
    ],
    "photos": [],
    "attachments": [],
    "aggregates": [],
    "permissions": {}
}

List Listings

Get a list of listings.

Query String Parameters

page

optional

Page number when list has multiple pages.

limit

optional

, default is 15

Number of results per page. Maximum is 20.

cat

optional

Category ID to filter listings.

layout

optional

Specify the type of page making the request to automatically exclude custom fields not visible for that layout. Supported values are: list, detail, comparison

exclude

optional

Exclude one or more relations from the object response. The parameter allows multiple comma separated values: user, fields, photos, attachments, aggregates. The fields relation also supports excluding specific fields: fields[jr_latitude,jr_longitude]

include

optional

The include parameter allows specifying which relations to include in the response. At this time it only allows including specific custom fields, while excluding all others. The supported format is: fields[jr_state,jr_city]

q

optional

Search keywords to filter listings.

lat + lng

optional

Use lat (latitude )and lng (longitude) parameters to perform a geographical search.

radius

optional

, default is uses site config

Radius to use for geographical searches.

distance_in

optional

, default is uses site config

Distance metric for geographical searches. Allowed values: km, mi.

sort

optional

, default is created

The field you want to sort by. Supported values are: created, -created, title, -title, updated, -updated, rating, -rating featured

Returns

An object containing the array of listing objects and meta data for pagination.

request
Header Authorization: Bearer USER_TOKEN_HERE optional
get /jreviews/listings
response 
{
    "data": [
        {
            "id": 123,
            ...
        },
        {
            "id": 124,
            ...
        },
        ...
    ],
    "links": {
        "first": "https://jreviews.com/directory-api/jreviews/listings/?pg=1",
        "last": "https://jreviews.com/directory-api/jreviews/listings/?pg=22",
        "prev": null,
        "next": "https://jreviews.com/directory-api/jreviews/listings/?pg=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 22,
        "links": [...],
        "path": "https://jreviews.com/directory-api/jreviews/listings/",
        "per_page": 15,
        "to": 15,
        "total": 326
    }
]

Delete Listing

Delete a listing.

URL Parameters

id

required

The listing ID.

Returns

Returns a successful message if the call succeeded.

request
Header Authorization: Bearer USER_TOKEN_HERE required
delete /jreviews/listings/:id
response 
{
    "message" => "Listing was successfully deleted."
}

Comments

Endpoints
post
get
patch
get
get
delete

Create Comment

Create a listing comment which can include ratings if these are setup for the listing type.

Payload Parameters

title

configuration dependent

The comment title.

comments

configuration dependent

The comment body.

ratings

configuration dependent

Array of rating values keyed by rating criteria ID. 

"ratings" => [
    1 => 5,
    2 => 4,
]

fields

optional

An array of custom field name/value pairs to store with the listing. For example: 

"fields" => [
    "jr_visitwasfor" => "leisure"
]

For multiple option fields, specify the values as an array

Returns

A comment object.

request
Header Authorization: Bearer USER_TOKEN_HERE required
post /jreviews/listings/:id/comments
response 
{
    "id": 63,
    "link": "https://jreviews.com/directory-api/jreviews/comments/63",
    "title": "Delicious!",
    "comment": "This makes for a perfect dessert and it's delicious. The mint adds a nice touch.",
    "created": "2022-07-17T15:50:14.000000Z",
    "user": {},
    "rating": 5,
    "rating_criteria": [
    {
        "id": 1,
        "title": "Easy",
        "rating": 5
    },
    {
        "id": 2,
        "title": "Tasty",
        "rating": 4
    }
    ],
    "owner_reply": null,
    "listing": {},
    "fields": [],
    "photos": [],
    "aggregates": {},
    "permissions": {},
}

Get Comment

Get a single comment.

URL Parameters

id

required

The comment ID

Query String Parameters

layout

optional

Specify the type of page making the request to automatically exclude custom fields not visible for that layout. Supported values are: list, detail,

exclude

optional

Exclude one or more relations from the object response. The parameter allows multiple comma separated values: user, fields, photos, attachments, aggregates. The fields relation also supports excluding specific fields: fields[jr_pros,jr_cons]

include

optional

The include parameter allows specifying which relations to include in the response. At this time it only allows including specific custom fields, while excluding all others. The supported format is: fields[jr_pros,jr_cons]

Returns

A comment object.

request
Header Authorization: Bearer USER_TOKEN_HERE optional
get /jreviews/comments/:id
response 
{
    "id": 63,
    "link": "https://jreviews.com/directory-api/jreviews/comments/63",
    "title": "Delicious!",
    "comment": "This makes for a perfect dessert and it's delicious. The mint adds a nice touch.",
    "created": "2022-07-17T15:50:14.000000Z",
    "user": {},
    "rating": 5,
    "rating_criteria": [
    {
        "id": 1,
        "title": "Easy",
        "rating": 5
    },
    {
        "id": 2,
        "title": "Tasty",
        "rating": 4
    }
    ],
    "owner_reply": null,
    "listing": {},
    "fields": [],
    "photos": [],
    "aggregates": {},
    "permissions": {},
}

Update Comment

Update a comment.

URL Parameters

id

required

ID of the comment that is being updated.

Payload Parameters

title

optional

The comment title.

comments

optional

The comment body.

ratings

optional

Array of rating values keyed by rating criteria ID. 

"ratings" => [
    1 => 5,
    2 => 4,
]

fields

optional

An array of custom field name/value pairs to store with the listing. For example: 

"fields" => [
    "jr_visitwasfor" => "leisure"
]

For multiple option fields, specify the values as an array

Returns

A comment object.
request
Header Authorization: Bearer USER_TOKEN_HERE required
patch /jreviews/comments/:id
response 
{
    "id": 63,
    "link": "https://jreviews.com/directory-api/jreviews/comments/63",
    "title": "Delicious!",
    "comment": "This makes for a perfect dessert and it's delicious. The mint adds a nice touch.",
    "created": "2022-07-17T15:50:14.000000Z",
    "user": {},
    "rating": 5,
    "rating_criteria": [
    {
        "id": 1,
        "title": "Easy",
        "rating": 5
    },
    {
        "id": 2,
        "title": "Tasty",
        "rating": 4
    }
    ],
    "owner_reply": null,
    "listing": {},
    "fields": [],
    "photos": [],
    "aggregates": {},
    "permissions": {},
}

List Comments

Get a list of comments.

Query String Parameters

layout

optional

Specify the type of page making the request to automatically exclude custom fields not visible for that layout. Supported values are: list, detail,

exclude

optional

Exclude one or more relations from the object response. The parameter allows multiple comma separated values: user, fields, photos, attachments, aggregates. The fields relation also supports excluding specific fields: fields[jr_pros,jr_cons]

include

optional

The include parameter allows specifying which relations to include in the response. At this time it only allows including specific custom fields, while excluding all others. The supported format is: fields[jr_pros,jr_cons]

limit

optional

, default is 15

Number of results per page. Maximum is 20.

sort

optional

, default is created

The field you want to sort by. Supported values are: created, -created, rating, -rating, updated -updated

Returns

An object containing the array of comment objects and meta data for pagination.

request
Header Authorization: Bearer USER_TOKEN_HERE optional
get /jreviews/comments
response 
{
    "data": [
        {
            "id": 63,
            ...
        },
        {
            "id": 64,
            ...
        },
        ...
    ],
    "links": {
        "first": "https://jreviews.com/directory-api/jreviews/comments/?pg=1",
        "last": "https://jreviews.com/directory-api/jreviews/comments/?pg=5",
        "prev": null,
        "next": "https://jreviews.com/directory-api/jreviews/comments/?pg=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 5,
        "links": [...],
        "path": "https://jreviews.com/directory-api/jreviews/comments/",
        "per_page": 15,
        "to": 15,
        "total": 70
    }
]

List Listing Comments

Get a list of comments for a specific listing.

URL Parameters

id

required

The listing ID

Query String Parameters

layout

optional

Specify the type of page making the request to automatically exclude custom fields not visible for that layout. Supported values are: list, detail,

exclude

optional

Exclude one or more relations from the object response. The parameter allows multiple comma separated values: user, fields, photos, attachments, aggregates. The fields relation also supports excluding specific fields: fields[jr_pros,jr_cons]

include

optional

The include parameter allows specifying which relations to include in the response. At this time it only allows including specific custom fields, while excluding all others. The supported format is: fields[jr_pros,jr_cons]

limit

optional

, default is 15

Number of results per page. Maximum is 20.

sort

optional

, default is created

The field you want to sort by. Supported values are: created, -created, rating, -rating, updated -updated

Returns

An object containing the array of comment objects and meta data for pagination.

request
Header Authorization: Bearer USER_TOKEN_HERE optional
get /jreviews/listings/:id/comments
response 
{
    "data": [
        {
            "id": 63,
            ...
        },
        {
            "id": 64,
            ...
        },
        ...
    ],
    "links": {
        "first": "https://jreviews.com/directory-api/jreviews/jreviews/listings/100/comments/?pg=1",
        "last": "https://jreviews.com/directory-api/jreviews/jreviews/listings/100/comments/?pg=5",
        "prev": null,
        "next": "https://jreviews.com/directory-api/jreviews/jreviews/listings/100/comments/?pg=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 5,
        "links": [...],
        "path": "https://jreviews.com/directory-api/jreviews/jreviews/listings/100/comments/",
        "per_page": 15,
        "to": 15,
        "total": 70
    }
]

Delete Comment

Delete a comment.

URL Parameters

id

required

The comment ID.

Returns

Returns a successful message if the call succeeded.

request
Header Authorization: Bearer USER_TOKEN_HERE required
delete /jreviews/comments/:id
response 
{
    "message" => "Comment was successfully deleted."
}

Media

Listing owners can upload photos and attachments to their listings.
Endpoints
post
post
delete

Upload Photo to Listing

Only the listing owner is allowed to upload photos to the listing.

URL Parameters

id

required

The listing ID.

Payload Parameters

file

required

The photo to upload.

caption

optional

The photo caption.

main

optional

Boolean flag that allows setting the photo as the main media. The first photo uploaded to a listing is automatically set as the main media.

media_function

configuration dependent

Supported values are: logo, cover.

Returns

A photo object.
request
Header Authorization: Bearer USER_TOKEN_HERE required
Header Content-Type: multipart/form-data required
post /jreviews/listings/:id/photo
response 
{
    "id": 1,
    "caption": "Aerial view",
    "main": true,
    "link": "https://jreviews.com/path/to/photo.jpg",
    "thumbnails": {},
    "permissions": {}
}

Upload Attachment to Listing

Only the listing owner is allowed to upload attachments to the listing.

URL Parameters

id

required

The listing ID.

Payload Parameters

file

required

The attachment to upload.

title

optional

The attachment title.

Returns

An attachment object.
request
Header Authorization: Bearer USER_TOKEN_HERE required
Header Content-Type: multipart/form-data required
post /jreviews/listings/:id/attachment
response 
{
    "id": 1,
    "title": "Schematics",
    "link": "https://jreviews.com/directory-api/jreviews/attachment/1/download",
    "permissions": {}
}

Delete Media

URL Parameters

id

required

The media ID.

Returns

Returns a successful message if the call succeeded.

request
Header Authorization: Bearer USER_TOKEN_HERE required
delete /jreviews/media/:id
response 
{
    "message" => "Media was successfully deleted."
}

Listing Favorites

Endpoints
post
delete

Favorite Listing

URL Parameters

id

required

The listing ID

Returns

Returns object with updated favorite count.
request
post /jreviews/listings/:id/favorite
response 
{
    "did_update": true
    "count": 20
}

Unfavorite Listing

URL Parameters

id

required

The listing ID

Returns

Returns object with updated favorite count.
request
delete /jreviews/listings/:id/favorite
response 
{
    "did_update": true
    "count": 20
}

Me

Read or perform actions specific to the authenticated.
Endpoints
get
delete
get
get

Get Authenticated User

Get the authenticated user information.

Parameters

No parameters

Returns

Returns the user object for the authenticated user.
request
Header Authorization: Bearer USER_TOKEN_HERE required
get /jreviews/me
response 
{
    "id": 999
    "name": "alejandro"
    "email": "[email protected]"
    "avatar": "https://jreviews.com/path/to/avatars/alejandro.jpg"
}

Delete User Account

Delete the user's account.

Parameters

No parameters

Returns

Returns a successful message if the call succeeded.

request
Header Authorization: Bearer USER_TOKEN_HERE required
delete /jreviews/me
response 
{
    "message" => "The user account was successfully deleted."
}

Get Authenticated User Listings

Get list of listings submitted by the authenticated user.

Same parameters and response as /jreviews/listings

request
Header Authorization: Bearer USER_TOKEN_HERE required
get /jreviews/me/listings

Get Authenticated User Favorites

Get list of favorites for the authenticated user.

Same parameters and response as /jreviews/listings

request
Header Authorization: Bearer USER_TOKEN_HERE required
get /jreviews/me/favorites

Users

Endpoints
get

Get User Profile

Get a user's public profile.

URL Parameters

id

required

The user ID

Returns

Returns a user object.
request
get /jreviews/users/:id
response 
{
    "id" : 999,
    "name" : "alejandro",
    "avatar" : "https://jreviews.com/path/to/avatars/alejandro.jpg",
    "link" : "https://jreviews.com/directory-api/jreviews/users/999",
    "web" : "https://jreviews.com/profile/alejandro",
}

Field Options

Endpoints
get
get

Get Field Options

Get a complete list of options for a given field.

URL Parameters

name

required

The field's name starting with jr_. Only supports select, multi-select, radio, and checkbox fields.

Returns

An object containing the array of field options.

request
get /jreviews/fields/jr_state/options
response 
{
    "data": [
        {
        "value": "alabama",
        "text": "Alabama"
        },
        {
        "value": "alaska",
        "text": "Alaska"
        },
        {
        "value": "arizona",
        "text": "Arizona"
        },
        ...
    ]
}

Search Field Options

Search a field's options.

URL Parameters

name

required

The field's name starting with jr_. Only supports select, multi-select, radio, and checkbox fields.

Query String Parameters

q

required

Search keywords to filter options.

Returns

An object containing the array of field options matching the search query.

request
get /jreviews/fields/jr_state/search?q=ma
response 
{
    "data": [
        {
        "value": "california",
        "text": "California"
        }
    ]
}

API Limitations

Only the documented endpoints in this article are currently supported. JReviews has a very large number of features developed over 15 years. This means it will be difficult for the API to reach feature parity anytime soon.

At this time many existing website settings and functionality are not connected to the API. For example, the following is a small subset of features/implementations that are not-functional in the API.

  • Automated titles generated when creating a listing
  • Video and audio uploads
  • Email notifications
  • Hooks
  • Guest submissions
  • Custom field PHP output formatting