REST API · v1

FalconCard REST API

Karten, Leads und Analytics programmatisch verwalten — für CRM-Sync, Automatisierung und eigene Integrationen. Authentifizierung per Bearer-Token, JSON über HTTPS.

Erste Schritte

In drei Schritten vom Token zum ersten erfolgreichen Request. Die API spricht ausschließlich JSON über HTTPS und folgt gängigen REST-Konventionen — wenn du schon einmal eine HTTP-API integriert hast, fühlst du dich sofort zu Hause.

  1. 1

    Token erstellen

    Öffne dein Dashboard und navigiere zu Account → API-Tokens. Wähle die Scopes, die deine Integration braucht, und kopiere den Token sofort — er wird aus Sicherheitsgründen nur ein einziges Mal im Klartext angezeigt.

    Zu den API-Tokens
  2. 2

    Bearer-Header setzen

    Sende den Token bei jedem Request im Authorization-Header. Ergänze Accept: application/json, damit Fehler ebenfalls als JSON zurückkommen.

    Authorization: Bearer DEIN_API_TOKEN
  3. 3

    Ersten Request senden

    Frage deine Karten ab. Ein erfolgreicher Aufruf liefert HTTP 200 mit einem data-Array und einem meta-Objekt zur Pagination:

    cURL
    curl https://falconcard.net/api/v1/cards \
      -H "Authorization: Bearer DEIN_API_TOKEN" \
      -H "Accept: application/json"
    Antwort · 200 OK
    {
      "data": [
        {
          "id": 42,
          "slug": "max-mustermann-a1b2",
          "title": "Max Mustermann",
          "first_name": "Max",
          "last_name": "Mustermann",
          "status": "active",
          "is_public": true,
          "public_url": "https://falconcard.net/c/max-mustermann-a1b2",
          "updated_at": "2026-06-12T10:30:00+00:00"
        }
      ],
      "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 15,
        "total": 1
      }
    }

    Erkennst du diese Struktur, ist deine Authentifizierung korrekt. Alle Listen-Endpoints antworten nach demselben data + meta -Schema — Einzel-Ressourcen kommen in einem data-Objekt ohne meta.

Basis-URL: https://falconcard.net/api/v1 · alle Antworten sind JSON.

Authentifizierung

Jeder Request authentifiziert sich mit einem persönlichen Access-Token (Laravel Sanctum) im Header:

Authorization: Bearer DEIN_API_TOKEN

Tokens erstellst und widerrufst du jederzeit im Dashboard. Jeder Token trägt einen oder mehrere Scopes, die seine Rechte begrenzen.

Scopes

cards:read Karten auflisten und lesen
cards:write Karten anlegen, ändern und löschen
leads:read Leads auflisten und lesen
analytics:read Aufruf- und Klick-Analytics lesen

Konzepte

Vier Bausteine, die für jeden Endpoint identisch funktionieren — einmal verstanden, gelten sie überall.

Versionierung

Die aktuelle Version ist /api/v1 und im Pfad fixiert. Breaking Changes erscheinen unter einem neuen Präfix (z.B. /api/v2), bestehende Integrationen bleiben stabil.

Anfrage-Format

Schreib-Endpoints erwarten einen JSON-Body mit Content-Type: application/json. Zeitstempel sind ISO 8601 (UTC). Unbekannte Felder werden ignoriert, fehlende optionale Felder bleiben unverändert.

Rate-Limiting

Enterprise-Tokens dürfen 1000 Requests pro Minutesenden. Jede Antwort trägt X-RateLimit-Limit, X-RateLimit-Remaining und Retry-After. Bei Überschreitung kommt 429 Too Many Requests mit einem Retry-After-Header (Sekunden bis zum Reset) — warte diese Zeit ab, bevor du es erneut versuchst.

Header · jede Antwort
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 994
Retry-After: 37

Pagination

Listen-Endpoints liefern bis zu 15 Einträge pro Seite. Steuere über ?page= (1-basiert) und ?per_page= (max 100). Das meta-Objekt nennt current_page, last_page, per_page und total.

meta · jede Liste
"meta": {
  "current_page": 2,
  "last_page": 7,
  "per_page": 15,
  "total": 98
}

Verfügbarkeit. Die REST API ist Teil des Enterprise-Plans. Tokens anderer Pläne erhalten 403.

Endpoint-Referenz

Vollständige Referenz aller zehn Endpoints, gruppiert nach Ressource. Jede Definition bleibt mit der OpenAPI-Spec synchron — direkt importierbar in Postman, Insomnia, Scalar oder deinen Code-Generator.

Cards

Digitale Visitenkarten anlegen, lesen, ändern und löschen.

GET /api/v1/cards Scope cards:read

Listet die Karten des Accounts, zuletzt geänderte zuerst.

Parameter

Name Ort Typ Pflicht Beschreibung
page Query integer nein Seitennummer (1-basiert).
per_page Query integer nein Einträge pro Seite, max 100.

Erfolgs-Antwort

200 OK mit einem data-Array von Karten und einem meta-Objekt zur Pagination.

Fehler-Codes

401403429
POST /api/v1/cards Scope cards:write

Legt eine neue Karte an. slug und title werden automatisch erzeugt. Plan-abhängige Felder werden auf erlaubte Werte korrigiert.

Parameter

Keine Parameter.

Request-Body application/json

Feld Typ Constraints Beschreibung
first_name Pflicht string maxLength 100 Vorname.
last_name Pflicht string maxLength 100 Nachname.
job_title string | null maxLength 150 Position / Jobtitel.
company string | null maxLength 150 Firmenname.
bio string | null maxLength 1000 Kurzbeschreibung / Bio.
email string | null email · maxLength 255 Kontakt-E-Mail (gültiges E-Mail-Format).
phone string | null maxLength 50 Telefonnummer. Erlaubte Zeichen: Ziffern, Leerzeichen und + - ( ) . /
website string | null uri · maxLength 500 Website-URL.
booking_url string | null uri · maxLength 500 Link zur Terminbuchung.
video_url string | null uri · maxLength 500 Video-URL. Erfordert das Advanced-Analytics-Feature, sonst ignoriert. Plan-abhängig
address string | null maxLength 500 Postanschrift.
social_links array | null Liste von Social-Media-Links (Array aus Objekten).
design_config object | null Design-Overrides (Farben, Schrift, Layout) als Objekt.
template_id string | null maxLength 50 ID des zu verwendenden Templates.
is_public boolean | null default true Ob die Karte öffentlich erreichbar ist. Standard true.
show_branding boolean | null FalconCard-Branding einblenden. Ausblenden erfordert das Whitelabel-Feature, sonst auf true erzwungen. Plan-abhängig
show_lead_form boolean | null Lead-Formular auf der Karte anzeigen. Erfordert das Lead-Form-Feature, sonst auf false erzwungen. Plan-abhängig
seo_title string | null maxLength 100 SEO-Titel für die öffentliche Karte.
seo_description string | null maxLength 250 SEO-Meta-Description.
language string | null maxLength 5 Primärsprache der Karte (z.B. de).

Erfolgs-Antwort

201 Created mit der angelegten Karte im data-Objekt und einer message.

Fehler-Codes

401403422429
GET /api/v1/cards/{card} Scope cards:read

Gibt eine einzelne Karte inklusive ihrer erfassten Leads zurück.

Parameter

Name Ort Typ Pflicht Beschreibung
card Pfad integer ja ID der Karte.

Erfolgs-Antwort

200 OK mit der Karte (inkl. eingebettetem leads-Array) im data-Objekt.

Fehler-Codes

401403404429
PUT /api/v1/cards/{card} Scope cards:write

Aktualisiert eine Karte. Alle Felder sind optional; nur übergebene Felder ändern sich. PUT und PATCH verhalten sich identisch.

Parameter

Name Ort Typ Pflicht Beschreibung
card Pfad integer ja ID der Karte.

Request-Body application/json

Feld Typ Constraints Beschreibung
first_name string maxLength 100 Vorname.
last_name string maxLength 100 Nachname.
job_title string | null maxLength 150 Position / Jobtitel.
company string | null maxLength 150 Firmenname.
bio string | null maxLength 1000 Kurzbeschreibung / Bio.
email string | null email · maxLength 255 Kontakt-E-Mail (gültiges E-Mail-Format).
phone string | null maxLength 50 Telefonnummer. Erlaubte Zeichen: Ziffern, Leerzeichen und + - ( ) . /
website string | null uri · maxLength 500 Website-URL.
booking_url string | null uri · maxLength 500 Link zur Terminbuchung.
video_url string | null uri · maxLength 500 Video-URL. Erfordert das Advanced-Analytics-Feature, sonst ignoriert. Plan-abhängig
address string | null maxLength 500 Postanschrift.
social_links array | null Liste von Social-Media-Links (Array aus Objekten).
design_config object | null Design-Overrides (Farben, Schrift, Layout) als Objekt.
template_id string | null maxLength 50 ID des zu verwendenden Templates.
is_public boolean | null Ob die Karte öffentlich erreichbar ist. Standard true.
show_branding boolean | null FalconCard-Branding einblenden. Ausblenden erfordert das Whitelabel-Feature, sonst auf true erzwungen. Plan-abhängig
show_lead_form boolean | null Lead-Formular auf der Karte anzeigen. Erfordert das Lead-Form-Feature, sonst auf false erzwungen. Plan-abhängig
seo_title string | null maxLength 100 SEO-Titel für die öffentliche Karte.
seo_description string | null maxLength 250 SEO-Meta-Description.
language string | null maxLength 5 Primärsprache der Karte (z.B. de).
status string | null enum: active, draft, archived Veröffentlichungs-Status: active, draft oder archived.

Erfolgs-Antwort

200 OK mit der aktualisierten Karte im data-Objekt und einer message.

Fehler-Codes

401403404422429
PATCH /api/v1/cards/{card} Scope cards:write

Aktualisiert eine Karte. Alle Felder sind optional; nur übergebene Felder ändern sich. PUT und PATCH verhalten sich identisch.

Parameter

Name Ort Typ Pflicht Beschreibung
card Pfad integer ja ID der Karte.

Request-Body application/json

Feld Typ Constraints Beschreibung
first_name string maxLength 100 Vorname.
last_name string maxLength 100 Nachname.
job_title string | null maxLength 150 Position / Jobtitel.
company string | null maxLength 150 Firmenname.
bio string | null maxLength 1000 Kurzbeschreibung / Bio.
email string | null email · maxLength 255 Kontakt-E-Mail (gültiges E-Mail-Format).
phone string | null maxLength 50 Telefonnummer. Erlaubte Zeichen: Ziffern, Leerzeichen und + - ( ) . /
website string | null uri · maxLength 500 Website-URL.
booking_url string | null uri · maxLength 500 Link zur Terminbuchung.
video_url string | null uri · maxLength 500 Video-URL. Erfordert das Advanced-Analytics-Feature, sonst ignoriert. Plan-abhängig
address string | null maxLength 500 Postanschrift.
social_links array | null Liste von Social-Media-Links (Array aus Objekten).
design_config object | null Design-Overrides (Farben, Schrift, Layout) als Objekt.
template_id string | null maxLength 50 ID des zu verwendenden Templates.
is_public boolean | null Ob die Karte öffentlich erreichbar ist. Standard true.
show_branding boolean | null FalconCard-Branding einblenden. Ausblenden erfordert das Whitelabel-Feature, sonst auf true erzwungen. Plan-abhängig
show_lead_form boolean | null Lead-Formular auf der Karte anzeigen. Erfordert das Lead-Form-Feature, sonst auf false erzwungen. Plan-abhängig
seo_title string | null maxLength 100 SEO-Titel für die öffentliche Karte.
seo_description string | null maxLength 250 SEO-Meta-Description.
language string | null maxLength 5 Primärsprache der Karte (z.B. de).
status string | null enum: active, draft, archived Veröffentlichungs-Status: active, draft oder archived.

Erfolgs-Antwort

200 OK mit der aktualisierten Karte im data-Objekt und einer message.

Fehler-Codes

401403404422429
DELETE /api/v1/cards/{card} Scope cards:write

Löscht eine Karte endgültig.

Parameter

Name Ort Typ Pflicht Beschreibung
card Pfad integer ja ID der Karte.

Erfolgs-Antwort

200 OK mit einer Bestätigungs-message.

Fehler-Codes

401403404429

Leads

Über die Lead-Formulare deiner Karten erfasste Kontakte lesen.

GET /api/v1/leads Scope leads:read

Listet die über alle Karten erfassten Leads, neueste zuerst. Mit card_id auf eine Karte filtern.

Parameter

Name Ort Typ Pflicht Beschreibung
card_id Query integer nein Auf eine einzelne Karte einschränken, die dir gehört.
page Query integer nein Seitennummer (1-basiert).
per_page Query integer nein Einträge pro Seite, max 100.

Erfolgs-Antwort

200 OK mit einem data-Array von Leads und einem meta-Objekt.

Fehler-Codes

401403429
GET /api/v1/leads/{id} Scope leads:read

Gibt einen einzelnen Lead mit kompakter Referenz auf die erfassende Karte zurück.

Parameter

Name Ort Typ Pflicht Beschreibung
id Pfad integer ja ID des Leads.

Erfolgs-Antwort

200 OK mit dem Lead im data-Objekt.

Fehler-Codes

401403404429

Analytics

Aggregierte Aufruf- und Klick-Statistiken — über alle Karten oder pro Karte.

GET /api/v1/analytics/views Scope analytics:read

Aggregierte Aufruf-Metriken über alle Karten oder — via card_id — für eine einzelne Karte.

Parameter

Name Ort Typ Pflicht Beschreibung
card_id Query integer nein Auf eine einzelne Karte einschränken, die dir gehört.
period Query string (enum) nein Auswertungszeitraum. Erlaubt: 7d, 14d, 30d, 90d, 365d. Standard 30d.

Erfolgs-Antwort

200 OK mit total_views, unique_views, views_per_day sowie Geräten, Ländern und Referrern im data-Objekt.

Fehler-Codes

401403422429
GET /api/v1/analytics/clicks Scope analytics:read

Aggregierte Klick-Metriken über alle Karten oder — via card_id — für eine einzelne Karte.

Parameter

Name Ort Typ Pflicht Beschreibung
card_id Query integer nein Auf eine einzelne Karte einschränken, die dir gehört.
period Query string (enum) nein Auswertungszeitraum. Erlaubt: 7d, 14d, 30d, 90d, 365d. Standard 30d.

Erfolgs-Antwort

200 OK mit total_clicks, clicks_by_type und clicks_per_day im data-Objekt.

Fehler-Codes

401403422429

Code-Beispiele

Kopierfertige Snippets in cURL, JavaScript und Python. Ersetze DEIN_API_TOKEN durch deinen echten Token.

Karten auflisten
curl https://falconcard.net/api/v1/cards?per_page=15 \
  -H "Authorization: Bearer DEIN_API_TOKEN" \
  -H "Accept: application/json"
const res = await fetch("https://falconcard.net/api/v1/cards?per_page=15", {
  headers: {
    Authorization: "Bearer DEIN_API_TOKEN",
    Accept: "application/json",
  },
});
const { data, meta } = await res.json();
console.log(data, meta);
import requests

res = requests.get(
    "https://falconcard.net/api/v1/cards",
    params={"per_page": 15},
    headers={"Authorization": "Bearer DEIN_API_TOKEN"},
)
res.raise_for_status()
payload = res.json()
print(payload["data"], payload["meta"])
Karte anlegen
curl -X POST https://falconcard.net/api/v1/cards \
  -H "Authorization: Bearer DEIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Max",
    "last_name": "Mustermann",
    "job_title": "Geschäftsführer",
    "company": "FalconCard",
    "email": "max@example.com"
  }'
const res = await fetch("https://falconcard.net/api/v1/cards", {
  method: "POST",
  headers: {
    Authorization: "Bearer DEIN_API_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    first_name: "Max",
    last_name: "Mustermann",
    job_title: "Geschäftsführer",
    company: "FalconCard",
    email: "max@example.com",
  }),
});
const { data, message } = await res.json();
import requests

res = requests.post(
    "https://falconcard.net/api/v1/cards",
    headers={"Authorization": "Bearer DEIN_API_TOKEN"},
    json={
        "first_name": "Max",
        "last_name": "Mustermann",
        "job_title": "Geschäftsführer",
        "company": "FalconCard",
        "email": "max@example.com",
    },
)
res.raise_for_status()
print(res.json()["data"]["id"])
Leads auflisten
curl "https://falconcard.net/api/v1/leads?card_id=42&per_page=50" \
  -H "Authorization: Bearer DEIN_API_TOKEN" \
  -H "Accept: application/json"
const params = new URLSearchParams({ card_id: "42", per_page: "50" });
const res = await fetch(`https://falconcard.net/api/v1/leads?${params}`, {
  headers: {
    Authorization: "Bearer DEIN_API_TOKEN",
    Accept: "application/json",
  },
});
const { data } = await res.json();
import requests

res = requests.get(
    "https://falconcard.net/api/v1/leads",
    params={"card_id": 42, "per_page": 50},
    headers={"Authorization": "Bearer DEIN_API_TOKEN"},
)
res.raise_for_status()
for lead in res.json()["data"]:
    print(lead["name"], lead["email"])
Analytics abrufen
curl "https://falconcard.net/api/v1/analytics/views?card_id=42&period=30d" \
  -H "Authorization: Bearer DEIN_API_TOKEN" \
  -H "Accept: application/json"
const params = new URLSearchParams({ card_id: "42", period: "30d" });
const res = await fetch(`https://falconcard.net/api/v1/analytics/views?${params}`, {
  headers: {
    Authorization: "Bearer DEIN_API_TOKEN",
    Accept: "application/json",
  },
});
const { data } = await res.json();
console.log(data.total_views, data.unique_views);
import requests

res = requests.get(
    "https://falconcard.net/api/v1/analytics/views",
    params={"card_id": 42, "period": "30d"},
    headers={"Authorization": "Bearer DEIN_API_TOKEN"},
)
res.raise_for_status()
stats = res.json()["data"]
print(stats["total_views"], stats["unique_views"])

Beispiel: Karte anlegen

Request · cURL
curl -X POST https://falconcard.net/api/v1/cards \
  -H "Authorization: Bearer DEIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Max",
    "last_name": "Mustermann",
    "job_title": "Geschäftsführer",
    "company": "FalconCard",
    "email": "max@example.com"
  }'
Response · 201
{
  "data": {
    "id": 42,
    "slug": "max-mustermann-a1b2",
    "title": "Max Mustermann",
    "first_name": "Max",
    "last_name": "Mustermann",
    "status": "active",
    "is_public": true,
    "public_url": "https://falconcard.net/c/max-mustermann-a1b2",
    "created_at": "2026-06-12T10:30:00+00:00"
  },
  "message": "Karte erfolgreich erstellt."
}

Fehler

Alle Fehler liefern einen message-String. Validierungsfehler (422) enthalten zusätzlich eine errors-Map.

Status Name Beschreibung Beispiel-Body
401 Unauthorized Token fehlt oder ist ungültig.
{ "message": "Unauthenticated." }
403 Forbidden Plan enthält keinen API-Zugriff (nur Enterprise) oder dem Token fehlt der nötige Scope.
{
  "message": "API access is not available on your current plan. Please upgrade to Enterprise."
}
404 Not Found Ressource existiert nicht oder gehört nicht zu deinem Account.
{ "message": "Not found." }
422 Unprocessable Entity Validierung fehlgeschlagen — Body enthält eine errors-Map (Feld → Meldungen).
429 Too Many Requests Rate-Limit überschritten. Der Retry-After-Header nennt die Wartezeit in Sekunden.
{
  "message": "Too Many Requests",
  "retry_after": 37
}

422 enthalten zusätzlich eine errors-Map mit Feld → Liste von Meldungen:

422 Unprocessable Entity
{
  "message": "The last name field is required.",
  "errors": {
    "last_name": ["The last name field is required."],
    "email": ["The email must be a valid email address."]
  }
}

Maschinenlesbare Spezifikation

Die komplette API ist als OpenAPI 3.1 dokumentiert. Lade die Spec herunter und importiere sie in Postman, Insomnia oder Scalar — oder generiere daraus typsichere Clients für deine Sprache.

Kompatibel mit Postman · Insomnia · Scalar · OpenAPI-Generatoren

openapi.json herunterladen

Bereit für die Integration?

Importiere die OpenAPI-Spec in dein Tooling oder erstelle direkt im Dashboard deinen ersten API-Token.