Page History

...

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)

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

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

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

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

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

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.

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

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