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/2/invoke
holdDraw:
entryTypeidenticalEntriesPermittedwinnerHandlingwinnerStartshowEntriesshowWinnersrecordType 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.entryTypewinnerHandlingwinnerStartshowEntriesshowWinnersownerTimeZonelistDraws:
entryTypewinnerHandlingwinnerStartshowEntriesshowWinnersownerTimeZoneholdDraw
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:
credentialstitletitle must be in the [1,192] range.
recordTypepublic), 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.
entriesentriesDigestentries 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:
drawIdnull for
drawings of type "test".
statuscompleted, 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.
entryCountwinnerswinnerStart 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.
completionTimerecordUrlrecordType 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 3000000)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:
drawIdtitlerecordTypepublic, 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.
entryTypeopaque and email. Future values will include
twitterUser and facebookUser.
winnerStartholdDraw method for further details.
winnerHandlingreplace, remove and exclude. Please see the description for the holdDraw method for further details.
showEntriestrue) 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.
showWinnerstrue) 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.
statuscompleted
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.
ownerIdownerNameownerTimeZonecompletionTime in that time zone, if desired.
drawNumberdrawNumber for the first drawing held with a given account is 1, the drawNumber of the
second is 2, and so on and so forth.
entryCountnull if showEntries was set to false when the drawing was held, except if the credentials supplied are those of the drawing's owner.
entriesnull 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.
winnerCountnull if showWinners was
set to false when the drawing was held, except if the credentials supplied are those of the drawing's owner.
winnersentries 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.
completionTimerecordUrlrecordType 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:
drawIdtitlerecordTypepublic, 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.
entryTypeopaque and email. Future values will include
twitterUser and facebookUser.
winnerStartholdDraw method for further details.
winnerHandlingreplace, remove and exclude. Please see the description for the holdDraw method for further details.
showEntriestrue) 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.
showWinnerstrue) 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.
statuscompleted
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.
ownerIdownerNameownerTimeZonecompletionTime in that time zone, if desired.
drawNumberdrawNumber for the first drawing held with a given account is 1, the drawNumber of the
second is 2, and so on and so forth.
entryCountnull if showEntries was set to false when the drawing was held, except if the credentials supplied are those of the drawing's owner.
winnerCountnull if showWinners was
set to false when the drawing was held, except if the credentials supplied are those of the drawing's owner.
completionTimerecordUrlrecordType 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.