Developer platform

The Ideal Card API.

A programmatic surface over every NFC card, QR product, tap stream, order, and team seat. REST, JSON, HTTPS-only, versioned, and paginated by cursor. Built for CRMs, ERPs, back-office tools, and white-label apps.

By the Ideal Card team. Last reviewed . Contract v1.6.

Who this is for. Engineers integrating The Ideal Card into a CRM, back-office ERP, HR onboarding tool, or a white-label reseller product. If you're looking for no-code integrations, see Integrations — every SaaS in the catalog is built on the API you're reading about.

Overview

The Ideal Card API exposes every business object in the platform — products (cards, wearables, signage, accessories), profiles they resolve to, tap events, contacts captured on taps, orders, shipments, workspaces, teams, and integrations — as URL-addressable resources. Requests and responses are JSON. Every mutating call accepts an Idempotency-Key header. Errors follow RFC 7807 problem-document shape with a machine-readable type, a human-readable title, and a request_id to correlate with server logs.

Base URLs

  • Production — https://api.theidealcard.com
  • Sandbox (test data, no charges, resets nightly) — https://sandbox.api.theidealcard.com
  • EU data residency — https://eu.api.theidealcard.com
  • Enterprise dedicated instance — https://{tenant}.enterprise.api.theidealcard.com

Authentication

API key. Server-to-server calls send a bearer token: Authorization: Bearer sk_live_…. Keys are generated in the dashboard under Settings → Developer → API keys. Each key is scoped to a workspace, given a role (read, write, admin), and optionally IP-allowlisted. Rotate keys with zero downtime by minting a second key, migrating traffic, then revoking the old one; both are valid concurrently during rotation. Revoked keys stop working within 30 seconds globally.

OAuth 2.0. If you're building an app that other Ideal Card customers install, use the authorization-code flow with PKCE. Register your app to receive a client_id. Direct users to /oauth/authorize with a scope string. Exchange the authorization code at /oauth/token for an access token (1 hour TTL) and a refresh token (60 days, rotating on each use).

Versioning

The API is versioned in the URL: the current major is /v1. Breaking changes bump the major, and both versions run in parallel for at least twelve months. Additive changes (new fields, new endpoints, new webhook event types) ship without a version bump; existing clients ignore what they don't recognize. Deprecations are announced via the Sunset HTTP header, the changelog RSS feed, and email to every workspace owner who has called the deprecated endpoint in the previous 30 days.

Rate limits

Rate limits apply per workspace, not per key. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Exceeding the budget returns 429 with a Retry-After header. A token-bucket model permits bursts to 2x the sustained rate for up to 10 seconds.

TierSustainedBurstWebhook fanout
Free60 req/min120/min for 10s1 endpoint, 100 events/day
Pro600 req/min1,200/min for 10s5 endpoints, 10k events/day
Business3,000 req/min6,000/min for 10s25 endpoints, 250k events/day
EnterpriseNegotiatedNegotiatedUnlimited

Pagination

List endpoints return a cursor-paginated envelope. Passing ?limit=100&cursor=eyJ… paginates forward; the response includes meta.next_cursor (null when exhausted) and meta.has_more. Cursors are stable across concurrent inserts. Default page size is 25, maximum 100.

Errors

{
  "type": "https://theidealcard.com/errors/card-not-found",
  "title": "Card not found",
  "status": 404,
  "detail": "No card with id crd_9x2 exists in workspace ws_a11.",
  "instance": "/v1/cards/crd_9x2",
  "request_id": "req_01H8QK4RN2"
}

Quickstart

The five-minute integration: mint an API key, provision a card, bind it to a profile, subscribe to tap.recorded.

# 1. Provision a card and bind it to a profile URL
curl -X POST https://api.theidealcard.com/v1/cards \
  -H "Authorization: Bearer $IDEALCARD_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: onboard-2026-07-16-01" \
  -d '{
    "sku": "card-metal-black",
    "target_url": "https://ideal.bio/jane-doe",
    "label": "Jane Doe — Sales",
    "team_id": "team_9k2"
  }'

# 2. Pull last 30 days of taps for that card
curl -H "Authorization: Bearer $IDEALCARD_KEY" \
  "https://api.theidealcard.com/v1/taps?filter[card_id]=crd_01H8Q&filter[at:gte]=2026-06-16"

# 3. Subscribe to tap events
curl -X POST https://api.theidealcard.com/v1/webhooks \
  -H "Authorization: Bearer $IDEALCARD_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://acme.example.com/hooks/idealcard",
    "events": ["tap.recorded","contact.captured"],
    "secret": "whsec_pick_your_own_32_bytes_hex"
  }'
// Node.js
import IdealCard from "@theidealcard/node";

const client = new IdealCard({ apiKey: process.env.IDEALCARD_KEY });

const card = await client.cards.create({
  sku: "card-metal-black",
  target_url: "https://ideal.bio/jane-doe",
  label: "Jane Doe — Sales",
  team_id: "team_9k2",
}, { idempotencyKey: "onboard-2026-07-16-01" });

const taps = await client.taps.list({
  filter: { card_id: card.id, "at:gte": "2026-06-16" },
  limit: 100,
});

Core endpoints

Fifteen endpoints cover the bulk of what an integration needs. The full reference — roughly 110 endpoints across cards, wearables, signage, orders, shipments, taps, contacts, teams, workspaces, integrations, and admin actions — lives in the OpenAPI 3.1 spec at https://api.theidealcard.com/openapi.json.

MethodPathDescription
GET/v1/cardsList cards (and other NFC/QR products) in your workspace.
POST/v1/cardsProvision a new card, bind it to a target URL or profile.
PATCH/v1/cards/{id}Reassign target URL, change label, transfer to a new team seat.
DELETE/v1/cards/{id}Deactivate a card. Soft-delete; can be reactivated within 30 days.
GET/v1/tapsList tap events across the workspace with filter/sort.
GET/v1/analyticsTime-series analytics: taps, unique visitors, conversions, per team/card.
POST/v1/webhooksCreate a webhook subscription with HMAC secret.
GET/v1/webhooksList webhook subscriptions.
DELETE/v1/webhooks/{id}Delete a webhook subscription.
GET/v1/ordersList orders with line items, artwork, and shipment status.
POST/v1/ordersPlace a bulk order for cards or signage.
POST/v1/teamsCreate a team seat structure for org-wide rollouts.
POST/v1/teams/{id}/inviteInvite a member to a team; sends email or SCIM push.
GET/v1/contactsList contacts captured on tap-through forms.
GET/v1/products/catalogList every SKU with pricing, MOQ, and lead time.

Example: streaming taps

GET /v1/taps?filter[team_id]=team_9k2&filter[at:gte]=2026-07-01&sort=-at&limit=100 HTTP/1.1
Authorization: Bearer sk_live_…
{
  "data": [
    {
      "id": "tp_01H8QK",
      "card_id": "crd_01H8QK4RN2",
      "team_id": "team_9k2",
      "at": "2026-07-16T14:33:12Z",
      "source": "nfc",
      "device": {"platform":"iOS","version":"20.1","model":"iPhone 17 Pro"},
      "geo": {"country":"US","region":"NY","city":"New York","approximate":true},
      "referrer": null,
      "resolved_target": "https://ideal.bio/jane-doe",
      "contact_captured": true,
      "contact_id": "cnt_5j2"
    }
  ],
  "meta": {"next_cursor":"eyJhdCI6IjIwMjYtMDctMTZUMTQ6MzI6MDBaIn0","has_more":true,"limit":100}
}

Webhook events

Webhooks are the recommended way to react to activity in near-real-time. Each subscription targets one URL and an allowlist of event types. Deliveries retry on any non-2xx response with exponential backoff (2, 4, 8, 16, 32 minutes, then hourly for 24 hours).

EventDescription
tap.recordedFires on every NFC tap or QR scan.
contact.capturedFires when a tap-through form captures a contact.
card.provisionedFires when a card is created and its NFC UID assigned.
card.reassignedFires when a card's target URL is changed.
card.deactivatedFires when a card is soft-deleted.
order.placedFires when an order enters production.
order.shippedFires when a shipment is handed to carrier with tracking.
team.member.addedFires when a member joins a team seat.
team.member.removedFires when a member is removed from a team.
analytics.digestFires nightly with a rolled-up analytics summary per team.

Signature verification

Every delivery carries two headers: X-IdealCard-Timestamp and X-IdealCard-Signature (hex HMAC-SHA256 of "{timestamp}.{body}" using your secret). Verify by recomputing the HMAC, comparing in constant time, and rejecting anything with a timestamp older than 5 minutes.

import crypto from "node:crypto";

export function verify(req, secret) {
  const ts  = req.headers["x-idealcard-timestamp"];
  const sig = req.headers["x-idealcard-signature"];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${ts}.${req.rawBody}`)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

Permission scopes

ScopeGrants
cards.readList and retrieve cards, wearables, signage.
cards.writeProvision, reassign, deactivate cards.
taps.readRead tap streams and contact-capture records.
analytics.readRead time-series analytics and rollups.
orders.readList and retrieve orders and shipments.
orders.writePlace, cancel, and modify orders.
teams.manageCreate teams, invite members, modify seat allocations.
webhooks.manageCreate, list, delete webhook subscriptions.
workspace.adminManage users, billing, audit-log export.

Official SDKs

Every SDK wraps the same REST surface, provides type definitions, ships a webhook-verifier helper, and handles retries with exponential backoff.

  • Node.js — @theidealcard/node (GA)
  • Python — idealcard (GA)
  • PHP — theidealcard/idealcard-php (GA)
  • Ruby — idealcard gem (Beta)
  • Go — github.com/theidealcard/idealcard-go (Beta)
  • Java — com.theidealcard:idealcard-java (Beta)
  • Kotlin — idealcard-kotlin (Beta)
  • Swift — IdealCardKit (Beta)

Sandbox and testing

The sandbox at https://sandbox.api.theidealcard.com is a full-fidelity replica of production with three differences: workspaces reset nightly at 04:00 UTC, no orders are actually manufactured (they simulate a compressed 5-minute lifecycle), and webhooks include a X-IdealCard-Environment: sandbox header so your receiver can branch on it. Sandbox and production credentials are distinct.

Enterprise API

Enterprise customers can be provisioned onto a dedicated instance (https://{tenant}.enterprise.api.theidealcard.com) that is isolated from the shared multi-tenant plane. That instance has its own rate-limit budget, its own database cluster, and its own regional deployment (US, EU, or a customer-selected region). Custom SLAs of 99.95% or 99.99% uptime apply with 15-minute Sev 1 response and a named account engineer on call. The Enterprise API is a strict superset of the public API. It adds SCIM 2.0 user provisioning, SAML/OIDC identity binding, audit-log streaming to a customer-owned S3 bucket or SIEM webhook, field-level encryption key rotation, and cross-workspace analytics rollups for franchise organizations. Talk to Enterprise sales to scope your deployment.

Get an API key

Free tier includes 60 req/min and 100 webhook events/day. No card required.

Create account   Talk to Enterprise
AI