REST API · v1

FalconCard REST API

Manage cards, leads and analytics programmatically — for CRM sync, automation and your own integrations. Bearer-token authentication, JSON over HTTPS.

Getting started

From token to your first successful request in three steps. The API speaks JSON over HTTPS exclusively and follows common REST conventions — if you've ever integrated an HTTP API, you'll feel right at home.

  1. 1

    Create a token

    Open your dashboard and navigate to Account → API tokens. Pick the scopes your integration needs and copy the token right away — for security it is shown in plaintext only once.

    Go to API tokens
  2. 2

    Set the Bearer header

    Send the token in the Authorization header on every request. Add Accept: application/json so errors come back as JSON too.

    Authorization: Bearer DEIN_API_TOKEN
  3. 3

    Send your first request

    Fetch your cards. A successful call returns HTTP 200 with a data array and a meta object for pagination:

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

    If you see this shape, your authentication is correct. Every list endpoint responds with the same data + meta schema — single resources come back in a data object without meta.

Base URL: https://falconcard.net/api/v1 · all responses are JSON.

Authentication

Every request authenticates with a personal access token (Laravel Sanctum) in the header:

Authorization: Bearer DEIN_API_TOKEN

You can create and revoke tokens anytime in the dashboard. Each token carries one or more scopes that limit its permissions.

Scopes

cards:read List and read cards
cards:write Create, update and delete cards
leads:read List and read leads
analytics:read Read view and click analytics

Concepts

Four building blocks that work identically for every endpoint — learn them once, they apply everywhere.

Versioning

The current version is /api/v1 and is pinned in the path. Breaking changes ship under a new prefix (e.g. /api/v2), so existing integrations stay stable.

Request format

Write endpoints expect a JSON body with Content-Type: application/json. Timestamps are ISO 8601 (UTC). Unknown fields are ignored, missing optional fields stay unchanged.

Rate limiting

Enterprise tokens may send 1000 requests per minute. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and Retry-After. When exceeded you get 429 Too Many Requests with a Retry-After header (seconds until reset) — wait that long before retrying.

Headers · every response
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 994
Retry-After: 37

Pagination

List endpoints return up to 15 items per page. Control it with ?page= (1-based) and ?per_page= (max 100). The meta object reports current_page, last_page, per_page and total.

meta · every list
"meta": {
  "current_page": 2,
  "last_page": 7,
  "per_page": 15,
  "total": 98
}

Availability. The REST API is part of the Enterprise plan. Tokens from other plans receive 403.

Endpoint reference

Full reference for all ten endpoints, grouped by resource. Each definition stays in sync with the OpenAPI spec — ready to import into Postman, Insomnia, Scalar or your code generator.

Cards

Create, read, update and delete digital business cards.

GET /api/v1/cards Scope cards:read

Lists the account's cards, most recently updated first.

Parameters

Name In Type Required Description
page query integer no Page number (1-based).
per_page query integer no Items per page, max 100.

Success response

200 OK with a data array of cards and a meta object for pagination.

Error codes

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

Creates a new card. slug and title are generated automatically. Plan-gated fields are coerced to allowed values.

Parameters

No parameters.

Request body application/json

Field Type Constraints Description
first_name Required string maxLength 100 First name.
last_name Required string maxLength 100 Last name.
job_title string | null maxLength 150 Position / job title.
company string | null maxLength 150 Company name.
bio string | null maxLength 1000 Short description / bio.
email string | null email · maxLength 255 Contact email (valid email format).
phone string | null maxLength 50 Phone number. Allowed characters: digits, spaces and + - ( ) . /
website string | null uri · maxLength 500 Website URL.
booking_url string | null uri · maxLength 500 Link to appointment booking.
video_url string | null uri · maxLength 500 Video URL. Requires the advanced analytics feature, otherwise ignored. plan-gated
address string | null maxLength 500 Postal address.
social_links array | null List of social media links (array of objects).
design_config object | null Design overrides (colours, font, layout) as an object.
template_id string | null maxLength 50 ID of the template to use.
is_public boolean | null default true Whether the card is publicly reachable. Default true.
show_branding boolean | null Show FalconCard branding. Hiding it requires the whitelabel feature, otherwise forced to true. plan-gated
show_lead_form boolean | null Show the lead form on the card. Requires the lead form feature, otherwise forced to false. plan-gated
seo_title string | null maxLength 100 SEO title for the public card.
seo_description string | null maxLength 250 SEO meta description.
language string | null maxLength 5 Primary language of the card (e.g. de).

Success response

201 Created with the new card in the data object plus a message.

Error codes

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

Returns a single card including its captured leads.

Parameters

Name In Type Required Description
card path integer yes ID of the card.

Success response

200 OK with the card (including an embedded leads array) in the data object.

Error codes

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

Updates a card. All fields are optional; only provided fields change. PUT and PATCH behave identically.

Parameters

Name In Type Required Description
card path integer yes ID of the card.

Request body application/json

Field Type Constraints Description
first_name string maxLength 100 First name.
last_name string maxLength 100 Last name.
job_title string | null maxLength 150 Position / job title.
company string | null maxLength 150 Company name.
bio string | null maxLength 1000 Short description / bio.
email string | null email · maxLength 255 Contact email (valid email format).
phone string | null maxLength 50 Phone number. Allowed characters: digits, spaces and + - ( ) . /
website string | null uri · maxLength 500 Website URL.
booking_url string | null uri · maxLength 500 Link to appointment booking.
video_url string | null uri · maxLength 500 Video URL. Requires the advanced analytics feature, otherwise ignored. plan-gated
address string | null maxLength 500 Postal address.
social_links array | null List of social media links (array of objects).
design_config object | null Design overrides (colours, font, layout) as an object.
template_id string | null maxLength 50 ID of the template to use.
is_public boolean | null Whether the card is publicly reachable. Default true.
show_branding boolean | null Show FalconCard branding. Hiding it requires the whitelabel feature, otherwise forced to true. plan-gated
show_lead_form boolean | null Show the lead form on the card. Requires the lead form feature, otherwise forced to false. plan-gated
seo_title string | null maxLength 100 SEO title for the public card.
seo_description string | null maxLength 250 SEO meta description.
language string | null maxLength 5 Primary language of the card (e.g. de).
status string | null enum: active, draft, archived Publication status: active, draft or archived.

Success response

200 OK with the updated card in the data object plus a message.

Error codes

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

Updates a card. All fields are optional; only provided fields change. PUT and PATCH behave identically.

Parameters

Name In Type Required Description
card path integer yes ID of the card.

Request body application/json

Field Type Constraints Description
first_name string maxLength 100 First name.
last_name string maxLength 100 Last name.
job_title string | null maxLength 150 Position / job title.
company string | null maxLength 150 Company name.
bio string | null maxLength 1000 Short description / bio.
email string | null email · maxLength 255 Contact email (valid email format).
phone string | null maxLength 50 Phone number. Allowed characters: digits, spaces and + - ( ) . /
website string | null uri · maxLength 500 Website URL.
booking_url string | null uri · maxLength 500 Link to appointment booking.
video_url string | null uri · maxLength 500 Video URL. Requires the advanced analytics feature, otherwise ignored. plan-gated
address string | null maxLength 500 Postal address.
social_links array | null List of social media links (array of objects).
design_config object | null Design overrides (colours, font, layout) as an object.
template_id string | null maxLength 50 ID of the template to use.
is_public boolean | null Whether the card is publicly reachable. Default true.
show_branding boolean | null Show FalconCard branding. Hiding it requires the whitelabel feature, otherwise forced to true. plan-gated
show_lead_form boolean | null Show the lead form on the card. Requires the lead form feature, otherwise forced to false. plan-gated
seo_title string | null maxLength 100 SEO title for the public card.
seo_description string | null maxLength 250 SEO meta description.
language string | null maxLength 5 Primary language of the card (e.g. de).
status string | null enum: active, draft, archived Publication status: active, draft or archived.

Success response

200 OK with the updated card in the data object plus a message.

Error codes

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

Permanently deletes a card.

Parameters

Name In Type Required Description
card path integer yes ID of the card.

Success response

200 OK with a confirmation message.

Error codes

401403404429

Leads

Read contacts captured via the lead forms on your cards.

GET /api/v1/leads Scope leads:read

Lists leads captured across all cards, newest first. Filter to one card with card_id.

Parameters

Name In Type Required Description
card_id query integer no Restrict to a single card you own.
page query integer no Page number (1-based).
per_page query integer no Items per page, max 100.

Success response

200 OK with a data array of leads and a meta object.

Error codes

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

Returns a single lead with a compact reference to the capturing card.

Parameters

Name In Type Required Description
id path integer yes ID of the lead.

Success response

200 OK with the lead in the data object.

Error codes

401403404429

Analytics

Aggregated view and click statistics — across all cards or per card.

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

Aggregated view metrics across all cards or — via card_id — for a single card.

Parameters

Name In Type Required Description
card_id query integer no Restrict to a single card you own.
period query string (enum) no Reporting window. Allowed: 7d, 14d, 30d, 90d, 365d. Default 30d.

Success response

200 OK with total_views, unique_views, views_per_day plus devices, countries and referrers in the data object.

Error codes

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

Aggregated click metrics across all cards or — via card_id — for a single card.

Parameters

Name In Type Required Description
card_id query integer no Restrict to a single card you own.
period query string (enum) no Reporting window. Allowed: 7d, 14d, 30d, 90d, 365d. Default 30d.

Success response

200 OK with total_clicks, clicks_by_type and clicks_per_day in the data object.

Error codes

401403422429

Code examples

Copy-paste snippets in cURL, JavaScript and Python. Replace DEIN_API_TOKEN with your real token.

List cards
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"])
Create a card
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"])
List 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"])
Fetch analytics
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"])

Example: create a card

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

Errors

Every error returns a message string. Validation errors (422) additionally contain an errors map.

Status Name Description Example body
401 Unauthorized Token missing or invalid.
{ "message": "Unauthenticated." }
403 Forbidden Plan does not include API access (Enterprise only) or the token is missing the required scope.
{
  "message": "API access is not available on your current plan. Please upgrade to Enterprise."
}
404 Not Found Resource does not exist or does not belong to your account.
{ "message": "Not found." }
422 Unprocessable Entity Validation failed — the body contains an errors map (field → messages).
429 Too Many Requests Rate limit exceeded. The Retry-After header states the wait time in seconds.
{
  "message": "Too Many Requests",
  "retry_after": 37
}

422 additionally contain an errors map of field → list of messages:

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

Machine-readable specification

The complete API is documented as OpenAPI 3.1. Download the spec and import it into Postman, Insomnia or Scalar — or generate type-safe clients for your language from it.

Compatible with Postman · Insomnia · Scalar · OpenAPI generators

Download openapi.json

Ready to integrate?

Import the OpenAPI spec into your tooling or create your first API token right in the dashboard.