Multi-Round Giveaway Service API (Release 3)

  1. RANDOM.ORG
  2. API
  3. JSON-RPC
  4. Release 3
  5. Giveaway Service API

Introduction

This API gives clients access to RANDOM.ORG's Multi-Round Giveaway Service. Ideally suited to video streaming in real-time, the service randomizes your list of up to 3,000 participants in up to 30 rounds. The client first creates the giveaway and then runs the rounds one at a time. In the final round, the service generates a verification code, valid for one month, which proves your giveaway wasn't rigged.

Note: Use of this API is currently by invitation only. If you're interested in using it, please get in touch.

URL

The URL for invoking the Multi-Round Giveaway Service API is https://giveaways.random.org/api/json-rpc/2/invoke

beginGiveaway (method)

This method creates a new giveaway but does not yet run the rounds. Your client must set the method property of its JSON-RPC request object to beginGiveaway. The request must also contain an id member, which will be returned in the response.

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. For more information, please see the Authentication API.
description
The textual title that will be associated with the giveaway (e.g., ‘1954 Bowman Gum baseball card of Vern Bickford’). The length of the description must be in the [1,192] range.
entries
An array containing the entries to be randomized. The number of entries must be in the [2,3000] 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.
rounds
How many rounds there will be in this giveaway. The number of rounds must be in the [2,30] range. After it has been created, the giveaway will not be considered completed until the client has invoked the continueGiveaway method for all the rounds.

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 giveaway was created successfully, RANDOM.ORG returns a JSON-RPC response with the result property containing an object with the following named values:

giveawayKey
An alphanumeric verification code that identifies your giveaway. You can publish this to users, such that they can use it to verify the giveaway result. You can also compute the URL for your giveaway's verification page as follows: https://giveaways.random.org/verify/giveawayKey
ownerId
A numeric user ID that identifies the owner of the giveaway.
description
The textual description of the giveaway. This will be identical to the value supplied in the description parameter.
entries
The list of entries in this giveaway. This will be identical to the value supplied in the entries parameter.
rounds
The total number of rounds in this giveaway. This will be identical to the value supplied in the rounds parameter.
roundsHeld
The result of the rounds held so far, represented as an array of arrays with indices into the entries array. The first array contains the result of the first round, the second array of the second round, and so forth. If not all rounds have been run yet, the length of the roundsHeld array will be less than rounds.
created
A UTC timestamp showing the exact time at which the giveaway was created.
completed
A UTC timestamp showing the exact time at which the giveaway was completed. If the giveaway has not yet been completed (i.e., its last round has not been run yet), then the value of completed will be null.
expires
A timestamp UTC showing the exact time at which the giveaway will expire. This is normally one month after the created property.
completionTime
A timestamp UTC showing the exact time at which the request was completed by the service. The client can use it to display a timestamp.

Error Response

If an error occurred, RANDOM.ORG returns a JSON-RPC response in which the result property is absent and the error property contains an error object as described in Error Codes and Messages.

Example

The following request begins a new giveaway with four entries and three rounds. 

{
    "jsonrpc": "2.0",
    "method": "beginGiveaway",
    "params": {
        "credentials": {
            "login": "test9",
            "password": "secret"
        },
        "description": "Test Giveaway",
        "entries": ["John", "Jack", "Jill", "Jane"],
        "entriesDigest": "642370d3cf324e59a0006329085674e4",
        "rounds": 3,
        "delegationKey": null
    },
    "id": 14382
}

The service responds as follows: 

{
    "jsonrpc": "2.0",
    "result": {
        "giveawayKey": "dnabnj",
        "ownerId": 8464,
        "description": "Test Giveaway",
        "entries": ["John", "Jack", "Jill", "Jane"],
        "rounds": 3,
        "roundsHeld": [],
        "created": "2018-07-01 15:16:02Z",
        "completed": null,
        "expires": "2018-08-01 15:16:02Z",
        "completionTime": "2018-07-01 15:16:02Z"
    },
    "id": 14382
}

The result shows that the giveaway was created successfully and that it will have three rounds, but that no rounds have been run yet. (The roundsHeld array is empty.) The result also shows the exact timestamps (in UTC) at which the giveaway was created and will expire. Note that the completed property is null because the giveaway has not been completed yet, i.e., its last round has not been run.

The completionTime property indicates when the request was completed and can be used by the client for example to display a timestamp.

continueGiveaway (method)

This method runs a single round of a giveaway previously created with the beginGiveaway method. Your client must set the method property of its JSON-RPC request object to continueGiveaway. The request must also contain an id member, which will be returned in the response.

The client must invoke continueGiveaway once for each round in the giveaway. The giveaway is not considered to have been completed until the last round has been held.

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. For more information, please see the Authentication API.
giveawayKey
An alphanumeric verification code that identifies your giveaway. Must have been returned as the result of a previous request to beginGiveaway.

Optional Parameters

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 round was run successfully, RANDOM.ORG returns a JSON-RPC response with the result property containing an object with the following named values:

giveawayKey
An alphanumeric verification code that identifies your giveaway. This will be identical to the value supplied for the giveawaKey property of the request.
ownerId
A numeric user ID that identifies the owner of the giveaway.
description
The textual description of the giveaway.
entries
The list of entries in this giveaway.
rounds
The total number of rounds in this giveaway.
roundsHeld
The result of the rounds held so far, represented as an array of arrays with indices into the entries array. The first array contains the result of the first round, the second array of the second round, and so forth. If not all rounds have been held yet, the length of the roundsHeld array will be less than the value in rounds.
created
A UTC timestamp showing the exact time at which the giveaway was created.
completed
A UTC timestamp showing the exact time at which the giveaway was completed. If the giveaway has not yet been completed (i.e., its last round has not been run yet), then the value of completed will be null.
expires
A UTC timestamp showing the exact time at which the giveaway will expire.
completionTime
A UTC timestamp showing the exact time at which the request was completed by the service.

Error Response

If an error occurred, RANDOM.ORG returns a JSON-RPC response in which the result property is absent and the error property contains an error object as described in Error Codes and Messages.

Example 1

The following request runs the first round of the giveaway that was created in the example under beginGiveaway above. In our example, we issue the first call to continueGiveaway immediately after the call to beginGiveaway has returned. 

{
    "jsonrpc": "2.0",
    "method": "continueGiveaway",
    "params": {
        "credentials": {
            "login": "test9",
            "password": "secret"
        },
        "giveawayKey": "dnabnj",
        "delegationKey": null
    },
    "id": 7563
}

The service responds as follows: 

{
    "jsonrpc": "2.0",
    "result": {
        "giveawayKey": "dnabnj",
        "ownerId": 8464,
        "description": "Test Giveaway",
        "entries": ["John", "Jack", "Jill", "Jane"],
        "rounds": 3,
        "roundsHeld": [
            [3, 1, 0, 2]
        ],
        "created": "2018-07-01 15:16:02Z",
        "completed": null,
        "expires": "2018-08-01 15:16:02Z",
        "completionTime": "2018-07-01 15:16:02Z"
    },
    "id": 7563
}

The roundsHeld property now shows the result of the first round. The values are indices into the entries array. Note that the entries array is indexed from 0, so the result shows that Jane (index 3) came out first followed by Jack (index 1), followed by John (index 0) followed by Jill (index 2).

The completionTime timestamp is identical to our example for the beginGiveaway method because we issued the two calls in rapid succession.

Example 2

The following request runs the second round of our giveaway: 

{
    "jsonrpc": "2.0",
    "method": "continueGiveaway",
    "params": {
        "credentials": {
            "login": "test9",
            "password": "secret"
        },
        "giveawayKey": "dnabnj",
        "delegationKey": null
    },
    "id": 17053
}

The request is identical to the one in Example 1 above, apart from the fact that it has a different JSON-RPC request ID.

The servic responds as follows: 

{
    "jsonrpc": "2.0",
    "result": {
        "giveawayKey": "dnabnj",
        "ownerId": 8464,
        "description": "Test Giveaway",
        "entries": ["John", "Jack", "Jill", "Jane"],
        "rounds": 3,
        "roundsHeld": [
            [3, 1, 0, 2],
            [0, 1, 2, 3]
        ],
        "created": "2018-07-01 15:16:02Z",
        "completed": null,
        "expires": "2018-08-01 15:16:02Z",
        "completionTime": "2018-07-01 15:24:55Z"
    },
    "id": 17053
}

The response shows that the second round completed successfully too, and with a different result than the first. In fact, the result of the second round happens to be the same as the original order in which we supplied the entries. With a small number of entries like we have in this example, this is not unlikely to happen.

As you can see from the completionTime property, we waited just under nine minutes between the first two rounds in this giveaway. Because there is still one round to go, the completed property is still null.

Example 3

The following request runs the last round in our giveaway: 

{
    "jsonrpc": "2.0",
    "method": "continueGiveaway",
    "params": {
        "credentials": {
            "login": "test9",
            "password": "secret"
        },
        "giveawayKey": "dnabnj",
        "delegationKey": null
    },
    "id": 24892
}

As before, the request is nearly identical to the previous calls to continueGiveaway.

The service responds with the following: 

{
    "jsonrpc": "2.0",
    "result": {
        "giveawayKey": "dnabnj",
        "ownerId": 8464,
        "description": "Test Giveaway",
        "entries": ["John", "Jack", "Jill", "Jane"],
        "rounds": 3,
        "roundsHeld": [
            [3, 1, 0, 2],
            [0, 1, 2, 3],
            [1, 2, 3, 0]
        ],
        "created": "2018-07-01 15:16:02Z",
        "completed": "2018-07-01 15:24:56Z",
        "expires": "2018-08-01 15:16:02Z",
        "completionTime": "2018-07-01 15:24:56Z"
    },
    "id": 24892
}

The roundsHeld property now contains all three rounds, and the last of the rounds listed shows that Jack (index 1 into the entries array) was the winner of this giveaway, followed by Jill (index 2), Jane (index 3) and John (index 0). The completed property now shows the timestamp at which the giveaway was completed.

As for the earlier examples, the completionTime property shows when the service processed the request.

getGiveaway (method)

This method obtains the details of a giveaway. The giveaway must have been created with the beginGiveaway method and can be either in completed or not completed state. The records of giveaways are public, so no authentication is required to use this method. Your client must set the method property of its JSON-RPC request object to getGiveaway. The request must also contain an id member, which will be returned in the response.

Since all giveaway records are public, no authentication is necessary when invoking this method.

Required Parameters

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

giveawayKey
A key (i.e., verification code) that identifies the giveaway in question.

Optional Parameters

There are no optional parameters.

Successful Response

If the request completed successfully, RANDOM.ORG returns a JSON-RPC response with the result property containing an object with the following named values:

giveawayKey
An alphanumeric verification code that identifies the giveaway. This will be the same as supplied in the request.
ownerId
A numeric user ID that identifies the owner of the giveaway.
description
The textual description of the giveaway.
entries
The list of entries in this giveaway.
rounds
The total number of rounds in this giveaway.
roundsHeld
The result of the rounds held so far, represented as an array of arrays with indices into the entries array. The first array contains the result of the first round, the second array of the second round, and so forth. If not all rounds have been held yet, the length of roundsHeld will be less than rounds.
created
A UTC timestamp showing the exact time at which the giveaway was created.
completed
A UTC timestamp showing the exact time at which the giveaway was completed. If the giveaway has not yet been completed (i.e., its last round has not been run yet), then the value of completed will be null.
expires
A UTC timestamp showing the exact time at which the giveaway will expire.

Error Response

If an error occurred, RANDOM.ORG returns a JSON-RPC response in which the result property is absent and the error property contains an error object as described in Error Codes and Messages.

Example 1

The following requests the details of the sample giveaway from our How to Run a Giveaway guide. 

{
    "jsonrpc": "2.0",
    "method": "getGiveaway",
    "params": {
        "giveawayKey": "ckqfau"
    },
    "id": 16516
}

The service responds with the following: 

{
    "jsonrpc": "2.0",
    "result": {
        "giveawayKey": "ckqfau",
        "ownerId": 3,
        "description": "1954 Bowman Gum baseball card of Vern Bickford",
        "entries": [
            "John Doe",
            "Jane Doe",
            "Jill Doe",
            "John Q. Public"
        ],
        "rounds": 4,
        "roundsHeld": [
            [
                3, 1, 2, 0
            ],
            [
                3, 1, 2, 0
            ],
            [
                1, 3, 0, 2
            ],
            [
                2, 0, 1, 3
            ]
        ],
        "created": "2015-10-03 10:34:24Z",
        "completed": "2015-10-03 10:35:12Z",
        "expires": "2199-12-31 23:59:59Z"
    },
    "id": 16516
}

Example 2

The following requests the details of a giveaway that is still in progress, i.e., has rounds that have not been held yet: 

{
    "jsonrpc": "2.0",
    "method": "getGiveaway",
    "params": {
        "giveawayKey": "wmeeuw"
    },
    "id": 32631
}

The server responds with the following: 

{
    "jsonrpc": "2.0",
    "result": {
        "giveawayKey": "wmeeuw",
        "ownerId": 8464,
        "description": "Test Giveaway",
        "entries": [
            "Foo",
            "Bar",
            "Baz",
            "Quux"
        ],
        "rounds": 3,
        "roundsHeld": [
            [
                1, 2, 0, 3
            ]
        ],
        "created": "2018-07-02 08:56:06Z",
        "completed": null,
        "expires": "2018-08-02 08:56:06Z"
    },
    "id": 32631
}

Because the giveaway is not completed yet, the length of the array given in roundsHeld shorter than the total number of rounds given in the rounds property. The client needs to hold two more rounds in order for this giveaway to be completed.

listGiveaways (method)

This method lists all non-expired giveaways for a given RANDOM.ORG account. Your client must set the method property of its JSON-RPC request object to beginGiveaway. The request must also contain an id member, which will be returned in the response.

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. For more information, please see the Authentication API.

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 giveaway was created successfully, RANDOM.ORG returns a JSON-RPC response with the result property containing an array of objects. Each object contains information about a giveaway. The objects are sorted in reverse chronological order based on the time at which each giveaway was created.

Note that the objects do not contain all available information about the giveaways, but only the values described below. In particular, if the client needs to obtain the actual entries the giveaway or the results of each individual round, it must use the getGiveaway method for the giveaway in question.

giveawayKey
An alphanumeric verification code that identifies your giveaway. This will be identical to the value supplied for the giveawaKey property of the request.
ownerId
A numeric user ID that identifies the owner of the giveaway.
description
The textual description of the giveaway.
rounds
The total number of rounds in this giveaway.
created
A UTC timestamp showing the exact time at which the giveaway was created.
completed
A UTC timestamp showing the exact time at which the giveaway was completed. If the giveaway has not yet been completed (i.e., its last round has not been run yet), then the value of completed will be null.
expires
A UTC timestamp showing the exact time at which the giveaway will expire.

Error Response

If an error occurred, RANDOM.ORG returns a JSON-RPC response in which the result property is absent and the error property contains an error object as described in Error Codes and Messages.

Example

The following request a list of giveaways held with a given account. 

{
    "jsonrpc": "2.0",
    "method": "listGiveaways",
    "params": {
        "credentials": {
            "login": "test9",
            "password": "secret"
        },
        "delegationKey": null
    },
    "id": 4910
}

The service responds with the following: 

{
    "jsonrpc": "2.0",
    "result": [
        {
            "giveawayKey": "wmeeuw",
            "ownerId": 8464,
            "description": "Test Giveaway",
            "rounds": 3,
            "created": "2018-07-02 08:56:06Z",
            "completed": null,
            "expires": "2018-08-02 08:56:06Z"
        },
        {
            "giveawayKey": "dnabnj",
            "ownerId": 8464,
            "description": "Test Giveaway",
            "rounds": 3,
            "created": "2018-07-01 15:16:02Z",
            "completed": "2018-07-01 15:24:56Z",
            "expires": "2018-08-01 15:16:02Z"
        },
        {
            "giveawayKey": "pstqkd",
            "ownerId": 8464,
            "description": "Test Giveaway",
            "rounds": 3,
            "created": "2018-07-01 15:09:31Z",
            "completed": "2018-07-01 15:15:35Z",
            "expires": "2018-08-01 15:09:31Z"
        },
        {
            "giveawayKey": "ppaywx",
            "ownerId": 8464,
            "description": "Test Giveaway",
            "rounds": 11,
            "created": "2018-07-01 14:13:16Z",
            "completed": "2018-07-01 14:25:46Z",
            "expires": "2018-08-01 14:13:16Z"
        },
        {
            "giveawayKey": "qbwfaj",
            "ownerId": 8464,
            "description": "Test Giveaway",
            "rounds": 7,
            "created": "2018-07-01 14:07:54Z",
            "completed": "2018-07-01 14:11:34Z",
            "expires": "2018-08-01 14:07:54Z"
        }
    ],
    "id": 4910
}

The response shows that the account has five giveaways. Note that the most recent giveaway (the first object in the list) has a value of null for its completed property, meaning there are outstanding rounds that have not been run yet.

Terms and Conditions | Privacy | About Us | Contact Us
© 1998-2024 RANDOM.ORG