Page History

...

Table of Content Zone

location	top

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)

Code Block

title	API Login Endpoint

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

Other Jurisdictions

Please use the below if your country of residence is in one of the list jurisdictions.

Jurisdiction	Endpoint
Australia	`https://identitysso.betfair.au/api/login`
Italy	`https://identitysso.betfair.it/api/login`
Spain	`https://identitysso.betfair.es/api/login`
Romania	`https://identitysso.betfair.ro/api/login`
Sweden	`https://identitysso.betfair.se/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.
Content-Type (required)	Required to support passwords containing special characters	application/x-www-form-urlencoded

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-Type: application/x-www-form-urlencoded

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

Payload

username=username&password=password

Curl call sample

Code Block

language	bash

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:

Code Block

language	bash

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

Code Block

language	javascript

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

Status Values

Code Block

language	none

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.

Code Block

language	javascript

{
  "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:

Code Block

language	javascript

{
  "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:

Code Block

language	javascript

{
  "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.

Code Block

language	javascript

{
  "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

TRADING

loginStatus	Description
error	Description
ACCOUNT_ALREADY_LOCKED	the account is already locked
ACCOUNT_NOW_LOCKED	the account was just locked
ACCOUNT_PENDING_PASSWORD_CHANGE	The account must undergo password recovery to reactivate via https://identitysso.betfair.com/view/recoverpassword
ACTIONS_REQUIRED	You must login to https://www.betfair.com to provide missing information.
AGENT_CLIENT_MASTER	Agent Client Master
AGENT_CLIENT_MASTER_SUSPENDED	Suspended Trading Agent Client Master Account
TRADING_MASTER	Trading Master Account
TELBET_TERMS_CONDITIONS_NA	Telbet terms and conditions rejected
SUSPENDED	the account is suspended
STRONG_AUTH_CODE_REQUIRED	2 Step Authentication code is required. Please append this to your Betfair password.
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
AUTHORIZED_ONLY_FOR_DOMAIN_RO	You are attempting to login to the Betfair Romania domain with a non .ro account.
AUTHORIZED_ONLY_FOR_DOMAIN_SE	You are attempting to login to the Betfair Swedish domain with a non .se account.
BETTING_RESTRICTED_LOCATION	the account is accessed from a location where betting is restricted
CERT_AUTH_REQUIRED	Certificate required or certificate present but could not authenticate with it
CHANGE_PASSWORD_REQUIRED	Change password required
CLOSED	the account is closed
DANISH_AUTHORIZATION_REQUIRED	Danish authorization required
DENMARK_MIGRATION_REQUIRED	Denmark migration required
DUPLICATE_CARDS	duplicate cards
EMAIL_LOGIN_NOT_ALLOWED	This account has not opted in to log in with the email
INTERNATIONAL_TERMS_ACCEPTANCE_REQUIRED	The latest international terms and conditions must be accepted prior to logging in.
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.
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_USERNAME_OR_PASSWORD	the username or password are invalid
ITALIAN_CONTRACT_ACCEPTANCE_REQUIRED	The latest Italian contract version must be accepted. You must login to the website to accept the new conditions.
ITALIAN_PROFILING_ACCEPTANCE_REQUIRED	You must login to the website to accept the new conditions
KYC_SUSPEND	KYC suspended
MULTIPLE_USERS_WITH_SAME_CREDENTIAL	There is more than one account with the same credential
NOT_AUTHORIZED_BY_REGULATOR_IT DK	the user identified by the given credentials is not authorized in the ITDK'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 ITDK's jurisdiction.
NOT_AUTHORIZED_BY_REGULATOR_DK IT	the user identified by the given credentials is not authorized in the DKIT'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 DKIT's jurisdiction.
KYCPENDING_SUSPEND AUTH	KYC suspended pending authentication
ITALIANPERSONAL_CONTRACT_ACCEPTANCEMESSAGE_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
Personal message required for the user
SECURITY_QUESTION_WRONG_3X	the user has entered wrong the security answer 3 times
SECURITY_RESTRICTED_LOCATION	the account is restricted due to security concerns
SELF_EXCLUDED	the account has been self-excluded
SPAIN_MIGRATION_REQUIRED	Spain migration required
SPANISH_TERMS_ACCEPTANCE_REQUIRED	The latest Spanish terms and conditions version must be accepted. You must login to the website to accept the new conditions.
SUSPENDED	the account is suspended
SWEDEN_BANK_ID_VERIFICATION_REQUIRED	You must provided your Swedish bank id via Betfair.se before proceeding.
SWEDEN_NATIONAL_IDENTIFIER_REQUIRED	You must provided your Swedish National identifier via Betfair.se before proceeding.
TELBET_TERMS_CONDITIONS_NA	Telbet terms and conditions rejected
TEMPORARY_BAN_TOO_MANY_REQUESTS	The 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_REQUIRED	You must login to the website to accept the new conditions
AUTHORIZED_ONLY_FOR_DOMAIN_RO	You are attempting to login to the Betfair Romania domain with a non .ro account.
AUTHORIZED_ONLY_FOR_DOMAIN_SE	You are attempting to login to the Betfair Swedish domain with a non .se account.
SWEDEN_NATIONAL_IDENTIFIER_REQUIRED	You must provided your Swedish National identifier via Betfair.se before proceeding.
SWEDEN_BANK_ID_VERIFICATION_REQUIRED	You must provided your Swedish bank id via Betfair.se before proceeding.

TRADING_MASTER	Trading Master Account
TRADING_MASTER_SUSPENDED	Suspended Trading Master Account

Page History

Versions Compared

Old Version 58

New Version 59

Key

Overview and limitations

URL Definition (Global)

Other Jurisdictions

Parameters (POST)

Headers

POST Example

Payload

Curl call sample

Example of a successful login:

Response Structure

Status Values

Status Codes & Error values

Possible failure and exceptional return codes