Developers

Your cards, in your own systems

Connect your HR system, intranet, CRM or AI assistant to your company's digital business cards with your own API key. Each key works only with the scopes you choose.

API access is included in the Enterprise plan. See plans

Getting started

In the panel, open API Keys and create a key. Choose only the scopes the integration needs.
Copy the key right away; it is shown once. We store only its hash.
Send it in the Authorization header and test the connection with /api/v1/me.

curl https://digicardsystem.com/api/v1/me \
  -H "Authorization: Bearer dcs_…"

Scopes

Scope	Allows
`cards:read`	Read cards: list and details, card and vCard URLs.
`cards:write`	Create cards, update details, deactivate or reactivate. The plan's card limit applies.
`leads:read`	Read leads submitted through the contact form on card pages.

Endpoints

Request	Scope	Description
`GET /api/v1/me`	—	Connection test: the key's company, scopes, plan limits and usage.
`GET /api/v1/cards`	cards:read	Cards. Query: q (name, email, slug), status (active \| inactive \| all), page, pageSize (max 100).
`GET /api/v1/cards/{id}`	cards:read	A single card.
`POST /api/v1/cards`	cards:write	New card. firstName and lastName are required; slug defaults to the name, company to the company's default name. 201 on success.
`PATCH /api/v1/cards/{id}`	cards:write	Update: only the fields you send change; null or missing fields stay, "" clears a field. The previous version can be restored in the panel.
`POST /api/v1/cards/{id}/deactivate`	cards:write	Deactivates the card (e.g. an employee left). Nothing is deleted.
`POST /api/v1/cards/{id}/activate`	cards:write	Reactivates the card.
`GET /api/v1/leads`	leads:read	Leads, newest first. Query: since (ISO 8601; only newer), cardId, page, pageSize.

Lists return { "items": [...], "page": 1, "pageSize": 50, "total": 128 }. Dates are ISO 8601 in UTC; field names are camelCase.

Example: a new employee's card

Your HR system can open a card the day someone joins and deactivate it the day they leave:

curl -X POST https://digicardsystem.com/api/v1/cards \
  -H "Authorization: Bearer dcs_…" \
  -H "Content-Type: application/json" \
  -d '{ "firstName": "Ayşe", "lastName": "Yılmaz", "title": "Satış Müdürü",
        "department": "Satış", "email": "ayse@firma.com.tr", "mobile": "0532 000 00 00" }'

Validation errors return 400 with the field and the reason; if the plan's card limit is full, 403. Photos, logos, NFC and templates are managed in the panel.

Example response

GET /api/v1/me

{
  "company": { "id": "7d3c…", "slug": "ornek-firma", "name": "Örnek Firma" },
  "plan": { "code": "Enterprise", "name": "Enterprise", "maxCards": 12, "maxUsers": 3 },
  "usage": { "activeCards": 9, "activeUsers": 3 },
  "key": { "prefix": "dcs_Ab12Cd34", "scopes": ["cards:read", "cards:write", "leads:read"], "expiresAt": null }
}

Errors and limits

Errors are returned as application/problem+json with a short explanation in Accept-Language language (Turkish by default).

Code	Meaning
`400`	Invalid request parameters.
`401`	Missing, revoked or expired key.
`403`	The key lacks the scope, the plan does not include API access, the subscription is inactive, or the card limit is full.
`404`	Not found (or belongs to another company).
`429`	More than 120 requests per minute per key; wait for Retry-After.

Security

A key only ever sees its own company's data; cookies and panel sessions are ignored on the API.
Use keys server-to-server; do not embed them in web pages or mobile apps.
Create a separate key per integration and revoke it in the panel when in doubt; the others keep working.
Every key's last use is shown in the panel.
Always call https://. A key sent to http:// travels unencrypted before the redirect; if that happens, revoke the key.
Besides the per-key limit, each IP address may send up to 600 requests per minute; request bodies are limited to 64 KB (413 above that).
When an AI assistant reads leads, give it read-only scopes: lead text is written by anonymous visitors and may contain instructions aimed at the assistant.

More: Security · Integration guide for administrators

Versioning

Within /api/v1 we only make backward-compatible changes: new endpoints and new fields may appear; ignore fields you do not know.
A breaking change comes with a new version path (/api/v2) and is announced in advance; v1 keeps working during the transition.

Connect your AI assistant (MCP)

Your own AI assistant can work with your cards through the Model Context Protocol, using the same key and scopes: "open a card for our new sales manager", "deactivate the leaver's card", "list this week's leads". The assistant's AI usage stays on your own AI subscription.

Address (Streamable HTTP): https://digicardsystem.com/mcp

Tool	Scope	What it does
`get_company`	—	Company, plan, limits and the key's scopes
`list_cards`	cards:read	Lists and searches cards
`get_card`	cards:read	A single card
`create_card`	cards:write	Creates a card (plan card limit applies)
`update_card`	cards:write	Updates a card; previous version restorable in the panel
`deactivate_card`	cards:write	Deactivates a card
`activate_card`	cards:write	Reactivates a card
`list_leads`	leads:read	Leads from card pages

Claude Code:

claude mcp add --transport http digicardsystem https://digicardsystem.com/mcp \
  --header "Authorization: Bearer dcs_…"

Clients configured with JSON (for example Cursor):

{
  "mcpServers": {
    "digicardsystem": {
      "url": "https://digicardsystem.com/mcp",
      "headers": { "Authorization": "Bearer dcs_…" }
    }
  }
}

It works with MCP clients that can send the key in a request header. Browser connectors that require an OAuth sign-in are not supported yet. Every change made through MCP is recorded in the audit log with the channel "mcp".

OpenAPI

The machine-readable description of every endpoint: /openapi.json (OpenAPI 3). Import it into Postman, your code generator or an AI agent.

Create an API key Plans