API

The randomisation API allows your server or database programme to download randomisations on demand. The API is not enabled by default - you must request access to this feature.

Request

Access to the list of randomisations for your trial is provided by HTTP GET request to the url:

https://{PATH TO YOUR TRIAL}/api/csv

where the path to your trial is the url you would normally use to view the trial home page, e.g.

https://www.sealedenvelope.com/redpill/mytrial

Please note:

  • the API must be accessed via HTTPS, it will not work via HTTP.

  • You should connect to the url using HTTP basic authorisation using the username and password that we have supplied.

  • Access to the API is limited by IP address. Please supply us with a list of IP addresses that you expect to be connecting from.

Response

The response will be a CSV dump of all randomisations to date, sent with a content type of “text/plain”, e.g.

id,"Parent patient. Foreign key: patient table.id","Patient identifier","User who created row","User who last updated row","Date & time of randomisation","Randomisation code",Unblinded?,"Reason for unblinding","Date unblinded","Manual randomisation?","Randomised in error?","Reason marked in error","Date marked error","Timestamp for row creation","Date & time of last update to row","Reason for editing row",Notes,"Justifications for overriding validation","Validation status","Validation notes","Randomisation - Patient Initials","Randomisation - Patient's Date of Birth. dd/mm/yyyy","Randomisation - Currently taking antidepressant?","Randomisation - PHQ 2 Score. Number (up to 2 digits)","Randomisation - MINI indicated current major depressive episode?","Randomisation - AUDIT Score. Number (up to 2 digits)","Randomisation - Does the patient meet all other eligibility criteria?","Randomisation - Has the patient given written informed consent?","Date entered study","Date withdrew",Site,Country,Visit
1,1,AA001,"Jacob Benfield (ID 813)","Jacob Benfield (ID 813)","2014-05-01 10:05:25",OE9,0,,,No,0,,,"2014-05-01 10:05:25","2014-05-01 10:05:25",,,,"Not validated",,AA,10/08/1957,Yes,6,Yes,16,Yes,Yes,"2014-05-01 10:05:25",,UCL,"United Kingdom",Registration
2,2,BB002,"Jacob Benfield (ID 813)","Jacob Benfield (ID 813)","2014-05-01 14:58:40",WS4,0,,,No,0,,,"2014-05-01 14:58:40","2014-05-01 14:58:40",,,,"Not validated",,BB,17/02/1980,Yes,4,Yes,10,Yes,Yes,"2014-05-01 14:58:40",,UCL,"United Kingdom",Registration
3,3,CC003,"Jacob Benfield (ID 813)","Jacob Benfield (ID 813)","2014-05-01 17:11:13",QB2,0,,,No,0,,,"2014-05-01 17:11:13","2014-05-01 17:11:13",,,,"Not validated",,CC,5/5/1968,Yes,3,Yes,9,Yes,Yes,"2014-05-01 17:11:13",,UCL,"United Kingdom",Registration

The first line is a header. The data will vary by trial, but all trials will contain the following standard fields:

  • id: primary key, unique id
  • Parent patient. Foreign key: patient table.id. In Red Pill applications this is the id of the patient that the randomisation belongs to
  • Patient identifier: unique patient identifier, may be user entered or generated
  • User who created row: the name and user id of the randomiser
  • User who last updated row: the name and user id of the person who last edited the randomisation
  • Date & time of randomisation
  • Randomisation group or code: this will be the treatment group for unblinded trials or code for blinded trials
  • Unblinded?: has the patient been unblinded? 0=no, 1=yes
  • Reason for unblinding: the reason entered when the randomisation was unblinded
  • Date unblinded
  • Manual randomisation?: was this a manual randomisation?
  • Randomised in error?: was the patient randomised in error? 0=no, 1=yes
  • Reason marked in error
  • Date marked error: the date the randomisation was marked as in error
  • Timestamp for row creation
  • Date & time of last update to row
  • Reason for editing row
  • Notes
  • Justifications for overriding validation: reasons for overriding validation errors
  • Validation status: forms may be marked as ‘Not validated’, ‘Validated’, or ‘Data unusable’
  • Validation notes: notes recorded when changing the form validation status
  • Date entered study
  • Date withdrew
  • Site: name of site
  • Country
  • Visit: the visit that the form is associated with

For blinded trials the data will not contain the treatment group.

Testing

You can test the request by visiting the API URL in your browser. You should see a dialog box requesting the username and password. Enter the details we supplied and you should then see the response. If you are connecting from an unauthorised IP address you will instead see the message Authorization required over https.

Or using curl:

$ curl -u <username>:<password> https://www.sealedenvelope.com/redpill/mytrial/api/csv
Page updated 7 Sep 2017