Third-Party Draw Service API

Introduction

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.

Changes from Release 1

  • Changes to holdDraw:
    • The following new optional parameters were added:
      • entryType
      • identicalEntriesPermitted
      • winnerHandling
      • winnerStart
      • showEntries
      • showWinners
    • A possible value for the recordType parameter was changed from entrant-accessible to entrantAccessible for consistency.
    • The optional parameter winnerElimination was removed. Its function is now served by the winnerHandling parameter.
  • Changes to getDraw:
    • A new optional parameter maxEntries was added.
    • The following return values were added:
      • entryType
      • winnerHandling
      • winnerStart
      • showEntries
      • showWinners
      • ownerTimeZone
  • Changes to listDraws:
    • The following values were added to each of the objects returned:
      • 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.

Required Parameters

The following parameters are mandatory and should be specified in the params array of the JSON-RPC request:

credentials
Credentials that identify your client to RANDOM.ORG.
title
The textual description that will be associated with the drawing (e.g., ‘Prize Draw for two U2 concert tickets’). The length of the title must be in the [1,192] range.
recordType
This value determines whether the record of the drawing held by RANDOM.ORG will be viewable by anyone (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
An array containing the entries from which the winner(s) will be drawn. The number of entries must be in the [2,2000000] range.
entriesDigest
A 32-character hex-format MD5 checksum of the JSON-encoded entries array, calculated by the client. The server will calculate its own checksum and return an error if they did not match.
winnerCount
The number of winning entries requested. The value must be in the [1,50000] range.

Optional Parameters

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)
This parameter allows the client to specify what type each entry is. Possible values are 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)
This parameter is used to specify whether the 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)
This parameter specifies the ranking that the first winner picked will receive in the record. Effectively, it allows the client to number the winners from a different starting point than the default 1st winner, 2nd winner, etc. This is useful if different ranges of winners for the same campaign are being selected using several drawings, or if an additional drawing is being held to replace an ineligible winner from a previous drawing.
winnerHandling (default value remove)
If the drawing has a 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)
This value specifies whether the record of the drawing should show the number of entries (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)
This value only has effect for drawings where the 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)
A UUID that indicates that the caller is acting on behalf of another party. The delegationKey indicates who that other party is.

Successful Response

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
The numeric ID for the drawing assigned by RANDOM.ORG. This value is null for drawings of type "test".
status
Possible values are 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
The number of entries counted by RANDOM.ORG.
winners
A JSON array with the winning entries ordered by winner number. The client should consider the first element the first winner, the second element the second winner, and so on; subject to the value given for the 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
An ISO 8601 time stamp indicating the time at which the drawing was completed.
recordUrl
The URL at which the official record of the drawing can be found. If the drawing's 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.

Error Response

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.

Example 1

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.

Example 2

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.

Example 3

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.

Required Parameters

The following parameters are mandatory and should be specified in the params array of the JSON-RPC request:

drawId
The numeric ID for the drawing assigned by RANDOM.ORG.

Optional Parameters

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 2000000)
A cap on the number of entries that the client wishes to have included in the response. The response's entries array will contain no more than maxEntries values. Any entries returned will be the first in the entry list.
credentials (default value null)
Credentials that identify your client to RANDOM.ORG.
delegationKey (default value null)
A UUID that indicates that the caller is a delegate acting on behalf of another party. The 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.)

Successful Response

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
The numeric ID for the drawing assigned by RANDOM.ORG.
title
The textual description associated with the drawing (e.g., ‘Prize Draw for two U2 concert tickets’).
recordType
A string with three possible values: 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
A string describing the type of the entries. Possible values are opaque and email. Future values will include twitterUser and facebookUser.
winnerStart
A numeric value that indicates the ranking of the first winner picked as displayed in the record. Please see the description for the holdDraw method for further details.
winnerHandling
A value that indicates how the winners for the drawing were selected. Possible values are replace, remove and exclude. Please see the description for the holdDraw method for further details.
showEntries
A boolean value that indicates whether the record of the drawing shows the entries (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
A boolean value that indicates whether the record of the drawing shows the number of winners (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
This value indicates the status of the drawing. Possible values are 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
The numeric ID associated with the RANDOM.ORG account that held the drawing.
ownerName
The name associated with the RANDOM.ORG account that held the drawing (e.g., ‘Gorgeous Flowers LLC’).
ownerTimeZone
The time zone currently associated with the owner's account. This allows the client to display the completionTime in that time zone, if desired.
drawNumber
The serial number of the drawing within the owner's account. The 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
The number of entries in the drawing as counted by RANDOM.ORG. This value will be 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
The list of entries. This will be 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
The number of winning entries selected by RANDOM.ORG. This value will be 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
An array with the winning entries ordered by winning number (1st winner, 2nd winner, etc.). It is subject to the same access constraints as the 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
An ISO 8601 time stamp indicating the time at which the drawing was completed.
recordUrl
The URL at which the official record of the drawing can be found. If the drawing's recordType is private, the client must be logged in to view the record.

For a successful response, the error property is null.

Error Response

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.

Example 1

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.

Required Parameters

The following parameters are mandatory and should be specified in the params array of the JSON-RPC request:

credentials
Credentials that identify your client to RANDOM.ORG.

Optional Parameters

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)
A UUID that indicates that the caller is acting on behalf of another party. The delegationKey indicates who that other party is.

Successful Response

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
The numeric ID for the drawing assigned by RANDOM.ORG.
title
The textual description that will be associated with the drawing (e.g., ‘Prize Draw for two U2 concert tickets’).
recordType
A string with three possible values: 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
A string describing the type of the entries. Possible values are opaque and email. Future values will include twitterUser and facebookUser.
winnerStart
A numeric value that indicates the ranking of the first winner picked as displayed in the record. Please see the description for the holdDraw method for further details.
winnerHandling
A value that indicates how the winners for the drawing were selected. Possible values are replace, remove and exclude. Please see the description for the holdDraw method for further details.
showEntries
A boolean value that indicates whether the record of the drawing shows the entries (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
A boolean value that indicates whether the record of the drawing shows the number of winners (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
This value indicates the status of the drawing. Possible values are 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
The numeric ID associated with the RANDOM.ORG account that held the drawing.
ownerName
The name associated with the RANDOM.ORG account that held the drawing (e.g., ‘Gorgeous Flowers LLC’).
ownerTimeZone
The time zone currently associated with the owner's account. This allows the client to display the completionTime in that time zone, if desired.
drawNumber
The serial number of the drawing within the owner's account. The 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
The number of entries in the drawing as counted by RANDOM.ORG. This value will be 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
The number of winning entries selected by RANDOM.ORG. This value will be 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
An ISO 8601 time stamp indicating the time at which the drawing was completed.
recordUrl
The URL at which the official record of the drawing can be found. If the drawing's recordType is private, the client must be logged in to view the record.

For a successful response, the error property is null.

Error Response

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.

Example 1

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.