OpenMercantil User API

Authenticated Panel Pro endpoints — segments, lists, notes, tags, exports, audit. Requires session cookie (browser) and X-CSRF-Token header for mutations.

Operations 65

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /api/v1/user/me Get my account profile and plan · Current authenticated user #
Ask an LLM
“Which plan tier is my OpenMercantil account on?”
“Where do I get a fresh CSRF token together with my user profile?”
Tell an agent
Show my account profile, plan and persona.
Tell me whether my account has finished onboarding.
GET /api/v1/user/org Get my organization, seats and members · Get the current organization, seats and visible members #
Ask an LLM
“Which team members and seats does my organization have?”
“Can I create a team on my current plan if I don't belong to an organization yet?”
Tell an agent
Show my organization with its seats and visible members.
List the people in my team.
POST /api/v1/user/org Create an organization · Create an organization #
Ask an LLM
“Can I set up a team organization on a MAX or Enterprise plan?”
“What happens to my role when I start a new organization?”
Tell an agent
Create a new organization called {name} with me as owner.
Start a team named {name}.
PUT /api/v1/user/org Rename my organization · Rename the current organization #
Ask an LLM
“How do I change the name of my organization?”
“Who is allowed to rename the organization?”
Tell an agent
Rename my organization to {name}.
Change our team's display name to {name}.
POST /api/v1/user/org/invites Invite someone to my organization · Create or renew an organization invitation #
Ask an LLM
“How do I invite a colleague to join my organization?”
“Is there a daily limit on organization invitations or a seat cap?”
Tell an agent
Invite {email} to my organization.
Invite {email} to the team as {role}.
POST /api/v1/user/org/invites/{id}/resend Resend an organization invitation · Rotate and resend an organization invitation #
Ask an LLM
“My colleague lost their invite email; can I send the organization invitation again?”
“Does resending an invitation invalidate the old invite link?”
Tell an agent
Resend organization invitation {id}.
Rotate the token on invite {id} and email it again.
DELETE /api/v1/user/org/invites/{id} Cancel a pending organization invitation · Cancel a pending organization invitation #
Ask an LLM
“How do I withdraw an invitation that hasn't been accepted yet?”
“Can an admin cancel a pending team invite?”
Tell an agent destructive · confirm first
Cancel pending invitation {id}.
Withdraw the team invite {id} before it's accepted.
PUT /api/v1/user/org/members/{id} Change a team member's role · Change an organization member role #
Ask an LLM
“How do I promote a team member to admin?”
“Can the organization owner's own role be changed?”
Tell an agent
Change member {id}'s role to {role}.
Make organization member {id} a {role}.
DELETE /api/v1/user/org/members/{id} Remove a member from my organization · Remove a member from the organization #
Ask an LLM
“How do I remove someone from my organization?”
“Can an admin remove another admin or the owner?”
Tell an agent destructive · confirm first
Remove member {id} from the organization.
Kick {id} off our team.
POST /api/v1/user/org/leave Leave my current organization · Leave the current organization #
Ask an LLM
“How do I leave the organization I belong to?”
“Can an owner leave the organization without transferring ownership first?”
Tell an agent destructive · confirm first
Take me out of my current organization.
Leave the organization using CSRF token {csrf_token}.
GET /api/v1/user/persona See my persona and the available personas · Current persona config + available list #
Ask an LLM
“Which persona is my account set to?”
“What personas can I choose from?”
Tell an agent
Show my current persona and the list I can pick from.
List the available account personas.
POST /api/v1/user/persona Set my primary persona · Set persona_primary #
Ask an LLM
“How do I switch my account to a different persona?”
“Which values are valid when setting my primary persona?”
Tell an agent
Set my primary persona to {persona}.
Switch my account persona to {persona}.
GET /api/v1/user/segments List my saved company segments · List user segments #
Ask an LLM
“Which saved company segments have I built?”
“Can I show only my pinned segments?”
Tell an agent
List my saved segments.
Show my segments filtered by pinned = {pinned}, up to {limit}.
POST /api/v1/user/segments Save a new company segment · Create segment #
Ask an LLM
“How do I save a reusable filter of companies by province or CNAE prefix?”
“What filter anchor does a new segment need, and why would it be rejected with 422?”
Tell an agent
Create a segment called {name} with filters {filters}.
Save segment {name}, described as {description}, using filters {filters}, and pin it.
GET /api/v1/user/segments/{id} Get one saved segment · Get segment #
Ask an LLM
“What filters are stored in one of my segments?”
“Can I look up a single segment's definition by its id?”
Tell an agent
Get segment {id}.
Show the filters saved in segment {id}.
PUT /api/v1/user/segments/{id} Replace a segment's editable fields · Replace mutable segment fields #
Ask an LLM
“How do I overwrite a segment's name, description and filters all at once?”
“Can I fully replace an existing segment definition?”
Tell an agent
Replace segment {id} with name {name} and filters {filters_json}.
Overwrite all mutable fields of segment {id}.
PATCH /api/v1/user/segments/{id} Edit selected fields of a segment · Patch mutable segment fields #
Ask an LLM
“Can I tweak just one field of a segment, like its icon, without resending the rest?”
“How do I rename a segment and leave its filters untouched?”
Tell an agent
Rename segment {id} to {name}, leaving the other fields as they are.
Change only the icon of segment {id} to {icon}.
DELETE /api/v1/user/segments/{id} Delete a saved segment · Delete segment #
Ask an LLM
“How do I get rid of a segment I no longer use?”
“Is deleting a saved segment permanent?”
Tell an agent destructive · confirm first
Delete segment {id}.
Remove the saved company segment {id}.
POST /api/v1/user/segments/{id}/pin Pin or unpin a segment · Toggle pin #
Ask an LLM
“How do I pin a segment to the top of my list?”
“Does the pin action toggle, so calling it again unpins?”
Tell an agent
Toggle the pin on segment {id}.
Unpin segment {id}.
POST /api/v1/user/segments/{id}/run Run a segment to get matching companies · Execute segment filters → companies #
Ask an LLM
“Which companies match my saved segment right now?”
“What's the most companies a segment run can return, and is the count a global total?”
Tell an agent
Run segment {id} and return the matching companies.
Execute segment {id}, capped at {limit} companies.
GET /api/v1/user/lists List my saved lists · List user lists #
Ask an LLM
“What lists of companies and people have I saved?”
“Where can I see all my watchlists at once?”
Tell an agent
Show all my lists.
List my saved watchlists.
POST /api/v1/user/lists Create a list · Create list #
Ask an LLM
“How do I start a new watchlist to track companies?”
“Can I give a new list a color and a kind?”
Tell an agent
Create a list named {name}.
Create a {kind} list called {name} colored {color}.
GET /api/v1/user/lists/{id} Get a list and its items · Get list + items #
Ask an LLM
“Which companies are inside one of my lists?”
“Can I open a single list with all its entries?”
Tell an agent
Get list {id} with its items.
Show everything saved in list {id}.
PUT /api/v1/user/lists/{id} Replace a list's editable fields · Replace mutable list fields #
Ask an LLM
“How do I overwrite a list's name, description, color and kind in one go?”
“Can I fully replace the settings of an existing list?”
Tell an agent
Replace list {id} settings with name {name}, color {color} and kind {kind}.
Overwrite all mutable fields on list {id}.
PATCH /api/v1/user/lists/{id} Edit selected fields of a list · Patch mutable list fields #
Ask an LLM
“Can I just recolor a list without touching its name?”
“How do I rename a list while keeping its other settings?”
Tell an agent
Change only the color of list {id} to {color}.
Rename list {id} to {name} and keep everything else.
DELETE /api/v1/user/lists/{id} Delete a list and its items · Delete list and its items #
Ask an LLM
“What happens to the items when I delete a list?”
“How do I remove an entire watchlist?”
Tell an agent destructive · confirm first
Delete list {id} along with its items.
Remove watchlist {id} entirely.
POST /api/v1/user/lists/{id}/items Add a company or person to a list · Add item to list #
Ask an LLM
“How do I add a company to one of my watchlists?”
“Can I attach a note when adding an item to a list?”
Tell an agent
Add {type} {slug} to list {id}.
Put company {slug} on list {id} with the note {note}.
DELETE /api/v1/user/lists/{id}/items/{item_id} Remove an item from a list · Remove item from list #
Ask an LLM
“How do I take a single company off a list without deleting the list?”
“Can I drop one entry from a watchlist?”
Tell an agent destructive · confirm first
Remove item {item_id} from list {id}.
Drop entry {item_id} off watchlist {id}.
GET /api/v1/user/notes List my recent notes · Recent notes #
Ask an LLM
“What are the latest private notes I've written?”
“Can I limit how many recent notes come back?”
Tell an agent
Show my recent notes.
List my {limit} most recent notes.
POST /api/v1/user/notes Write a private note on a company or person · Create private note #
Ask an LLM
“How do I jot down a private note about a company?”
“Can I pin a note I attach to a person?”
Tell an agent
Add a private note to {target_type} {target_id} saying {body}.
Create a note titled {title} on {target_type} {target_id}: {body}.
GET /api/v1/user/notes/{id} Get one note · Get note #
Ask an LLM
“Can I open a single note by its id?”
“How do I read the full text of one of my notes?”
Tell an agent
Get note {id}.
Show me the full body of note {id}.
PUT /api/v1/user/notes/{id} Replace a note's title, body and pin · Replace mutable note fields #
Ask an LLM
“How do I rewrite a note completely, title and body together?”
“Can I overwrite every editable field of a note at once?”
Tell an agent
Replace note {id} with title {title} and body {body}.
Overwrite all editable fields of note {id}.
PATCH /api/v1/user/notes/{id} Edit selected fields of a note · Patch mutable note fields #
Ask an LLM
“Can I pin a note without resending its text?”
“How do I fix just the title of a note?”
Tell an agent
Set pinned to {pinned} on note {id} and leave the text alone.
Change only the title of note {id} to {title}.
DELETE /api/v1/user/notes/{id} Delete a note · Delete note #
Ask an LLM
“How do I delete a private note?”
“Can I permanently remove a note I wrote on a company?”
Tell an agent destructive · confirm first
Delete note {id}.
Erase my note {id}.
GET /api/v1/user/notes/for/{type}/{id} Get my notes about a company or person · Notes for a target #
Ask an LLM
“What notes have I written about a particular company?”
“Can I pull every note attached to one person?”
Tell an agent
Show all my notes about {type} {id}.
List notes attached to company {id}.
GET /api/v1/user/tags List my tags with usage counts · List user tags with counts #
Ask an LLM
“Which tags have I created and how many items use each?”
“Where can I see my tag counts?”
Tell an agent
List my tags with counts.
Show how many items carry each of my tags.
POST /api/v1/user/tags Create a tag · Create tag #
Ask an LLM
“How do I make a new tag to label companies?”
“Is the number of tags I can create limited by plan?”
Tell an agent
Create a tag named {name}.
Make a {color} tag called {name}.
DELETE /api/v1/user/tags/{id} Delete a tag and its assignments · Delete tag and assignments #
Ask an LLM
“If I delete a tag, is it removed from everything it was applied to?”
“How do I delete one of my tags?”
Tell an agent destructive · confirm first
Delete tag {id}.
Remove tag {id} and all of its assignments.
POST /api/v1/user/tags/{id}/assign Apply a tag to a company or person · Assign tag to target #
Ask an LLM
“How do I label a company with one of my tags?”
“Can I tag a person as well as a company?”
Tell an agent
Apply tag {id} to {target_type} {target_id}.
Tag company {target_id} with tag {id}.
POST /api/v1/user/tags/{id}/unassign Remove a tag from a company or person · Unassign tag from target #
Ask an LLM
“How do I take a tag off a company without deleting the tag?”
“Can I untag a single person?”
Tell an agent
Unassign tag {id} from {target_type} {target_id}.
Strip tag {id} off company {target_id}.
GET /api/v1/user/exports See my export history and monthly usage · Export history + monthly usage #
Ask an LLM
“Which exports have I run recently?”
“Can I see past exports alongside how much of this month's quota I've used?”
Tell an agent
Show my export history.
List my last {limit} exports with this month's usage.
GET /api/v1/user/exports/usage Check my monthly export quota · Monthly export quota usage only #
Ask an LLM
“How many exports do I have left this month?”
“What's my monthly export quota usage, without the history?”
Tell an agent
Check my monthly export quota usage.
Tell me how much of my export allowance remains.
GET /api/v1/user/audit View my account audit log · Audit log (MAX/Enterprise only) #
Ask an LLM
“Which plans include the account audit log, and how long is it kept?”
“Can I see who did what in my account?”
Tell an agent
Show my account audit log.
Get {limit} audit entries starting at offset {offset}.
POST /api/v1/persons/lookup Run a KYC lookup by DNI/NIE · Run an authenticated KYC documentary lookup #
Ask an LLM
“Can I run a KYC check on someone using their DNI or NIE?”
“Do I have to declare a legitimate purpose before a documentary person lookup?”
Tell an agent
Run a KYC lookup on DNI/NIE {dni_or_nie} for the purpose {finalidad}.
Look up identity document {dni_or_nie}; stated purpose: {finalidad}.
GET /api/v1/persons/lookup/usage Check my KYC lookup allowance · Get the caller's KYC lookup allowance and usage #
Ask an LLM
“How many KYC lookups does my plan allow and how many have I used?”
“Is my tier eligible for DNI lookups at all?”
Tell an agent
Check my KYC lookup allowance and usage.
Tell me how many DNI lookups I have left.
GET /api/v1/persons/lookup/history See my past KYC lookups · Get the caller's redacted KYC lookup history #
Ask an LLM
“Which KYC lookups have I run before?”
“Are identifiers masked in my lookup history?”
Tell an agent
Show my redacted KYC lookup history.
List {limit} past KYC lookups from offset {offset}.
GET /api/v1/user/api-credentials List my API credentials · List API credential metadata #
Ask an LLM
“Which API keys exist on my account and what scopes do they have?”
“Can I see an API key's prefix and last four characters without the secret?”
Tell an agent
List my API credentials.
Page through my API keys, {limit} at a time from cursor {cursor}.
POST /api/v1/user/api-credentials Create an API credential · Create an API credential #
Ask an LLM
“How do I generate a new API key?”
“What is the longest expiry I can set on a new API credential?”
Tell an agent
Create an API credential named {name} with scopes {scopes}.
Issue a new API key scoped to {scopes} expiring {expires_at}.
POST /api/v1/user/api-credentials/{id}/rotate Rotate an API credential · Rotate one API credential #
Ask an LLM
“How do I swap a compromised API key for a new token?”
“Does rotating an API key revoke the old one?”
Tell an agent destructive · confirm first
Rotate API credential {id}.
Rotate key {id} and give the replacement the scopes {scopes}.
DELETE /api/v1/user/api-credentials/{id} Revoke an API credential · Revoke one API credential #
Ask an LLM
“How do I permanently disable an API key?”
“Can I revoke a key without getting a replacement token?”
Tell an agent destructive · confirm first
Revoke API credential {id}.
Disable API key {id} for good.
GET /api/v1/user/webhooks List my outbound webhooks · List outbound webhook metadata #
Ask an LLM
“Which webhooks have I registered and which event types are allowed?”
“Is the webhook delivery worker healthy?”
Tell an agent
List my outbound webhooks.
Show the webhook event allowlist and worker health.
POST /api/v1/user/webhooks Register an outbound webhook · Create an outbound webhook #
Ask an LLM
“How do I get notified at my own HTTPS endpoint when registry events happen?”
“Can a webhook subscribe to wildcard events?”
Tell an agent
Create a webhook to {url} for events {events}.
Send {events} notifications to my endpoint {url}.
PATCH /api/v1/user/webhooks/{id} Update a webhook's URL, events or status · Update an outbound webhook #
Ask an LLM
“How do I point an existing webhook at a new URL?”
“Can I pause a webhook without deleting it?”
Tell an agent
Change webhook {id} to deliver to {url}.
Set webhook {id} active to {active}.
DELETE /api/v1/user/webhooks/{id} Delete an outbound webhook · Delete an outbound webhook #
Ask an LLM
“How do I stop and remove a webhook for good?”
“Can I delete a webhook I no longer need?”
Tell an agent destructive · confirm first
Delete webhook {id}.
Remove outbound webhook {id} permanently.
POST /api/v1/user/webhooks/{id}/rotate Rotate a webhook's signing secret · Rotate an outbound webhook signing secret #
Ask an LLM
“How do I get a new signing secret for a webhook?”
“What happens to pending deliveries signed with the old webhook secret?”
Tell an agent destructive · confirm first
Rotate the signing secret for webhook {id}.
Issue a fresh signature key on webhook {id}.
POST /api/v1/support/ticket/{id}/reply Reply to my support ticket · Reply to a support ticket owned by the authenticated user #
Ask an LLM
“How do I add a reply to a support ticket I opened?”
“Can I reply to a support ticket that's already closed?”
Tell an agent
Reply to ticket {id}: {body}.
Post {body} on my support ticket {id}.
GET /api/v1/csrf Get a CSRF token for my session · Get a live same-origin CSRF token #
Ask an LLM
“Where do I get a CSRF token before making an account change?”
“Is my browser session currently authenticated?”
Tell an agent
Get a fresh CSRF token.
Check whether my session is logged in and fetch its CSRF token.
POST /api/v1/resend-verification Resend my email verification link · Resend the account email-verification link #
Ask an LLM
“I never got the verification email; can it be sent again?”
“Is resending the verification link rate-limited?”
Tell an agent
Resend my account verification email.
Send the email-verification link again with CSRF token {csrf_token}.
POST /api/v1/credits/checkout Buy a credit pack · Create an idempotent credit-pack Checkout session #
Ask an LLM
“How do I buy more credits?”
“Is a retry of a credit-pack checkout safe from double charging?”
Tell an agent
Start checkout for credit pack {pack}.
Buy the {pack} credit pack.
POST /api/v1/empresa/{slug}/informe-legal Generate a redacted legal report on a company · Create the authenticated user's redacted corporate legal report #
Ask an LLM
“Can I get a legal report on a Spanish company using my credits?”
“Is the company legal report legal advice or an official certificate?”
Tell an agent
Generate the legal report for company {slug}.
Spend credits on a redacted informe legal for {slug}.
POST /api/v1/checkout Start a subscription checkout · Create a subscription Checkout session #
Ask an LLM
“How do I upgrade to a paid plan?”
“Can I pay annually and apply a coupon when subscribing?”
Tell an agent
Start a subscription checkout for the {plan} plan.
Subscribe me to {plan} billed {billing} with coupon {coupon}.
GET /api/v1/billing/invoices List my invoices and subscription · List the authenticated user's invoices and subscription #
Ask an LLM
“Where can I download my past invoices?”
“What subscription am I currently paying for?”
Tell an agent
List my invoices.
Show my current subscription and billing history.
GET /api/v1/billing/portal Open my Stripe billing portal · Redirect to the authenticated user's Stripe portal #
Ask an LLM
“How do I get to the Stripe portal to change my card?”
“Is there a link that redirects me straight to my billing portal?”
Tell an agent
Redirect me to my Stripe billing portal.
Take me to the page where I manage my payment method.
POST /api/v1/billing/portal Create a Stripe portal session URL · Create a Stripe portal session as JSON #
Ask an LLM
“Can I get the Stripe portal session as JSON instead of a redirect?”
“Which endpoint should a new client use to create a billing portal session?”
Tell an agent
Create a billing portal session and return its URL as JSON.
Create a Stripe portal session with CSRF token {csrf_token}.
POST /api/v1/portal Create a portal session via the legacy alias · Create a Stripe Customer Portal session through the legacy alias #
Ask an LLM
“Does the old /portal route still create a Stripe Customer Portal session?”
“Can I pass the CSRF token as a form field on the deprecated portal alias?”
Tell an agent
Open a customer portal session through the deprecated /portal alias.
Call the legacy portal route with form field csrf {csrf}.

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/openmercantil:openmercantil-user-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openmercantil-user-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: OpenMercantil User API
  version: 1.9.3
  summary: Versioned public-read, browser-account, billing, support and provider-callback contracts.
  description: Public JSON API for Spanish company information derived from BORME and other public sources.
  termsOfService: https://openmercantil.es/terminos-de-uso
  contact:
    name: OpenMercantil
    url: https://openmercantil.es/soporte
    email: social@openmercantil.es
  license:
    name: Source-specific upstream terms; see response catalog metadata
    url: https://openmercantil.es/terminos-de-uso
  x-publisher:
    name: OpenMercantil
    url: https://openmercantil.es/
    email: social@openmercantil.es
  x-spatial: http://publications.europa.eu/resource/authority/country/ESP
  x-temporal: 2009-01-01/..
  x-language: es
  x-dcat-catalog: https://openmercantil.es/catalog.rdf
  x-rate-limit:
    free:
      per_min: 60
      per_day: 200
      kind: anonymous-ip
    profesional:
      per_min: 120
      per_day: 5000
      kind: api-key
    max:
      per_min: 600
      per_day: 50000
      kind: api-key
    enterprise:
      per_min: 1200
      per_day: 500000
      kind: contract
  x-methodology: https://openmercantil.es/metodologia
  x-sources: https://openmercantil.es/fuentes
  x-corrections: https://openmercantil.es/correcciones
  x-contract-status: Public read, browser-account and provider-callback surfaces are explicitly separated in this contract. Operator/admin routes are excluded. The public MCP consumes only the allowlisted GET read plane.
  x-account-segment-contract:
    projection: company_public_v2 immutable corporate sidecar
    synchronous_row_cap: 500
    bounded_count_cap: 50001
    count_semantics: The segment run response count is the number of rows returned, never a global total. Dataset preview uses total_is_lower_bound=true and total_lower_bound when the bounded count reaches 50001.
    related_web_dataset_surface:
      preview_path: /mi-cuenta/datasets/preview
      export_path: /mi-cuenta/datasets/export.csv
      synchronous_export_max_rows: 500
      overflow_status: 503
      overflow_error: async_export_required
  x-company-identity-contract:
    version: '1.0'
    projection: company_public_v2 immutable generation-bound corporate sidecar
    applies_to: Every /api/v1/company/{slug}*, /api/v1/empresa/{slug}* and /api/v1/grafo/{slug} read before any report, cache, graph or dataset lookup. /api/v1/companies/compare resolves both requested subjects in one bounded company_public_v2 batch before either row is exposed; MCP company tools inherit these preflights through REST.
    resolution:
      published: canonical corporate slug admitted
      safe_alias: internally canonicalized and Content-Location emitted
      withheld: neutral 404; includes absent, personal and ambiguous/quarantined identities
      unavailable: 503 with no-store; clients must not infer absence
    search: Exact corporate CIF, exact canonical/safe-alias slug, or bounded name_prefix2 pool scored in application code. DNI/NIE and ambiguous CIFs return zero items.
    public_company_count: company_public_projection_state.row_count
servers:
- url: https://openmercantil.es
  description: Production
tags:


# --- truncated at 32 KB (129 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/openmercantil/refs/heads/main/openapi/openmercantil-user-api-openapi.yml