API Documentation

Build powerful integrations with the PIN Clinical Intelligence Platform

Authentication Endpoints Examples

🔐 Authentication

PIN API uses OAuth 2.0 for authentication. All API requests must include a valid access token in the Authorization header.

Getting Started

  1. Register your application in the PIN Developer Portal
  2. Obtain your client ID and client secret
  3. Request an access token using the OAuth 2.0 flow
  4. Include the token in your API requests
// Example authentication request
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET
// Using the access token
const response = await fetch('https://api.pin.ai/v1/patients', {
  headers: {
    'Authorization': 'Bearer ACCESS_TOKEN'
  }
});

⚡ Rate Limits

API requests are rate-limited to ensure fair usage and system stability:

  • Standard Tier: 1,000 requests per hour
  • Professional Tier: 10,000 requests per hour
  • Enterprise Tier: 100,000 requests per hour

Rate limit headers are included in all API responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

👥 Patients

GET /v1/patients

Retrieve a list of patients with optional filtering and pagination.

Parameter Type Required Description
page integer Optional Page number (default: 1)
limit integer Optional Results per page (default: 50, max: 100)
search string Optional Search term for patient name or ID
// Example request
GET /v1/patients?page=1&limit=10&search=John

// Example response
{
  "data": [
    {
      "id": "patient_123",
      "name": "John Doe",
      "date_of_birth": "1980-01-15",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 150
  }
}
GET /v1/patients/{id}

Retrieve detailed information for a specific patient.

// Example request
GET /v1/patients/patient_123

// Example response
{
  "id": "patient_123",
  "name": "John Doe",
  "date_of_birth": "1980-01-15",
  "gender": "male",
  "contact": {
    "email": "john.doe@example.com",
    "phone": "+1-555-0123"
  },
  "medical_history": [...],
  "created_at": "2024-01-01T00:00:00Z"
}
POST /v1/patients

Create a new patient record.

// Example request
POST /v1/patients
Content-Type: application/json

{
  "name": "Jane Smith",
  "date_of_birth": "1985-05-20",
  "gender": "female",
  "contact": {
    "email": "jane.smith@example.com"
  }
}

📊 Clinical Data

GET /v1/patients/{id}/clinical-data

Retrieve clinical data for a specific patient.

Parameter Type Required Description
start_date string Optional Start date for data range (YYYY-MM-DD)
end_date string Optional End date for data range (YYYY-MM-DD)
data_type string Optional Filter by data type (pain_scores, medications, etc.)
POST /v1/patients/{id}/clinical-data

Add new clinical data for a patient.

📈 Analytics

GET /v1/analytics/outcomes

Retrieve analytics data for patient outcomes and trends.

GET /v1/analytics/population-health

Get population health analytics and insights.

📋 Reports

GET /v1/reports

List available reports and their status.

POST /v1/reports

Generate a new report.

GET /v1/reports/{id}/download

Download a generated report.

🔗 Webhooks

PIN supports webhooks for real-time notifications of events such as new patient data, report completion, and system alerts.

POST /v1/webhooks

Register a new webhook endpoint.

{
  "url": "https://your-app.com/webhook",
  "events": [
    "patient.created",
    "clinical_data.updated",
    "report.completed"
  ]
}

❌ Error Handling

PIN API returns standard HTTP status codes and includes detailed error information in the response body.

Status Code Meaning Description
200 OK Request successful
201 Created Resource created successfully
400 Bad Request Invalid request parameters
401 Unauthorized Invalid or missing authentication
403 Forbidden Insufficient permissions
404 Not Found Resource not found
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server error occurred
// Example error response
{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Invalid date format. Use YYYY-MM-DD.",
    "details": {
      "parameter": "start_date",
      "value": "01/01/2024"
    }
  }
}