Community Agent API

Use your AI assistant to explore the Fiscal Solutions Retail Compliance Community and register for events. You do not need an API key. When you join or register for the first time, the assistant will guide you through business-email verification.

Base URL: {site origin}/api/agent/v1 (the same host that serves this page)

Version: v1 (1.0.0). Breaking changes get a new version with at least 6 months' deprecation notice.

JSON over HTTPS. Times are ISO 8601 with offset plus an IANA timezone. IDs are opaque. The API is agent-agnostic; platform adapters (MCP, Meta AI Connectors) sit on top as separate layers.

Discovery — Community, Forum, Community Day and registration-requirement endpoints are public. No account and no credential.

Connector credential (operators only) — joining and registering are called through a centrally operated connector (for example a future Meta AI connector) configured once by Fiscal Solutions or an approved connector operator. It is sent as X-Agent-Client-Key and managed behind the scenes. It identifies the integration, never a person, and is never a Community member credential: members are never asked for it and never receive it. It does not by itself authorise any member action.

Member session — personal actions send Authorization: Bearer <member_session_token>, returned by link_existing_member, join_community or recover_membership. Valid 90 days, revocable. A session only ever sees its own member's data, even when many people use the same connector.

Email verification — start_email_verification emails a 6-digit code to a business address (10-minute expiry, 5 attempts). The code may be read through the user's own authorized email integration or typed by the user in chat. verify_email_code returns a single-use proof valid for 15 minutes — and, because the person is now verified, the membership_state and the required_legal_action actually needed for that person (see the conditional legal sequence below). Membership state is never revealed before verification.

Scopes: community.read, registrations.read, registrations.write, join_access.read. Rate limits: 120 calls/min per client and IP; 5 codes/hour per email.

Only Forums published by an administrator are returned. Community Day questions are limited to event-specific information (dietary requirements, arrival note).

Do not present the full Terms of Use and Privacy Policy before email verification. First verify the business email; verify_email_code then returns the state of that verified person and the legal action actually required:

Optional marketing consent is separate and never required; do not ask for it unless the user raises it.

1. Request and verify a code. 2. Read the returned membership_state; for a new member, collect first name, last name, company, job title and country, present the returned legal versions and obtain explicit acceptance. 3. Call join_community with the selected event.

POST /api/agent/v1/email-verifications
X-Agent-Client-Key: <connector credential, held by the operator>
{ "email": "jane.doe@retailer.com", "purpose": "join",
  "event": { "type": "forum", "id": "<forum id>" } }

201 { "request_id": "req_...", "status": "code_sent",
      "resource_id": "<challenge id>",
      "next_action": "Ask the user for the 6-digit code ..." }

POST /api/agent/v1/email-verifications/<challenge id>/verify
{ "code": "123456" }

200 { "request_id": "req_...", "status": "verified",
      "verified_email_proof": "<proof>",
      "membership_state": "none | active | inactive | reactivation_requested | suspended",
      "required_legal_action": "accept_new_member_terms | reaccept_updated_versions | none",
      "required_legal_versions": [ { "id": "...", "doc_type": "terms",
        "version_label": "1.0", "content": "...", "url": "..." } ],
      "next_action": "..." }

POST /api/agent/v1/membership
X-Agent-Client-Key: <connector credential, held by the operator>
Idempotency-Key: 5f1c9e0a-join-jane
{
  "verified_email_proof": "<proof>",
  "profile": { "first_name": "Jane", "last_name": "Doe", "company": "Retailer Ltd",
               "job_title": "Head of Tax", "country": "Germany" },
  "legal_acceptance": { "legal_version_ids": ["<terms id>", "<privacy id>"],
    "accept_terms": true, "acknowledge_privacy": true,
    "user_statement": "I accept the Terms and acknowledge the Privacy Policy." },
  "event": { "type": "forum", "id": "<forum id>" }
}

201 { "request_id": "req_...", "status": "member_created",
      "member_session_token": "<member_session_token>",
      "event_registration": { "status": "registered" }, "next_action": "..." }

POST /api/agent/v1/forums/<forum id>/registrations
X-Agent-Client-Key: <connector credential, held by the operator>
Authorization: Bearer <member_session_token>
Idempotency-Key: 9b2e-forum-jane

200 { "request_id": "req_...", "status": "registered" | "already_registered" | "pending",
      "resource_id": "...", "next_action": "..." }

pending means the registration is saved and the webinar-provider sync is being retried; ambiguous provider responses are reconciled by email. Webinar credentials never leave the server. Repeating a write with the same Idempotency-Key replays the stored outcome.

A member has one active registration per Forum: a repeat call, even with a new Idempotency-Key, returns already_registered with the original registration and personal link, and never re-registers or resends the confirmation email. After a verified person is established, get_registration_requirements reports the legal action actually required — current active members are not asked to accept legal texts again; only new members and versions requiring re-acceptance are.

Join access — get_forum_join_access returns the member's own personal link with an access_status of link_available_room_not_yet_open (with room_opens_at, about 30 minutes before start), open, ended or link_unavailable.

Every error also carries a state the assistant can act on: verification_required, legal_action_required, already_registered or pending. Successful calls return registered, already_registered or pending in status.

200 OK · 201 Created · 202 Accepted/pending · 4xx/5xx errors in this shape:

{ "request_id": "req_...", "status": "error",
  "error": { "code": "legal_action_required", "message": "..." },
  "next_action": "Present the current documents and call accept_current_legal_versions." }

For connector operator onboarding, integration support or questions, contact admin@fiscal.community.