Numbers API

Overview
version: 1.0

The William Hill Numbers API uses a single method that allows you to generate random numbers for your application.

Numbers can either be unique or can be produced with the chance that some might be the same. For example, you can have a highest value of 6 and a lowest value of 1 with a count of 2 with a Unique value of N (No) - this will give you two numbers between 1 and 6 which are independent, just like two dice being rolled.

The Numbers API is a Private API and therefore not automatically available to developers on the Developer Portal. To use this API, you will need to contact your business manager who will guide you through the requirements and acceptance of separate Terms and Conditions of use before you can have the API assigned to your application.
Summary
MethodNameDescriptionResource
getRandomNumbersThis method is used to generate random numbers for your app; within the request, you can specify the lowest number, the highest number and the amount of numbers returned. There is also an option to generate a unique set of numbers with no repetition of the same numbers allowed in the return.https://sandbox.whapi.com/v1/numbers/generate/integers
ResourcesExpand AllCollapse All
getRandomNumbers()
This method is used to generate random numbers for your app; within the request, you can specify the lowest number, the highest number and the amount of numbers returned. There is also an option to generate a unique set of numbers with no repetition of the same numbers allowed in the return.
Example Request
GET /v1/numbers/generate/integers?gameCode=POKER&highest=100&lowest=0&count=7&unique=Y HTTP/1.1
Host: sandbox.whapi.com 
Accept: application/vnd.who.Sportsbook+xml;v=1;charset=utf-8
who-apiKey: l7xx999dd7276c4e4ff7b6aa810cb106xxxx
who-secret: 04d2db4f6baa456489774afc121exxxx
who-ticket: TGT-619-Ei7EcapNaeKiopvNEYke6PIlPKihKZHYb0lKjrsyDqpJRgEyw3-brsuxxxx
Request Parameters
header parameters
NameTypeDescription
who-apiKeystring
(required)
A unique identifier of your application that is generated by the API portal and presented in the header.
who-secretstring
(required)
Another unique identifier for your application. The secret must never be sent over HTTP.
who-ticketstringThe authentication ticket associated with the user session. The getRandomNumbers method operates in two distinct ways – ‘Demo’ mode and ‘Live’ mode. In Demo mode, where no money is involved, the who-ticket is not required and can be used without it. In Live mode, when there is a financial outcome, the developer must supply a valid authentication and the who-ticket must be supplied. Important: The service should not be used in Live mode without a who-ticket.
acceptstring
(required)
options:
application/vnd.who.Sportsbook+xml;v=1;charset=utf-8, application/vnd.who.Sportsbook+json;v=1;charset=utf-8
The representation of the response.
query parameters
NameTypeDescription
gameCodestring
(required)
Identifier that indicates the game for which the RNG (Random Number Generator) has been used. Characters allowed: A-Z, a-z, 0-9, -, /, ., _, # 1-30 characters
highestinteger
(required)
Highest possible value to be returned (positive) The maximum numerical value that the service currently supports is (2^31)-1 or 2147483647. Characters allowed: 0-9, 1-10 characters long.
lowestinteger
(required)
Lowest possible value to be returned. Integer (positive). Field length 1 to 10. Valid characters are 0-9.
countinteger
(required)
Number of values to be returned. Integer (positive). Field length 1 to 2. Valid characters are 0-9.
uniquestring
(required)
options:
Y, N
Y for unique, N for non-unique.
Response Description
whoNumbers
Object Name Type Constraints Optional Description
element sessionId String - No This is either the IP address of the customer if not authenticated, or if used in ‘Live’ mode, when there is a financial outcome, it is the IP address and customerId for the account the ticket was generated for. This is used for audit purposes in case of financial query about a game outcome.
node randomNumbers Node - No randomNumbers node
randonNumbers
Object Name Type Constraints Optional Description
element number Integer Multiple elements in this node No Random number
ResponsesExpand AllCollapse All
Status: 200 (Ok) - Success
Representations
application/vnd.who.Sportsbook+xml;v=1;charset=utf-8
<whoNumbers>
   <sessionID>10.1.29.232/6859</sessionID> 
   <randomNumbers> 
      <number>17</number> 
      <number>91</number> 
      <number>22</number> 
      <number>40</number> 
      <number>19</number> 
      <number>63</number> 
      <number>0</number> 
   </randomNumbers> 
</whoNumbers>
application/vnd.who.Sportsbook+json;v=1;charset=utf-8
{ 
   "whoNumbers": { 
      "sessionID": "10.1.29.232/6859", 
      "randomNumbers": [ 
         "17", 
         "91", 
         "22", 
         "40", 
         "19", 
         "63", 
         "0" 
      ] 
   } 
}
Status: 200 (Ok) - Fault 10070 - No gameCode in query
Representations
application/vnd.who.Sportsbook+xml;v=1;charset=utf-8
<whoFaults>
   <fault>
      <faultCode>10070</faultCode>
      <faultString>Missing request parameter.</faultString>
      <faultName>gameCode</faultName>
   </fault>
</whoFaults>
application/vnd.who.Sportsbook+json;v=1;charset=utf-8
{
   "whoFaults":[
      {
         "faultCode":"10070",
         "faultString":"Missing request parameter.",
         "faultName":"gameCode"
      }
   ]
}
Status: 200 (Ok) - Fault 10070 - No highest in query
Representations
application/vnd.who.Sportsbook+xml;v=1;charset=utf-8
<whoFaults>
   <fault>
      <faultCode>10070</faultCode>
      <faultString>Missing request parameter.</faultString>
      <faultName>highest</faultName>
   </fault>
</whoFaults>
application/vnd.who.Sportsbook+json;v=1;charset=utf-8
{
   "whoFaults":[
      {
         "faultCode":"10070",
         "faultString":"Missing request parameter.",
         "faultName":"highest"
      }
   ]
}
Status: 200 (Ok) - Fault 10070 - No lowest in query
Representations
application/vnd.who.Sportsbook+xml;v=1;charset=utf-8
<whoFaults>
   <fault>
      <faultCode>10070</faultCode>
      <faultString>Missing request parameter.</faultString>
      <faultName>lowest</faultName>
   </fault>
</whoFaults>
application/vnd.who.Sportsbook+json;v=1;charset=utf-8
{
   "whoFaults":[
      {
         "faultCode":"10070",
         "faultString":"Missing request parameter.",
         "faultName":"lowest"
      }
   ]
}
Status: 200 (Ok) - Fault 10070 - No count in query
Representations
application/vnd.who.Sportsbook+xml;v=1;charset=utf-8
<whoFaults>
   <fault>
      <faultCode>10070</faultCode>
      <faultString>Missing request parameter.</faultString>
      <faultName>count</faultName>
   </fault>
</whoFaults>
application/vnd.who.Sportsbook+json;v=1;charset=utf-8
{
   "whoFaults":[
      {
         "faultCode":"10070",
         "faultString":"Missing request parameter.",
         "faultName":"count"
      }
   ]
}
Status: 200 (Ok) - Fault 10070 - No unique in query
Representations
application/vnd.who.Sportsbook+xml;v=1;charset=utf-8
<whoFaults>
   <fault>
      <faultCode>10070</faultCode>
      <faultString>Missing request parameter.</faultString>
      <faultName>unique</faultName>
   </fault>
</whoFaults>
application/vnd.who.Sportsbook+json;v=1;charset=utf-8
{
   "whoFaults":[
      {
         "faultCode":"10070",
         "faultString":"Missing request parameter.",
         "faultName":"unique"
      }
   ]
}
Status: 200 (Ok) - Fault 10071 - gameCode parameter in query is invalid
Representations
application/vnd.who.Sportsbook+xml;v=1;charset=utf-8
<whoFaults>
   <fault>
      <faultCode>10071</faultCode>
      <faultString>Invalid request parameter.</faultString>
      <faultName>gameCode</faultName>
   </fault>
</whoFaults>
application/vnd.who.Sportsbook+json;v=1;charset=utf-8
{
   "whoFaults":[
      {
         "faultCode":"10071",
         "faultString":"Invalid request parameter.",
         "faultName":"gameCode"
      }
   ]
}
Status: 200 (Ok) - Fault 10071 - highest parameter in query is invalid
Representations
application/vnd.who.Sportsbook+xml;v=1;charset=utf-8
<whoFaults>
   <fault>
      <faultCode>10071</faultCode>
      <faultString>Invalid request parameter.</faultString>
      <faultName>highest</faultName>
   </fault>
</whoFaults>
application/vnd.who.Sportsbook+json;v=1;charset=utf-8
{
   "whoFaults":[
      {
         "faultCode":"10071",
         "faultString":"Invalid request parameter.",
         "faultName":"highest"
      }
   ]
}
Status: 200 (Ok) - Fault 10071 - lowest parameter in query is invalid
Representations
application/vnd.who.Sportsbook+xml;v=1;charset=utf-8
<whoFaults>
   <fault>
      <faultCode>10071</faultCode>
      <faultString>Invalid request parameter.</faultString>
      <faultName>lowest</faultName>
   </fault>
</whoFaults>
application/vnd.who.Sportsbook+json;v=1;charset=utf-8
{
   "whoFaults":[
      {
         "faultCode":"10071",
         "faultString":"Invalid request parameter.",
         "faultName":"lowest"
      }
   ]
}
Status: 200 (Ok) - Fault 10071 - count parameter in query is invalid
Representations
application/vnd.who.Sportsbook+xml;v=1;charset=utf-8
<whoFaults>
   <fault>
      <faultCode>10071</faultCode>
      <faultString>Invalid request parameter.</faultString>
      <faultName>count</faultName>
   </fault>
</whoFaults>
application/vnd.who.Sportsbook+json;v=1;charset=utf-8
{
   "whoFaults":[
      {
         "faultCode":"10071",
         "faultString":"Invalid request parameter.",
         "faultName":"count"
      }
   ]
}
Status: 200 (Ok) - Fault 10071 - unique parameter in query is invalid
Representations
application/vnd.who.Sportsbook+xml;v=1;charset=utf-8
<whoFaults>
   <fault>
      <faultCode>10071</faultCode>
      <faultString>Invalid request parameter.</faultString>
      <faultName>unique</faultName>
   </fault>
</whoFaults>
application/vnd.who.Sportsbook+json;v=1;charset=utf-8
{
   "whoFaults":[
      {
         "faultCode":"10071",
         "faultString":"Invalid request parameter.",
         "faultName":"unique"
      }
   ]
}
Status: 200 (Ok) - Fault 27210 - Lowest parameter greater than or equal to highest parameter.
Representations
application/vnd.who.Sportsbook+xml;v=1;charset=utf-8
<whoFaults>
    <fault>
        <faultCode>27210</faultCode>
        <faultString>Lowest parameter greater than or equal to highest parameter.</faultString>
        <faultName></faultName>
    </fault>
</whoFaults>
application/vnd.who.Sportsbook+json;v=1;charset=utf-8
{
  "whoFaults": [
    {
      "faultCode": "27210",
      "faultString": "Lowest parameter greater than or equal to highest parameter.",
      "faultName": ""
    }
  ]
}
Status: 200 (Ok) - Fault 27220 - Count parameter too large.
Representations
application/vnd.who.Sportsbook+xml;v=1;charset=utf-8
<whoFaults>
    <fault>
        <faultCode>27220</faultCode>
        <faultString>Count parameter too large.</faultString>
        <faultName></faultName>
    </fault>
</whoFaults>
application/vnd.who.Sportsbook+json;v=1;charset=utf-8
{
  "whoFaults": [
    {
      "faultCode": "27220",
      "faultString": "Count paramter too large.",
      "faultName": ""
    }
  ]
}
Error Handling
General Error Structure
As an application developer, you will need to see a standard error response when the system generates an error. As well as supplying a standard HTTP status code, we also supply a unique William Hill fault code, fault string and fault name (in some cases) to help you identify and resolve any issues that you may be having with our API or your requests and code.

Where the elements can be defined as the following:
  • Fault code - A unique William Hill identifier for the error
  • Fault string - A unique William Hill text string to enable you to identify the error (in English only)
  • HTTP code - the standard HTTP status code for the error
  • HTTP response - the standard HTTP response for the error

Note: A Fault name may also be generated in order to pinpoint the exact parameter where a request has failed.

Available Response Formats

The error codes are supplied in the following representations:

  • XML
  • JSON
Error Response Body

The response body will contain the unique William Hill fault code and fault string appropriate to the corresponding error.

The response will be sent according to the representation type governed by the accept parameter within the original request. The default representation is for application/xml and this representation will be returned if either the accept header is absent or if the accept header is set to application/xml.

Generic William Hill Error Codes

Click here to view the complete list of William Hill error codes for the APIs.

API Specific Error Codes

Error codeFault stringHTTP codeHTTP response
27210 Lowest parameter greater than or equal to highest parameter 200 Success
27220 Count parameter too large 200 Success
HTTP Status Codes

For more information about how William Hill uses HTTP status codes with their APIs, click here.