The Third-Party Draw Service allows clients to hold ‘drawings’ (US English) or ‘draws’ (UK, Irish and Australian English) in which a number of winners are selected from a pool of entries.
In the following, the term ‘entrant’ refers to an individual participating in a random drawing. Each entrant has an ‘entrant identifier,’ which uniquely identifies him or her, such as a customer number, ticket number or email address. It is important that the identifiers are unique to each entrant, and the service is intended to help ensure this.
When a drawing is to be held, the client constructs a list of ‘entries’ from the entrant identifiers and uses the Third-Party Draw Service to select the winning entries. All entries in a drawing have exactly the same chance of getting selected as winner. It is possible to give an entrant multiple chances to win by listing their entrant identifier multiple times. An entrant with multiple entries will have as many chances of winning as they have entries.
The methods described here are sufficient to hold new drawings and to manage drawings that have already been completed. For documentation about each method, click or tap on the method names in the tab near the top of the page.
The URL for invoking the Third-Party Draw Service API is: https://api.random.org/json-rpc/4/invoke
holdDraw
:
entryType
identicalEntriesPermitted
winnerHandling
winnerStart
showEntries
showWinners
recordType
parameter was changed from entrant-accessible
to entrantAccessible
for consistency.
winnerElimination
was removed. Its function is now served by the winnerHandling
parameter.
getDraw
:
maxEntries
was added.entryType
winnerHandling
winnerStart
showEntries
showWinners
ownerTimeZone
listDraws
:
entryType
winnerHandling
winnerStart
showEntries
showWinners
ownerTimeZone
holdDraw
This method holds a drawing in one single
operation. All information required for the
drawing is passed as parameters. For this
reason, the client must have collected all the entries from which
the winner(s) will be selected before the method is invoked. Once
the invocation is made, it is not possible to add entries or to
delete or modify the drawing. Your client must
set the method
property of its JSON-RPC request
object to holdDraw
.
The following parameters are mandatory and should be specified
in the params
array of the JSON-RPC request:
credentials
title
title
must be in the [1,192] range.
recordType
public
), only to the owner of the drawing (private
) or whether the record will
allow identifer-based lookups
(entrantAccessible
). If the value for
recordType
is set to test
, no record
of the result is generated and no charge is made for the drawing. Drawings of type test
are mainly useful for development
purposes. Please see the FAQ
for further details.
entries
entriesDigest
entries
array, calculated
by the client. The server will calculate its own
checksum and return an error if they did not match.
To generate the checksum on the client side, you
will need to serialize the entries
array to a string
and then calculate the MD5 hash of the string.
The serialization should be done without using whitespace for formatting.
winnerCount
The following parameters are optional and can be included in
the params
object of your JSON-RPC request if you
want functionality that is different from the default:
entryType
(default value opaque
)opaque
and
email
. Future values will include
twitterUser
and facebookUser
. If the
value opaque
is given, no special behaviour is
performed by the drawing's record in regard to
entry lookup or presentation. This is the correct value for ticket numbers,
customer numbers, etc.identicalEntriesPermitted
(default value false
)entries
array
is allowed to contain identical identifiers.
If identicalEntriesPermitted
is set
to false
, RANDOM.ORG will check
the entries
array for duplicates and return an
error response in case duplicates are found.
winnerStart
(default value 1
)winnerHandling
(default value remove
)winnerCount
value that is greater than 1, then winnerHandling
controls how those winners are selected. If
winnerHandling
is set to replace
, an
entry which has been selected as winner is inserted back (i.e.,
replaced) into
the pool of elegible entries and can hence be selected as winner
again. If winnerHandling
is
set to remove
, the winning entry is removed from
the pool of legible entries; however, if the entry appeared
multiple times in the entries
array (and
identicalEntriesPermitted
is set to true
), those other
entries still remain in the pool of elegible entries and can be selected as winner in subsequent
selections. If winnerHandling
is set to
exclude
, all occurrences of the winning entry are
eliminated from the pool of elegible entries, essentially allowing each
winner to win only once, regardless of the
number of times the corresponding entry occurred in the entries
array.
If the drawing has a
winnerCount
value of 1, then
winnerHandling
has no effect.
showEntries
(default value true
)true
) or not (false
).
For drawings where the recordType
is public
, a showEntries
value of true
will
create a record that shows the number of entries as well as
the entire list of entries, whereas a value of false
will
create a record that shows neither of these fields. (In both
cases, the record will show the number of winners as well as the
actual winning identifiers.) For drawings where the recordType
is entrantAccessible
, a showEntries
value of true
will create a record that shows the number of entries and
allows that entry list to be queried as is normal behaviour for
entrantAccessible
drawings,
whereas a value of false
will not show the number
of entries but will still allow the entry list to be queried.
The showEntries
value has no effect for drawings where the recordType
is private
.
showWinners
(default value true
)recordType
is entrantAccessible
.
For those drawings, the parameter specifies whether the record of the drawing
should show the number of winners (true
) or not (false
).
The parameter also affects how the record of the drawing will behave.
For a drawing where showWinners
was set
to true
when the drawing was held,
the record will show the winning rank for entries
when queried (e.g., ‘The entry had 6
chances and was picked as 2nd winner’). For a
drawing where showWinners
was set to
false
, the record will show whether an
entry was picked as winner but not show the
rank (e.g., ‘The entry had 6 chances
and was picked as a winner’).
delegationKey
(default value null
)delegationKey
indicates who that
other party is.
If the drawing was held successfully,
RANDOM.ORG returns a JSON-RPC response with the
result
property containing an object with the following
named values:
drawId
null
for
drawings of type "test".
status
completed
, withheld
and test
. The
value indicates the status of the drawing. If there was
sufficient credit in the client's account, the status will be
completed
. It may be withheld
if insufficient credit was
available in the client's account in which the account must be
topped up for the result to be revealed. For drawings of type
test
, this value is test
.
entryCount
winners
winnerStart
parameter
in the request. The value for winners
is null
if the drawing's status is withheld
,
meaning that the winning entries have been picked but that the client
must add credit to their account to reveal the result.
completionTime
recordUrl
recordType
is private
, the client must be logged in
to view the record. This value is null
for drawings of type
test
.
For a successful response, the error
property is
null
.
If an error occurred, RANDOM.ORG returns a
JSON-RPC response in which the result
property is
null
and the error
property contains an
error object as described in Error Codes and Messages.
The following requests a drawing to be held in which three entries appear and one winner is selected amongst them. The client presents a login/password combination as its credentials in order for RANDOM.ORG to authenticate it. The client requests the resulting record of the RANDOM.ORG to be public, which means that anyone will be able to review the full details from the RANDOM.ORG site. We assume the client has enough prepaid credit in their account to cover the cost of the drawing.
{ "jsonrpc": "2.0", "method": "holdDraw", "params": { "credentials": { "login": "test", "password": "secret" }, "title": "My Grand Prize Draw", "recordType": "public", "entries": ["foo","bar","baz"], "entriesDigest": "a8cd76db952b9803be9163ead5dc4a2d", "winnerCount": 1 }, "id": 42 }
The service responds with the following:
{ "jsonrpc": "2.0", "result": { "drawId": 22993, "status": "completed", "entryCount": 3, "winners": ["bar"], "completionTime": "2011-10-10 13:19:12Z", "recordUrl": "https://draws.random.org/records/22993" }, "error": null, "id": 42 }
The drawId
returned is the numeric identifier of the
drawing allocated by RANDOM.ORG.
The value of the status
field tells the client that
the drawing completed successfully
and entryCount
gives the total number entries found
by RANDOM.ORG in the entries
array
supplied by the client. The client's account will have been
billed for the cost of the RANDOM.ORG.
The winners
array contains the single winner that the
client requested. RANDOM.ORG also returns the
exact time at which the drawing was completed
as well as a URL to the record of the drawing.
Since the client requested the recordType
to
be public
, the web address returned in
the recordUrl
can be viewed by anyone.
As in Example 1, the following requests a drawing to be held in which three entries appear and one winner is selected amongst them. However, in this example, the cost of the drawing exceeds the amount of credit in the client's account. The request is identical to that of the previous example:
{ "jsonrpc": "2.0", "method": "holdDraw", "params": { "credentials": { "login": "test", "password": "secret" }, "title": "My Grand Prize Draw", "recordType": "public", "entries": ["foo","bar","baz"], "entriesDigest": "a8cd76db952b9803be9163ead5dc4a2d", "winnerCount": 1 }, "id": 42 }
The service responds with the following:
{ "jsonrpc": "2.0", "result": { "drawId": 22993, "status": "withheld", "entryCount": 3, "winners": null, "completionTime": "2011-10-10 13:19:12Z", "recordUrl": "https://draws.random.org/records/22993" }, "error": null, "id": 42 }
The drawId
returned is the numeric identifier of the
drawing allocated by RANDOM.ORG.
The value of the status
field tells the client that
the drawing completed successfully but that the
result is withheld, because the client's credit balance is now in
the red. The client must now add sufficient credit to their
account in in order to bring its balance up to at least $0.00.
Adding the credit will automatically clear the drawing from
its withheld state. As in the previous
example, entryCount
gives the total number entries
found by RANDOM.ORG in the entries
array supplied by the client. Because the result of the
drawing is withheld, the value returned
for winners
is null
.
RANDOM.ORG also returns the exact time at which the
drawing was completed as well as a URL to the
record of the drawing. Since the client
requested the recordType
to be public
,
the web address returned in the recordUrl
can be
viewed by anyone, but until the client brings its credit balance
into the black, the record of the drawing will
show that the result is withheld.
As in Example 2, the following requests a drawing to be held in which three entries appear and one winner is selected amongst them. However, in this example, the client's credit balance is negative. The request is identical to that of the previous example:
{ "jsonrpc": "2.0", "method": "holdDraw", "params": { "credentials": { "login": "test", "password": "secret" }, "title": "My Grand Prize Draw", "recordType": "public", "entries": ["foo","bar","baz"], "entriesDigest": "a8cd76db952b9803be9163ead5dc4a2d", "winnerCount": 1 }, "id": 42 }
The service responds with the following:
{ "jsonrpc": "2.0", "error": { "code": 601, "message": "Your credit balance is negative; please add at least $12.65", "data": [ 12.65 ] }, "id": 42 }
In this case, the drawing is not held. Instead, the response tells the client that it must top up its credit balance by a minimum amount before it can retry the drawing.
getDraw
This method allows a client to obtain information about a
completed drawing, subject to access control of
the drawing's privacy settings. Your client
must set the method
property of its JSON-RPC request
object to getDraw
.
The following parameters are mandatory and should be specified
in the params
array of the JSON-RPC request:
drawId
The following parameters are optional and can be included in
the params
object of your JSON-RPC request if you
want functionality that is different from the default:
maxEntries
(default value 4000000
)entries
array will contain
no more than maxEntries
values. Any
entries returned will be the first in the entry
list.
credentials
(default value null
)delegationKey
(default value null
)delegationKey
indicates who that other party is.
If the caller includes a different value from null
for the delegationKey
in the request, it must also
include its own credentials
. (The delegator's credentials are not required.)
If the drawing completed successfully,
RANDOM.ORG returns a JSON-RPC response with the
result
property containing an object with the following
named values:
drawId
title
recordType
public
, entrantAccessible
and
private
. The value determines whether the record of the
drawing held by RANDOM.ORG will be viewable by anyone
(public
), just the owner of the drawing (private
) or whether it
allows identifer-based lookups (entrantAccessible
). Please see the FAQ
for further details.
entryType
opaque
and email
. Future values will include
twitterUser
and facebookUser
.
winnerStart
holdDraw
method for further details.
winnerHandling
replace
, remove
and exclude
. Please see the description for the holdDraw
method for further details.
showEntries
true
) or not (false
). The amount of information shown depends on the drawing's recordType
. Please see the description for the holdDraw
method for further details.
showWinners
true
) or not (false
).
The value is only meaningful for drawings with a
recordType
that is entrantAccessible
.
Please see the description for the holdDraw
method for further details.
status
completed
and withheld
. If there was sufficient
credit in the client's account when the drawing was
held, the value of status
will be
completed
. If insufficient credit was
available in the client's account when the drawing
was held, the value of status
will be
withheld
in which case the account must
be topped up for the result to be revealed.
ownerId
ownerName
ownerTimeZone
completionTime
in that time zone, if desired.
drawNumber
drawNumber
for the first drawing held with a given account is 1
, the drawNumber
of the
second is 2
, and so on and so forth.
entryCount
null
if showEntries
was set to false
when the drawing was held, except if the credentials
supplied are those of the drawing's owner.
entries
null
unless
the client authenticates itself (using
the credentials
parameter) as the owner of the
drawing or as a delegate acting on the
owner's behalf; or unless the drawing is
public and was held with a showEntries
value of true
. A maximum of maxEntries
(from the request) entries are returned.
winnerCount
null
if showWinners
was
set to false
when the drawing was held, except if the credentials
supplied are those of the drawing's owner.
winners
entries
array. The value of
winners
will be null
if the
drawing's status is withheld
,
meaning that the winners have been picked but that the drawing's owner
must add credit to their account to reveal the result.
completionTime
recordUrl
recordType
is private
, the client must be logged in
to view the record.
For a successful response, the error
property is
null
.
If an error occurred, RANDOM.ORG returns a
JSON-RPC response in which the result
property is
null
and the error
property contains an
error object as described in Error Codes and Messages.
The following requests the recorded detail about a drawing previously held. The client presents a login/password combination as its credentials in order for RANDOM.ORG to authenticate it.
{ "jsonrpc": "2.0", "method": "getDraw", "params": { "credentials": { "login": "test", "password": "secret" }, "drawId": 22993 }, "id": 42 }
The service responds with the following:
{ "jsonrpc": "2.0", "result": { "drawId": 22993, "title": "My Grand Prize Draw", "recordType": "public", "winnerHandling": "remove", "winnerStart": 1, "showEntries": true, "showWinners": true, "status": "completed", "ownerId": 3, "ownerName": "My Company LLC", "drawNumber": 1, "entryCount": 3, "entries": ["foo","bar","baz"], "winnerCount": 1, "winners": ["bar"], "completionTime": "2011-10-10 13:19:12Z", "recordUrl": "https://draws.random.org/records/22993" }, "error": null, "id": 42 }
The drawId
returned is the numeric identifier of
the drawing allocated by RANDOM.ORG.
The value of the status
field tells the client
that the drawing is complete
and entryCount
gives the total number entries in it.
The entries
array contains the actual entries from
which the winners were drawn. The winners
array
contains the actual winning entries and winnerCount
tells how many there are. RANDOM.ORG also returns
the exact time at which the drawing was
completed as well as a URL to the record of the
drawing.
listDraws
This method lets a RANDOM.ORG account holder list all the drawings in their account. Your client must
set the method
property of its JSON-RPC request
object to listDraws
.
Note that listDraws
returns a lot of
details for each drawing in the relevant account, but
the details do not include the entry and winner lists
for the drawings. To obtain the winner and entry lists,
the client should use
getDraw
.
The following parameters are mandatory and should be specified
in the params
array of the JSON-RPC request:
credentials
The following parameters are optional and can be included in
the params
object of your JSON-RPC request if you
want functionality that is different from the default:
delegationKey
(default value null
)delegationKey
indicates who that
other party is.
If the drawing was held successfully,
RANDOM.ORG returns a JSON-RPC response with the
result
property containing an array of objects, one for each drawing that the account in question owns. Each object contains the following
named values:
drawId
title
recordType
public
, entrantAccessible
and
private
. The value determines whether the record of the
drawing held by RANDOM.ORG will be viewable by anyone
(public
), just the owner of the drawing (private
) or whether it
allows identifer-based lookups (entrantAccessible
). Please see the FAQ
for further details.
entryType
opaque
and email
. Future values will include
twitterUser
and facebookUser
.
winnerStart
holdDraw
method for further details.
winnerHandling
replace
, remove
and exclude
. Please see the description for the holdDraw
method for further details.
showEntries
true
) or not (false
). The amount of information shown depends on the drawing's recordType
. Please see the description for the holdDraw
method for further details.
showWinners
true
) or not (false
).
The value is only meaningful for drawings with a
recordType
that is entrantAccessible
.
Please see the description for the holdDraw
method for further details.
status
completed
and withheld
. If there was sufficient
credit in the client's account when the drawing was
held, the value of status
will be
completed
. If insufficient credit was
available in the client's account when the drawing
was held, the value of status
will be
withheld
in which case the account must
be topped up for the result to be revealed.
ownerId
ownerName
ownerTimeZone
completionTime
in that time zone, if desired.
drawNumber
drawNumber
for the first drawing held with a given account is 1
, the drawNumber
of the
second is 2
, and so on and so forth.
entryCount
null
if showEntries
was set to false
when the drawing was held, except if the credentials
supplied are those of the drawing's owner.
winnerCount
null
if showWinners
was
set to false
when the drawing was held, except if the credentials
supplied are those of the drawing's owner.
completionTime
recordUrl
recordType
is private
, the client must be logged in
to view the record.
For a successful response, the error
property is
null
.
If an error occurred, RANDOM.ORG returns a
JSON-RPC response in which the result
property is
null
and the error
property contains an
error object as described in Error Codes and Messages.
The following requests a list of drawings held with a given account. The client presents a login/password combination as its credentials in order for RANDOM.ORG to authenticate it.
{ "jsonrpc": "2.0", "method": "listDraws", "params": { "credentials": { "login": "random", "password": "secret" } }, "id": 42 }
The service responds with the following:
{ "jsonrpc": "2.0", "result": [ { "drawId": 617, "title": "iPod Shuffle Giveaway #3", "recordType": "entrantAccessible", "entryType": "opaque", "winnerHandling": "remove", "winnerStart": 1, "showEntries": true, "showWinners": true, "status": "completed", "ownerId": 1, "ownerName": "RANDOM.ORG", "ownerTimeZone": "Europe/Dublin", "drawNumber": 3, "entryCount": 379, "winnerCount": 2, "completionTime": "2009-06-03 14:12:43Z", "recordUrl": "https://draws.random.org/records/617" }, { "drawId": 584, "title": "iPod Shuffle Giveaway #2", "recordType": "entrantAccessible", "entryType": "opaque", "winnerHandling": "remove", "winnerStart": 1, "showEntries": true, "showWinners": true, "status": "completed", "ownerId": 1, "ownerName": "RANDOM.ORG", "ownerTimeZone": "Europe/Dublin", "drawNumber": 2, "entryCount": 248, "winnerCount": 2, "completionTime": "2009-05-17 20:22:41Z", "recordUrl": "https://draws.random.org/records/584" }, { "drawId": 567, "title": "iPod Shuffle Giveaway #1", "recordType": "entrantAccessible", "entryType": "opaque", "winnerHandling": "remove", "winnerStart": 1, "showEntries": true, "showWinners": true, "status": "completed", "ownerId": 1, "ownerName": "RANDOM.ORG", "ownerTimeZone": "Europe/Dublin", "drawNumber": 1, "entryCount": 96, "winnerCount": 1, "completionTime": "2009-05-10 20:47:00Z", "recordUrl": "https://draws.random.org/records/567" } ], "id": 42 }
The method returns an array that contains an element
for each drawing that has been held with the account.
Each element contains values that describe the
drawing. For full details about each value, please
see the documentation for getDraw
. Note
that the values returned by listDraws
do
not contain the actual entry lists or winner lists.