Naar de inhoud

REST API · v1

FalconCard REST API

Beheer kaarten, leads en analytics programmatisch — voor CRM-synchronisatie, automatisering en uw eigen integraties. Authenticatie met Bearer-token, JSON via HTTPS.

01

Aan de slag

Van token naar uw eerste succesvolle verzoek in drie stappen. De API spreekt uitsluitend JSON via HTTPS en volgt gangbare REST-conventies — als u ooit een HTTP API hebt geïntegreerd, voelt u zich meteen thuis.

  1. Een token aanmaken

    Open uw dashboard en navigeer naar Account → API-tokens. Kies de scopes die uw integratie nodig heeft en kopieer het token direct — om veiligheidsredenen wordt het slechts één keer in platte tekst weergegeven.

    Naar API-tokens
  2. De Bearer-header instellen

    Stuur het token bij elk verzoek mee in de Authorization-header. Voeg Accept: application/json toe zodat fouten ook als JSON terugkomen.

    Authorization: Bearer DEIN_API_TOKEN
  3. Uw eerste verzoek versturen

    Haal uw kaarten op. Een succesvolle aanroep retourneert HTTP 200 met een data-array en een meta-object voor paginering:

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

Als u deze structuur ziet, is uw authenticatie correct. Elk lijst-endpoint reageert met hetzelfde data + meta -schema — losse resources komen terug in een data-object zonder meta.

Basis-URL: https://falconcard.net/api/v1 · alle responses zijn JSON.

02

Authenticatie

Elk verzoek wordt geauthenticeerd met een persoonlijk toegangstoken (Laravel Sanctum) in de header:

Authorization: Bearer DEIN_API_TOKEN

U kunt tokens op elk moment aanmaken en intrekken in het dashboard. Elk token draagt een of meer scopes die de rechten ervan beperken.

Scopes

cards:read

Kaarten weergeven en lezen

cards:write

Kaarten aanmaken, bijwerken en verwijderen

leads:read

Leads weergeven en lezen

analytics:read

Weergave- en klikanalytics lezen

03

Concepten

Vier bouwstenen die voor elk endpoint identiek werken — leer ze één keer en ze gelden overal.

Versiebeheer

De huidige versie is /api/v1 en is vastgelegd in het pad. Ingrijpende wijzigingen verschijnen onder een nieuw prefix (bijv. /api/v2), zodat bestaande integraties stabiel blijven.

Verzoekformaat

Schrijf-endpoints verwachten een JSON-body met Content-Type: application/json. Tijdstempels zijn ISO 8601 (UTC). Onbekende velden worden genegeerd, ontbrekende optionele velden blijven ongewijzigd.

Rate limiting

Enterprise-tokens mogen 1000 verzoeken per minuut versturen. Elke response draagt X-RateLimit-Limit en X-RateLimit-Remaining. Bij overschrijding krijgt u 429 Too Many Requests met een Retry-After-header (seconden tot reset) — wacht zo lang voordat u het opnieuw probeert.

Headers · elke response
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 994

Paginering

Lijst-endpoints retourneren tot 15 items per pagina. Stuur dit aan met ?page= (1-gebaseerd) en ?per_page= (max. 100). Het meta-object meldt current_page, last_page, per_page en total.

meta · elke lijst
"meta": {
  "current_page": 2,
  "last_page": 7,
  "per_page": 15,
  "total": 98
}

Beschikbaarheid. De REST API maakt deel uit van het Enterprise-abonnement. Tokens van andere abonnementen ontvangen 403.

04

Endpoint-referentie

Volledige referentie voor alle tien endpoints, gegroepeerd per resource. Elke definitie blijft synchroon met de OpenAPI-spec — klaar om te importeren in Postman, Insomnia, Scalar of uw codegenerator.

01

Cards

Maak digitale visitekaartjes aan, lees, werk bij en verwijder ze.

GET
/api/v1/cards Scope cards:read

Toont de kaarten van het account, meest recent bijgewerkt eerst.

Parameters

Naam In Type Vereist Beschrijving
page query integer nee Paginanummer (1-gebaseerd).
per_page query integer nee Items per pagina, max. 100.

Succesvolle response

200 OK met een data-array van kaarten en een meta-object voor paginering.

Foutcodes

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

Maakt een nieuwe kaart aan. slug en title worden automatisch gegenereerd. Abonnementsafhankelijke velden worden afgedwongen naar toegestane waarden.

Parameters

Geen parameters.

Verzoek-body application/json

Veld Type Beperkingen Beschrijving
first_name Vereist string maxLength 100 Voornaam.
last_name Vereist string maxLength 100 Achternaam.
job_title string | null maxLength 150 Functie / functietitel.
company string | null maxLength 150 Bedrijfsnaam.
bio string | null maxLength 1000 Korte beschrijving / bio.
email string | null email · maxLength 255 Contact-e-mail (geldig e-mailformaat).
phone string | null maxLength 50 Telefoonnummer. Toegestane tekens: cijfers, spaties en + - ( ) . /
website string | null uri · maxLength 500 Website-URL.
booking_url string | null uri · maxLength 500 Link naar het maken van afspraken.
video_url string | null uri · maxLength 500 Video-URL. Vereist de functie geavanceerde analytics, anders genegeerd. abonnementsafhankelijk
address string | null maxLength 500 Postadres.
social_links array | null maxItems 20 · platform: enum · url: http(s) uri or handle (completed) · maxLength 500 · label: maxLength 100 Lijst met social media-links (array van objecten).
design_config object | null — Ontwerp-overrides (kleuren, lettertype, lay-out) als object.
template_id string | null maxLength 50 ID van het te gebruiken sjabloon.
is_public boolean | null default true Of de kaart openbaar bereikbaar is. Standaard true.
show_branding boolean | null — Toon FalconCard-branding. Verbergen vereist de whitelabel-functie, anders afgedwongen naar true. abonnementsafhankelijk
show_lead_form boolean | null — Toon het leadformulier op de kaart. Vereist de leadformulier-functie, anders afgedwongen naar false. abonnementsafhankelijk
seo_title string | null maxLength 100 SEO-titel voor de openbare kaart.
seo_description string | null maxLength 250 SEO-metabeschrijving.
language string enum: de en bg cs da el es fr hr hu it nl pl pt ro sk sl sv uk Primaire taal van de kaart (bijv. de).

Succesvolle response

201 Created met de nieuwe kaart in het data-object plus een message.

Foutcodes

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

Retourneert een enkele kaart inclusief de vastgelegde leads.

Parameters

Naam In Type Vereist Beschrijving
card pad integer ja ID van de kaart.

Succesvolle response

200 OK met de kaart (inclusief een ingesloten leads-array) in het data-object.

Foutcodes

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

Werkt een kaart bij. Alle velden zijn optioneel; alleen opgegeven velden wijzigen. PUT en PATCH gedragen zich identiek.

Parameters

Naam In Type Vereist Beschrijving
card pad integer ja ID van de kaart.

Verzoek-body application/json

Veld Type Beperkingen Beschrijving
first_name string maxLength 100 Voornaam.
last_name string maxLength 100 Achternaam.
job_title string | null maxLength 150 Functie / functietitel.
company string | null maxLength 150 Bedrijfsnaam.
bio string | null maxLength 1000 Korte beschrijving / bio.
email string | null email · maxLength 255 Contact-e-mail (geldig e-mailformaat).
phone string | null maxLength 50 Telefoonnummer. Toegestane tekens: cijfers, spaties en + - ( ) . /
website string | null uri · maxLength 500 Website-URL.
booking_url string | null uri · maxLength 500 Link naar het maken van afspraken.
video_url string | null uri · maxLength 500 Video-URL. Vereist de functie geavanceerde analytics, anders genegeerd. abonnementsafhankelijk
address string | null maxLength 500 Postadres.
social_links array | null maxItems 20 · platform: enum · url: http(s) uri or handle (completed) · maxLength 500 · label: maxLength 100 Lijst met social media-links (array van objecten).
design_config object | null — Ontwerp-overrides (kleuren, lettertype, lay-out) als object.
template_id string | null maxLength 50 ID van het te gebruiken sjabloon.
is_public boolean | null — Of de kaart openbaar bereikbaar is. Standaard true.
show_branding boolean | null — Toon FalconCard-branding. Verbergen vereist de whitelabel-functie, anders afgedwongen naar true. abonnementsafhankelijk
show_lead_form boolean | null — Toon het leadformulier op de kaart. Vereist de leadformulier-functie, anders afgedwongen naar false. abonnementsafhankelijk
seo_title string | null maxLength 100 SEO-titel voor de openbare kaart.
seo_description string | null maxLength 250 SEO-metabeschrijving.
language string enum: de en bg cs da el es fr hr hu it nl pl pt ro sk sl sv uk Primaire taal van de kaart (bijv. de).
status string | null enum: active, draft, archived Publicatiestatus: active, draft of archived.

Succesvolle response

200 OK met de bijgewerkte kaart in het data-object plus een message.

Foutcodes

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

Werkt een kaart bij. Alle velden zijn optioneel; alleen opgegeven velden wijzigen. PUT en PATCH gedragen zich identiek.

Parameters

Naam In Type Vereist Beschrijving
card pad integer ja ID van de kaart.

Verzoek-body application/json

Veld Type Beperkingen Beschrijving
first_name string maxLength 100 Voornaam.
last_name string maxLength 100 Achternaam.
job_title string | null maxLength 150 Functie / functietitel.
company string | null maxLength 150 Bedrijfsnaam.
bio string | null maxLength 1000 Korte beschrijving / bio.
email string | null email · maxLength 255 Contact-e-mail (geldig e-mailformaat).
phone string | null maxLength 50 Telefoonnummer. Toegestane tekens: cijfers, spaties en + - ( ) . /
website string | null uri · maxLength 500 Website-URL.
booking_url string | null uri · maxLength 500 Link naar het maken van afspraken.
video_url string | null uri · maxLength 500 Video-URL. Vereist de functie geavanceerde analytics, anders genegeerd. abonnementsafhankelijk
address string | null maxLength 500 Postadres.
social_links array | null maxItems 20 · platform: enum · url: http(s) uri or handle (completed) · maxLength 500 · label: maxLength 100 Lijst met social media-links (array van objecten).
design_config object | null — Ontwerp-overrides (kleuren, lettertype, lay-out) als object.
template_id string | null maxLength 50 ID van het te gebruiken sjabloon.
is_public boolean | null — Of de kaart openbaar bereikbaar is. Standaard true.
show_branding boolean | null — Toon FalconCard-branding. Verbergen vereist de whitelabel-functie, anders afgedwongen naar true. abonnementsafhankelijk
show_lead_form boolean | null — Toon het leadformulier op de kaart. Vereist de leadformulier-functie, anders afgedwongen naar false. abonnementsafhankelijk
seo_title string | null maxLength 100 SEO-titel voor de openbare kaart.
seo_description string | null maxLength 250 SEO-metabeschrijving.
language string enum: de en bg cs da el es fr hr hu it nl pl pt ro sk sl sv uk Primaire taal van de kaart (bijv. de).
status string | null enum: active, draft, archived Publicatiestatus: active, draft of archived.

Succesvolle response

200 OK met de bijgewerkte kaart in het data-object plus een message.

Foutcodes

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

Verwijdert een kaart permanent.

Parameters

Naam In Type Vereist Beschrijving
card pad integer ja ID van de kaart.

Succesvolle response

200 OK met een bevestigingsbericht.

Foutcodes

401403404429
02

Leads

Lees contacten die zijn vastgelegd via de leadformulieren op uw kaarten.

GET
/api/v1/leads Scope leads:read

Toont leads die over alle kaarten zijn vastgelegd, nieuwste eerst. Filter op één kaart met card_id.

Parameters

Naam In Type Vereist Beschrijving
card_id query integer nee Beperk tot een enkele kaart die u bezit.
page query integer nee Paginanummer (1-gebaseerd).
per_page query integer nee Items per pagina, max. 100.

Succesvolle response

200 OK met een data-array van leads en een meta-object.

Foutcodes

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

Retourneert een enkele lead met een compacte verwijzing naar de vastleggende kaart.

Parameters

Naam In Type Vereist Beschrijving
id pad integer ja ID van de lead.

Succesvolle response

200 OK met de lead in het data-object.

Foutcodes

401403404429
03

Analytics

Geaggregeerde weergave- en klikstatistieken — over alle kaarten of per kaart.

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

Geaggregeerde weergavemetrieken over alle kaarten of — via card_id — voor een enkele kaart.

Parameters

Naam In Type Vereist Beschrijving
card_id query integer nee Beperk tot een enkele kaart die u bezit.
period query string (enum) nee Rapportagevenster. Toegestaan: 7d, 14d, 30d, 90d, 365d. Standaard 30d.

Succesvolle response

200 OK met total_views, unique_views, views_per_day plus devices, countries en referrers in het data-object.

Foutcodes

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

Geaggregeerde klikmetrieken over alle kaarten of — via card_id — voor een enkele kaart.

Parameters

Naam In Type Vereist Beschrijving
card_id query integer nee Beperk tot een enkele kaart die u bezit.
period query string (enum) nee Rapportagevenster. Toegestaan: 7d, 14d, 30d, 90d, 365d. Standaard 30d.

Succesvolle response

200 OK met total_clicks, clicks_by_type en clicks_per_day in het data-object.

Foutcodes

401403422429

05

Codevoorbeelden

Kant-en-klare snippets in cURL, JavaScript en Python. Vervang DEIN_API_TOKEN door uw echte token.

Kaarten weergeven
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"])
Een kaart aanmaken
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 weergeven
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 ophalen
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"])

Voorbeeld: een kaart aanmaken

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

06

Fouten

Elke fout retourneert een message-string. Validatiefouten (422)bevatten daarnaast een errors-map.

Status Name Beschrijving Voorbeeld-body
401 Unauthorized Token ontbreekt of is ongeldig.
{ "message": "Unauthenticated." }
403 Forbidden Het abonnement omvat geen API-toegang (alleen Enterprise) of het token mist de vereiste scope.
{
  "message": "API access is not available on your current plan. Please upgrade to Enterprise."
}
404 Not Found Resource bestaat niet of behoort niet tot uw account.
{ "message": "Not found." }
422 Unprocessable Entity Validatie mislukt — de body bevat een errors-map (veld → berichten).
429 Too Many Requests Rate limit overschreden. De Retry-After-header geeft de wachttijd in seconden aan.
{
  "message": "Too Many Requests",
  "retry_after": 37
}

422 bevatten daarnaast een errors-map van veld → lijst met berichten:

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

Machineleesbare specificatie

De volledige API is gedocumenteerd als OpenAPI 3.1. Download de spec en importeer deze in Postman, Insomnia of Scalar — of genereer er typeveilige clients voor uw taal uit.

Compatibel met Postman · Insomnia · Scalar · OpenAPI-generatoren

openapi.json downloaden

08

Klaar om te integreren?

Importeer de OpenAPI-spec in uw tooling of maak uw eerste API-token direct in het dashboard aan.