{ "variable": [ { "id": "baseUrl", "key": "baseUrl", "type": "string", "name": "string", "value": "http:\/\/bitaqa.test" } ], "info": { "name": "Bitaqa API", "_postman_id": "6c46019a-c7cb-4fac-9e73-8a5b449c28ea", "description": "REST API v1 for the Bitaqa NFC business-card platform: provision cards, sync HR employees, read analytics and manage touchpoints and webhooks.", "schema": "https:\/\/schema.getpostman.com\/json\/collection\/v2.1.0\/collection.json" }, "item": [ { "name": "Analytics", "description": "\nAggregated tap\/click analytics. All endpoints accept an optional\n`from`\/`to` date range (defaults to the last 30 days, maximum span\n366 days) and require the `analytics:read` token ability.", "item": [ { "name": "Card analytics", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/cards\/:slug\/analytics", "query": [ { "key": "from", "value": "2026-06-01", "description": "Start date (Y-m-d). Defaults to 30 days before `to`.", "disabled": false }, { "key": "to", "value": "2026-06-30", "description": "End date (Y-m-d). Defaults to today.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/cards\/:slug\/analytics?from=2026-06-01&to=2026-06-30", "variable": [ { "id": "slug", "key": "slug", "value": "k7m2p9qr", "description": "The card slug." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Summary, per-day timeseries and top link channels for one card." }, "response": [ { "header": [], "code": 200, "body": "{\"from\": \"2026-06-01\", \"to\": \"2026-06-30\", \"summary\": {\"views\": 58, \"unique_visitors\": 41, \"link_clicks\": 23, \"vcard_downloads\": 6, \"shares\": 2, \"qr_scans\": 4, \"journey_submits\": 0}, \"timeseries\": [{\"date\": \"2026-06-01\", \"views\": 3, \"link_clicks\": 1, \"vcard_downloads\": 0}], \"channels\": [{\"channel\": \"whatsapp\", \"count\": 12}]}", "name": "" } ] }, { "name": "Organization summary", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/analytics\/summary", "query": [ { "key": "from", "value": "2026-06-01", "description": "Start date (Y-m-d). Defaults to 30 days before `to`.", "disabled": false }, { "key": "to", "value": "2026-06-30", "description": "End date (Y-m-d). Defaults to today.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/analytics\/summary?from=2026-06-01&to=2026-06-30" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Org-wide totals, top link channels and a per-branch breakdown." }, "response": [ { "header": [], "code": 200, "body": "{\"from\": \"2026-06-01\", \"to\": \"2026-06-30\", \"summary\": {\"views\": 412, \"unique_visitors\": 267, \"link_clicks\": 158, \"vcard_downloads\": 41, \"shares\": 12, \"qr_scans\": 33, \"journey_submits\": 9}, \"channels\": [{\"channel\": \"whatsapp\", \"count\": 74}], \"by_branch\": [{\"branch_id\": 1, \"name_en\": \"Ruwi\", \"name_ar\": \"\u0631\u0648\u064a\", \"views\": 210, \"link_clicks\": 80, \"vcard_downloads\": 22}]}", "name": "" } ] } ] }, { "name": "Branches", "description": "", "item": [ { "name": "List branches", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/branches", "query": [ { "key": "search", "value": "ruwi", "description": "Match against name or code.", "disabled": false }, { "key": "per_page", "value": "15", "description": "Results per page (max 100).", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/branches?search=ruwi&per_page=15" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"search\":\"b\"}" }, "description": "Branch directory with coordinates, opening hours and services.\nRequires the `cards:read` token ability." }, "response": [] } ] }, { "name": "Cards", "description": "\nProvision and manage the organization's digital business cards. Card\nendpoints are tenant-scoped: slugs belonging to another organization\nalways return 404.", "item": [ { "name": "List cards", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/cards", "query": [ { "key": "status", "value": "active", "description": "Filter by status: draft, pending, active, inactive or rejected.", "disabled": false }, { "key": "branch_id", "value": "1", "description": "Filter by branch.", "disabled": false }, { "key": "department_id", "value": "1", "description": "Filter by department.", "disabled": false }, { "key": "search", "value": "sara", "description": "Match against display name, email or slug.", "disabled": false }, { "key": "per_page", "value": "15", "description": "Results per page (max 100).", "disabled": false }, { "key": "page", "value": "1", "description": "Page number.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/cards?status=active&branch_id=1&department_id=1&search=sara&per_page=15&page=1" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"status\":\"architecto\",\"branch_id\":16,\"department_id\":16,\"search\":\"n\"}" }, "description": "Requires the `cards:read` token ability." }, "response": [] }, { "name": "Provision a card", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/cards", "query": [], "raw": "{{baseUrl}}\/api\/v1\/cards" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"email\":\"sara@alameen.test\",\"display_name_en\":\"Sara Al Busaidi\",\"display_name_ar\":\"\u0633\u0627\u0631\u0629 \u0627\u0644\u0628\u0648\u0633\u0639\u064a\u062f\u064a\u0629\",\"title_en\":\"Relationship Manager\",\"title_ar\":\"\u0645\u062f\u064a\u0631 \u0639\u0644\u0627\u0642\u0627\u062a \u0627\u0644\u0639\u0645\u0644\u0627\u0621\",\"phone\":\"+96891234567\",\"whatsapp\":\"+96891234567\",\"website\":\"https:\\\/\\\/alameen.test\",\"branch_id\":1,\"department_id\":1,\"template_key\":\"classic\",\"status\":\"pending\",\"links\":[{\"type\":\"custom\",\"label_en\":\"b\",\"label_ar\":\"n\",\"value\":\"g\"}]}" }, "description": "Creates a card for the given employee email \u2014 reusing the matching\norganization user, or provisioning a new user (random password,\nlocal source) when none exists. Requires the `cards:write` ability." }, "response": [ { "header": [], "code": 201, "body": "{\"data\": {\"slug\": \"k7m2p9qr\", \"status\": \"pending\", \"display_name_en\": \"Sara Al Busaidi\", \"links\": [], \"public_url\": \"http:\/\/bitaqa.test\/alameen\/k7m2p9qr\"}}", "name": "" } ] }, { "name": "Get a card", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/cards\/:slug", "query": [], "raw": "{{baseUrl}}\/api\/v1\/cards\/:slug", "variable": [ { "id": "slug", "key": "slug", "value": "k7m2p9qr", "description": "The card slug." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Requires the `cards:read` token ability." }, "response": [] }, { "name": "Update a card", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/cards\/:slug", "query": [], "raw": "{{baseUrl}}\/api\/v1\/cards\/:slug", "variable": [ { "id": "slug", "key": "slug", "value": "k7m2p9qr", "description": "The card slug." } ] }, "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"display_name_en\":\"Sara Al Busaidi\",\"display_name_ar\":\"b\",\"title_en\":\"n\",\"title_ar\":\"g\",\"bio_en\":\"z\",\"bio_ar\":\"m\",\"email\":\"gulgowski.asia@example.com\",\"phone\":\"j\",\"whatsapp\":\"n\",\"website\":\"i\",\"branch_id\":16,\"department_id\":16,\"template_key\":\"modern\",\"links\":[{\"type\":\"linkedin\",\"label_en\":\"n\",\"label_ar\":\"g\",\"value\":\"z\"}]}" }, "description": "Partial update. When `links` is present the existing links are\nreplaced with the given set. Requires the `cards:write` ability." }, "response": [] }, { "name": "Deactivate a card", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/cards\/:slug\/deactivate", "query": [], "raw": "{{baseUrl}}\/api\/v1\/cards\/:slug\/deactivate", "variable": [ { "id": "slug", "key": "slug", "value": "k7m2p9qr", "description": "The card slug." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Instant status flip (no approval step) \u2014 the public page stops\nserving on the very next tap. Requires the `cards:write` ability." }, "response": [] }, { "name": "Activate a card", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/cards\/:slug\/activate", "query": [], "raw": "{{baseUrl}}\/api\/v1\/cards\/:slug\/activate", "variable": [ { "id": "slug", "key": "slug", "value": "k7m2p9qr", "description": "The card slug." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Instant status flip to active. Requires the `cards:write` ability." }, "response": [] } ] }, { "name": "Employees", "description": "\nPush HR directory changes into Bitaqa.", "item": [ { "name": "Sync employees", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/employees\/sync", "query": [], "raw": "{{baseUrl}}\/api\/v1\/employees\/sync" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "[]" }, "description": "Batch upsert (max 500 rows) matched by `employee_ref`, falling back\nto `email`. New employees are created with an auto-provisioned\nPENDING card. Rows with `active: false` deactivate the user and flip\ntheir cards to inactive immediately; re-activated users keep their\ncards inactive until re-approved. Requires the `employees:write`\ntoken ability." }, "response": [ { "header": [], "code": 200, "body": "{\"created\": 2, \"updated\": 1, \"deactivated\": 1, \"reactivated\": 0, \"failures\": [{\"index\": 4, \"errors\": {\"email\": [\"The email field is required.\"]}}], \"note\": \"Re-activated employees keep their cards inactive until re-approved.\"}", "name": "" } ] } ] }, { "name": "Touchpoints", "description": "\nPhysical NFC\/QR touchpoints (branch counters, marketing material)\nthat open a journey when tapped.", "item": [ { "name": "List touchpoints", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/touchpoints", "query": [ { "key": "type", "value": "branch_counter", "description": "Filter by type: staff_card, branch_counter or marketing_material.", "disabled": false }, { "key": "journey", "value": "feedback", "description": "Filter by journey: card, inquiry, service_request, feedback, booking or locator.", "disabled": false }, { "key": "branch_id", "value": "1", "description": "Filter by branch.", "disabled": false }, { "key": "search", "value": "lobby", "description": "Match against the internal name.", "disabled": false }, { "key": "per_page", "value": "15", "description": "Results per page (max 100).", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/touchpoints?type=branch_counter&journey=feedback&branch_id=1&search=lobby&per_page=15" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"type\":\"architecto\",\"journey\":\"architecto\",\"branch_id\":16,\"search\":\"n\"}" }, "description": "Requires the `touchpoints:read` token ability." }, "response": [] }, { "name": "Create a touchpoint", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/touchpoints", "query": [], "raw": "{{baseUrl}}\/api\/v1\/touchpoints" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"type\":\"branch_counter\",\"journey\":\"feedback\",\"name\":\"Qurum branch counter\",\"branch_id\":1,\"is_active\":true}" }, "description": "The public slug is generated server-side. Requires the\n`touchpoints:write` token ability." }, "response": [ { "header": [], "code": 201, "body": "{\"data\": {\"slug\": \"w3n8k2mq\", \"type\": \"branch_counter\", \"journey\": \"feedback\", \"name\": \"Qurum branch counter\", \"branch_id\": 1, \"is_active\": true, \"public_url\": \"http:\/\/bitaqa.test\/alameen\/w3n8k2mq\"}}", "name": "" } ] }, { "name": "Update a touchpoint", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/touchpoints\/:slug", "query": [], "raw": "{{baseUrl}}\/api\/v1\/touchpoints\/:slug", "variable": [ { "id": "slug", "key": "slug", "value": "w3n8k2mq", "description": "The touchpoint slug." } ] }, "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"type\":\"branch_counter\",\"journey\":\"feedback\",\"name\":\"Lobby stand \u2014 renamed\",\"branch_id\":16,\"is_active\":false}" }, "description": "Requires the `touchpoints:write` token ability." }, "response": [] }, { "name": "Delete a touchpoint", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/touchpoints\/:slug", "query": [], "raw": "{{baseUrl}}\/api\/v1\/touchpoints\/:slug", "variable": [ { "id": "slug", "key": "slug", "value": "w3n8k2mq", "description": "The touchpoint slug." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Requires the `touchpoints:write` token ability." }, "response": [ { "header": [], "code": 204, "body": "{}", "name": "" } ] } ] }, { "name": "Webhooks", "description": "\nWebhook endpoints receiving signed event deliveries\n(`X-Bitaqa-Signature: t=,v1=hmac_sha256(secret, ts.'.'.body)`).\nAll endpoints require the `webhooks:manage` token ability.", "item": [ { "name": "List webhook endpoints", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/webhooks", "query": [], "raw": "{{baseUrl}}\/api\/v1\/webhooks" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Secrets are masked \u2014 they are only revealed once, on creation." }, "response": [] }, { "name": "Create a webhook endpoint", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/webhooks", "query": [], "raw": "{{baseUrl}}\/api\/v1\/webhooks" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"url\":\"https:\\\/\\\/example.com\\\/hooks\\\/bitaqa\",\"events\":[\"appointment.created\"],\"secret\":\"b\"}" }, "description": "The signing secret (provided or generated) is returned ONCE in this\nresponse as `secret` \u2014 store it now; it is stored encrypted and\nnever shown again." }, "response": [ { "header": [], "code": 201, "body": "{\"data\": {\"id\": 7, \"url\": \"https:\/\/example.com\/hooks\/bitaqa\", \"events\": [\"card.created\"], \"secret\": \"********a1b2\", \"is_active\": true}, \"secret\": \"whsec_9fK2...\"}", "name": "" } ] }, { "name": "Delete a webhook endpoint", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/webhooks\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/webhooks\/:id", "variable": [ { "id": "id", "key": "id", "value": 7, "description": "The webhook endpoint id." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [ { "header": [], "code": 204, "body": "{}", "name": "" } ] } ] } ], "auth": { "type": "bearer", "bearer": [ { "key": "Authorization", "type": "string" } ] } }