Accounts API

Overview
version: 1.0

The Accounts API is a collection of methods used to query a customer account. It retrieves account-related data such as the user account balance, first and last name, or is the registered customer contactable via partners of William Hill with marketing information.
Summary
MethodNameDescriptionResource
getDetailsRetrieves a limited set of customer account details. For security purposes, only a subset is supplied, which does not include fields such as security questions and answers.https://sandbox.whapi.com/v1/accounts/me
putFlagsClear the 'Protection of funds' flag set on a customers account.https://sandbox.whapi.com/v1/accounts/me/flags
getBalanceThis method can be used to retrieve the customer’s account balance in UK Sterling.https://sandbox.whapi.com/v1/accounts/me/balance
getPaymentsRetrieves the customer’s account payments in UK Sterling.https://sandbox.whapi.com/v1/accounts/me/payments
ResourcesExpand AllCollapse All
getDetails()
Retrieves a limited set of customer account details. For security purposes, only a subset is supplied, which does not include fields such as security questions and answers.
Request Example
GET /v1/accounts/me HTTP/1.1
Host: sandbox.whapi.com
Accept: application/xml
who-apiKey: l7xxa54460c573b5497c9b24b505xxxxxxxx
who-secret: l7xxa54460c573b5497c9b24b505xxxxxxxx
who-ticket: TGT-499-yv2cRDgYvAvFFdFZC5RTvtbrbXiSDbm3UeDb5jIju5tc4qb1uP-brsxxxx
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.
acceptstring
(required)
options:
application/xml, application/json
The representation of the response.
who-ticketstring
(required)
The ticket associated with the user session.
Response Description
whoAccounts
Object Name Type Constraints Optional Description
element status String - No The status of the account
element accountNum String - No The account number of the account
element accountId String - No The William Hill account id
element customerId String - No The William Hill customer id
element currencyCode String - No A three-character ISO4217 currency code. This will be the currency that the customer registered in (for example : GBP (UK Pound Sterling))
element countryCode String - No A two-character ISO 3166-1-Alpha-2 code representing the customer's country of registration. William Hill must recognise and accept bets from the country otherwise an error will be thrown.
element title String - No The title of the name of the customer with that account
element firstname String - No The first name of the customer with that account
element lastName String - No The last name of the customer with that account
element street1 String - No Line number 1 of the customer's street address written out in full
element street2 String - No Line number 2 of the customer's street address written out in full
element street3 String - No Line number 3 of the customer's street address written out in full
element city String - No The city of the customer's address
element county String - No The county of the customer's address
element postCode String - No The postCode of the customer's address
element country String - No The country of the customer's address
element email String - No The primary email address of the customer with that account. Must be unique.
element mobile String - No The mobile number of the customer with that account
element partnerContactable String Y or N No Is it okay for William Hill to give the customer's contact details to companies with which it has partnerships? These companies may subsequently contact the user with marketing information using any of the contact methods supplied at registration
element contactable String Y or N No Can William Hill contact the customer with marketing information using any of the contact methods supplied at registration?
node flags Node - No The flags node
flags
Object Name Type Constraints Optional Description
node flag Node - No The flag node
flag
Object Name Type Constraints Optional Description
element pocf String N = Not agreed No The status of the proctection of customer funds flag. This response will be returned if the customer has not accepted the protection of funds statement. If this flag is set to N then any attempt to make a deposit will be rejected. (N = Not agreed) A statement must be read and agreed by the customer before the flag is cleared from the account. Example statement: “I understand that my funds will be given a ‘basic’ level of protection by being held in a specially designated bank account, in accordance with our regulatory obligations”.
ResponsesExpand AllCollapse All
Status: 200 (Ok) - Success - Details obtained
Representations
application/xml
<whoAccounts>
   <status>A</status>
   <accountNum>14652314</accountNum>
   <accountId>18164</accountId>
   <customerId>48</customerId>
   <currencyCode>GBP</currencyCode>
   <countryCode>GB</countryCode>
   <title>Mr</title>
   <firstName>Joe</firstName>
   <lastName>Bloggs</lastName>
   <street1>10 Rillington Place</street1>
   <street2>Old Basing</street2>
   <street3>Lychpit</street3>
   <city>Basingstoke</city>
   <county>Hampshire</county>
   <postcode>RG248YQ</postcode>
   <country>United Kingdom</country>
   <email>jbloggs@email.com</email>
   <mobile>09876543210</mobile>
   <partnerContactable>N</partnerContactable>
   <contactable>Y</contactable>
   <flags>
      <flag>
         <pocf>N</pocf>
      </flag>
   </flags>
</whoAccounts>
application/json
{
  "whoAccounts": {
    "status": "A",
    "accountNum": "14652314",
    "accountId": "18164",
    "customerId": "48",
    "currencyCode": "GBP",
    "countryCode": "GB",
    "title": "Mr",
    "firstName": "Joe",
    "lastName": "Bloggs",
    "street1": "10 Rillington Place",
    "street2": "Old Basing",
    "street3": "Lychpit",
    "city": "Basingstoke",
    "county": "Hampshire",
    "postcode": "RG248YQ",
    "country": "United Kingdom",
    "email": "jbloggs@email.com",
    "mobile": "09876543210",
    "partnerContactable": "N",
    "contactable": "Y"
    "flags": [
       {
          "pocf": "N"
       }
    ]
  }
}
putFlags()
Clear the 'Protection of funds' flag set on a customers account.
Request Example
PUT /v1/accounts/me/flags?pocf=A HTTP/1.1
Host: sandbox.whapi.com
Accept: application/xml
who-apiKey: l7xxa54460c573b5497c9b24b505xxxxxxxx
who-secret: l7xxa54460c573b5497c9b24b505xxxxxxxx
who-ticket: TGT-499-yv2cRDgYvAvFFdFZC5RTvtbrbXiSDbm3UeDb5jIju5tc4qb1uP-brsxxxx
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.
acceptstring
(required)
options:
application/xml, application/json
The representation of the response.
who-ticketstring
(required)
The authentication ticket associated with the user session.
query parameters
NameTypeDescription
pocfstring
(required)
The Protection of Customer funds flag. Only valid character is 'A'.
ResponsesExpand AllCollapse All
Status: 204 (No Content) - Success - Flag set
Status: 200 (Ok) - Fault 10070 - Missing protection of customer funds parameter
Representations
application/xml
<whoFaults>
   <fault>
      <faultCode>10070</faultCode>
      <faultString>Missing request parameter.</faultString>
      <faultName>status</faultName>
   </fault>
</whoFaults>
application/json
{
   "whoFaults":[
      {
         "faultCode":"10070",
         "faultString":"Missing request parameter.",
         "faultName":"status"
      }
   ]
}
Status: 200 (Ok) - Fault 10071 - invalid protection of customer funds parameter
Representations
application/xml
<whoFaults>
   <fault>
      <faultCode>10071</faultCode>
      <faultString>Invalid request parameter.</faultString>
      <faultName>status</faultName>
   </fault>
</whoFaults>
application/json
{
   "whoFaults":[
      {
         "faultCode":"10071",
         "faultString":"Invalid request parameter.",
         "faultName":"status"
      }
   ]
}
getBalance()
This method can be used to retrieve the customer’s account balance in UK Sterling.
Request Example
GET /v1/accounts/me/balance HTTP/1.1
Host: sandbox.whapi.com
Accept: application/xml
who-apiKey: l7xxa54460c573b5497c9b24b505xxxxxxxx
who-secret: l7xxa54460c573b5497c9b24b505xxxxxxxx
who-ticket: TGT-499-yv2cRDgYvAvFFdFZC5RTvtbrbXiSDbm3UeDb5jIju5tc4qb1uP-brsxxxx
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.
acceptstring
(required)
options:
application/xml, application/json
The representation of the response.
who-ticketstring
(required)
The authentication ticket associated with the user session.
Response Description
whoAccounts
Object Name Type Constraints Optional Description
element currencyCode String - No The currency code of the account's currency
element balance Decimal [0-9]*.[0-9]{2} No The balance amount of the account
element availableFunds Decimal [0-9]*.[0-9]{2} No the funds that are available to the user of the account
element withdrawableFunds Decimal [0-9]*.[0-9]{2} No The funds available for withdrawal for the user of the account
ResponsesExpand AllCollapse All
Status: 200 (Ok) - Success - Balance obtained
Representations
application/xml
<whoAccounts>
   <currencyCode>GBP</currencyCode>
   <balance>234.23</balance>
   <availableFunds>234.23</availableFunds>
   <withdrawableFunds>234.23</withdrawableFunds>
</whoAccounts>
application/json
{
  "whoAccounts": {
    "currencyCode": "GBP",
    "balance": "234.23",
    "availableFunds": "234.23",
    "withdrawableFunds": "234.23"
  }
}
getPayments()
Retrieves the customer’s account payments in UK Sterling.
Request Example
GET /v1/accounts/me/payments?fromDateTimeZoned=2013-09-21T13:34:20+01:00&toDateTimeZoned=2013-09-25T13:34:20+01:00&blockSize=10&blockNum=0&sortOrder=A HTTP/1.1
Host: sandbox.whapi.com
Accept: application/xml
who-apiKey: l7xxa54460c573b5497c9b24b505xxxxxxxx
who-secret: l7xxa54460c573b5497c9b24b505xxxxxxxx
who-ticket: TGT-499-yv2cRDgYvAvFFdFZC5RTvtbrbXiSDbm3UeDb5jIju5tc4qb1uP-brsxxxx
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.
acceptstring
(required)
options:
application/xml, application/json
The representation of the response.
who-ticketstring
(required)
The authentication ticket associated with the user session.
query parameters
NameTypeDescription
blockSizestring
(required)
The number of transactions per page to retrieve (Valid whole number > 0 <= 20)
blockNumstring
(required)
The page number of the transactions you wish to retrieve. This parameter limits the number of transactions retrieved per call to the number entered in the blockSize. This stops the call retrieving a customer's entire payment history and can be increased until an empty response is obtained. (Valid whole number >= 0)
fromDateTimeZonedstringThe start date and time for the payment history to be retrieved (e.g. 2013-09-21T13:34:20+01:00)
toDateTimeZonedstringThe end date and time for the payment history to be retrieved (e.g. 2013-09-25T13:34:20+01:00)
sortOrderstringThe sort order of the results, A = ascending, D = descending
Response Description
whoAccounts
Object Name Type Constraints Optional Description
collection payments Node - No payments node
payments
Object Name Type Constraints Optional Description
node payment Node Multiple child nodes No payment node
payment
Object Name Type Constraints Optional Description
attribute id String - No Id of the payment
element methodId String - No Id of the payment method
element type String Characters allowed: A-Z, a-z No Type of the payment
element action String D|W No Action of the payment (D = Deposit and W = Withdrawal)
element paymentDateTimeZoned String - No The date and time when the payment was made
element amount Decimal [0-9]*.[0-9]{2} No The amount of the payment
element commision Decimal [0-9]*.[0-9]{2} No The commision for the payment
element status String - No The status of the payment
element channel String - No The channel through which the payment was made
element ipAddress String - No The IP address from which the payment was made
ResponsesExpand AllCollapse All
Status: 200 (Ok) - Success - Payments obtained
Representations
application/xml
<whoAccounts>
   <payments>
      <payment id="277">
         <methodId>111</methodId>
         <type>CSH</type>
         <action>D</action>
         <paymentDateTimeZoned>2013-09-25T13:34:20+01:00</paymentDateTimeZoned>
         <amount>20.56</amount>
         <commission>0.00</commission>
         <status>Y</status>
         <channel>M</channel>
         <ipAddress>10.0.0.12</ipAddress>
      </payment>
      <payment id="276">
         <methodId>111</methodId>
         <type>CC</type>
         <action>W</action>
         <paymentDateTimeZoned>2013-09-25T13:34:20+01:00</paymentDateTimeZoned>
         <amount>25.00</amount>
         <commission>0.00</commission>
         <status>Y</status>
         <channel>I</channel>
         <ipAddress>10.0.0.12</ipAddress>
      </payment>
   </payments>
</whoAccounts>
application/json
{
  "whoAccounts": {
    "payments": [
        {
          "id": "277",
          "methodId": "111",
          "type": "CSH",
          "action": "D",
          "paymentDateTimeZoned": "2013-09-25T13:34:20+01:00",
          "amount": "20.56",
          "commission": "0.00",
          "status": "Y",
          "channel": "M",
          "ipAddress": "10.0.0.12"
        },
        {
          "id": "276",
          "methodId": "111",
          "type": "CC",
          "action": "W",
          "paymentDateTimeZoned": "2013-09-25T13:34:20+01:00",
          "amount": "25.00",
          "commission": "0.00",
          "status": "Y",
          "channel": "I",
          "ipAddress": "10.0.0.12"
        }
     ]
  }
}
Status: 200 (Ok) - Fault 10070 - No blockSize parameter
Representations
application/xml
<whoFaults>
   <fault>
      <faultCode>10070</faultCode>
      <faultString>Missing request parameter.</faultString>
      <faultName>blockSize</faultName>
   </fault>
</whoFaults>
application/json
{
   "whoFaults":[
      {
         "faultCode":"10070",
         "faultString":"Missing request parameter.",
         "faultName":"blockSize"
      }
   ]
}
Status: 200 (Ok) - Fault 10070 - No blockNum parameter
Representations
application/xml
<whoFaults>
   <fault>
      <faultCode>10070</faultCode>
      <faultString>Missing request parameter.</faultString>
      <faultName>blockNum</faultName>
   </fault>
</whoFaults>
application/json
{
   "whoFaults":[
      {
         "faultCode":"10070",
         "faultString":"Missing request parameter.",
         "faultName":"blockNum"
      }
   ]
}
Status: 200 (Ok) - Fault 10071 - blockSize parameter is not an integer between 0 and 20
Representations
application/xml
<whoFaults>
   <fault>
      <faultCode>10071</faultCode>
      <faultString>Invalid request parameter.</faultString>
      <faultName>blockSize</faultName>
   </fault>
</whoFaults>
application/json
{
   "whoFaults":[
      {
         "faultCode":"10071",
         "faultString":"Invalid request parameter.",
         "faultName":"blockSize"
      }
   ]
}
Status: 200 (Ok) - Fault 10071 - blockNum parameter is not an integer above 0
Representations
application/xml
<whoFaults>
   <fault>
      <faultCode>10071</faultCode>
      <faultString>Invalid request parameter.</faultString>
      <faultName>blockNum</faultName>
   </fault>
</whoFaults>
application/json
{
   "whoFaults":[
      {
         "faultCode":"10071",
         "faultString":"Invalid request parameter.",
         "faultName":"blockNum"
      }
   ]
}
Status: 200 (Ok) - Fault 10071 - fromDateTimeZoned parameter is invalid
Representations
application/xml
<whoFaults>
   <fault>
      <faultCode>10071</faultCode>
      <faultString>Invalid request parameter.</faultString>
      <faultName>fromDateTimeZoned</faultName>
   </fault>
</whoFaults>
application/json
{
   "whoFaults":[
      {
         "faultCode":"10071",
         "faultString":"Invalid request parameter.",
         "faultName":"fromDateTimeZoned"
      }
   ]
}
Status: 200 (Ok) - Fault 10071 - toDateTimeZoned parameter is invalid
Representations
application/xml
<whoFaults>
   <fault>
      <faultCode>10071</faultCode>
      <faultString>Invalid request parameter.</faultString>
      <faultName>toDateTimeZoned</faultName>
   </fault>
</whoFaults>
application/json
{
   "whoFaults":[
      {
         "faultCode":"10071",
         "faultString":"Invalid request parameter.",
         "faultName":"toDateTimeZoned"
      }
   ]
}
Status: 200 (Ok) - Fault 10071 - sortOrder parameter must be either A or D
Representations
application/xml
<whoFaults>
   <fault>
      <faultCode>10071</faultCode>
      <faultString>Invalid request parameter.</faultString>
      <faultName>sortOrder</faultName>
   </fault>
</whoFaults>
application/json
{
   "whoFaults":[
      {
         "faultCode":"10071",
         "faultString":"Invalid request parameter.",
         "faultName":"sortOrder"
      }
   ]
}
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
22209 Username already exists 409 Conflict
22210 Username already exists 200 Success
22211 Username must be between six and fifteen characters 200 Success
22220 Email address is already registered 200 Success
22221 Email address has an invalid character 200 Success
22222 Email address is greater than sixty characters 200 Success
22223 Password must be between six and fifteen characters 200 Success
22224 Username has an invalid format 200 Success
22225 Username and email address are already registered 200 Success
22230 Account limit not set 200 Success
HTTP Status Codes

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