🧩 Developer Platform

API Developer Guide

A connected quickstart from authentication to booking creation, error handling, and webhook automation.

⚡ Avg API Latency

~180ms

✅ Platform Uptime

99.95%

🧠 Rate Limit

120 req/min/key

Quickstart

Use server-side bearer authentication, then call availability and booking endpoints in sequence.

HTTPS Only JSON Requests Timezone Aware Webhook Driven 
Authorization: Bearer pmc_live_xxxxxxxxxxxx
Content-Type: application/json
X-Request-Id: req_client_001

Request → Response Visualization

A visual contract for what your backend sends and what PinmyCal API returns.

📤 Request

Authenticated payload sent by your backend service.

POST /v1/bookings
Authorization: Bearer pmc_live_xxxxx
Content-Type: application/json

{
    "eventTypeId": "evt_demo",
    "invitee": {
        "name": "Jordan Lee",
        "email": "jordan@company.com"
    },
    "start": "2026-03-10T09:30:00Z",
    "timezone": "Asia/Kolkata"
}

⚙️ Processing

PinmyCal validates, checks slot state, and provisions calendar/conferencing details.

📥 Response

Consistent JSON object with status, identifiers, and traceability.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "ok",
    "bookingId": "bk_1027",
    "meetingUrl": "https://meet.google.com/abc-defg-hij",
    "requestId": "req_9Gf21"
}

Connected API Flow

Follow this end-to-end sequence to power a production booking journey.

1

🔑Validate token & workspace

Auth
GET /v1/users/me
Host: api.pinmycal.com
Authorization: Bearer pmc_live_xxxxxxxxxxxx
2

📅Check availability

GET

Request

GET /v1/availability?eventTypeId=evt_demo&date=2026-03-10&timezone=Asia/Kolkata

Response

{
  "status": "ok",
  "slots": ["2026-03-10T09:30:00Z", "2026-03-10T11:00:00Z"]
}
Mar 10, 2026 • Asia/Kolkata
09:30 AM 11:00 AM 12:30 PM Booked 02:00 PM

Tip: If no slots are available, show the next available day and offer waitlist/retry options.

3

🧾Create booking

POST

Request

POST /v1/bookings
{
  "eventTypeId": "evt_demo",
  "invitee": {
    "name": "Jordan Lee",
    "email": "jordan@company.com"
  },
  "start": "2026-03-10T09:30:00Z",
  "timezone": "Asia/Kolkata"
}

Response

{
  "status": "ok",
  "bookingId": "bk_1027",
  "meetingUrl": "https://meet.google.com/abc-defg-hij",
  "requestId": "req_9Gf21"
}
4

📡Listen for webhook events

Webhook
booking.created
booking.rescheduled
booking.cancelled
Header: X-PMC-Signature: sha256=...
Retry policy: exponential backoff up to 24h

Response + Error Handling

Visualize response states and handle failures with clear recovery rules in client and backend services.

200 Success

Resource created or fetched successfully; continue normal booking flow.

{
  "status": "ok",
  "bookingId": "bk_1027",
  "requestId": "req_9Gf21"
}

202 Accepted

Request queued for asynchronous processing; poll status or wait for webhook callback.

{
  "status": "accepted",
  "jobId": "job_4421",
  "eta": "15s"
}

4xx / 5xx Failure

Return user-safe error copy, log request ID, and choose retry strategy by error type.

{
  "status": "error",
  "code": "INVALID_TOKEN",
  "message": "Bearer token expired",
  "requestId": "req_9Gf21"
}

401 INVALID_TOKEN

Rotate token, refresh credentials, and retry once with a new bearer token.

403 PERMISSION_DENIED

Verify workspace scope and required role permissions before reattempting.

422 VALIDATION_FAILED

Map field-level validation errors to UI and re-submit with corrected payload.

429 RATE_LIMITED

Use exponential backoff with jitter and honor Retry-After header values.

5xx SERVER_ERROR

Retry idempotent calls with capped attempts and circuit-breaker protection.

Observability

Store requestId, status code, latency, and endpoint to speed incident triage.

Webhook Security Checklist

Apply these controls in production to secure event delivery and prevent duplicate processing.

Signature Verification

Validate X-PMC-Signature against raw payload body using your webhook secret.

Replay Protection

Reject stale signatures by validating timestamp windows (recommended ≤ 5 minutes).

Idempotency Guard

Persist eventId and skip duplicate deliveries to avoid repeated writes.

Transport Security

Allow HTTPS only, enforce TLS 1.2+, and deny plain HTTP callback endpoints.

Least Privilege

Scope API keys per environment and rotate secrets every 60-90 days.

Audit & Alerts

Log requestId, source IP, and failure reason; alert on repeated signature failures.

  • Return HTTP 2xx quickly, then process asynchronously in worker queues.
  • Retry failed deliveries with backoff; keep dead-letter queue for manual replay.
  • Mask PII in logs and dashboards while preserving operational identifiers.