General API Info
Supported Methods
Arms
Data Access Groups
Events
Field Names
Files
File Repository
Instruments
Logging
Metadata
Projects
Records
Repeating Instruments and Events
Reports
REDCap
Surveys
Users & User Privileges
User Roles
REDCap API Documentation
Method Name
Randomize Record
Description
This method allows the current API user to randomize a record.
URL
Supported Request Method
Permissions Required
To use this method you must have the Randomize privilege in the project.
Parameters (case sensitive)
Required
token
The API token specific to your REDCap project and username (each token is unique to each user for each project). See the section on the left-hand menu for obtaining a token for a given project.
The API token specific to your REDCap project and username (each token is unique to each user for each project). See the section on the left-hand menu for obtaining a token for a given project.
content
record
record
action
randomize
randomize
record
The record name (id) of the record to randomize. The record must already exist and contain all necessary stratification information.
The record name (id) of the record to randomize. The record must already exist and contain all necessary stratification information.
randomization_id
The unique id of the randomization (viewable on the Randomization page for users with Design permissions, or on the API Playground page). Corresponds to a specific target field and event.
The unique id of the randomization (viewable on the Randomization page for users with Design permissions, or on the API Playground page). Corresponds to a specific target field and event.
format
csv, json, xml [default], odm ('odm' refers to CDISC ODM XML format, specifically ODM version 1.3.1)
csv, json, xml [default], odm ('odm' refers to CDISC ODM XML format, specifically ODM version 1.3.1)
Optional
ReturnsreturnFormat
csv, json, xml - specifies the format of error messages. If you do not pass in this flag, it will select the default format for you passed based on the 'format' flag you passed in or if no format flag was passed in, it will default to 'xml'.
csv, json, xml - specifies the format of error messages. If you do not pass in this flag, it will select the default format for you passed based on the 'format' flag you passed in or if no format flag was passed in, it will default to 'xml'.
returnAlt
false [default], true - return the value for the alternative target field, i.e. the randomization number for open allocations. Note: with concealed allocations only the value '*' will be returned, not the real allocation group (which would break the blinding).
false [default], true - return the value for the alternative target field, i.e. the randomization number for open allocations. Note: with concealed allocations only the value '*' will be returned, not the real allocation group (which would break the blinding).
Performs the specified randomization for the record and returns the value for the target randomization field (plus optionally the alternative target value), or an error message on failure (such as if the record does not exist or if stratification information is missing).
JSON Example:
{
"randomization_id": 123,
"record": "21",
"target_field": "1",
"target_field_alt": "R-1005"
}
CSV Example:
randomization_id,record,target_field,target_field_alt 123,21,1,R-1005
XML Example:
<?xml version="1.0" encoding="UTF-8" ?>
<item>
<randomization_id>123</randomization_id>
<record>21</record>
<target_field>1</target_field>
<target_field_alt>R-1005</target_field_alt>
</item>