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.
| Tier | Sustained | Burst | Webhook fanout |
|---|---|---|---|
| Free | 60 req/min | 120/min for 10s | 1 endpoint, 100 events/day |
| Pro | 600 req/min | 1,200/min for 10s | 5 endpoints, 10k events/day |
| Business | 3,000 req/min | 6,000/min for 10s | 25 endpoints, 250k events/day |
| Enterprise | Negotiated | Negotiated | Unlimited |
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.
| Method | Path | Description |
|---|---|---|
| GET | /v1/cards | List cards (and other NFC/QR products) in your workspace. |
| POST | /v1/cards | Provision 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/taps | List tap events across the workspace with filter/sort. |
| GET | /v1/analytics | Time-series analytics: taps, unique visitors, conversions, per team/card. |
| POST | /v1/webhooks | Create a webhook subscription with HMAC secret. |
| GET | /v1/webhooks | List webhook subscriptions. |
| DELETE | /v1/webhooks/{id} | Delete a webhook subscription. |
| GET | /v1/orders | List orders with line items, artwork, and shipment status. |
| POST | /v1/orders | Place a bulk order for cards or signage. |
| POST | /v1/teams | Create a team seat structure for org-wide rollouts. |
| POST | /v1/teams/{id}/invite | Invite a member to a team; sends email or SCIM push. |
| GET | /v1/contacts | List contacts captured on tap-through forms. |
| GET | /v1/products/catalog | List 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).
| Event | Description |
|---|---|
tap.recorded | Fires on every NFC tap or QR scan. |
contact.captured | Fires when a tap-through form captures a contact. |
card.provisioned | Fires when a card is created and its NFC UID assigned. |
card.reassigned | Fires when a card's target URL is changed. |
card.deactivated | Fires when a card is soft-deleted. |
order.placed | Fires when an order enters production. |
order.shipped | Fires when a shipment is handed to carrier with tracking. |
team.member.added | Fires when a member joins a team seat. |
team.member.removed | Fires when a member is removed from a team. |
analytics.digest | Fires 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
| Scope | Grants |
|---|---|
cards.read | List and retrieve cards, wearables, signage. |
cards.write | Provision, reassign, deactivate cards. |
taps.read | Read tap streams and contact-capture records. |
analytics.read | Read time-series analytics and rollups. |
orders.read | List and retrieve orders and shipments. |
orders.write | Place, cancel, and modify orders. |
teams.manage | Create teams, invite members, modify seat allocations. |
webhooks.manage | Create, list, delete webhook subscriptions. |
workspace.admin | Manage 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 —
idealcardgem (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