Betterview API is an insurance-specific API that allows access to a vast amount of data, including Nearmap RSI (Roof Spotlight Index), Peril Vulnerability Scores, and PartnerHub data graphs (third-party data) via the PropertyInsight and PropertyNow APIs.

To make a call to the Betterview API, you must authenticate using Auth0 to retrieve a Bearer Token that is valid for 24 hours. Once retrieved, this token will allow use of all Betterview APIs until expiration at which point another token needs to be generated.

Authentication

Betterview uses Auth0 to provide for bearer token auth. The auth workflow with Betterview API works with the following steps:

1. Make a call to the Auth0 endpoint at: https://betterview.auth0.com/oauth/token.
2. Receive a token back in the response.
3. Use that token until expiration. The token is valid for 24 hours and its expiration date is included in the token response.

The API reference has lots of references on how to apply the bearer token. Basically, one creates an authorization header that looks something like this:

Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ik4wSkdNVE0yT1VaRU9FRXdSVEJFTlVRM1FrTXlNalkxUmpnMVJUTTNNakJCTURSQk56QkNNZyJ9...

Token Retrieval Request

You need a Client ID and Secret from Betterview to retrieve a token. To get a secret and API key, contact Betterview. From there, the following example demonstrates how to retrieve a token.

curl --request POST \
  --url https://betterview.auth0.com/oauth/token \
  --header 'content-type: application/json' \
  --data '{"client_id":"<Client ID Here>","client_secret":"<Client Secret Here>","audience":"https://api.betterview.net","grant_type":"client_credentials"}'

More documentation on this initial request can be seen at Auth0: https://auth0.com/docs/api/authentication#get-token

Token Retrieval Response

Once a token has been requested, the response should look something like this:

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IlJEQTFNRFV5UWpRM1JqZ3lSamRGUlVNNE1VWTNPVEV4UTBVMVF6ZEJOVU0yUmprd01VTkZRUSJ9...",
    "expires_in": 86400,
    "token_type": "Bearer"
}

• The field, access_token is the string that one needs to make requests. The string has, largely, been redacted here to save space.
• The field, expires_in is how long, in seconds, before the token expires. To save opening a calculator, 86400 seconds = 24 hours.
• The field token_type just indicates that the token should be used with Bearer authentication.

IMPORTANT: It is recommended that you store the auth token somewhere and use it for the 24 hours before it expires. If this isn't done, and the API hits are frequent enough, we may come back and ask to have the token stored somewhere.