Hoppa till innehållet

REST API · v1

FalconCard REST API

Hantera kort, leads och analys programmatiskt — för CRM-synk, automatisering och dina egna integrationer. Autentisering med Bearer-token, JSON över HTTPS.

01

Kom igång

Från token till din första lyckade förfrågan i tre steg. API:et talar uteslutande JSON över HTTPS och följer vanliga REST-konventioner — har du någonsin integrerat ett HTTP-API känner du dig direkt hemma.

  1. Skapa en token

    Öppna din instrumentpanel och navigera till Konto → API-tokens. Välj de scopes din integration behöver och kopiera token direkt — av säkerhetsskäl visas den i klartext bara en gång.

    Gå till API-tokens
  2. Sätt Bearer-headern

    Skicka token i Authorization-headern på varje förfrågan. Lägg till Accept: application/json så att fel också kommer tillbaka som JSON.

    Authorization: Bearer DEIN_API_TOKEN
  3. Skicka din första förfrågan

    Hämta dina kort. Ett lyckat anrop returnerar HTTP 200 med en data-array och ett meta-objekt för paginering:

cURL
curl https://falconcard.net/api/v1/cards \
  -H "Authorization: Bearer DEIN_API_TOKEN" \
  -H "Accept: application/json"
Svar · 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
  }
}

Ser du den här formen är din autentisering korrekt. Varje list-endpoint svarar med samma data + meta -schema — enskilda resurser kommer tillbaka i ett data-objekt utan meta.

Bas-URL: https://falconcard.net/api/v1 · alla svar är JSON.

02

Autentisering

Varje förfrågan autentiseras med en personlig åtkomsttoken (Laravel Sanctum) i headern:

Authorization: Bearer DEIN_API_TOKEN

Du kan när som helst skapa och återkalla tokens i instrumentpanelen. Varje token bär ett eller flera scopes som begränsar dess behörigheter.

Scopes

cards:read

Lista och läsa kort

cards:write

Skapa, uppdatera och radera kort

leads:read

Lista och läsa leads

analytics:read

Läsa visnings- och klickanalys

03

Koncept

Fyra byggstenar som fungerar likadant för varje endpoint — lär dig dem en gång, de gäller överallt.

Versionering

Den aktuella versionen är /api/v1 och är fastlåst i sökvägen. Brytande ändringar levereras under ett nytt prefix (t.ex. /api/v2), så att befintliga integrationer förblir stabila.

Förfrågansformat

Write-endpoints förväntar sig en JSON-body med Content-Type: application/json. Tidsstämplar är ISO 8601 (UTC). Okända fält ignoreras, saknade valfria fält förblir oförändrade.

Rate limiting

Enterprise-tokens får skicka 1000 förfrågningar per minut. Varje svar bär X-RateLimit-Limit och X-RateLimit-Remaining. När gränsen överskrids får du 429 Too Many Requests med en Retry-After-header (sekunder till återställning) — vänta så länge innan du försöker igen.

Headers · varje svar
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 994

Paginering

List-endpoints returnerar upp till 15 objekt per sida. Styr det med ?page= (1-baserad) och ?per_page= (max 100). Meta-objektet rapporterar current_page, last_page, per_page och total.

meta · varje lista
"meta": {
  "current_page": 2,
  "last_page": 7,
  "per_page": 15,
  "total": 98
}

Tillgänglighet. REST API ingår i Enterprise-planen. Tokens från andra planer får 403.

04

Endpoint-referens

Fullständig referens för alla tio endpoints, grupperade per resurs. Varje definition hålls synkroniserad med OpenAPI-specifikationen — redo att importeras i Postman, Insomnia, Scalar eller din kodgenerator.

01

Cards

Skapa, läsa, uppdatera och radera digitala visitkort.

GET
/api/v1/cards Scope cards:read

Listar kontots kort, senast uppdaterade först.

Parametrar

Namn I Typ Obligatorisk Beskrivning
page query integer nej Sidnummer (1-baserat).
per_page query integer nej Objekt per sida, max 100.

Lyckat svar

200 OK med en data-array av kort och ett meta-objekt för paginering.

Felkoder

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

Skapar ett nytt kort. slug och title genereras automatiskt. Planbegränsade fält tvingas till tillåtna värden.

Parametrar

Inga parametrar.

Förfrågans-body application/json

Fält Typ Begränsningar Beskrivning
first_name Obligatorisk string maxLength 100 Förnamn.
last_name Obligatorisk string maxLength 100 Efternamn.
job_title string | null maxLength 150 Befattning / titel.
company string | null maxLength 150 Företagsnamn.
bio string | null maxLength 1000 Kort beskrivning / bio.
email string | null email · maxLength 255 Kontakt-e-post (giltigt e-postformat).
phone string | null maxLength 50 Telefonnummer. Tillåtna tecken: siffror, mellanslag och + - ( ) . /
website string | null uri · maxLength 500 Webbplats-URL.
booking_url string | null uri · maxLength 500 Länk till tidsbokning.
video_url string | null uri · maxLength 500 Video-URL. Kräver funktionen avancerad analys, ignoreras annars. planbegränsad
address string | null maxLength 500 Postadress.
social_links array | null maxItems 20 · platform: enum · url: http(s) uri or handle (completed) · maxLength 500 · label: maxLength 100 Lista över länkar till sociala medier (array av objekt).
design_config object | null — Designöverstyrningar (färger, typsnitt, layout) som ett objekt.
template_id string | null maxLength 50 ID för mallen som ska användas.
is_public boolean | null default true Om kortet är offentligt åtkomligt. Standard true.
show_branding boolean | null — Visa FalconCard-varumärke. Att dölja det kräver funktionen whitelabel, annars tvingas till true. planbegränsad
show_lead_form boolean | null — Visa lead-formuläret på kortet. Kräver funktionen lead-formulär, annars tvingas till false. planbegränsad
seo_title string | null maxLength 100 SEO-titel för det offentliga kortet.
seo_description string | null maxLength 250 SEO-metabeskrivning.
language string enum: de en bg cs da el es fr hr hu it nl pl pt ro sk sl sv uk Kortets primära språk (t.ex. de).

Lyckat svar

201 Created med det nya kortet i data-objektet plus ett message.

Felkoder

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

Returnerar ett enskilt kort inklusive dess insamlade leads.

Parametrar

Namn I Typ Obligatorisk Beskrivning
card path integer ja Kortets ID.

Lyckat svar

200 OK med kortet (inklusive en inbäddad leads-array) i data-objektet.

Felkoder

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

Uppdaterar ett kort. Alla fält är valfria; endast angivna fält ändras. PUT och PATCH beter sig identiskt.

Parametrar

Namn I Typ Obligatorisk Beskrivning
card path integer ja Kortets ID.

Förfrågans-body application/json

Fält Typ Begränsningar Beskrivning
first_name string maxLength 100 Förnamn.
last_name string maxLength 100 Efternamn.
job_title string | null maxLength 150 Befattning / titel.
company string | null maxLength 150 Företagsnamn.
bio string | null maxLength 1000 Kort beskrivning / bio.
email string | null email · maxLength 255 Kontakt-e-post (giltigt e-postformat).
phone string | null maxLength 50 Telefonnummer. Tillåtna tecken: siffror, mellanslag och + - ( ) . /
website string | null uri · maxLength 500 Webbplats-URL.
booking_url string | null uri · maxLength 500 Länk till tidsbokning.
video_url string | null uri · maxLength 500 Video-URL. Kräver funktionen avancerad analys, ignoreras annars. planbegränsad
address string | null maxLength 500 Postadress.
social_links array | null maxItems 20 · platform: enum · url: http(s) uri or handle (completed) · maxLength 500 · label: maxLength 100 Lista över länkar till sociala medier (array av objekt).
design_config object | null — Designöverstyrningar (färger, typsnitt, layout) som ett objekt.
template_id string | null maxLength 50 ID för mallen som ska användas.
is_public boolean | null — Om kortet är offentligt åtkomligt. Standard true.
show_branding boolean | null — Visa FalconCard-varumärke. Att dölja det kräver funktionen whitelabel, annars tvingas till true. planbegränsad
show_lead_form boolean | null — Visa lead-formuläret på kortet. Kräver funktionen lead-formulär, annars tvingas till false. planbegränsad
seo_title string | null maxLength 100 SEO-titel för det offentliga kortet.
seo_description string | null maxLength 250 SEO-metabeskrivning.
language string enum: de en bg cs da el es fr hr hu it nl pl pt ro sk sl sv uk Kortets primära språk (t.ex. de).
status string | null enum: active, draft, archived Publiceringsstatus: active, draft eller archived.

Lyckat svar

200 OK med det uppdaterade kortet i data-objektet plus ett message.

Felkoder

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

Uppdaterar ett kort. Alla fält är valfria; endast angivna fält ändras. PUT och PATCH beter sig identiskt.

Parametrar

Namn I Typ Obligatorisk Beskrivning
card path integer ja Kortets ID.

Förfrågans-body application/json

Fält Typ Begränsningar Beskrivning
first_name string maxLength 100 Förnamn.
last_name string maxLength 100 Efternamn.
job_title string | null maxLength 150 Befattning / titel.
company string | null maxLength 150 Företagsnamn.
bio string | null maxLength 1000 Kort beskrivning / bio.
email string | null email · maxLength 255 Kontakt-e-post (giltigt e-postformat).
phone string | null maxLength 50 Telefonnummer. Tillåtna tecken: siffror, mellanslag och + - ( ) . /
website string | null uri · maxLength 500 Webbplats-URL.
booking_url string | null uri · maxLength 500 Länk till tidsbokning.
video_url string | null uri · maxLength 500 Video-URL. Kräver funktionen avancerad analys, ignoreras annars. planbegränsad
address string | null maxLength 500 Postadress.
social_links array | null maxItems 20 · platform: enum · url: http(s) uri or handle (completed) · maxLength 500 · label: maxLength 100 Lista över länkar till sociala medier (array av objekt).
design_config object | null — Designöverstyrningar (färger, typsnitt, layout) som ett objekt.
template_id string | null maxLength 50 ID för mallen som ska användas.
is_public boolean | null — Om kortet är offentligt åtkomligt. Standard true.
show_branding boolean | null — Visa FalconCard-varumärke. Att dölja det kräver funktionen whitelabel, annars tvingas till true. planbegränsad
show_lead_form boolean | null — Visa lead-formuläret på kortet. Kräver funktionen lead-formulär, annars tvingas till false. planbegränsad
seo_title string | null maxLength 100 SEO-titel för det offentliga kortet.
seo_description string | null maxLength 250 SEO-metabeskrivning.
language string enum: de en bg cs da el es fr hr hu it nl pl pt ro sk sl sv uk Kortets primära språk (t.ex. de).
status string | null enum: active, draft, archived Publiceringsstatus: active, draft eller archived.

Lyckat svar

200 OK med det uppdaterade kortet i data-objektet plus ett message.

Felkoder

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

Raderar ett kort permanent.

Parametrar

Namn I Typ Obligatorisk Beskrivning
card path integer ja Kortets ID.

Lyckat svar

200 OK med ett bekräftelsemeddelande.

Felkoder

401403404429
02

Leads

Läs kontakter som samlats in via lead-formulären på dina kort.

GET
/api/v1/leads Scope leads:read

Listar leads som samlats in över alla kort, nyaste först. Filtrera till ett kort med card_id.

Parametrar

Namn I Typ Obligatorisk Beskrivning
card_id query integer nej Begränsa till ett enskilt kort som du äger.
page query integer nej Sidnummer (1-baserat).
per_page query integer nej Objekt per sida, max 100.

Lyckat svar

200 OK med en data-array av leads och ett meta-objekt.

Felkoder

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

Returnerar en enskild lead med en kompakt referens till det insamlande kortet.

Parametrar

Namn I Typ Obligatorisk Beskrivning
id path integer ja Leadens ID.

Lyckat svar

200 OK med leaden i data-objektet.

Felkoder

401403404429
03

Analytics

Aggregerad visnings- och klickstatistik — för alla kort eller per kort.

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

Aggregerade visningsmått över alla kort eller — via card_id — för ett enskilt kort.

Parametrar

Namn I Typ Obligatorisk Beskrivning
card_id query integer nej Begränsa till ett enskilt kort som du äger.
period query string (enum) nej Rapporteringsfönster. Tillåtna: 7d, 14d, 30d, 90d, 365d. Standard 30d.

Lyckat svar

200 OK med total_views, unique_views, views_per_day plus devices, countries och referrers i data-objektet.

Felkoder

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

Aggregerade klickmått över alla kort eller — via card_id — för ett enskilt kort.

Parametrar

Namn I Typ Obligatorisk Beskrivning
card_id query integer nej Begränsa till ett enskilt kort som du äger.
period query string (enum) nej Rapporteringsfönster. Tillåtna: 7d, 14d, 30d, 90d, 365d. Standard 30d.

Lyckat svar

200 OK med total_clicks, clicks_by_type och clicks_per_day i data-objektet.

Felkoder

401403422429

05

Kodexempel

Kopiera-och-klistra-snuttar i cURL, JavaScript och Python. Ersätt DEIN_API_TOKEN med din riktiga token.

Lista kort
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"])
Skapa ett kort
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"])
Lista leads
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"])
Hämta analys
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"])

Exempel: skapa ett kort

Förfrågan · 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"
  }'
Svar · 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."
}

06

Fel

Varje fel returnerar en message-sträng. Valideringsfel (422)innehåller dessutom en errors-mappning.

Status Name Beskrivning Exempel-body
401 Unauthorized Token saknas eller är ogiltig.
{ "message": "Unauthenticated." }
403 Forbidden Planen inkluderar inte API-åtkomst (endast Enterprise) eller så saknar token det nödvändiga scopet.
{
  "message": "API access is not available on your current plan. Please upgrade to Enterprise."
}
404 Not Found Resursen finns inte eller tillhör inte ditt konto.
{ "message": "Not found." }
422 Unprocessable Entity Valideringen misslyckades — bodyn innehåller en errors-mappning (fält → meddelanden).
429 Too Many Requests Rate limit överskriden. Retry-After-headern anger väntetiden i sekunder.
{
  "message": "Too Many Requests",
  "retry_after": 37
}

422 innehåller dessutom en errors-mappning av fält → lista med meddelanden:

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."]
  }
}

07

Maskinläsbar specifikation

Hela API:et är dokumenterat som OpenAPI 3.1. Ladda ner specifikationen och importera den i Postman, Insomnia eller Scalar — eller generera typsäkra klienter för ditt språk från den.

Kompatibel med Postman · Insomnia · Scalar · OpenAPI-generatorer

Ladda ner openapi.json

08

Redo att integrera?

Importera OpenAPI-specifikationen i dina verktyg eller skapa din första API-token direkt i instrumentpanelen.