REST API¶

The randomization service can be accessed programmatically via its HTTP API. Authentication is handled via a user-specific API key provided by the system administrator.

Warning

Store your API key securely. It grants full access to randomize participants and read study data.

Endpoints¶

GET /study_config¶

Return study configuration.

Example request:

GET /study_config HTTP/1.1
Host: https://rcg.bsd.uchicago.edu/urand

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
    "message": "Success",
    "results": {
      "D": "range",
      "alpha": 0,
      "beta": 1,
      "factors": {
        "african_american": [
          "Yes (including mixed)",
          "No"
        ],
        "crime_violence_screener_count": [
          "Low",
          "Moderate (1-2)",
          "High (3-5)"
        ],
        "electronic_monitoring": [
          "Yes",
          "Other"
        ],
        "hispanic_descent": [
          "Yes",
          "Other"
        ],
        "incarceration_days": [
          "Low (0-12)",
          "Moderate (13-90)",
          "High (91+)"
        ],
        "local_site": [
          "11-Cook County – Chicago",
          "30-Dupage County",
          "40-Grundy County",
          "50-Mclean County",
          "60-Tazewell County",
          "70-Will County"
        ],
        "prior_opioid_overdose": [
          "Yes",
          "No"
        ],
        "prior_substance_use_treatment": [
          "Any MOUD treatment",
          "Any other SUD treatment",
          "Other"
        ],
        "probation_parole_community_supervision": [
          "Yes (1+ days)",
          "Other"
        ],
        "sex": [
          "Male",
          "Female"
        ],
        "substance_screener_symptoms": [
          "Low",
          "Moderate (1-2)",
          "High (3-5)"
        ],
        "substance_use_days": [
          "Low (0-12)",
          "Moderate (13-44)",
          "High"
        ],
        "young_adult": [
          "Yes (18-25)",
          "Other (26 or older)"
        ]
      },
      "starting_seed": 100,
      "treatments": [
        "MART",
        "RMC-Q",
        "RMC-A"
      ],
      "urn_selection": "method1",
      "w": 1
    },
    "status": 200
  }

Query Parameters:

api_key – API Key
study – study name

Response Headers:

Content-Type – application/json

Status Codes:

200 OK – participnts found for study
400 Bad Request – Invalid request
401 Unauthorized – Unauthorized access
404 Not Found – Study not found

Return:

(status Status code, message Status message/ error info, results Study configuration)

Rtype:

(str, str, dict)

GET /study_participants¶

Return list of study participants with their factor levels and treatment assignments

Example request:

GET /study_participants HTTP/1.1
Host: https://rcg.bsd.uchicago.edu/urand

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
    "message":"Success",
    "results":[
        {
            "bg_state":{
                "bit_generator":"PCG64",
                "has_uint32":1,
                "state":{
                    "inc":30008503642980956324491363429807189605,
                    "state":164404244729103591598495580972637239091
                },
                "uinteger":3586218795
            },
            "datetime":"Wed, 10 Feb 2021 00:01:08 GMT",
            "f_african_american":"Yes (including mixed)",
            "f_crime_violence_screener_count":"Low",
            "f_electronic_monitoring":"Yes",
            "f_hispanic_descent":"Other",
            "f_incarceration_days":"Moderate (13-90)",
            "f_local_site":"40-Grundy County",
            "f_prior_opioid_overdose":"Yes",
            "f_prior_substance_use_treatment":"Any other SUD treatment",
            "f_probation_parole_community_supervision":"Other",
            "f_sex":"Male",
            "f_substance_screener_symptoms":"High (3-5)",
            "f_substance_use_days":"High",
            "f_young_adult":"Other (26 or older)",
            "id":"0",
            "trt":"RMC-Q",
            "user":"dummy"
        },
        {
            "bg_state":{
                "bit_generator":"PCG64",
                "has_uint32":0,
                "state":{
                    "inc":30008503642980956324491363429807189605,
                    "state":175296851311552035585228848780835049764
                },
                "uinteger":3586218795
            },
            "datetime":"Wed, 10 Feb 2021 00:01:08 GMT",
            "f_african_american":"No",
            "f_crime_violence_screener_count":"Moderate (1-2)",
            "f_electronic_monitoring":"Yes",
            "f_hispanic_descent":"Yes",
            "f_incarceration_days":"Low (0-12)",
            "f_local_site":"70-Will County",
            "f_prior_opioid_overdose":"Yes",
            "f_prior_substance_use_treatment":"Any other SUD treatment",
            "f_probation_parole_community_supervision":"Other",
            "f_sex":"Male",
            "f_substance_screener_symptoms":"Moderate (1-2)",
            "f_substance_use_days":"Moderate (13-44)",
            "f_young_adult":"Yes (18-25)",
            "id":"1",
            "trt":"MART",
            "user":"dummy"
        }
    ],
    "status":200
}

Query Parameters:

api_key – API Key
study – study name
id – participant id
factor – Factor value. All study factor levels should be passed

Response Headers:

Content-Type – application/json

Status Codes:

200 OK – participnts found for study
400 Bad Request – Invalid request
401 Unauthorized – Unauthorized access
404 Not Found – Study not found

Return:

(status Status code, message Status message/ error info, List of participants)

Rtype:

(str, str, list)

POST /study_participants¶

Randomize a new participant

Example request:

POST /study_participants HTTP/1.1
Host: https://rcg.bsd.uchicago.edu/urand

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
   "message":"Success",
   "results":[
      {
         "bg_state":{
            "bit_generator":"PCG64",
            "has_uint32":1,
            "state":{
               "inc":30008503642980956324491363429807189605,
               "state":164404244729103591598495580972637239091
            },
            "uinteger":3586218795
         },
         "datetime":"Wed, 10 Feb 2021 00:01:08 GMT",
         "f_african_american":"Yes (including mixed)",
         "f_crime_violence_screener_count":"Low",
         "f_electronic_monitoring":"Yes",
         "f_hispanic_descent":"Other",
         "f_incarceration_days":"Moderate (13-90)",
         "f_local_site":"40-Grundy County",
         "f_prior_opioid_overdose":"Yes",
         "f_prior_substance_use_treatment":"Any other SUD treatment",
         "f_probation_parole_community_supervision":"Other",
         "f_sex":"Male",
         "f_substance_screener_symptoms":"High (3-5)",
         "f_substance_use_days":"High",
         "f_young_adult":"Other (26 or older)",
         "id":"0",
         "trt":"RMC-Q",
         "user":"dummy"
      },
      {
         "bg_state":{
            "bit_generator":"PCG64",
            "has_uint32":0,
            "state":{
               "inc":30008503642980956324491363429807189605,
               "state":175296851311552035585228848780835049764
            },
            "uinteger":3586218795
         },
         "datetime":"Wed, 10 Feb 2021 00:01:08 GMT",
         "f_african_american":"No",
         "f_crime_violence_screener_count":"Moderate (1-2)",
         "f_electronic_monitoring":"Yes",
         "f_hispanic_descent":"Yes",
         "f_incarceration_days":"Low (0-12)",
         "f_local_site":"70-Will County",
         "f_prior_opioid_overdose":"Yes",
         "f_prior_substance_use_treatment":"Any other SUD treatment",
         "f_probation_parole_community_supervision":"Other",
         "f_sex":"Male",
         "f_substance_screener_symptoms":"Moderate (1-2)",
         "f_substance_use_days":"Moderate (13-44)",
         "f_young_adult":"Yes (18-25)",
         "id":"1",
         "trt":"MART",
         "user":"dummy"
      }
   ],
   "status":200
}

Query Parameters:

api_key – API Key
study – study name
id – participant id
factor – Factor value. All study factor levels should be passed

Response Headers:

Content-Type – application/json

Status Codes:

200 OK – participnts found for study
400 Bad Request – Invalid request
401 Unauthorized – Unauthorized access
404 Not Found – Study not found

Return:

(status Status code, message Status message/ error info, results Participant info)

Rtype:

(str, str, dict)

Examples¶

Get Study Configuration¶

curl -s "http://localhost:5000/study_config?\
api_key=YOUR_KEY&study=My+Study" | python -m json.tool

Response:

{
  "message": "Success",
  "results": {
    "factors": {
      "age_group": ["18-40", "41-65", "65+"],
      "sex": ["Male", "Female"]
    },
    "treatments": ["Treatment A", "Treatment B"],
    "D": "chisquare",
    "alpha": 0,
    "beta": 1,
    "w": 1
  },
  "status": 200
}

List Participants¶

curl -s "http://localhost:5000/study_participants?\
api_key=YOUR_KEY&study=My+Study" | python -m json.tool

Randomize a Participant¶

curl -X POST "http://localhost:5000/study_participants?\
api_key=YOUR_KEY&study=My+Study&id=P026&age_group=18-40&sex=Female&\
disease_severity=Mild&prior_treatment=No"

Response:

{
  "message": "Success",
  "results": [{
    "id": "P026",
    "f_age_group": "18-40",
    "f_sex": "Female",
    "f_disease_severity": "Mild",
    "f_prior_treatment": "No",
    "trt": "Treatment A",
    "datetime": "2025-09-15 14:30:00",
    "user": "alice"
  }],
  "status": 200
}

Error Handling¶

All endpoints return a JSON object with message, results, and status fields. Common error codes:

Code	Meaning
`400`	Missing required parameters or invalid factor values.
`401`	Invalid or missing API key.
`404`	Study name not found in configuration.