BeaconCR Developer Portal
The BeaconCR REST API lets sponsors and research sites integrate their own systems with the registry platform — enrolling participants, collecting study data, managing patient-reported outcomes, and pulling audit-ready exports — without clicking through the admin interface.
Who this is for
The API is designed for two audiences:
- Sponsor integrations. Organizations running or funding registry studies can synchronize study structures, enrollment status, and exports into their own reporting and analysis pipelines.
- Site systems. Research sites can connect scheduling, EHR-adjacent workflows, or data-capture tools so that participant status and visit data stay in step with what already happens in their clinic.
Access is server-to-server. Every client is issued to a specific organization, every token is scoped to that organization, and cross-organization access is not possible.
Base URL
All endpoints hang off a versioned base path:
https://<host>/api/v1/
Replace <host> with the hostname of your BeaconCR deployment. Thev1 segment pins your integration to a stable contract — see versioning for how breaking changes are handled.
What the API covers
Version 1 exposes the following resource areas:
| Area | Endpoints | What you can do |
|---|---|---|
| Organizations | GET /organizations/me | Confirm which organization a token belongs to and what it can reach. |
| Studies | GET/POST /studies, GET/PATCH /studies/{id} | List, create, and update registry studies and their lifecycle status. |
| Sites | GET/POST /studies/{id}/sites | Manage the participating sites activated under a study. |
| Forms and visits | /studies/{id}/forms, /studies/{id}/visits | Read case report form definitions and their versions; work with visit schedules. |
| Participants | GET/POST /studies/{id}/participants | Enroll participants, update status, and write data points with a reason for change. |
| Queries | GET/POST /studies/{id}/queries | Open and resolve data queries raised against collected data. |
| ePRO | /studies/{id}/epro/* | List instruments, issue invitations, and read submitted patient responses. |
| Consent | GET /studies/{id}/consents | Track consent status and retrieve signed consent documents. |
| Exports | POST /studies/{id}/exports | Start asynchronous export jobs and download the finished files. |
| Audit events | GET /audit-events | Read the append-only audit trail, filtered by type, actor, and time range. |
| Webhooks | GET/POST/PATCH/DELETE /webhooks | Register endpoints that receive signed event deliveries. |
Field-level detail for every endpoint lives in the interactive API reference, which is rendered from the platform's OpenAPI document and can be downloaded as a YAML file from that page.
How an integration typically flows
- An administrator creates an API client in the admin interface and copies the credentials (shown once at creation — see getting started).
- Your server exchanges the credentials for a short-lived access token (valid for at most one hour).
- The token authorizes calls against the specific scopes your client was granted — for example reading studies, writing participant data, or starting exports.
- List endpoints use cursor pagination, updates use ETag-based optimistic concurrency, and POSTs accept idempotency keys so a retried request cannot create duplicates.
- Changes that other systems care about — a signed consent, a submitted ePRO response, a locked study — can be pushed to you as signed webhook deliveries instead of you polling.
Start here
New to the API? Follow the getting-started guide: create a client, request a token, and make your first call — all in a few minutes.
Get started