POST /patients

Endpoint

POST https://api.mycura.org/api/cura/patients

Request Body

string

Patient’s full name

string

Patient’s phone number in ANY format. Supports:

+15551234567 (E.164 format)
15551234567 (11-digit)
5551234567 (10-digit)
(555) 123-4567 (formatted)
Any other format - will be automatically normalized to 11-digit format

array

Array of medical conditions as strings (e.g., ["Hypertension", "Diabetes"])

array

Array of current medications

Show Medication Object Structure

string

Medication name

string

Dosage information (e.g., “10mg”)

string

How often taken (e.g., “daily”, “twice daily”)

string

Known allergies (comma-separated or as a single string)

array

Array of note objects for additional patient information

boolean

Whether medication reminders are enabled for this patient (default: false)

object

Prescription refill information

string

How the patient joined the system (e.g., “WEB”, “WHATSAPP”, “API”)

Response

boolean

Indicates if the patient was created successfully

object

The created patient object with generated ID and timestamps

Show Patient Object Fields

string

Generated unique patient identifier (UUID)

string

Patient’s full name

string

Normalized phone number (11-digit format)

array

Array of medical conditions

array

Array of current medications

string

Known allergies

array

Additional notes

boolean

Whether reminders are enabled

object

Prescription refill information

string

How patient joined

string

Timestamp when patient was created

string

Timestamp when patient was last updated

string

Error message if the request failed (only present when success is false)

Examples

Basic Patient Creation

curl -X POST "https://api.mycura.org/api/cura/patients" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "name": "Jane Doe",
    "phone_number": "5551234567",
    "reminders_enabled": true
  }'

const response = await fetch('https://api.mycura.org/api/cura/patients', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    name: 'Jane Doe',
    phone_number: '5551234567',
    reminders_enabled: true
  })
});

const data = await response.json();
console.log(data.patient);

import requests

response = requests.post(
    'https://api.mycura.org/api/cura/patients',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': 'YOUR_API_KEY'
    },
    json={
        'name': 'Jane Doe',
        'phone_number': '5551234567',
        'reminders_enabled': True
    }
)

data = response.json()
print(data['patient'])

Comprehensive Patient Creation

curl -X POST "https://api.mycura.org/api/cura/patients" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "name": "Jane Doe",
    "phone_number": "(555) 123-4567",
    "conditions": ["Hypertension", "Type 2 Diabetes"],
    "allergies": "Penicillin",
    "medications": [
      {
        "name": "Lisinopril",
        "dosage": "10mg",
        "frequency": "daily"
      },
      {
        "name": "Metformin",
        "dosage": "500mg",
        "frequency": "twice daily"
      }
    ],
    "reminders_enabled": true
  }'

const patientData = {
  name: 'Jane Doe',
  phone_number: '(555) 123-4567',
  conditions: ['Hypertension', 'Type 2 Diabetes'],
  allergies: 'Penicillin',
  medications: [
    {
      name: 'Lisinopril',
      dosage: '10mg',
      frequency: 'daily'
    },
    {
      name: 'Metformin',
      dosage: '500mg',
      frequency: 'twice daily'
    }
  ],
  reminders_enabled: true
};

const response = await fetch('https://api.mycura.org/api/cura/patients', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify(patientData)
});

const data = await response.json();
console.log('Created patient:', data.patient);

Response Examples

Success Response

{
  "success": true,
  "patient": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Jane Doe",
    "phone_number": "15551234567",
    "conditions": [
      "Hypertension",
      "Type 2 Diabetes"
    ],
    "allergies": "Penicillin",
    "medications": [
      {
        "name": "Lisinopril",
        "dosage": "10mg",
        "frequency": "daily"
      },
      {
        "name": "Metformin",
        "dosage": "500mg",
        "frequency": "twice daily"
      }
    ],
    "notes": [],
    "reminders_enabled": true,
    "refill_info": null,
    "join_status": "API",
    "created_at": "2024-01-20T10:30:00Z",
    "updated_at": "2024-01-20T10:30:00Z"
  }
}

Duplicate Patient Error (409)

{
  "error": "Patient with this phone number already exists",
  "patient": {
    "id": "existing-patient-uuid",
    "name": "Jane Doe",
    "phone_number": "15551234567"
  }
}

Phone Number Handling

Phone Number Flexibility: The API accepts phone numbers in ANY format and automatically normalizes them.

All these formats are accepted and normalized to 15551234567:

+15551234567
15551234567
5551234567
(555) 123-4567
555-123-4567
555.123.4567

The system will:

Remove all non-digit characters
Add country code 1 if missing (for 10-digit numbers)
Store in normalized 11-digit format

Duplicate Prevention

The API automatically prevents duplicate patients based on phone number. If you attempt to create a patient with a phone number that already exists (in any format), the API will:

Return HTTP status code 409 Conflict
Include the existing patient data in the response
Not create a new record

This works even if phone numbers are in different formats:

Creating with 5551234567 after +15551234567 → Duplicate detected
Creating with (555) 123-4567 after 15551234567 → Duplicate detected

Use Cases

New Patient Registration

Create patient records during onboarding or registration:

async function registerNewPatient(formData) {
  try {
    const response = await fetch('https://api.mycura.org/api/cura/patients', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': apiKey
      },
      body: JSON.stringify({
        name: formData.fullName,
        phone_number: formData.phone,
        reminders_enabled: formData.wantsReminders
      })
    });
    
    const data = await response.json();
    
    if (response.status === 409) {
      // Patient already exists
      console.log('Patient already exists:', data.patient);
      return data.patient;
    }
    
    if (!data.success) {
      throw new Error(data.error);
    }
    
    // Store patient ID for future use
    localStorage.setItem('patientId', data.patient.id);
    return data.patient;
  } catch (error) {
    console.error('Registration failed:', error);
    throw error;
  }
}

Integration Workflow

Create patients as part of a larger integration workflow:

async function onboardPatient(patientInfo) {
  // 1. Create patient in Cura
  const response = await createPatient(patientInfo);
  const patient = response.patient;
  
  // 2. Immediately ask an onboarding question
  const welcomeResponse = await fetch('https://api.mycura.org/api/cura/chat', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': apiKey
    },
    body: JSON.stringify({
      message: 'What should I know about managing my health conditions?',
      patientId: patient.id
    })
  });
  
  const chatData = await welcomeResponse.json();
  
  // 3. Return both patient and initial guidance
  return {
    patient,
    initialGuidance: chatData.response
  };
}

Best Practices

Data Privacy

Only collect necessary patient information
Implement proper consent mechanisms
Follow healthcare data compliance requirements (HIPAA, etc.)
Use secure transmission (HTTPS)

Data Quality

Validate data on the client side before submission
Phone numbers can be in any format - the API will normalize them
Provide clear error messages for validation failures
Handle 409 duplicate responses gracefully

Integration

Store the returned patient ID for future API calls
Handle duplicate patient scenarios gracefully (409 status)
Implement retry logic for network failures
The API will mark patients created via API with join_status: "API"

Error Codes

Status Code	Error Message	Description
400	”Failed to create patient”	Required fields are missing or invalid
401	”Unauthorized - Invalid API key”	The provided API key is invalid
409	”Patient with this phone number already exists”	Patient with same phone (any format) exists
500	”Failed to create patient”	An unexpected error occurred

Overview

Conversation Threads

Chat & Messaging

Patient Management

Endpoint

Request Body

Response

Examples

Basic Patient Creation

Comprehensive Patient Creation

Response Examples

Success Response

Duplicate Patient Error (409)

Phone Number Handling

Duplicate Prevention

Use Cases

Best Practices

Error Codes

​Endpoint

​Request Body

​Response

​Examples

​Basic Patient Creation

​Comprehensive Patient Creation

​Response Examples

​Success Response

​Duplicate Patient Error (409)

​Phone Number Handling

​Duplicate Prevention

​Use Cases

​Best Practices

​Error Codes

Endpoint

Request Body

Response

Examples

Basic Patient Creation

Comprehensive Patient Creation

Response Examples

Success Response

Duplicate Patient Error (409)

Phone Number Handling

Duplicate Prevention

Use Cases

Best Practices

Error Codes