Enterprise plan

API reference

Manage your digital business cards programmatically, pull scan analytics into your own systems, and receive real-time webhook notifications for card, scan, and lead events.

This API manages personal cards. ShepCard Business customer cards are managed in the Business workspace and are excluded from personal API tokens. See the Business guide for customer workflows.

https://shepcard.com/api/v11,000 requests / hour per tokenGet started

Quickstart

1. Upgrade to Enterprise
The API is an Enterprise feature. Upgrade from Dashboard → Billing.
2. Create an API token
Go to Settings → Developer and create a token with the scopes you need. Copy it immediately - it is shown only once.
3. Make your first request
Call any endpoint with the token in the Authorization header. Try it in the playground below.

bash

curl https://shepcard.com/api/v1/cards \
  -H "Authorization: Bearer scp_YOUR_TOKEN_HERE"

Authentication

All endpoints require a Bearer token in the Authorization header. Tokens start with scp_ followed by 48 hex characters and can carry any combination of three scopes:

Scope	Grants
read	List, get, and view cards
write	Create, update, and delete cards; register webhooks
analytics	Fetch scan analytics

Tokens are stored hashed

ShepCard stores only a SHA-256 hash of your token. The plaintext is shown exactly once at creation and can never be recovered - delete and recreate if you lose it.

Revocation is instant

Deleting a token in Settings stops it working immediately. Plan downgrades are also enforced per request, so a lapsed Enterprise subscription disables tokens right away.

Endpoints

GET/cardsread

Returns all of your cards, newest first. Pass ?archived=true to include archived cards (excluded by default).

bash

curl "https://shepcard.com/api/v1/cards" \
  -H "Authorization: Bearer scp_YOUR_TOKEN_HERE"

json - 200 OK

{
  "cards": [
    {
      "id": "cmsf2y1k20001abcde1234567",
      "name": "Demo Card",
      "slug": "demo",
      "published": true,
      "archived": false,
      "theme": { "palette": "ocean", "colors": { "primary": "#0ea5e9" } },
      "background": null,
      "sections": [],
      "seoTitle": null,
      "seoDescription": null,
      "viewCount": 128,
      "teamId": null,
      "createdAt": "2026-07-20T09:14:22.000Z",
      "updatedAt": "2026-08-02T16:40:05.000Z"
    }
  ]
}

POST/cardswrite

Creates a card and fires the card.created webhook. Your plan's card limit applies here too - exceeding it returns 403.

Field	Type	Required
name	string	yes
slug	string (custom URL; defaults to a slug from name)	no
published	boolean	no
theme	object (palette + colors)	no
background	string \| null (image URL)	no
sections	array (ordered card sections)	no

bash

curl -X POST https://shepcard.com/api/v1/cards \
  -H "Authorization: Bearer scp_YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada Lovelace - Card",
    "published": true,
    "theme": { "palette": "ocean" },
    "sections": [
      { "id": "sec_1", "type": "profile", "data": { "name": "Ada Lovelace", "title": "Mathematician" } },
      { "id": "sec_2", "type": "contact", "data": { "email": "[email protected]", "phone": "+233 20 000 0000" } }
    ]
  }'

json - 201 Created

{
  "card": {
    "id": "cmsf3aaaa0001abcd12345678",
    "name": "Ada Lovelace - Card",
    "slug": "ada-lovelace-card",
    "published": true,
    "archived": false,
    "theme": { "palette": "ocean" },
    "background": null,
    "sections": [
      { "id": "sec_1", "type": "profile", "data": { "name": "Ada Lovelace", "title": "Mathematician" } },
      { "id": "sec_2", "type": "contact", "data": { "email": "[email protected]", "phone": "+233 20 000 0000" } }
    ],
    "seoTitle": null,
    "seoDescription": null,
    "viewCount": 0,
    "teamId": null,
    "createdAt": "2026-08-04T10:00:00.000Z",
    "updatedAt": "2026-08-04T10:00:00.000Z"
  }
}

GET/cards/{cardId}read

Returns one card. A card that does not exist - or belongs to another account - returns 404, never 403.

bash

curl https://shepcard.com/api/v1/cards/cmsf3aaaa0001abcd12345678 \
  -H "Authorization: Bearer scp_YOUR_TOKEN_HERE"

PUT/cards/{cardId}write

Partial update - send only the fields you want to change. All create fields are accepted, plus seoTitle and seoDescription. Changing slug to one already in use returns 409. Fires card.updated.

bash

curl -X PUT https://shepcard.com/api/v1/cards/cmsf3aaaa0001abcd12345678 \
  -H "Authorization: Bearer scp_YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada Lovelace - Consulting",
    "seoDescription": "Mathematician and writer, available for consulting."
  }'

DELETE/cards/{cardId}write

Permanently deletes a card (the dashboard shares the same delete - nothing is restorable). Fires card.deleted with {id, name, slug}.

bash

curl -X DELETE https://shepcard.com/api/v1/cards/cmsf3aaaa0001abcd12345678 \
  -H "Authorization: Bearer scp_YOUR_TOKEN_HERE"

json - 200 OK

{ "success": true }

GET/cards/{cardId}/scans?days=30analytics

Scan analytics for one card. days (1–365, default 30) controls the range of the daily series and breakdowns; totalScans and recentScans cover all history.

bash

curl "https://shepcard.com/api/v1/cards/cmsf3aaaa0001abcd12345678/scans?days=30" \
  -H "Authorization: Bearer scp_YOUR_TOKEN_HERE"

json - 200 OK

{
  "card": { "id": "cmsf3aaaa0001abcd12345678", "name": "Ada Lovelace - Card", "slug": "ada-lovelace-card" },
  "totalScans": 42,
  "scansThisMonth": 9,
  "uniqueVisitors": 3,
  "byDay": [
    { "date": "2026-07-06", "scans": 0 },
    { "date": "2026-07-07", "scans": 2 },
    { "date": "2026-07-08", "scans": 1 }
  ],
  "byDevice": [
    { "device": "Mobile", "count": 34 },
    { "device": "Desktop", "count": 8 }
  ],
  "byCountry": [
    { "country": "GH", "count": 30 },
    { "country": "US", "count": 12 }
  ],
  "recentScans": [
    {
      "id": "cmsf4bbbb0002efgh23456789",
      "country": "GH",
      "device": "Mobile",
      "browser": "Chrome",
      "referrer": null,
      "createdAt": "2026-08-04T08:12:01.000Z"
    }
  ]
}

POST/webhookswrite

Registers a webhook endpoint. The URL must be https:// - plain HTTP is rejected with 400. The signing secret is included only in this response.

Field	Type	Required
url	string (https:// only)	yes
events	array: card.created, card.updated, card.deleted, scan.recorded, lead.created	yes

bash

curl -X POST https://shepcard.com/api/v1/webhooks \
  -H "Authorization: Bearer scp_YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/shepcard",
    "events": ["card.created", "card.updated", "scan.recorded"]
  }'

json - 201 Created

{
  "webhook": {
    "id": "cmsf5cccc0003ijkl34567890",
    "url": "https://example.com/hooks/shepcard",
    "events": ["card.created", "card.updated", "scan.recorded"],
    "secret": "920a80fc3b31980514133a3cdbfe9a403706dc3ef3cd04f70607d10eef762738",
    "active": true,
    "createdAt": "2026-08-04T10:05:00.000Z",
    "updatedAt": "2026-08-04T10:05:00.000Z"
  }
}

Try it live

API playground

Pick an endpoint, paste your token, and send a live request from your browser. Your token is used in memory only - it is never stored or logged.

GET/api/v1/cardsscope: read

List your cards. Add ?archived=true to include archived cards.

API token (from Settings → Developer)

Tip: create a token in Settings → Developer first. Requests go to /api/v1 on this origin - use the Postman collection or curl for cross-origin workflows.

Webhooks

Webhooks push events to your endpoint the moment they happen. Each delivery is an HTTP POST with a JSON body and three custom headers:

delivery headers

Content-Type: application/json
x-shepcard-event: scan.recorded
x-shepcard-delivery: 3f9c2c1e-aaaa-bbbb-cccc-3f9c2c1e0000
x-shepcard-signature: <hex HMAC-SHA256 of the raw body>

json - request body

{
  "event": "scan.recorded",
  "data": {
    "id": "cmsf4bbbb0002efgh23456789",
    "cardId": "cmsf3aaaa0001abcd12345678",
    "cardSlug": "ada-lovelace-card",
    "createdAt": "2026-08-04T08:12:01.000Z",
    "ip": "154.160.6.10",
    "country": "GH",
    "device": "Mobile",
    "browser": "Chrome",
    "referrer": null
  },
  "deliveryId": "3f9c2c1e-aaaa-bbbb-cccc-3f9c2c1e0000",
  "deliveredAt": "2026-08-04T08:12:01.437Z"
}

Event	Fired when	Payload data
card.created	A card is created (API or dashboard)	Full card object
card.updated	A card is updated (API or dashboard)	Full card object
card.deleted	A card is deleted	{id, name, slug}
scan.recorded	Someone scans your card	Scan details (id, cardId, device, country, …)
lead.created	A lead form is submitted on your card	Lead details (id, cardId, name, email, message)

Verify every signature

Compute HMAC-SHA256 of the raw request body with your webhook's secret and compare it to x-shepcard-signature. Never trust an unverified delivery.

node.js

const crypto = require('crypto')

// rawBody: the exact body string - do not re-stringify the parsed JSON
function verifySignature(rawBody, signature, secret) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
  if (expected.length !== signature.length) return false
  const a = Buffer.from(expected, 'hex')
  const b = Buffer.from(signature, 'hex')
  return crypto.timingSafeEqual(a, b)
}

Retry policy

• 2xx/3xx - delivery complete
• 4xx - no retry (fix the payload)
• Network error, timeout, or 5xx - up to 3 attempts at ~1s and ~5s
• Each attempt has a 10-second timeout

Best practices

• Respond 2xx fast; do heavy work asynchronously
• Deduplicate with deliveryId - retries can repeat an event
• Return 4xx for malformed payloads, never 5xx
• Test locally with webhook.site or ngrok (https required)

Rate limits

Each token is limited to 1,000 requests per hour (rolling window). Exceeding the limit returns 429 with a Retry-After header telling you how many seconds to wait.

bash

curl -i https://shepcard.com/api/v1/cards \
  -H "Authorization: Bearer scp_YOUR_TOKEN_HERE"

HTTP/1.1 429 Too Many Requests
retry-after: 3590
{ "error": "Rate limit exceeded" }

Each token has its own window - create additional tokens per integration if you need more sustained volume.

Errors

Errors always return JSON with an error message.

json - 409 Conflict

{ "error": "This URL is already taken" }

Status	Meaning
400	Invalid request - missing or malformed field
401	Missing or invalid Authorization header / token
403	Plan does not include the API, token lacks the scope, or card limit reached
404	Card or webhook not found (non-owned cards return 404 too)
409	Slug collision - a card with that URL already exists
429	Rate limit exceeded - see Retry-After
500	Internal server error - retry; contact support if it persists

Postman

The fastest way to explore the API interactively outside the browser - a ready-made collection covers every endpoint.

Download the collection - shepcard-api.postman_collection.json

Import it in Postman - File → Import (or drag the file in). You get a ShepCard API collection with requests organized under Cards / Analytics / Webhooks.

Set one variable - baseUrl already points at https://shepcard.com/api/v1 and every request carries Authorization: Bearer {{token}}, so the only thing to fill in is token = your scp_… token. Point baseUrl at your dev server instead if you are testing locally.

A typical flow

Cards → Create a card - the response's cardId is saved to a variable automatically.
Cards → List cards - your new card appears.
Cards → Update a card - change the name and watch it reflect in List cards.
Webhooks → Register a webhook - paste a https://webhook.site URL, then create a card and watch the delivery arrive with its signature headers.
Cards → Delete a card - cleanup when done.

API reference

Quickstart

1. Upgrade to Enterprise

2. Create an API token

3. Make your first request

Authentication

Tokens are stored hashed

Revocation is instant

Endpoints

Try it live

API playground

Webhooks

Verify every signature

Retry policy

Best practices

Rate limits

Errors

Postman

A typical flow