Patients

The Patients API allows you to create, retrieve, update, and search patient records. Every patient record includes demographic information, contact details, and medical history references.

The Patient Object

All patient endpoints return or accept the following object structure:

Field	Type	Description
id	string	Unique patient identifier (pat_*)
first_name	string	Patient's first name
last_name	string	Patient's last name
email	string	Email address (unique)
phone	string	Phone number with country code
date_of_birth	string	ISO 8601 date (YYYY-MM-DD)
gender	enum	male, female, other
status	enum	active, inactive, archived
address	object	Street, city, state, postal_code, country
medical_history	array	References to medical record entries
created_at	string	ISO 8601 timestamp (UTC)
updated_at	string	ISO 8601 timestamp (UTC)

GET/patients

List all patients

Returns a paginated list of patients. Use cursor-based pagination to retrieve subsequent pages. Results are sorted by created_at in descending order.

Parameters

Parameter	Type	Required	Description
limit	integer	Optional	Number of results per page (1-100). Default: 20
cursor	string	Optional	Pagination cursor from a previous response
status	string	Optional	Filter by status: active, inactive, archived

Example Request

Requestbash

curl -X GET "https://api.odento.app/api/v1/patients?limit=10" \
  -H "X-API-Key-ID: ok_live_abc123def456ghi789jkl012" \
  -H "X-API-Key-Secret: os_abc123def456ghi789jkl012mno345pqr678stu901vwx234yzab567"

Example Response

Response200json

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "pat_5f8d3a2b1c9e4a7b",
        "first_name": "Priya",
        "last_name": "Sharma",
        "email": "priya.sharma@example.com",
        "phone": "+919876543210",
        "date_of_birth": "1990-05-15",
        "gender": "female",
        "status": "active",
        "created_at": "2025-01-15T10:30:00Z",
        "updated_at": "2025-01-20T14:15:00Z"
      },
      {
        "id": "pat_3a7b9c1d2e5f8a4b",
        "first_name": "Rahul",
        "last_name": "Verma",
        "email": "rahul.verma@example.com",
        "phone": "+919876543211",
        "date_of_birth": "1985-08-22",
        "gender": "male",
        "status": "active",
        "created_at": "2025-01-14T09:00:00Z",
        "updated_at": "2025-01-14T09:00:00Z"
      }
    ],
    "pagination": {
      "has_more": true,
      "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNS0wMS0xNFQwOTowMDowMFoifQ==",
      "per_page": 10
    }
  }
}

Try It Out

API Playground— try it out

https://api.odento.app

Headers

This is a simulated response — no real API calls are made from the browser.

POST/patients

Create a patient

Creates a new patient record. Email must be unique within the organization. Returns the created patient object.

Parameters

Parameter	Type	Required	Description
first_name	string	Required	Patient first name
last_name	string	Required	Patient last name
email	string	Required	Unique email address
phone	string	Required	Phone number with country code
date_of_birth	string	Optional	ISO 8601 date (YYYY-MM-DD)
gender	string	Optional	male, female, or other
address	object	Optional	Address object with street, city, state, postal_code, country

Example Request

Requestbash

curl -X POST https://api.odento.app/api/v1/patients \
  -H "X-API-Key-ID: ok_live_abc123def456ghi789jkl012" \
  -H "X-API-Key-Secret: os_abc123def456ghi789jkl012mno345pqr678stu901vwx234yzab567" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Priya",
    "last_name": "Sharma",
    "email": "priya.sharma@example.com",
    "phone": "+919876543210",
    "date_of_birth": "1990-05-15",
    "gender": "female",
    "address": {
      "street": "12 MG Road",
      "city": "Bengaluru",
      "state": "Karnataka",
      "postal_code": "560001",
      "country": "India"
    }
  }'

Example Response

Response201json

{
  "success": true,
  "data": {
    "id": "pat_5f8d3a2b1c9e4a7b",
    "first_name": "Priya",
    "last_name": "Sharma",
    "email": "priya.sharma@example.com",
    "phone": "+919876543210",
    "date_of_birth": "1990-05-15",
    "gender": "female",
    "status": "active",
    "address": {
      "street": "12 MG Road",
      "city": "Bengaluru",
      "state": "Karnataka",
      "postal_code": "560001",
      "country": "India"
    },
    "medical_history": [],
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

GET/patients/{id}

Retrieve a patient

Retrieves the full patient record by ID, including medical history references.

Parameters

Parameter	Type	Required	Description
id	string	Required	The patient ID (pat_*)

Example Request

Requestbash

curl -X GET https://api.odento.app/api/v1/patients/pat_5f8d3a2b1c9e4a7b \
  -H "X-API-Key-ID: ok_live_abc123def456ghi789jkl012" \
  -H "X-API-Key-Secret: os_abc123def456ghi789jkl012mno345pqr678stu901vwx234yzab567"

Example Response

Response200json

{
  "success": true,
  "data": {
    "id": "pat_5f8d3a2b1c9e4a7b",
    "first_name": "Priya",
    "last_name": "Sharma",
    "email": "priya.sharma@example.com",
    "phone": "+919876543210",
    "date_of_birth": "1990-05-15",
    "gender": "female",
    "status": "active",
    "address": {
      "street": "12 MG Road",
      "city": "Bengaluru",
      "state": "Karnataka",
      "postal_code": "560001",
      "country": "India"
    },
    "medical_history": [
      {
        "id": "med_rec_abc123",
        "type": "diagnosis",
        "title": "Dental caries - upper left molar",
        "recorded_at": "2025-01-20T14:00:00Z"
      }
    ],
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-20T14:15:00Z"
  }
}

PATCH/patients/{id}

Update a patient

Updates the specified patient record. Only the fields included in the request body will be modified; all other fields remain unchanged.

Parameters

Parameter	Type	Required	Description
id	string	Required	The patient ID (pat_*)
first_name	string	Optional	Updated first name
last_name	string	Optional	Updated last name
phone	string	Optional	Updated phone number
address	object	Optional	Updated address object
status	string	Optional	Updated status: active, inactive, archived

Example Request

Requestbash

curl -X PATCH https://api.odento.app/api/v1/patients/pat_5f8d3a2b1c9e4a7b \
  -H "X-API-Key-ID: ok_live_abc123def456ghi789jkl012" \
  -H "X-API-Key-Secret: os_abc123def456ghi789jkl012mno345pqr678stu901vwx234yzab567" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+919876500000",
    "address": {
      "street": "45 Brigade Road",
      "city": "Bengaluru",
      "state": "Karnataka",
      "postal_code": "560025",
      "country": "India"
    }
  }'

Example Response

Response200json

{
  "success": true,
  "data": {
    "id": "pat_5f8d3a2b1c9e4a7b",
    "first_name": "Priya",
    "last_name": "Sharma",
    "email": "priya.sharma@example.com",
    "phone": "+919876500000",
    "date_of_birth": "1990-05-15",
    "gender": "female",
    "status": "active",
    "address": {
      "street": "45 Brigade Road",
      "city": "Bengaluru",
      "state": "Karnataka",
      "postal_code": "560025",
      "country": "India"
    },
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-22T08:45:00Z"
  }
}

GET/patients/search

Search patients

Search patients by name, email, phone, or any combination of fields. Returns matching patients ranked by relevance.

Parameters

Parameter	Type	Required	Description
q	string	Required	Search query (matches name, email, phone)
limit	integer	Optional	Max results to return (1-50). Default: 10

Example Request

Requestbash

curl -X GET "https://api.odento.app/api/v1/patients/search?q=priya" \
  -H "X-API-Key-ID: ok_live_abc123def456ghi789jkl012" \
  -H "X-API-Key-Secret: os_abc123def456ghi789jkl012mno345pqr678stu901vwx234yzab567"

Example Response

Response200json

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "pat_5f8d3a2b1c9e4a7b",
        "first_name": "Priya",
        "last_name": "Sharma",
        "email": "priya.sharma@example.com",
        "phone": "+919876543210",
        "status": "active"
      },
      {
        "id": "pat_9c2d4e7f1a3b6c8d",
        "first_name": "Priyanka",
        "last_name": "Gupta",
        "email": "priyanka.gupta@example.com",
        "phone": "+919876543220",
        "status": "active"
      }
    ],
    "total": 2
  }
}

DELETE/patients/{id}

Delete a patient

Permanently deletes a patient record. This action cannot be undone. The patient's medical history records are archived but not deleted.

Parameters

Parameter	Type	Required	Description
id	string	Required	The patient ID (pat_*)

Example Request

Requestbash

curl -X DELETE https://api.odento.app/api/v1/patients/pat_5f8d3a2b1c9e4a7b \
  -H "X-API-Key-ID: ok_live_abc123def456ghi789jkl012" \
  -H "X-API-Key-Secret: os_abc123def456ghi789jkl012mno345pqr678stu901vwx234yzab567"

Example Response

Response200json

{
  "success": true,
  "data": {
    "id": "pat_5f8d3a2b1c9e4a7b",
    "deleted": true
  }
}

GET/patients/{id}/records

List patient medical records

Retrieves all medical records associated with a patient, including diagnoses, treatments, prescriptions, and lab results.

Parameters

Parameter	Type	Required	Description
id	string	Required	The patient ID (pat_*)
type	string	Optional	Filter by record type: diagnosis, treatment, prescription, lab_result
limit	integer	Optional	Results per page (1-100). Default: 20
cursor	string	Optional	Pagination cursor

Example Request

Requestbash

curl -X GET "https://api.odento.app/api/v1/patients/pat_5f8d3a2b1c9e4a7b/records?type=diagnosis" \
  -H "X-API-Key-ID: ok_live_abc123def456ghi789jkl012" \
  -H "X-API-Key-Secret: os_abc123def456ghi789jkl012mno345pqr678stu901vwx234yzab567"

Example Response

Response200json

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "med_rec_abc123",
        "type": "diagnosis",
        "title": "Dental caries - upper left molar",
        "description": "Class II caries on tooth #26 extending into dentin.",
        "icd10_code": "K02.1",
        "recorded_by": "usr_abc123",
        "recorded_at": "2025-01-20T14:00:00Z"
      },
      {
        "id": "med_rec_def456",
        "type": "diagnosis",
        "title": "Gingivitis - generalized",
        "description": "Generalized mild gingivitis with bleeding on probing.",
        "icd10_code": "K05.1",
        "recorded_by": "usr_abc123",
        "recorded_at": "2025-01-18T11:30:00Z"
      }
    ],
    "pagination": {
      "has_more": false,
      "next_cursor": null,
      "per_page": 20
    }
  }
}

The Patient Object

List all patients

Parameters

Example Request

Example Response

Try It Out

Create a patient

Parameters

Example Request

Example Response

Retrieve a patient

Parameters

Example Request

Example Response

Update a patient

Parameters

Example Request

Example Response

Search patients

Parameters

Example Request

Example Response

Delete a patient

Parameters

Example Request

Example Response

List patient medical records

Parameters

Example Request

Example Response

Was this page helpful?