Sessions API

Overview
version: 1.0

The William Hill Sessions API uses a central authentication service (CAS*) on all resources that require access to a customer’s account or betting functionality. To authenticate, you’ll need to supply a sportsbook username and password, in return you will be given an authentication ticket, which you can use on the majority of requests found within our services.

The Sessions API should be used whenever you want to login a customer and:

(a) continue to use the William Hill API for that customer’s transactions

(b) use other CAS-enabled William Hill services outside the suite of APIs

CAS is an enterprise Single Sign-On solution for web services (see https://wiki.jasig.org/display/CAS/Home). It is used by many William Hill services. Note: all requests must be executed over HTTPS and include an API key and secret.

Authentication Ticket Expiration Times
When a customer is logged in using the Sessions API, they are given an Authentication Ticket; using this ticket on subsequent API requests gives you access to account activities (such as placing a bet, deposits, etc). However, this ticket is only valid for a given period of time depending on how it is used. If the ticket is used and then has a period of inactivity longer than 7,200 seconds (2 hours), then the ticket will expire and further requests using the ticket will be denied - in effect, a customer has been logged out and will need to authenticate again.

Normally, any ticket issued only has a maximum life expectancy of 28,000 seconds (8 hours) after which it can no longer be used, even if it has been used regularly. The customer again will be effectively logged out and will need to authenticate again. If you wish to avoid this, you need to set the query parameter extended to Y, which will enable your application to generate a ticket valid for 60 days without expiring due to inactivity.

Note: this parameter can only be implemented when developing applications for mobile and not desktop applications. When developing your applications you will have to code for these expiry events and present the customer with a further authentication request when appropriate.

Summary
MethodNameDescriptionResource
logInLogs in a customer by obtaining an authentication ticket. It can then be used directly with the other William Hill APIs to access a customer’s sportsbook account, place a bet, etc.

Note: to obtain a valid response you need to enter the query parameters in xwww-formurlencoded format.
https://sandbox.whapi.com/v1/sessions/tickets
getServiceTicketObtains a one-time Service Ticket that can be used to access other CAS enabled William Hill services that are not available through the standard suite of APIs. You first need to have logged in a customer to obtain an Authentication Ticket.https://sandbox.whapi.com/v1/sessions/tickets/{tgt}
logOutLogs out a customer.https://sandbox.whapi.com/v1/sessions/tickets/{tgt}
validateSessionObtains a response stating whether a session associated with the provided authentication ticket is still active. You first need to have logged in a customer to obtain an Authentication Ticket.https://sandbox.whapi.com/v1/sessions/tickets/{tgt}
ResourcesExpand AllCollapse All
logIn()
Logs in a customer by obtaining an authentication ticket. It can then be used directly with the other William Hill APIs to access a customer’s sportsbook account, place a bet, etc.

Note: to obtain a valid response you need to enter the query parameters in xwww-formurlencoded format.
Request Example
POST /v1/sessions/tickets HTTP/1.1
Host: sandbox.whapi.com
Accept: application/xml
who-apiKey: l7xxa54460c573b5497c9b24b505xxxxxxxx
who-secret: l7xxa54460c573b5497c9b24b505xxxxxxxx
Content-Type: application/x-www-form-urlencoded
Payload:
username=jsmith&password=pa55w0rd
Request Parameters
header parameters
NameTypeDescription
acceptstring
(required)
options:
application/xml, application/json
The representation of the response.
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.
query parameters
NameTypeDescription
usernamestring
(required)
Customer username.
passwordstring
(required)
Customer password.
extendedstring
default:
N
options:
Y, N,
Whether extended login or normal login is required. If the parameter is set to Y your application will generate an authentication ticket valid for a period of 60 days, without expiring due to inactivity. If the parameter is left blank or set to N this means your application will support the normal expiry times for tickets: The ticket expires after 2 hours of inactivity. The ticket is valid for a maximum of 8 hours after it has been issued.
Response Description
whoSessions
Object Name Type Constraints Optional Description
element location String - No This is the URL of the target service sent in the request. This is a combination of the endpoint and the ticket for future operations such as DELETE. For example https://{gateway}/v1/tickets/TGT-100-aVlfzM4eVR0F6kckkQxQhCYOgsj1duNMPk4aOThApEzdZ7i90s-brsuxxxx
element ticket String - No The TGT ticket.
element expiryDateTimeZoned String - Yes The time when the ticket expires presented in a time-zoned format.
element extended String - Yes The value you have selected previous to executing the request. If the value is Y, this enables your application to generate a ticket valid for 60 days without expiring due to inactivity.
ResponsesExpand AllCollapse All
Status: 201 (Created) - Success - Login
Representations
application/xml
<whoSessions>
   <location>https://sandbox.whapi.com/v1/sessions/tickets/{TGT-id}</location>
   <ticket>TGT-17-ig7EtXM7Jlyy60dm67QFWr0bEnZndUlQiKnrZjBUb0S8lI1Q7Q-brsux198</ticket>
</whoSessions>
application/json
{
   "whoSessions": {
      "location": "https://sandbox.whapi.com/v1/sessions/tickets/TGT-id",
      "ticket": "TGT-17-ig7EtXM7Jlyy60dm67QFWr0bEnZndUlQiKnrZjBUb0S8lI1Q7Q-brsux198"
   }
}
Status: 201 (Created) - Success - Login - extended
Representations
application/xml
<whoSessions>
   <location>https://sandbox.whapi.com/v1/sessions/tickets/{TGT-id}</location>
   <ticket>TGT-17-ig7EtXM7Jlyy60dm67QFWr0bEnZndUlQiKnrZjBUb0S8lI1Q7Q-brsux198</ticket>
   <expiryDateTimeZoned>2015-02-03T08:48:34+0000</expiryDateTimeZoned>
   <extended>Y</extended>
</whoSessions>
application/json
{
   "whoSessions": [
      {
         "location": "https://sandbox.whapi.com/v1/sessions/tickets/TGT-id",
         "ticket": "TGT-17-ig7EtXM7Jlyy60dm67QFWr0bEnZndUlQiKnrZjBUb0S8lI1Q7Q-brsux198",
         "expiryDateTimeZoned":"2015-02-03T09:03:59+0000",
         "extended":"Y"
      }
   ]
}
Status: 404 (Not Found) - Fault 11000 - Application metadata not configured correctly
Representations
application/xml
<whoFaults>
   <fault>
      <faultCode>11000</faultCode>
      <faultString>Application metadata not configured correctly</faultString>
      <faultName>extended</faultName>
   </fault>
</whoFaults>
application/json
{             
   "whoFaults": [
      {
         "faultCode": "11000",
         "faultString": "Application metadata not configured correctly",
         "extended": "extended"
      }
   ]  
}
Status: 401 (Unauthorized) - Fault 20000 - Login - failed
Representations
application/xml
<whoFaults>            
   <fault>
      <faultCode>20000</faultCode>
      <faultString>Credentials failed to validate</faultString>
   </fault>              
</whoFaults>
application/json
{
   "whoFaults":[
      {
         "faultCode": "20000",
         "faultString": "Credentials failed to validate"
      }
   ]
}
Status: 403 (Forbidden) - Fault 20020 - Account is under self-exclusion
Representations
application/xml
<whoFaults>            
   <fault>
      <faultCode>20020</faultCode>
      <faultString>Account is under self-exclusion</faultString>
   </fault>              
</whoFaults>
application/json
{
   "whoFaults":[
      {
         "faultCode": "20020",
         "faultString": "Account is under self-exclusion"
      }
   ]
}
Status: 403 (Forbidden) - Fault 20030 - Account is not active
Representations
application/xml
<whoFaults>            
   <fault>
      <faultCode>20030</faultCode>
      <faultString>Account is not active</faultString>
   </fault>              
</whoFaults>
application/json
{
   "whoFaults":[
      {
         "faultCode": "20030",
         "faultString": "Account is not active"
      }
   ]
}
Status: 403 (Forbidden) - Fault 20031 - Account is locked
Representations
application/xml
<whoFaults>            
   <fault>
      <faultCode>20031</faultCode>
      <faultString>Account is locked</faultString>
   </fault>              
</whoFaults>
application/json
{
   "whoFaults":[
      {
         "faultCode": "20031",
         "faultString": "Account is locked"
      }
   ]
}
Status: 403 (Forbidden) - Fault 20032 - Account is closed
Representations
application/xml
<whoFaults>            
   <fault>
      <faultCode>20032</faultCode>
      <faultString>Account is closed</faultString>
   </fault>              
</whoFaults>
application/json
{
   "whoFaults":[
      {
         "faultCode": "20032",
         "faultString": "Account is closed"
      }
   ]
}
Status: 403 (Forbidden) - Fault 20033 - Account is under age-verification
Representations
application/xml
<whoFaults>            
   <fault>
      <faultCode>20033</faultCode>
      <faultString>Account is under age-verification</faultString>
   </fault>              
</whoFaults>
application/json
{
   "whoFaults":[
      {
         "faultCode": "20033",
         "faultString": "Account is under age-verification"
      }
   ]
}
getServiceTicket()
Obtains a one-time Service Ticket that can be used to access other CAS enabled William Hill services that are not available through the standard suite of APIs. You first need to have logged in a customer to obtain an Authentication Ticket.
Request Example
POST /v1/sessions/tickets/{tgt}?target=https://example.com HTTP/1.1
Host: sandbox.whapi.com
Accept: application/xml
who-apiKey: l7xxa54460c573b5497c9b24b505xxxxxxxx
who-secret: l7xxa54460c573b5497c9b24b505xxxxxxxx
Request Parameters
template parameters
NameTypeDescription
tgtstring
(required)
Ticket Granting Ticket obtained from a previous request
header parameters
NameTypeDescription
acceptstring
(required)
options:
application/xml, application/json
The representation of the response.
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.
query parameters
NameTypeDescription
targetstring
(required)
The target URL of the CAS enabled service that you want to use with the service ticket.
Response Description
whoSessions
Object Name Type Constraints Optional Description
element ticket String - No The reference code of the one-time service ticket.
element location String - No This is the URL of the target service sent in the request.
ResponsesExpand AllCollapse All
Status: 201 (Created) - Success - Service Ticket created
Representations
application/xml
<whoSessions>
   <ticket>ST-828-tiqqWaFMDJwMX1nkpniq-brsux350</ticket>
   <location>http://www.example.com/</location>
</whoSessions>
application/json
{
   "whoSessions": {
      "ticket":"ST-861-kM1s6zg4QBb6xf4CF4oe-brsux349",
      "location":"http://www.example.com/"
   }
}
Status: 403 (Forbidden) - Forbidden - Target service not established
Representations
application/xml
<whoFaults>
   <fault>
      <faultCode>20040</faultCode>
      <faultString>Target service not established</faultString>
      <faultName>target</faultName>
   </fault>
</whoFaults>
application/json
{
   "whoFaults": [
      {
         "faultCode": "20040",
         "faultString": "Target service not established",
         "faultName": "target"
      }
   ]
}
logOut()
Logs out a customer.
Request Example
DELETE /v1/sessions/tickets/{tgt} HTTP/1.1
Host: sandbox.whapi.com
Accept: application/xml
who-apiKey: l7xxa54460c573b5497c9b24b505xxxxxxxx
who-secret: l7xxa54460c573b5497c9b24b505xxxxxxxx
Request Parameters
template parameters
NameTypeDescription
tgtstring
(required)
Ticket Granting Ticket obtained from a previous request
header parameters
NameTypeDescription
acceptstring
(required)
options:
application/xml, application/json
The representation of the response.
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.
ResponsesExpand AllCollapse All
Status: 200 (Ok) - Success - Logout successful
validateSession()
Obtains a response stating whether a session associated with the provided authentication ticket is still active. You first need to have logged in a customer to obtain an Authentication Ticket.
Request Example
HEAD /v1/sessions/tickets/{tgt} HTTP/1.1
Host: sandbox.whapi.com
Accept: application/xml
who-apiKey: l7xxa54460c573b5497c9b24b505xxxxxxxx
who-secret: l7xxa54460c573b5497c9b24b505xxxxxxxx
Request Parameters
template parameters
NameTypeDescription
tgtstring
(required)
Ticket Granting Ticket obtained from a previous request
header parameters
NameTypeDescription
acceptstring
(required)
options:
application/xml, application/json
The representation of the response.
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.
ResponsesExpand AllCollapse All
Status: 204 (No Content) - The TGT is valid.
Status: 400 (Bad Request) - Any other error in the client request.
Status: 410 (Gone) - The TGT is no longer valid.
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
20000 Credentials failed to validate 401 Unauthorized
20010 Missing request parameter 200 OK
20020 Account is under self-exclusion 403 Forbidden
20030 Account is not active 403 Forbidden
20031 Account is locked 403 Forbidden
20032 Account is closed 403 Forbidden
20033 Account is under age-verification 403 Forbidden
20040 Target service not established 403 Forbidden
20060 Time-out is applied on the account 403 Forbidden
HTTP Status Codes

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