Skip to end of metadata
Go to start of metadata

Overview and limitations

The API login endpoint is the simplest method of integration for most applications in terms of expected development time but comes at the cost of being less flexible to edge-cases than the embedded Betfair embedded login page. It will allow a user to provide a username and password or a username and (password + 2 factor auth code) if they have strong authentication enabled.

  • Customers who writing bots are for their own use are strongly recommended to use the non-interactive endpoint with an SSL certificate.
  • We recommend that 3rd party applications which will be exposed to a wide range of users use the Interactive Login method of embedding the Betfair embedded login page as this will allow your application to handle additional workflows, such as terms and conditions updates as well as additional jurisdictional specific identifiers.

The Keep alive and logout methods remain the same with this method of login.

URL Definition (Global)

API Login Endpoint
https://identitysso.betfair.com/api/login

Other Jurisdictions

Italian jurisdiction users:

 

https://identitysso.betfair.it/api/login

 

Spanish jurisdiction users:

 

https://identitysso.betfair.es/api/login

 

Romania jurisdiction users:

https://identitysso.betfair.ro/api/login

Parameters (POST)

Name

Description

Sample

username (mandatory)

The username to be used for the login

 

password (mandatory)

The password to be used for the login. For strong auth customers, this should be their password with a 2 factor auth code appended to the password string.

 

Headers

Name

Description

Sample

Accept (mandatory)

Signals that the response should be returned as JSON

application/json

X-Application (mandatory)

AppKey used by the customer to identify the product.

 

The presence of the "Accept: application/json" will signal SSO that it should respond with JSON and not with a HTML page.

POST Example

Accept: application/json

X-Application: <AppKey>

Content-Typeapplication/x-www-form-urlencoded 

URL endpoint: https://identitysso.betfair.com/api/login

Payload

username=username&password=password

Curl call sample

 

curl -k -i -H "Accept: application/json" -H "X-Application: <AppKey>" -X POST -d 'username=<username>&password=<password>' https://identitysso.betfair.com/api/login

 

Example of a successful login:

 

curl -k -i -H "Accept: application/json" -H "X-Application: <AppKey>" -X POST -d 'username=<username>&password=<password>' https://identitysso.betfair.com/api/login
 
{
  "token":"SESSION_TOKEN",
  "product":"APP_KEY",
  "status":"SUCCESS",
  "error":""
}

 

Response Structure

{
  "token":"<token_passed_as_header>",
  "product":"product_passed_as_header",
  "status":"<status>",
  "error":"<error>"
}

 

Status Values

SUCCESS
LIMITED_ACCESS
LOGIN_RESTRICTED
FAIL

 

Status Codes & Error values

The below describes the status codes that can be returned and the associated error values:

 

LIMITED_ACCESS - Access is limited (e.g. accounts can login but can't bet due to account suspension), product session will be provided.

 

{
  "token": product_token,
  "product": product,
  "status": LIMITED_ACCESS,
  "error": error
}
 
error = {PENDING_AUTH | SECURITY_QUESTION_WRONG_3X | KYC_SUSPEND | SUSPENDED}

 

LOGIN_RESTRICTED - login is restricted (in case of indirection point this is what will be returned), product session will not be provided:

 

{
  "token": "",
  "product": product,
  "status": LOGIN_RESTRICTED,
  "error": error
}
 
error = {STRONG_AUTH_CODE_REQUIRED | DENMARK_MIGRATION_REQUIRED | DANISH_AUTHORIZATION_REQUIRED | SPAIN_MIGRATION_REQUIRED | SPANISH_TERMS_ACCEPTANCE_REQUIRED | ITALY_MIGRATION_REQUIRED | ITALIAN_CONTRACT_ACCEPTANCE_REQUIRED | CHANGE_PASSWORD_REQUIRED | PERSONAL_MESSAGE_REQUIRED}

 

FAIL - All other cases are treated as errors, product session will not be provided:

 

{
  "token": "",
  "product": product,
  "status": FAIL,
  "error": error
}
 
error = {TRADING_MASTER | TRADING_MASTER_SUSPENDED | AGENT_CLIENT_MASTER | AGENT_CLIENT_MASTER_SUSPENDED | DENMARK_MIGRATION_REQUIRED | INVALID_PIN | INVALID_USERNAME_OR_PASSWORD | PIN_DELETED_ON_FAILED_COUNT_EXCEEDED | UNRECOGNIZED_DEVICE | DUPLICATE_CARDS | ACCOUNT_NOW_LOCKED | ACCOUNT_ALREADY_LOCKED | SECURITY_RESTRICTED_LOCATION | BETTING_RESTRICTED_LOCATION | INVALID_CONNECTIVITY_TO_REGULATOR | INVALID_CONNECTIVITY_TO_REGULATOR | INVALID_CONNECTIVITY_TO_REGULATOR_IT | INVALID_CONNECTIVITY_TO_REGULATOR_DK| NOT_AUTHORIZED_BY_REGULATOR | NOT_AUTHORIZED_BY_REGULATOR | NOT_AUTHORIZED_BY_REGULATOR_DK | NOT_AUTHORIZED_BY_REGULATOR_IT | TELBET_TERMS_CONDITIONS_NA | CLOSED | SELF_EXCLUDED | NOT_AUTHORIZED_FOR_DOMAIN_ES | NOT_AUTHORIZED_FOR_DOMAIN_IT | NOT_AUTHORIZED_FOR_DOMAIN_COM | AUTHORIZED_ONLY_FOR_DOMAIN_ES}

 

Please note that master account access is restricted for API/JSON requests.

 

{
  "token": "",
  "product": "APP_KEY",
  "status": FAIL,
  "error": error
}
 
error = {INPUT_VALIDATION_ERROR | FORBIDDEN | INVALID_USERNAME_OR_PASSWORD | NO_SESSION | INVALID_PIN | INVALID_PIN_LOGIN_REQUEST | INVALID_PIN_LOGIN_REQUEST}

 

Possible failure and exceptional return codes

 

loginStatus
 Description
TRADING_MASTER_SUSPENDED  Suspended Trading Master Account
TRADING_MASTER  Trading Master Account
TELBET_TERMS_CONDITIONS_NA  Telbet terms and conditions rejected
SUSPENDED  the account is suspended
SPANISH_TERMS_ACCEPTANCE_REQUIRED  The latest Spanish terms and conditions version must be accepted
SPAIN_MIGRATION_REQUIRED  Spain migration required
SELF_EXCLUDED  the account has been self excluded
SECURITY_RESTRICTED_LOCATION  the account is restricted due to security concerns
SECURITY_QUESTION_WRONG_3X  the user has entered wrong the security question 3 times
PERSONAL_MESSAGE_REQUIRED  personal message required for the user
PENDING_AUTH  pending authentication
NOT_AUTHORIZED_BY_REGULATOR_IT  the user identified by the given credentials is not authorized in the IT's jurisdictions due to the regulators' policies. Ex: the user for which this session should be created is not allowed to act(play, bet) in the IT's jurisdiction.
NOT_AUTHORIZED_BY_REGULATOR_DK  the user identified by the given credentials is not authorized in the DK's jurisdictions due to the regulators' policies. Ex: the user for which this session should be created is not allowed to act(play, bet) in the DK's jurisdiction.
KYC_SUSPEND  KYC suspended
ITALIAN_CONTRACT_ACCEPTANCE_REQUIRED  The latest Italian contract version must be accepted
INVALID_USERNAME_OR_PASSWORD  the username or password are invalid
INVALID_CONNECTIVITY_TO_REGULATOR_IT  the IT regulator cannot be accessed due to some internal problems in the system behind or in at regulator; timeout cases included.
INVALID_CONNECTIVITY_TO_REGULATOR_DK the DK regulator cannot be accessed due to some internal problems in the system behind or in at regulator; timeout cases included.
DUPLICATE_CARDS  duplicate cards
DENMARK_MIGRATION_REQUIRED  Denmark migration required
DANISH_AUTHORIZATION_REQUIRED  Danish authorization required
CLOSED   the account is closed
CHANGE_PASSWORD_REQUIRED  change password required
CERT_AUTH_REQUIRED  Certificate required or certificate present but could not authenticate with it
BETTING_RESTRICTED_LOCATION  the account is accessed from a location where betting is restricted
AGENT_CLIENT_MASTER_SUSPENDED  Suspended Agent Client Master
AGENT_CLIENT_MASTER  Agent Client Master
ACCOUNT_NOW_LOCKED  the account was just locked
ACCOUNT_ALREADY_LOCKED   the account is already locked
TEMPORARY_BAN_TOO_MANY_REQUESTSThe limit for successful login requests per minute has been exceeded. New login attempts will be banned for 20 minutes
ACCOUNT_PENDING_PASSWORD_CHANGE the account must undergo password recovery to reactivate via https://identitysso.betfair.com/view/recoverpassword
ITALIAN_PROFILING_ACCEPTANCE_REQUIREDYou must login to the website to accept the new conditions

 

 


  • No labels