Tenants

Endpoints for listing tenants (stores) the authenticated user could sign up for.

---

List Tenants

GET /api/v2/tenants

Returns tenants where the authenticated user does not have an account, ordered by popularity (user count). Supports optional country filtering, name search, and cursor pagination.

Tenant Mode: Multi-tenant (do NOT send X-Farfalla-Tenant-Id). When X-CustomFenice-Tenant-Id is sent with a value other than 1, the list is restricted to that tenant's family (owner plus tenants whose aggregator_id equals the header value). May be empty if the user is already registered in every family member.

Request:

curl "https://app.publica.la/api/v2/tenants?country_code=AR&per_page=10" \
  -H "Authorization: Bearer {access_token}" \
  -H "Accept: application/json"

Query Parameters

Parameter	Type	Default	Description
country_code	string (2 chars)	-	ISO 3166-1 alpha-2 country code
query	string (2-128 chars)	-	Case-insensitive substring match against tenant name
per_page	integer (1-100)	20	Items per page
cursor	string	-	Cursor for next page (provided by the previous response)

info

When country_code is omitted no country filter is applied and all eligible tenants are returned. The query parameter is normalized to NFC form before matching to handle accented characters consistently.

Response

200 OK

{
  "data": [
    {
      "id": 42,
      "name": "Editorial Planeta",
      "domain": "planeta.publica.la",
      "logo": "https://cdn.publica.la/planeta/logo/logo.png",
      "country_code": "AR",
      "country_name": "Argentina",
      "colors": {
        "primary": "#1a1a2e",
        "secondary": "#e94560"
      }
    },
    {
      "id": 15,
      "name": "Grupo Santillana",
      "domain": "santillana.publica.la",
      "logo": "https://cdn.publica.la/santillana/logo/logo.png",
      "country_code": "AR",
      "country_name": "Argentina",
      "colors": {
        "primary": "#ffffff",
        "secondary": "#0066cc"
      }
    }
  ],
  "meta": {
    "per_page": 10,
    "next_cursor": "eyJ1c2Vyc19jb3VudCI6MTIzNCwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ",
    "prev_cursor": null
  }
}

Response Fields

Field	Type	Description
data[].id	integer	Tenant ID
data[].name	string	Tenant display name
data[].domain	string	Tenant domain (custom domain or subdomain)
data[].logo	string	Logo URL
data[].country_code	string or null	Tenant country (from sign-up intent)
data[].country_name	string or null	Country name in English
data[].colors	object	Brand colors (primary, secondary)
meta.per_page	integer	Page size
meta.next_cursor	string or null	Opaque cursor for the next page. null when there are no more pages
meta.prev_cursor	string or null	Opaque cursor for the previous page. null on the first page

Ordering

Results are ordered by popularity (number of users, descending). Tenants with more users appear first. This ordering is fixed and not configurable via API parameters.

Filtering

• Only tenants with an active plan (has_plan = true) are included
• Tenants where the user already has an account are excluded
• Country filtering uses the tenant's signUpIntent.country_code
• Custom app scope: see the note under "List Tenants" above

Pagination

Uses cursor-based pagination. Save meta.next_cursor from the response and pass it back in the cursor query parameter on the next request, along with the same filters:

# Page 1
curl "https://app.publica.la/api/v2/tenants?country_code=AR&per_page=5" \
  -H "Authorization: Bearer {access_token}"

# Page 2 (re-send all filters and the cursor from meta.next_cursor)
curl "https://app.publica.la/api/v2/tenants?country_code=AR&per_page=5&cursor=eyJ1c2Vyc..." \
  -H "Authorization: Bearer {access_token}"

The cursor is opaque. Treat it as a token: do not parse, modify, or store individual fields from it. When meta.next_cursor is null, there are no more pages.

Error Responses

Code	Cause
412	X-Farfalla-Tenant-Id header was sent (not allowed on multi-tenant endpoints)
422	country_code is not exactly 2 characters, query is out of range, or per_page is out of range

---

See Also

• API v2 Overview - Authentication and tenant modes
• User Endpoints - User profile includes tenant list