Developer Documentation

syfrah API v1

Access comprehensive clinical trials data programmatically. Build powerful applications with our REST API covering 500,000+ trials from global registries.

Get StartedError HandlingUse Cases
Base URLhttps://api.syfrah.com/v1

Authentication

Bearer YOUR_KEY

Rate Limits

Free: 100/day • Pro: 10K/day

Response Format

JSON with consistent structure

SDKs

Python & JS Soon

Rate Limit Headers

All API responses include rate limit information in the headers:

X-RateLimit-Limit

Requests allowed per day

X-RateLimit-Remaining

Requests remaining today

X-RateLimit-Reset

Unix timestamp when limit resets

Retry-After

Seconds to wait (when rate limited)

Trials

Search, filter, and retrieve clinical trial data

Search and filter clinical trials with advanced query options. Supports pagination, sorting, and multiple filter combinations.

Parameters
q
string

Full-text search query

phase
string

Phase filter: phase_1, phase_2, phase_3, phase_4 (comma-separated for multiple)

status
string

Status: recruiting, completed, active_not_recruiting, terminated, withdrawn

condition
string

Medical condition (normalized slug or name)

intervention
string

Drug/intervention name (normalized slug or name)

sponsor
string

Sponsor name (normalized slug or name)

country
string

Country code (ISO 3166-1 alpha-2, e.g., US, GB, DE)

has_results
boolean

Filter trials with published results (true/false)

enrollment_min
number

Minimum enrollment size

enrollment_max
number

Maximum enrollment size

sort
string

Sort order: relevance (default), enrollment_desc, enrollment_asc, date_desc, date_asc

page
number

Page number (default: 1)

per_page
number

Results per page (default: 20, max: 100)

Request
curl -X GET "https://api.syfrah.com/v1/trials?status=recruiting&phase=phase_3&condition=diabetes&sort=enrollment_desc" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "trials": [
    {
      "source_id": "NCT04368728",
      "public_title": "Study of XYZ Drug in Type 2 Diabetes",
      "phase": "Phase 3",
      "status": "Recruiting",
      "conditions": ["Diabetes Type 2"],
      "interventions": ["XYZ Drug"],
      "sponsors": ["Pharma Corp"],
      "countries": ["US", "GB", "DE"],
      "actual_enrollment": 1500,
      "has_results": false
    }
  ],
  "total": 847,
  "page": 1,
  "per_page": 20,
  "total_pages": 43
}

Retrieve complete information about a specific clinical trial including conditions, interventions, sponsors, sites, and contacts.

Parameters
source_id*
string

Trial identifier (e.g., NCT04368728, EUCTR2020-001234-56)

Request
curl -X GET "https://api.syfrah.com/v1/trials/NCT04368728" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "source_id": "NCT04368728",
  "source_registry": "ctgov",
  "public_title": "Study of XYZ Drug in Type 2 Diabetes",
  "scientific_title": "A Randomized, Double-Blind, Placebo-Controlled...",
  "phase": "Phase 3",
  "recruitment_status": "Recruiting",
  "study_type": "Interventional",
  "target_size": 2000,
  "actual_enrollment": 1500,
  "registration_date": "2023-01-15",
  "first_enrollment_date": "2023-03-20",
  "has_results": false,
  "conditions": [
    {
      "name": "Diabetes Type 2",
      "normalized": "diabetes-type-2",
      "is_primary": true
    }
  ],
  "interventions": [
    {
      "name": "XYZ Drug",
      "normalized": "xyz-drug",
      "intervention_type": "Drug",
      "arm_group": "Treatment Arm"
    }
  ],
  "sponsors": [
    {
      "name": "Pharma Corp",
      "normalized": "pharma-corp",
      "role": "lead_sponsor"
    }
  ],
  "countries": [
    { "code": "US", "site_count": 45 },
    { "code": "GB", "site_count": 12 }
  ]
}

Retrieve published results for a completed trial, including participant flow, baseline characteristics, outcomes, and adverse events.

Parameters
source_id*
string

Trial identifier

Request
curl -X GET "https://api.syfrah.com/v1/trials/NCT04368728/results" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "source_id": "NCT04368728",
  "has_results": true,
  "results_first_posted": "2024-06-15",
  "participant_flow": {
    "recruitment_details": "Recruited from 57 sites across 3 countries",
    "groups": [
      { "id": "G1", "title": "Treatment", "participants": 1000 },
      { "id": "G2", "title": "Placebo", "participants": 500 }
    ]
  },
  "baseline_characteristics": {
    "population_description": "Adults 18-75 with T2D",
    "measures": [
      { "title": "Age", "units": "years", "param": "Mean", "value": "54.2" }
    ]
  },
  "outcome_measures": [
    {
      "title": "Primary: HbA1c Change from Baseline",
      "type": "primary",
      "time_frame": "12 weeks",
      "description": "Change in HbA1c levels",
      "groups": [
        { "id": "G1", "value": "-1.2%", "spread": "0.3" }
      ]
    }
  ],
  "adverse_events": {
    "time_frame": "24 weeks",
    "description": "All adverse events reported",
    "serious_events": { "total": 12, "deaths": 0 },
    "other_events": { "total": 145 }
  }
}

Find trials similar to the specified trial based on conditions, interventions, phase, and sponsor relationships.

Parameters
source_id*
string

Trial identifier

limit
number

Max results (default: 10, max: 50)

Request
curl -X GET "https://api.syfrah.com/v1/trials/NCT04368728/similarities?limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "source_trial": "NCT04368728",
  "similar_trials": [
    {
      "source_id": "NCT05123456",
      "public_title": "Similar Diabetes Study",
      "similarity_score": 0.89,
      "shared_conditions": ["Diabetes Type 2"],
      "shared_interventions": [],
      "same_phase": true,
      "same_sponsor": false
    },
    {
      "source_id": "NCT05234567",
      "public_title": "Another Related Trial",
      "similarity_score": 0.76,
      "shared_conditions": ["Diabetes Type 2"],
      "shared_interventions": ["Metformin"],
      "same_phase": true,
      "same_sponsor": true
    }
  ]
}

Graph Query

Advanced graph-based queries for complex relationship searches

Execute complex queries with nested AND/OR conditions and graph traversals. Supports multi-hop relationships between trials, sponsors, investigators, and conditions.

Parameters
entity*
string

Target entity: trials, sponsors, investigators, conditions

root*
object

Query group with logic (AND/OR) and conditions array

page
number

Page number (default: 1)

per_page
number

Results per page (default: 20, max: 100)

Request
curl -X POST "https://api.syfrah.com/v1/graph/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity": "trials",
    "root": {
      "id": "root",
      "logic": "AND",
      "conditions": [
        {
          "id": "1",
          "field": "status",
          "operator": "is",
          "value": "recruiting"
        },
        {
          "id": "2",
          "field": "phase",
          "operator": "is_any_of",
          "value": ["phase_2", "phase_3"]
        }
      ]
    }
  }'
Response
{
  "results": [
    {
      "id": "NCT04368728",
      "entity_type": "trial",
      "public_title": "Study of XYZ Drug...",
      "phase": "Phase 3",
      "status": "Recruiting"
    }
  ],
  "total": 847,
  "page": 1,
  "per_page": 20,
  "total_pages": 43,
  "metadata": {
    "execution_time_ms": 45,
    "filters_applied": 2,
    "graph_hops": 0
  }
}

Get count of results for a graph query without fetching data. Useful for building live previews and validating queries before execution.

Parameters
entity*
string

Target entity type

root*
object

Query structure (same as /graph/query)

Request
curl -X POST "https://api.syfrah.com/v1/graph/count" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entity": "trials", "root": {"id": "root", "logic": "AND", "conditions": [{"id": "1", "field": "status", "operator": "is", "value": "recruiting"}]}}'
Response
{
  "count": 847,
  "execution_time_ms": 12
}

Retrieve the graph schema with available nodes, edges, fields, and operators. Use this to dynamically build query interfaces.

Request
curl -X GET "https://api.syfrah.com/v1/graph/schema" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "nodes": [
    {
      "name": "trials",
      "label": "Trials",
      "fields": [
        {
          "name": "condition",
          "label": "Condition",
          "field_type": "autocomplete",
          "operators": ["is", "is_not", "contains", "is_any_of"]
        },
        {
          "name": "phase",
          "label": "Phase",
          "field_type": "enum",
          "operators": ["is", "is_any_of"],
          "values": ["phase_1", "phase_2", "phase_3", "phase_4"]
        },
        {
          "name": "status",
          "label": "Status",
          "field_type": "enum",
          "operators": ["is", "is_any_of"],
          "values": ["recruiting", "completed", "active_not_recruiting", "terminated"]
        },
        {
          "name": "enrollment",
          "label": "Enrollment",
          "field_type": "number",
          "operators": ["equals", "greater_than", "less_than", "between"]
        }
      ]
    }
  ],
  "edges": [
    {
      "name": "trial_condition",
      "label": "has condition",
      "from": "trials",
      "to": "conditions",
      "bidirectional": true
    },
    {
      "name": "trial_sponsor",
      "label": "sponsored by",
      "from": "trials",
      "to": "sponsors",
      "bidirectional": true
    }
  ],
  "operators": [
    { "name": "is", "label": "is", "applicable_types": ["string", "enum"] },
    { "name": "is_not", "label": "is not", "applicable_types": ["string", "enum"] },
    { "name": "contains", "label": "contains", "applicable_types": ["string"] },
    { "name": "is_any_of", "label": "is any of", "applicable_types": ["enum", "string"] },
    { "name": "greater_than", "label": ">", "applicable_types": ["number", "date"] },
    { "name": "less_than", "label": "<", "applicable_types": ["number", "date"] },
    { "name": "between", "label": "between", "applicable_types": ["number", "date"] }
  ]
}

Entities

Browse conditions, sponsors, drugs, and countries

Get condition details including MeSH IDs, ICD-10 codes, synonyms, and all associated trials.

Parameters
slug*
string

Normalized condition name (e.g., diabetes-type-2)

page
number

Page number (default: 1)

per_page
number

Results per page (default: 20, max: 100)

Request
curl -X GET "https://api.syfrah.com/v1/conditions/diabetes-type-2?per_page=50" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "condition": "Diabetes Type 2",
  "normalized": "diabetes-type-2",
  "mesh_id": "D003924",
  "icd10_codes": ["E11", "E11.9"],
  "synonyms": ["T2D", "NIDDM", "Type 2 Diabetes Mellitus", "Adult-Onset Diabetes"],
  "parent_conditions": ["Diabetes Mellitus", "Metabolic Diseases"],
  "trials": [
    {
      "source_id": "NCT04368728",
      "public_title": "Study of XYZ Drug...",
      "phase": "Phase 3",
      "status": "Recruiting"
    }
  ],
  "total": 4521,
  "page": 1,
  "per_page": 50,
  "total_pages": 91
}

Get sponsor profile with type classification, aliases, and complete trial portfolio.

Parameters
slug*
string

Normalized sponsor name (e.g., pfizer)

page
number

Page number (default: 1)

per_page
number

Results per page (default: 20, max: 100)

Request
curl -X GET "https://api.syfrah.com/v1/sponsors/pfizer" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "name": "Pfizer",
  "normalized": "pfizer",
  "sponsor_type": "industry",
  "country": "US",
  "aliases": ["Pfizer Inc.", "Pfizer Pharmaceuticals", "Pfizer Ltd"],
  "stats": {
    "total_trials": 2847,
    "recruiting": 234,
    "completed": 1892,
    "with_results": 1456,
    "phase_distribution": {
      "phase_1": 456,
      "phase_2": 892,
      "phase_3": 1123,
      "phase_4": 376
    },
    "top_conditions": [
      { "name": "Breast Cancer", "count": 234 },
      { "name": "COVID-19", "count": 189 }
    ]
  },
  "trials": [...],
  "total": 2847,
  "page": 1,
  "per_page": 20
}

Get drug/intervention details with mechanism of action, DrugBank ID, and all trials using this intervention.

Parameters
slug*
string

Normalized drug name (e.g., metformin)

page
number

Page number (default: 1)

per_page
number

Results per page (default: 20, max: 100)

Request
curl -X GET "https://api.syfrah.com/v1/drugs/metformin" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "name": "Metformin",
  "normalized": "metformin",
  "intervention_type": "Drug",
  "drugbank_id": "DB00331",
  "mechanism_of_action": "Biguanide antihyperglycemic agent that decreases hepatic glucose production",
  "synonyms": ["Glucophage", "Metformin HCl", "Metformin Hydrochloride"],
  "atc_codes": ["A10BA02"],
  "trials": [...],
  "total": 3456,
  "page": 1,
  "per_page": 20
}

Get all trials conducted in a specific country with site statistics.

Parameters
code*
string

ISO 3166-1 alpha-2 country code (e.g., US, GB, DE)

page
number

Page number (default: 1)

per_page
number

Results per page (default: 20, max: 100)

Request
curl -X GET "https://api.syfrah.com/v1/countries/US" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "code": "US",
  "name": "United States",
  "total_sites": 45678,
  "stats": {
    "recruiting": 12345,
    "completed": 28901
  },
  "trials": [...],
  "total": 156789,
  "page": 1,
  "per_page": 20
}

Investigators

Access Key Opinion Leader (KOL) data and collaboration networks

Get detailed investigator profile with affiliations, h-index, publications, and trial statistics.

Parameters
id*
string

Investigator UUID

Request
curl -X GET "https://api.syfrah.com/v1/investigators/abc-123-def" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "investigator": {
    "investigator_id": "abc-123-def",
    "name": "Dr. Jane Smith",
    "orcid_id": "0000-0002-1234-5678",
    "affiliations": ["Harvard Medical School", "Massachusetts General Hospital"],
    "countries": ["US"],
    "h_index": 45,
    "total_publications": 120,
    "email": "j.smith@hms.harvard.edu"
  },
  "stats": {
    "total_trials": 34,
    "trials_as_pi": 12,
    "trials_as_co_investigator": 22,
    "active_trials": 8,
    "phase_distribution": { "phase_1": 5, "phase_2": 15, "phase_3": 14 },
    "therapeutic_areas": { "oncology": 20, "cardiology": 14 },
    "top_sponsors": [
      { "name": "Pfizer", "count": 8 },
      { "name": "NIH", "count": 6 }
    ]
  }
}

Get the investigator's collaboration network as a graph with nodes (collaborators) and weighted edges (shared trials).

Parameters
id*
string

Investigator UUID

depth
number

Network depth/hops (default: 2, max: 3)

min_weight
number

Minimum collaboration weight to include (default: 1)

Request
curl -X GET "https://api.syfrah.com/v1/investigators/abc-123-def/network?depth=2" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "center_investigator": {
    "investigator_id": "abc-123-def",
    "name": "Dr. Jane Smith"
  },
  "nodes": [
    {
      "investigator_id": "abc-123-def",
      "name": "Dr. Jane Smith",
      "influence_score": 0.85,
      "trial_count": 34,
      "depth": 0
    },
    {
      "investigator_id": "xyz-456-ghi",
      "name": "Dr. John Doe",
      "influence_score": 0.72,
      "trial_count": 28,
      "depth": 1
    }
  ],
  "edges": [
    {
      "source": "abc-123-def",
      "target": "xyz-456-ghi",
      "weight": 5,
      "shared_trials": ["NCT001", "NCT002", "NCT003", "NCT004", "NCT005"]
    }
  ],
  "metadata": {
    "total_nodes": 45,
    "total_edges": 89,
    "max_depth": 2
  }
}

Search investigators by name, affiliation, or therapeutic area.

Parameters
q*
string

Search query (name or affiliation)

therapeutic_area
string

Filter by specialty

country
string

Filter by country code

limit
number

Max results (default: 20, max: 100)

Request
curl -X GET "https://api.syfrah.com/v1/investigators/search?q=smith&therapeutic_area=oncology&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "investigators": [
    {
      "investigator_id": "abc-123-def",
      "name": "Dr. Jane Smith",
      "affiliation": "Harvard Medical School",
      "country": "US",
      "trial_count": 34,
      "influence_score": 0.85
    }
  ],
  "total": 156
}

Get ranked list of Key Opinion Leaders by influence score, optionally filtered by therapeutic area.

Parameters
therapeutic_area
string

Filter by specialty (e.g., oncology, cardiology, neurology)

country
string

Filter by country code

limit
number

Max results (default: 20, max: 100)

Request
curl -X GET "https://api.syfrah.com/v1/investigators/top-kols?therapeutic_area=oncology&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
[
  {
    "investigator_id": "abc-123-def",
    "name": "Dr. Jane Smith",
    "influence_score": 0.95,
    "trial_count": 67,
    "h_index": 52,
    "affiliations": ["Harvard Medical School"],
    "therapeutic_areas": ["oncology", "hematology"]
  },
  {
    "investigator_id": "xyz-456-ghi",
    "name": "Dr. John Doe",
    "influence_score": 0.91,
    "trial_count": 54,
    "h_index": 48,
    "affiliations": ["Stanford University"],
    "therapeutic_areas": ["oncology"]
  }
]

Analytics

Access analytics, trends, and enrollment predictions

Get overall platform statistics including totals, distributions, and recent activity.

Request
curl -X GET "https://api.syfrah.com/v1/analytics/dashboard" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "total_trials": 523847,
  "total_sponsors": 12456,
  "total_conditions": 8934,
  "total_drugs": 15678,
  "total_investigators": 234567,
  "trials_last_30_days": 1247,
  "trials_last_7_days": 312,
  "phase_distribution": {
    "early_phase_1": 12000,
    "phase_1": 45000,
    "phase_2": 120000,
    "phase_3": 180000,
    "phase_4": 95000,
    "not_applicable": 71847
  },
  "status_distribution": {
    "recruiting": 45000,
    "active_not_recruiting": 32000,
    "completed": 280000,
    "terminated": 15000,
    "withdrawn": 8000,
    "suspended": 2000
  },
  "top_conditions": [
    { "name": "Breast Cancer", "count": 12456 },
    { "name": "COVID-19", "count": 11234 }
  ],
  "last_updated": "2024-01-15T12:00:00Z"
}

Get time-series data for global trial activity over specified period.

Parameters
months
number

Lookback period in months (default: 24, max: 60)

granularity
string

Data granularity: month (default), quarter, year

Request
curl -X GET "https://api.syfrah.com/v1/analytics/trends/global?months=12&granularity=month" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "data": [
    {
      "year_month": "2024-01",
      "trials_registered": 1247,
      "trials_started": 892,
      "trials_completed": 456,
      "trials_terminated": 34,
      "cumulative_total": 520000
    },
    {
      "year_month": "2024-02",
      "trials_registered": 1189,
      "trials_started": 834,
      "trials_completed": 512,
      "trials_terminated": 28,
      "cumulative_total": 521189
    }
  ],
  "summary": {
    "avg_monthly_registrations": 1218,
    "trend_direction": "increasing",
    "trend_percentage": 3.2
  },
  "start_date": "2023-01-01",
  "end_date": "2024-12-31"
}

Get AI-powered enrollment prediction with risk assessment and projected completion date based on historical benchmarks.

Parameters
source_id*
string

Trial identifier

Request
curl -X GET "https://api.syfrah.com/v1/trials/NCT04368728/enrollment-prediction" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "source_id": "NCT04368728",
  "target_enrollment": 2000,
  "current_enrollment": 1500,
  "percent_enrolled": 75.0,
  "enrollment_start_date": "2023-03-20",
  "days_enrolling": 365,
  "current_velocity": 4.1,
  "predicted_velocity": 3.8,
  "benchmark_velocity": 4.5,
  "velocity_percentile": 42,
  "predicted_completion_date": "2025-06-15",
  "original_target_date": "2025-03-01",
  "delay_days": 106,
  "confidence_interval": {
    "low": "2025-04-01",
    "high": "2025-08-30",
    "confidence": 0.90
  },
  "risk_score": 35,
  "risk_level": "medium",
  "risk_factors": [
    "Enrollment velocity 16% below benchmark",
    "2 sites have dropped out in last 90 days",
    "Competing trial started recruiting in same indication"
  ],
  "recommendations": [
    "Consider adding sites in high-performing regions",
    "Review eligibility criteria for potential expansion"
  ]
}

Autocomplete

Get suggestions for search filters and form fields

Get autocomplete suggestions for filter fields with result counts. Useful for building search UIs with type-ahead.

Parameters
field*
string

Field to search: conditions, interventions, sponsors, countries, investigators

q*
string

Search query (minimum 2 characters)

limit
number

Max suggestions (default: 10, max: 50)

Request
curl -X GET "https://api.syfrah.com/v1/autocomplete/conditions?q=diab&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "field": "conditions",
  "query": "diab",
  "suggestions": [
    { "value": "Diabetes Type 2", "normalized": "diabetes-type-2", "count": 4521 },
    { "value": "Diabetes Type 1", "normalized": "diabetes-type-1", "count": 2134 },
    { "value": "Diabetic Neuropathy", "normalized": "diabetic-neuropathy", "count": 892 },
    { "value": "Diabetic Retinopathy", "normalized": "diabetic-retinopathy", "count": 654 },
    { "value": "Gestational Diabetes", "normalized": "gestational-diabetes", "count": 445 }
  ]
}

Error Handling

All errors follow a consistent JSON structure for easy handling in your application.

Error Response Format

{
  "error": {
    "code": "invalid_parameter",
    "message": "The 'phase' parameter must be one of: phase_1, phase_2, phase_3, phase_4",
    "param": "phase",
    "doc_url": "https://docs.syfrah.com/errors#invalid_parameter"
  },
  "request_id": "req_abc123xyz"
}

Error Codes

invalid_api_keyAPI key is missing, invalid, or expired
invalid_parameterA parameter has an invalid value
missing_parameterA required parameter is missing
resource_not_foundThe requested resource doesn't exist
rate_limit_exceededToo many requests, slow down
invalid_queryGraph query syntax is invalid
internal_errorSomething went wrong on our end

HTTP Status Codes

200OKRequest succeeded
201CreatedResource created successfully
400Bad RequestInvalid request parameters
401UnauthorizedInvalid or missing API key
403ForbiddenValid key but insufficient permissions
404Not FoundResource doesn't exist
429Too Many RequestsRate limit exceeded
500Internal ErrorServer error, retry later
503Service UnavailableTemporary maintenance

Handling Errors (Python)

import requests


response = requests.get(
    "https://api.syfrah.com/v1/trials/INVALID_ID",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)


if response.status_code == 200:
    data = response.json()
elif response.status_code == 404:
    error = response.json()["error"]
    print(f"Not found: {error['message']}")
elif response.status_code == 429:
    retry_after = response.headers.get("Retry-After", 60)
    print(f"Rate limited. Retry after {retry_after}s")
else:
    error = response.json()["error"]
    print(f"Error {error['code']}: {error['message']}")

Common Use Cases

Practical examples to help you get the most out of the API.

Paginate Through All Results

Fetch all trials matching a query by iterating through pages.

import requests


def fetch_all_trials(params):
    """Fetch all trials matching params."""
    all_trials = []
    page = 1


    while True:
        response = requests.get(
            "https://api.syfrah.com/v1/trials",
            headers={"Authorization": "Bearer YOUR_API_KEY"},
            params={**params, "page": page, "per_page": 100}
        )
        data = response.json()
        all_trials.extend(data["trials"])


        if page >= data["total_pages"]:
            break
        page += 1


    return all_trials


# Example: Get all recruiting Phase 3 trials
trials = fetch_all_trials({
    "status": "recruiting",
    "phase": "phase_3"
})
print(f"Found {len(trials)} trials")

Competitive Intelligence Query

Find competing trials using the Graph Query API.

import requests


# Find all Phase 2/3 recruiting trials in diabetes
# from competitors (not your company)
query = {
    "entity": "trials",
    "root": {
        "id": "root",
        "logic": "AND",
        "conditions": [
            {"id": "1", "field": "condition", "operator": "is", "value": "diabetes-type-2"},
            {"id": "2", "field": "phase", "operator": "is_any_of", "value": ["phase_2", "phase_3"]},
            {"id": "3", "field": "status", "operator": "is", "value": "recruiting"},
            {"id": "4", "field": "sponsor", "operator": "is_not", "value": "your-company"}
        ]
    }
}


response = requests.post(
    "https://api.syfrah.com/v1/graph/query",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json=query
)
competitors = response.json()
print(f"Found {competitors['total']} competing trials")

Identify KOLs for a Condition

Find top investigators in a therapeutic area.

import requests


# Get top oncology KOLs
response = requests.get(
    "https://api.syfrah.com/v1/investigators/top-kols",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={
        "therapeutic_area": "oncology",
        "country": "US",
        "limit": 20
    }
)
kols = response.json()


# Get network for top KOL
top_kol = kols[0]
network = requests.get(
    f"https://api.syfrah.com/v1/investigators/{top_kol['investigator_id']}/network",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"depth": 2}
).json()


print(f"Top KOL: {top_kol['name']}")
print(f"Influence score: {top_kol['influence_score']:.2f}")
print(f"Network size: {len(network['nodes'])} collaborators")

Monitor Trial Enrollment

Track enrollment progress and get risk alerts.

import requests


def check_enrollment_risk(trial_ids):
    """Check enrollment risk for multiple trials."""
    at_risk = []


    for trial_id in trial_ids:
        response = requests.get(
            f"https://api.syfrah.com/v1/trials/{trial_id}/enrollment-prediction",
            headers={"Authorization": "Bearer YOUR_API_KEY"}
        )


        if response.status_code == 200:
            pred = response.json()
            if pred["risk_level"] in ["medium", "high"]:
                at_risk.append({
                    "trial_id": trial_id,
                    "risk_level": pred["risk_level"],
                    "risk_score": pred["risk_score"],
                    "factors": pred["risk_factors"],
                    "delay_days": pred.get("delay_days", 0)
                })


    return at_risk


# Check your portfolio
portfolio = ["NCT04368728", "NCT05123456", "NCT05234567"]
risks = check_enrollment_risk(portfolio)


for r in risks:
    print(f"{r['trial_id']}: {r['risk_level']} risk ({r['risk_score']}/100)")
    print(f"  Factors: {', '.join(r['factors'][:2])}")

API Versioning

The API version is included in the URL path (/v1/). We follow semantic versioning and will maintain backward compatibility within a major version.

  • v1 (current) - Stable, production-ready. Breaking changes will be announced 6 months in advance.
  • Deprecation policy - Deprecated endpoints return a X-Deprecation-Notice header.
  • Changelog - Available at /changelog with all API updates.

Ready to get started?

Create your account and get your API key in minutes.

View PricingContact Sales