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.
• A key. Use one of these:
  • A scoped key (recommended, on the Marketplace plan): create one in Add-ons › API keys with only the permissions your app needs. See API keys and permissions and Scoped keys below.
  • The site key: in 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.
• Which plan. Every plan includes the REST API with the site key (the basic API). The Full API, with scoped keys, webhook subscriptions, the MCP server and higher limits, is part of the Marketplace plan. No separate sign-up is needed.
• Your site’s own developer page. /api/docs on your site (for example https://www.your-marketplace.com/api/docs) lists every endpoint with the permission it needs, every webhook event and every MCP tool, generated from your site itself. Administrators reach it from the API & webhook docs link at the top of Add-ons. It becomes public once you switch on webhooks or the MCP server, or create a scoped key; until then only your administrators can see it. Search engines are asked not to index it.
• OpenAPI. The same API is described as an OpenAPI 3.1 file at /api/openapi.json on your site, for code generators, Postman and AI tools. It lists every endpoint with the permission it needs, and every webhook event. The same people who can read /api/docs can download it.
• Rate limit. Requests are limited per minute: 120 per key by default, which you can change. See Rate limits below.

The site key opens the whole REST API: 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. For anything new, prefer a scoped key with only the permissions you need.

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.

Sending the key

Scoped keys

A scoped key only opens the parts of the API its permissions allow. Each permission covers one group of endpoints:

The read permission only covers actions that read: listing, showing one item, orders/products, and the translation and export actions. Everything else needs the write permission, whatever the HTTP method, so GET /api/v1/orders/create needs orders:write just like POST /api/v1/orders.

Without users:read, email addresses are removed from the answers, for example the buyer’s email in orders.

A missing permission returns 403 with This API key does not have the orders:write scope (or the permission needed). The public endpoints and the user-token endpoints work as before.

The site key keeps the API it always had (listings, users, orders and content) but nothing newer: it can’t subscribe to webhooks and it doesn’t work with the MCP server.

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.

Rate limits

Every request counts towards a limit per minute, set by the site owner in Add-ons › API keys › Rate limit (120 by default). A scoped key is counted on its own; the site key is counted per caller’s internet address at 5 times the limit; requests with a user token are counted per member; and the public endpoints below are counted per address at 5 times the limit. See API keys: Rate limit.

Each counted response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (when the minute ends, as a Unix time). Over the limit the answer is 429 with a Retry-After header in seconds: wait that long before trying again.

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.

Webhook subscriptions (REST hooks)

Instead of the site owner adding a webhook in the panel, an app such as a Zapier integration can subscribe itself, on the Marketplace plan. This needs a scoped key with webhooks:manage, plus the read permission of each event it subscribes to (users:read for user.created, orders:read for order.paid, messages:read for message.created, listings:read for the rest). Webhooks must be switched on in Add-ons › Webhooks.

A site can have up to 5 webhooks added this way, on top of the owner’s own. A subscribed webhook gets email addresses only if its key has users:read, and private messages only with messages:read. Revoking the key pauses its webhooks. Deliveries, retries and the signature are the same as for any webhook: see What the app receives.

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

• API keys and permissions — scoped keys for each app.
• Webhooks — get events pushed to your app as they happen.
• Connect an AI assistant — the MCP server.
• General settings — where the site 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.