REST API

Every Yclas marketplace comes with a REST API. Developers use it to build mobile apps, show your listings on another website, sync data with other systems or automate jobs such as creating paid orders.

This page is the full reference, written for developers. If you only want to connect a ready-made service, you don’t need it.

Before you start

• Base address. Every request goes to your marketplace’s own address followed by /api/v1/, for example https://www.your-marketplace.com/api/v1/categories. Use your custom domain if you have one, and always use HTTPS.
• Your API key. In the admin panel, go to Settings › General, open Advanced and copy the API Key. Every marketplace gets a random key when it is created. You can replace it with your own value and click Save changes; the old key stops working straight away.
• No sign-up or extra plan needed. The API is part of every marketplace.

Your API key opens the whole marketplace: with it anyone can list your orders (including buyers’ email addresses) and create orders marked as paid. Keep it on a server or inside a compiled app, never in a public web page’s JavaScript, and change it in Settings › General if it leaks.

Three levels of access

You get a user token when a member signs in or registers through the API (see Sign in and sign up). Each member has one token, and it stays the same until it is regenerated, so store it securely in your app and send it with every request made on the member’s behalf. Requests that use a user token don’t need the API key.

Send the user token as a query or body parameter (user_token=…). A user_token HTTP header is not read reliably, and many servers drop headers with underscores in their names.

How requests work

Addresses and methods

/api/v1/<resource>(/<action>)(/<id>)(.<format>)

The HTTP method picks the action when you don’t name one:

A named action works with any method, so POST /api/v1/auth/login and GET /api/v1/auth/login do the same thing.

If your client or hosting can’t send PUT or DELETE, send a GET with ?method=PUT (or DELETE, POST), or send the real method in an X-HTTP-Method-Override header.

Sending data

Send parameters in the query string, as a form body (application/x-www-form-urlencoded or multipart/form-data for file uploads) or as JSON with Content-Type: application/json. Query and body parameters are merged.

Output formats

Responses are JSON by default. Add an extension for another format:

Add attachment=name to download the response as name.<format>. For JSONP, add callback=yourFunction.

Filtering

Most lists accept any of the item’s database fields as a filter: GET /api/v1/categories?id_category_parent=1.

Unknown fields are ignored. Private fields (passwords, tokens, email addresses, IP addresses, wallet balances and the like) can never be used to filter or sort.

Searching, sorting and choosing fields

Pagination

Listings, your own listings, users, orders, blog posts and messages are paginated with page (starting at 1) and items_per_page (10 by default). Every list also returns:

• an X-Total-Count header with the total number of matching items;
• a Link header with the next, last, first and previous_page addresses, where they exist.

Categories, locations, pages and FAQs always return everything in one response.

You can combine all of these: GET /api/v1/listings?q=bike&id_category=7&price<=500&sort=-published&page=2&items_per_page=20&apikey=…

Errors

Errors come back with a matching HTTP status and a body like this:

{"code": 401, "error": "Wrong Api Key"}

An empty list is a 404, not an empty array, so treat No records found as “zero results” in your app. If your client can’t read error statuses, add suppressResponseCodes=true: every response is then 200 and the real code is in a responseCode field.

Public endpoints

No key needed.

Categories

Useful filters: id_category_parent=1 (children of category 1), parent_deep=1 (top level), has_image=1.

Locations

If Automatically Sort All Locations Alphabetically is on in Settings › General, the list is always sorted by name and your sort is ignored.

Custom fields

These describe the custom fields your forms use: type, label, options and which categories they apply to.

In listings, a custom field’s value is stored as cf_<name>, for example cf_mileage.

Vehicle data

When vehicle data is switched on, the brand, model and generation lists behind its drop-downs are available too: GET /api/v1/autodatabrands, /autodatabrands/{id} (with its models), /autodatamodels, /autodatamodels/{id} (with its generations), /autodatagenerations and /autodatagenerations/{id}.

Endpoints that need the API key

Sign in and sign up

GET /api/v1/auth/login?email=member@example.com&password=…&apikey=YOUR_KEY

{"user": {"id_user": "42", "name": "Ana", "user_token": "06f8bbb8c7da102e5decf0820fb0d6c0b282d637", "image": "https://…", …}}

device_id stores the device’s push-notification id on the member, for mobile apps.

For social sign-in, token is an access token your app got from Google or Facebook. The provider must be set up in social login, and the marketplace checks the token with the provider: a Google token must have been issued to the same client ID, and Facebook needs the app secret saved in the settings. The member’s identity, email and name always come from the provider. If an account with that email already exists and the provider hasn’t confirmed the email, sign-in is refused with 409 and the member has to sign in with their password.

Common errors: Wrong Api Key, Wrong user name or password, User already exists, Invalid social login.

Listings

Published listings, as visitors see them. Expired listings and past events are left out.

• q searches listing titles.
• id_category and id_location include subcategories and sub-locations.
• Add latitude and longitude to get a distance for each listing (listings without coordinates are left out), and sort=distance to show the nearest first.
• Any other listing field works as a filter: id_user=5, price__between=100,500, cf_condition=new.

GET /api/v1/listings?latitude=41.40&longitude=2.20&sort=distance&items_per_page=20&apikey=YOUR_KEY

Listing status values: 0 not published, 1 published, 20 waiting for email confirmation, 30 spam, 40 sold, 50 unavailable.

Users

A public profile contains the id, name, description, role, location, dates, rating, phone, address, coordinates, language, user custom fields (cf_…) and image. Email addresses are never included.

Orders

Useful filters: id_user, id_ad, id_product, status (0 created, 1 paid, 5 refused, 10 waiting for confirmation, 99 refunded), paymethod, created, pay_date.

To create an order, send id_user, id_ad and id_product. Optional: amount (otherwise the normal price is used), currency, featured_days (for featuring), paymethod (defaults to API) and txn_id (your payment provider’s transaction id). Because the order is confirmed as paid, the purchase takes effect immediately, exactly as if the member had paid on your site. Use it to record payments taken somewhere else.

Blog posts, pages and FAQs

Filter by locale to get one language, for example locale=es_ES.

Translations

Fetch the wording of your site in each language, including your own edits from Language and translations, to use in an app.

Add all=1 to include texts that aren’t translated yet (with an empty translation), and file=apps for the texts used by the mobile apps instead of the website’s (file=messages, the default). An unknown locale falls back to en_US. Compare the last_update_… times with the time you last downloaded to know when to fetch again.

Endpoints that need a user token

These act as the signed-in member. Send user_token with every request.

The member’s listings

Listing fields you can send when creating or updating:

Any other field is ignored. The owner, status, featured dates and counters are set by the marketplace itself, so you can’t publish, feature or move a listing to another member through the API.

A new listing goes through the same rules as one posted on your site: spam checks, banned words, moderation, confirmation emails and paid categories. The answer tells you what to show the member:

{"message": "Please pay before we publish your listing.", "checkout_url": "https://…/ad/checkout/123", "ad": {…}}

message is the text to show (it depends on the marketplace’s moderation setting). When checkout_url isn’t empty, open it so the member can pay. Changing the category of a listing in a paid category can also return a checkout_url.

Administrators can update and deactivate any listing with their own token. Setting stock to 0 marks a listing as unavailable, and raising it again republishes it.

Favourites

Messages

These use your marketplace’s messaging system. Messages are grouped in threads, and a thread is identified by the id of its first message (id_message_parent).

Filter threads with id_ad (messages about one listing) or id_user_from (threads started by one member). A thread with no id_ad is a direct message between members.

To send a message, always include message and one of:

If the member already has an open thread with that seller about that listing (or with that member), the message is added to it instead of starting a new one.

Profile

PUT /api/v1/profile accepts name, email, description, password, phone, id_location, address, latitude, longitude, subscriber (1 to receive newsletters, 0 not to), digest_interval (never, daily, weekly or monthly) and the member’s user custom fields as cf_<name>, except those marked for administrators only and the verified badge (cf_verifiedbadge). Any other field, such as the role or status, is ignored.

To read the member’s own profile, use GET /api/v1/users/{id} with their user_token.

Tips

• Cache what rarely changes. Categories, locations, custom fields and translations change only when you edit them, so fetch them once per session rather than on every screen.
• Build links with url. Listings, blog posts, pages and FAQs include their public address, which already follows your marketplace’s URL settings.
• Prices come formatted. price in listings and categories is formatted for display in your site’s currency and format. In favourites and messages it is the plain number.
• Test safely. Create a test member and a test category, and use them while you develop; switch them off when you are done.

Related guides

• General settings — where the API key lives.
• Custom fields — the extra listing fields the API returns as cf_….
• Social login — needed for auth/social.
• Messaging between members — the conversations behind the messages endpoints.