Overview and limitationsThe 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)https://identitysso.betfair.com/api/login |
Other JurisdictionsPlease use the below if your country of residence is in one of the list jurisdictions. Jurisdiction | Endpoint |
---|
Australia | https:
| Italy | https:
| Spain | https: | Romania | https: | Sweden | https:
|
Parameters (POST) | | |
---|
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 | | |
---|
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 |
Overview and limitationsThe 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)https://identitysso.betfair.com/api/login |
Other JurisdictionsPlease use the below if your country of residence is in one of the list jurisdictions. Jurisdiction | Endpoint |
---|
Australia | https:
| Italy | https:
| Spain | https: | Romania | https: | Sweden | https:
|
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. | |
HeadersName | 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 ExampleAccept: application/json X-Application: <AppKey> : application/x-www-form-urlencoded URL endpoint: https://identitysso.betfair.com/api/login Payloadusername=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 ValuesSUCCESS
LIMITED_ACCESS
LOGIN_RESTRICTED
FAIL |
Status Codes & Error valuesThe 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 | 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 | 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_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_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. |
|
|
|
|
The presence of the "Accept: application/json" will signal SSO that it should respond with JSON and not with a HTML page. POST ExampleAccept: application/json X-Application: <AppKey> : application/x-www-form-urlencoded URL endpoint: https://identitysso.betfair.com/api/login Payloadusername=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 ValuesSUCCESS
LIMITED_ACCESS
LOGIN_RESTRICTED
FAIL |
Status Codes & Error valuesThe 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} |
{
"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_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 | 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 | 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_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_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. |
|