API Overview

The programmatic API allows external systems (e.g., hospital HIS/EMR, CRM, ticketing systems) to automate survey workflows: create contacts, send surveys, and track responses.

Base URL

All API endpoints are available at:

https://fikrr.diwakarmaurya.com/api

Authentication

All API requests require an API key passed via the x-api-key header:

curl -H "x-api-key: YOUR_API_KEY" \
  https://fikrr.diwakarmaurya.com/api/directory/contacts

Alternatively, use a Bearer token in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://fikrr.diwakarmaurya.com/api/directory/contacts

API keys are scoped to a user and inherit that user’s organization membership and permissions. All queries are automatically scoped to the API key owner’s organization — you cannot access data from other organizations.

Creating API Keys

API keys can be created from Settings > API Keys in the web UI.

Error Format

All errors return a consistent JSON structure:

{
  "code": "NOT_FOUND",
  "status": 404,
  "message": "Contact not found"
}

Code	Status	Description
`BAD_REQUEST`	400	Invalid input or missing required fields
`FORBIDDEN`	403	User lacks required permission or organization membership
`NOT_FOUND`	404	Resource not found
`CONFLICT`	409	Duplicate resource or state conflict
`INTERNAL_SERVER_ERROR`	500	Unexpected server error

Rate Limits

API requests are rate-limited per API key:

100 requests/minute per API key
1,000 requests/hour per API key

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1709654400

Content Type

All request and response bodies use JSON:

Content-Type: application/json

Typical Integration Flow

A typical external system integration follows this pattern:

Create contacts — Upsert contacts by externalId from your system
Send surveys — Quick distribute a survey to those contacts
Track responses — Check response status by externalId
React to completions — Configure webhooks for real-time notifications