BetterOff External API documentation version v1

https://api-lewisham.betteroff.org.uk/external/v1

Test/Production URLs

The URLs shown in this document indicate the API endpoints in the production environment. To access the API in a test environment instead, replace www with www2 or api with api2.

Example Production API URLs

https://lewisham.betteroff.org.uk/#/oauth
https://api-lewisham.betteroff.org.uk/oauth/token

Equivalent Test Environment URLs

https://lewisham2.betteroff.org.uk/#/oauth
https://api-lewisham-2.betteroff.org.uk/oauth/token

Introduction

To invoke the API endpoints, a client must first obtain an OAuth2 access token and submit this token with each API request. A client obtains an API token by authenticating with the BetterOff (BO) OAuth2 provider. Readers unfamiliar with OAuth2 should first read this short article - from the beginning until the end of the Web Server Apps section - to familiarize themselves with the concepts involved.

Client Registration

Applications wishing to use BO as an OAuth2 provider must register themselves specifying a client ID, secret and one or more redirect URIs. The purpose of these is explained below

Client ID: uniquely identifies an OAuth2 client (analogous to a username)
Client Secret: a secret shared by the client and BO that is used to authenticate the client (analogous to a password)
Redirect URIs: during the OAuth2 authentication process an authorization code is sent from BO to the client. The redirect URI indicates the address (within the client) to which this code should be sent. Typically, one URL is registered for each client environment (staging, production, etc.)

Authenticating with OAuth2

oauth authentication sequence

Authorization Code Request

To initiate the process, the user clicks on a link (or similar) in the client application that issues a HTTP GET request to the following URL

https://lewisham.betteroff.org.uk/#/oauth?response_type=code&client_id=${client_id}&scope=profile&redirect_uri=${redirect_uri}&state=${state}

The ${placeholders} shown in this URL should be replaced with these URL-encoded values

client_id the identity assigned to this client during registration
redirect_uri the URI to which the authorization code will be send. This must match one of the redirect URIs specified during registration
state this parameter is recommended (but not mandatory) as it prevents cross-site request forgery vulnerabilities. The value of this parameter should be a pseudo-random unguessable value and it must be stored within the client application (the server-side session is often used).
scope this parameter defines the operations that a client can perform. If multiple scopes are requested, they should be spearated by a space. The available scopes are
- profile read a user's profile
- snapshot read/write a user's income snapshot
- scenario read/write a user's income scenarios
- entitlement read/write a user's benefit entitlements

When the URL above is requested, the browser will display the BO OAuth page. This page requires the user to login to BO if they are not already authenticated. Following authentication, a dialog is displayed that asks the user if they consent to the client application accessing their BOK data. If consent is given, an authorization code will be sent to the specified redirect URL.

Authorization Code Response

Success

For example, if the authorization code generated by BO was foo, and the redirect URI and state parameters specified by the client in the request were http://example.com/callback and RandomSecret, the browser will redirect to the following URL

http://example.com/callback?code=foo&state=RandomSecret

If a state parameter was included in the authorization code request, the same parameter should be included in the response. It is the responsibility of the client to check that the response parameter matches the request parameter, and to abandon the authentication process if they do not.

Failure

If an authorization code request is unsuccessful because the user did not consent to sharing their data with the client, the redirect URL will be called back with the parameters shown below instead

http://example.com/callback?error=access_denied&error_description=User%20denied%20access

Access Token

The final step in the process requires the client to exchange the authorization code from the previous step for an access token by issuing a HTTP POST request to https://api-lewisham.betteroff.org.uk/oauth/token

with the following parameters:

scope=${scope}&grant_type=authorization_code&code=${auth_code}&client_id=${client_id}&client_secret=${client_secret}&redirect_uri=${redirect_uri}

The ${placeholders} shown above should be replaced with the following x-www-form-urlencoded values

scope the scope defines the operations that a client can perform. If multiple scopes from the list above are needed, they should be separated by a space
auth_code the authorization code received during the previous step
client_id the identity assigned to this client during registration
client_secret the secret assigned to this client during registration
redirect_uri the same redirect URI that was used in the authorization code request

Success

If the access token request is successful, a JSON response similar to the following will be received

{
  "access_token":"1e0c011d-6451-40f3-aea9-4ab1ddfe2503",
  "token_type":"bearer",
  "refresh_token":"f98f274a-3ab6-40d1-ae8e-447bee60fc79",
  "expires_in":43199,
  "scope":"profile",
  "username":"5bc21915-7bf2-4516-913a-2d62398616d4"
}

The fields in the response are described below

access_token an token that is used when accessing the BO API endpoints
token_type the type of access token
refresh_token this token can be used to refresh/renew an access token to prevent it from expiring
expires_in the number of seconds remaining until this token expires
scope the scope of the access token
username a unique identifier used within BO for the authenticated user

Failure

If an access token request fails, a JSON response such as that shown below will be returned instead (in this example the failure was caused by an invalid client ID)

{
  "error": "invalid_client",
  "error_description": "Bad client credentials"
}

Access Token Refresh

By default, access tokens expire 12 hours after they are issued, as indicated by the expires_in property in the example access token response (43,200 seconds = 12 hours). A refresh_token is issued alongside each access token, which expires after 30 days by default. It is possible to use (an unexpired) refresh token to obtain a new access token in order to effectively extend the access token’s lifespan. If a refresh token is used to refresh an access token that has not yet expired, a new access token will be issued, and the original access token will be invalidated.

An access token can be refreshed by making a HTTP POST request to https://api-lewisham.betteroff.org.uk/oauth/token with the following parameters:

scope=profile&grant_type=refresh_token&refresh_token=${refresh_token}&client_id=${client_id}&client_secret=${client_secret}

The ${placeholders} shown above should be replaced with the following x-www-form-urlencoded values

refresh_token the refresh token that was received in the access token’s response
client_id the identity assigned to this client during registration
client_secret the secret assigned to this client during registration

The response to an access token refresh request is identical to that of an access token request (see above).

API endpoints

/userProfile

/userProfile get

get

Get the current user's profile

Request
Response

Headers

Authorization: required (string)
A bearer token whose value is the access token issued during (OAuth2) authentication. This endpoint is only accessible to clients that include profile in the requested (OAuth2) scopes when authenticating.
Example:
```
Bearer 7b1b8198-a35e-4186-b509-160161af2a5a
```

HTTP status code 200

The fields shown in the example response are mandatory and not nullable unless stated otherwise below

Nullable Fields

email
imageUrl

Optional Fields

The fields listed below may be omitted from the response entirely

claims A list of OAuth providers that can be user to sign in to this account. The properties shown for each provider may change over time and from one user to another, e.g. the Facebook email field will be omitted if the user chooses not to share their email address when they create a BetterOff account using Facebook.

Body

Type: application/json

Example:

{
  "name": "John Doe",
  "email": "john@example.com",
  "username": "73cbe7cb-5c8d-46de-87ea-b13518b4d847",
  "imageUrl": "https://example.com/foo.jpg",
  "roleNames": [
    "ROLE_USER"
  ],
  "registrationTime": "2015-09-30T14:12:32Z",
  "postcode": "HD1 2UD",
  "claims": {
    "facebook": {
      "picture": "https://example.com/foo.jpg",
      "first_name": "Seán",
      "email": "john-facebook@example.com",
      "name": "Seán Doe",
      "last_name": "Doe"
    },
    "google": {
      "id": "102691171464652848237",
      "picture": "https://lh4.googleusercontent.com/AAAAAAAAAAw/yjrIKwv8/photo.jpg",
      "email": "john.google@example.com",
      "name": "John Doe",
      "locale": "en_GB",
      "family_name": "Doe",
      "verified_email": "true",
      "given_name": "Johnny"
    },
    "enfield": {
      "authmethod": "OAuth2",
      "lastname": "Doe",
      "anonymous": "False",
      "http://identityserver.thinktecture.com/claims/client": "BetterOffLocalDev2",
      "emailaddress": "john.doe@example.com",
      "http://identityserver.thinktecture.com/claims/scope": "https://localhost:8443/oauth/callback/enfield",
      "unique_name": "john.doe@example.com",
      "primarysid": "1db9c75e-b766-e511-8147-fc15b426be0c",
      "address1_postalcode": "EN1 3XA",
      "authenticationlevel": "1",
      "address1_city": "Enfield",
      "ispersistent": "True",
      "sid": "ed240458-b766-e511-8147-fc15b426be0c",
      "iss": "https://authuat.dev.enfield.gov.uk/identity/",
      "nbf": "1443713759",
      "nameid": "john.doe@example.com",
      "firstname": "John",
      "logicalname": "Contact",
      "auth_time": "2015-10-01T15:35:59.566Z",
      "address1_line2": "Silver Street",
      "exp": "1443742559",
      "address1_line1": "Civic Centre",
      "nameidentifier": "1db9c75e-b766-e511-8147-fc15b426be0c",
      "aud": "https://localhost:8443/oauth/callback/enfield",
      "salutation": "Mr"
    }
  }
}

HTTP status code 400

The request sent by the client was invalid. The error messages are returned in a JSON array.

Body

Type: application/json

Example:

{"errors":[{"error":"Invalid token: no-such-token"}]}

HTTP status code 401

Unauthorized. User has not autheticated or the token presented is invalid

HTTP status code 403

Access denied

HTTP status code 404

Resource was not found

HTTP status code 405

HTTP method not allowed

HTTP status code 500

Server error. An error occurred within BetterOff

/entitlements

/entitlements get post

get

Get the current user's entitlements

post

Save a user's entitlements. Any entitlements that already exist will be replaced. All the fields shown in the example are mandatory, except for the entitlement code.

Get the current user's entitlements

Request
Response

Headers

Authorization: required (string)
A bearer token whose value is the access token issued during (OAuth2) authentication. This endpoint is only accessible to clients that include entitlement in the requested (OAuth2) scopes when authenticating.
Example:
```
Bearer 7b1b8198-a35e-4186-b509-160161af2a5a
```

HTTP status code 200

Body

Type: application/json

Example:

[
  {
    "code": "housing_benefit",
    "definite": true,
    "name": "Housing benefit"
  },
  {
    "code": "tax_credit",
    "definite": true,
    "name": "Tax Credit"
  }
]

HTTP status code 400

The request sent by the client was invalid. The error messages are returned in a JSON array.

Body

Type: application/json

Example:

{"errors":[{"error":"Invalid token: no-such-token"}]}

HTTP status code 401

Unauthorized. User has not autheticated or the token presented is invalid

HTTP status code 403

Access denied

HTTP status code 404

Resource was not found

HTTP status code 405

HTTP method not allowed

HTTP status code 500

Server error. An error occurred within BetterOff

Save a user's entitlements. Any entitlements that already exist will be replaced. All the fields shown in the example are mandatory, except for the entitlement code.

Request
Response

Headers

Authorization: required (string)
A bearer token whose value is the access token issued during (OAuth2) authentication. This endpoint is only accessible to clients that include entitlement in the requested (OAuth2) scopes when authenticating.
Example:
```
Bearer 7b1b8198-a35e-4186-b509-160161af2a5a
```

Body

Type: application/json

Example:

{
  "entitlements": [
    {
      "code": "housing_benefit",
      "name": "Housing benefit",
      "definite": true
    },
    {
      "name": "Tax Credit",
      "definite": false
    }
  ]
}

HTTP status code 201

The entitlements were successfully saved

Body

Type: application/json

Example:

[
  {
    "code": "housing_benefit",
    "definite": true,
    "name": "Housing benefit"
  },
  {
    "code": "tax_credit",
    "definite": true,
    "name": "Tax Credit"
  }
]

HTTP status code 400

The request sent by the client was invalid. The error messages are returned in a JSON array.

Body

Type: application/json

Example:

{"errors":[{"error":"Invalid token: no-such-token"}]}

HTTP status code 401

Unauthorized. User has not autheticated or the token presented is invalid

HTTP status code 403

Access denied

HTTP status code 404

Resource was not found

HTTP status code 405

HTTP method not allowed

HTTP status code 500

Server error. An error occurred within BetterOff

/incomeSnapshot

/incomeSnapshot get post

get

Get the current user's most recent income snapshot

post

Save a new income snapshot. The names used for the incomes and benefits must be unique within an income snapshot.

Get the current user's most recent income snapshot

Request
Response

Headers

Authorization: required (string)
A bearer token whose value is the access token issued during (OAuth2) authentication. This endpoint is only accessible to clients that include snapshot in the requested (OAuth2) scopes when authenticating.
Example:
```
Bearer 7b1b8198-a35e-4186-b509-160161af2a5a
```

HTTP status code 200

Body

Type: application/json

Example:

{
  "data": {
    "annualValue": 10957.5,
    "benefitAnnualValue": 7305,
    "incomeAnnualValue": 3652.5,
    "dateCreated": "2015-11-18T10:50:19Z",
    "benefits": [
      {
        "amount": 10,
        "annualValue": 3652.5,
        "frequency": "Daily",
        "id": 1,
        "name": "housing",
        "entitlement": null
      },
      {
        "amount": 10,
        "annualValue": 3652.5,
        "frequency": "Daily",
        "id": 2,
        "name": "child benefit",
        "entitlement": "child_benefit"
      }
    ],
    "id": 1,
    "incomes": [
      {
        "amount": 10,
        "annualValue": 3652.5,
        "frequency": "Daily",
        "id": 1,
        "name": "part-time hairdressing",
        "entitlement": null
      }
    ]
  }
}

HTTP status code 400

The request sent by the client was invalid. The error messages are returned in a JSON array.

Body

Type: application/json

Example:

{"errors":[{"error":"Invalid token: no-such-token"}]}

HTTP status code 401

Unauthorized. User has not autheticated or the token presented is invalid

HTTP status code 403

Access denied

HTTP status code 404

No income snapshots found for the current user

HTTP status code 405

HTTP method not allowed

HTTP status code 500

Server error. An error occurred within BetterOff

Save a new income snapshot. The names used for the incomes and benefits must be unique within an income snapshot.

Request
Response

Headers

Authorization: required (string)
A bearer token whose value is the access token issued during (OAuth2) authentication. This endpoint is only accessible to clients that include snapshot in the requested (OAuth2) scopes when authenticating.
Example:
```
Bearer 7b1b8198-a35e-4186-b509-160161af2a5a
```

Body

Type: application/json

Example:

{
  "benefits": [
    {
      "amount": 10,
      "name": "housing",
      "frequency": "Daily",
      "entitlement": "housing_benefit"
    }
  ],
  "incomes": [
    {
      "amount": 10,
      "name": "share dividends",
      "frequency": "Daily"
    },
    {
      "amount": 10,
      "name": "online sales of ShamWow",
      "frequency": "Daily"
    }
  ]
}

HTTP status code 201

The income snapshot was successfully saved

Body

Type: application/json

Example:

{
  "data": {
    "annualValue": 10957.5,
    "benefitAnnualValue": 7305,
    "incomeAnnualValue": 3652.5,
    "dateCreated": "2015-11-18T10:50:19Z",
    "benefits": [
      {
        "amount": 10,
        "annualValue": 3652.5,
        "frequency": "Daily",
        "id": 1,
        "name": "housing",
        "entitlement": null
      },
      {
        "amount": 10,
        "annualValue": 3652.5,
        "frequency": "Daily",
        "id": 2,
        "name": "child benefit",
        "entitlement": "child_benefit"
      }
    ],
    "id": 1,
    "incomes": [
      {
        "amount": 10,
        "annualValue": 3652.5,
        "frequency": "Daily",
        "id": 1,
        "name": "part-time hairdressing",
        "entitlement": null
      }
    ]
  }
}

HTTP status code 400

The request sent by the client was invalid. The error messages are returned in a JSON array.

Body

Type: application/json

Example:

{"errors":[{"error":"Invalid token: no-such-token"}]}

HTTP status code 401

Unauthorized. User has not autheticated or the token presented is invalid

HTTP status code 403

Access denied

HTTP status code 404

Resource was not found

HTTP status code 405

HTTP method not allowed

HTTP status code 500

Server error. An error occurred within BetterOff

/incomeScenario

Collection of income scenarios owned by the current user

/incomeScenario get options post

get

Get a list of income scenarios owned by the current user

options

Returns the list of HTTP methods supported by this endpoint

post

Save a new income scenario. The names used for the incomes and benefits must be unique within an income scenario.

Get a list of income scenarios owned by the current user

Request
Response

Headers

Authorization: required (string)
A bearer token whose value is the access token issued during (OAuth2) authentication. This endpoint is only accessible to clients that include scenario in the requested (OAuth2) scopes when authenticating.
Example:
```
Bearer 7b1b8198-a35e-4186-b509-160161af2a5a
```

Query Parameters

evaluationPeriod: (one of Daily, Weekdays, Weekly, Fortnightly, Four-weekly, 13-weekly, Monthly, Yearly - default: Yearly)
Defines the length of period for which the scenario will be evaluated
max: (number - default: 50)
Maximum number of results in one response
offset: (number - default: 0)
Index of the first result to be included
sort: (string)
The property name used to sort the results
sort direction: (one of asc, desc)
Indicates whether the results should be sorted in ascending or descending order

HTTP status code 200

Body

Type: application/json

Example:

{
  "data": [
    {
      "period": "Yearly",
      "periodicDeltaBenefitTotal": 3652.5,
      "periodicDeltaIncomeTotal": 0,
      "snapshotBenefitTotal": 0,
      "snapshotIncomeTotal": 7305,
      "title": "scenario1",

      "benefits": [
        {
          "amount": 10,
          "frequency": "Daily",
          "name": "housing benefit",
          "operation": "Add",
          "periodicDelta": 3652.5,
          "valid": true,
          "entitlement": "housing_benefit"
        },
        {
          "amount": 30,
          "frequency": "Daily",
          "name": "changed benefit",
          "operation": "Change",
          "periodicDelta": null,
          "valid": false,
          "entitlement": null
        }
      ],
      "id": 2,
      "incomes": [
        {
          "amount": 20,
          "frequency": "Daily",
          "name": "removed income",
          "operation": "Remove",
          "periodicDelta": null,
          "valid": false,
          "entitlement": null
        }
      ]

    },
    {
      "period": "Yearly",
      "periodicDeltaBenefitTotal": 3652.5,
      "periodicDeltaIncomeTotal": 0,
      "snapshotBenefitTotal": 0,
      "snapshotIncomeTotal": 7305,
      "title": "scenario2",

      "benefits": [
        {
          "amount": 10,
          "frequency": "Daily",
          "name": "added benefit",
          "operation": "Add",
          "periodicDelta": 3652.5,
          "valid": true,
          "entitlement": null
        },
        {
          "amount": 30,
          "frequency": "Daily",
          "name": "changed benefit",
          "operation": "Change",
          "periodicDelta": null,
          "valid": false,
          "entitlement": null
        }
      ],
      "id": 1,
      "incomes": [
        {
          "amount": 20,
          "frequency": "Daily",
          "name": "removed income",
          "operation": "Remove",
          "periodicDelta": null,
          "valid": false,
          "entitlement": null
        }
      ]
    }
  ],
  "errors": [],
  "max": 50,
  "offset": 0,
  "total": 2
}

HTTP status code 400

The request sent by the client was invalid. The error messages are returned in a JSON array.

Body

Type: application/json

Example:

{"errors":[{"error":"Invalid token: no-such-token"}]}

HTTP status code 401

Unauthorized. User has not autheticated or the token presented is invalid

HTTP status code 403

Access denied

HTTP status code 404

Resource was not found

HTTP status code 405

HTTP method not allowed

HTTP status code 500

Server error. An error occurred within BetterOff

Returns the list of HTTP methods supported by this endpoint

Request
Response

Headers

Authorization: required (string)
A bearer token whose value is the access token issued during (OAuth2) authentication. This endpoint is only accessible to clients that include scenario in the requested (OAuth2) scopes when authenticating.
Example:
```
Bearer 7b1b8198-a35e-4186-b509-160161af2a5a
```

HTTP status code 200

Headers

Allow: required (string)
The list of HTTP methods supported by this endpoint
Example:
```
GET, POST, PUT, DELETE, OPTIONS
```

HTTP status code 400

The request sent by the client was invalid. The error messages are returned in a JSON array.

Body

Type: application/json

Example:

{"errors":[{"error":"Invalid token: no-such-token"}]}

HTTP status code 401

Unauthorized. User has not autheticated or the token presented is invalid

HTTP status code 403

Access denied

HTTP status code 404

Resource was not found

HTTP status code 405

HTTP method not allowed

HTTP status code 500

Server error. An error occurred within BetterOff

Save a new income scenario. The names used for the incomes and benefits must be unique within an income scenario.

Request
Response

Headers

Authorization: required (string)
A bearer token whose value is the access token issued during (OAuth2) authentication. This endpoint is only accessible to clients that include scenario in the requested (OAuth2) scopes when authenticating.
Example:
```
Bearer 7b1b8198-a35e-4186-b509-160161af2a5a
```

Query Parameters

evaluationPeriod: (one of Daily, Weekdays, Weekly, Fortnightly, Four-weekly, 13-weekly, Monthly, Yearly - default: Yearly)
Defines the length of period for which the scenario will be evaluated

Body

Type: application/json

Example:

{
  "title": "my scenario",
  "benefits": [
    {
      "amount": 10,
      "name": "housing",
      "frequency": "Daily",
      "operation": "Add",
      "entitlement": "housing_benefit"
    }
  ],
  "incomes": [
    {
      "amount": 10,
      "name": "part-time hairdressing",
      "frequency": "Daily",
      "operation": "Remove"
    },
    {
      "amount": 10,
      "name": "leaflet delivery",
      "frequency": "Daily",
      "operation": "Change"
    }
  ]
}

HTTP status code 201

Saving the income scenario succeeded

Body

Type: application/json

Example:

{
  "period": "Yearly",
  "periodicDeltaBenefitTotal": 3652.5,
  "periodicDeltaIncomeTotal": 0,
  "snapshotBenefitTotal": 0,
  "snapshotIncomeTotal": 7305,
  "title": "my scenario",

  "data": {
    "benefits": [
      {
        "amount": 10,
        "frequency": "Daily",
        "name": "housing benefit",
        "operation": "Add",
        "periodicDelta": 3652.5,
        "valid": true,
        "entitlement": "housing_benefit"
      }
    ],
    "id": 4,
    "incomes": [
      {
        "amount": 10,
        "frequency": "Daily",
        "name": "part-time job",
        "operation": "Remove",
        "periodicDelta": null,
        "valid": false,
        "entitlement": null
      }
    ]
  },
  "errors": []
}

HTTP status code 400

The request sent by the client was invalid. The error messages are returned in a JSON array.

Body

Type: application/json

Example:

{"errors":[{"error":"Invalid token: no-such-token"}]}

HTTP status code 401

Unauthorized. User has not autheticated or the token presented is invalid

HTTP status code 403

Access denied

HTTP status code 404

Resource was not found

HTTP status code 405

HTTP method not allowed

HTTP status code 500

Server error. An error occurred within BetterOff

/incomeScenario/{id} put delete

put

Update an income scenario. The names used for the incomes and benefits must be unique within an income scenario.

delete

Delete an income scenario owned by the current user

Update an income scenario. The names used for the incomes and benefits must be unique within an income scenario.

Request
Response

URI Parameters

id: required (string)

Headers

Authorization: required (string)
A bearer token whose value is the access token issued during (OAuth2) authentication. This endpoint is only accessible to clients that include scenario in the requested (OAuth2) scopes when authenticating.
Example:
```
Bearer 7b1b8198-a35e-4186-b509-160161af2a5a
```

Query Parameters

evaluationPeriod: (one of Daily, Weekdays, Weekly, Fortnightly, Four-weekly, 13-weekly, Monthly, Yearly - default: Yearly)
Defines the length of period for which the scenario will be evaluated

Body

Type: application/json

Example:

{
  "title": "my scenario",
  "benefits": [
    {
      "amount": 10,
      "name": "housing",
      "frequency": "Daily",
      "operation": "Add",
      "entitlement": "housing_benefit"
    }
  ],
  "incomes": [
    {
      "amount": 10,
      "name": "part-time hairdressing",
      "frequency": "Daily",
      "operation": "Remove"
    },
    {
      "amount": 10,
      "name": "leaflet delivery",
      "frequency": "Daily",
      "operation": "Change"
    }
  ]
}

HTTP status code 200

Body

Type: application/json

Example:

{
  "period": "Yearly",
  "periodicDeltaBenefitTotal": 3652.5,
  "periodicDeltaIncomeTotal": 0,
  "snapshotBenefitTotal": 0,
  "snapshotIncomeTotal": 7305,
  "title": "my scenario",

  "data": {
    "benefits": [
      {
        "amount": 10,
        "frequency": "Daily",
        "name": "housing benefit",
        "operation": "Add",
        "periodicDelta": 3652.5,
        "valid": true,
        "entitlement": "housing_benefit"
      }
    ],
    "id": 4,
    "incomes": [
      {
        "amount": 10,
        "frequency": "Daily",
        "name": "part-time job",
        "operation": "Remove",
        "periodicDelta": null,
        "valid": false,
        "entitlement": null
      }
    ]
  },
  "errors": []
}

HTTP status code 400

The request sent by the client was invalid. The error messages are returned in a JSON array.

Body

Type: application/json

Example:

{"errors":[{"error":"Invalid token: no-such-token"}]}

HTTP status code 401

Unauthorized. User has not autheticated or the token presented is invalid

HTTP status code 403

Access denied

HTTP status code 404

Resource was not found

HTTP status code 405

HTTP method not allowed

HTTP status code 500

Server error. An error occurred within BetterOff

Delete an income scenario owned by the current user

Request
Response

URI Parameters

id: required (string)

Headers

Authorization: required (string)
A bearer token whose value is the access token issued during (OAuth2) authentication. This endpoint is only accessible to clients that include scenario in the requested (OAuth2) scopes when authenticating.
Example:
```
Bearer 7b1b8198-a35e-4186-b509-160161af2a5a
```

HTTP status code 204

The income scenario was successfully deleted

HTTP status code 400

The request sent by the client was invalid. The error messages are returned in a JSON array.

Body

Type: application/json

Example:

{"errors":[{"error":"Invalid token: no-such-token"}]}

HTTP status code 401

Unauthorized. User has not autheticated or the token presented is invalid

HTTP status code 403

Access denied

HTTP status code 404

Resource was not found

HTTP status code 405

HTTP method not allowed

HTTP status code 500

Server error. An error occurred within BetterOff

BetterOff External API documentation version v1

Environments

Test/Production URLs

Example Production API URLs

Equivalent Test Environment URLs

API Authentication

Introduction

Client Registration

Authenticating with OAuth2

Authorization Code Request

Authorization Code Response

Success

Failure

Access Token

Success

Failure

Access Token Refresh

API endpoints

/userProfile

/userProfile get

/entitlements

/entitlements get post

/incomeSnapshot

/incomeSnapshot get post

/incomeScenario

/incomeScenario get options post

/incomeScenario/{id} put delete

BetterOff External API documentation version v1

Test/Production URLs

Example Production API URLs

Equivalent Test Environment URLs

Introduction

Client Registration

Authenticating with OAuth2

Authorization Code Request

Authorization Code Response

Success

Failure

Access Token

Success

Failure

Access Token Refresh

/userProfile

get /userProfile

Headers

HTTP status code 200

Nullable Fields

Optional Fields

Body

HTTP status code 400

Body

HTTP status code 401

HTTP status code 403

HTTP status code 404

HTTP status code 405

HTTP status code 500

/entitlements

get /entitlements

Headers

HTTP status code 200

Body

HTTP status code 400

Body

HTTP status code 401

HTTP status code 403

HTTP status code 404

HTTP status code 405

HTTP status code 500

post /entitlements

Headers

Body

HTTP status code 201

Body

HTTP status code 400

Body

HTTP status code 401

HTTP status code 403

HTTP status code 404

HTTP status code 405

HTTP status code 500

/incomeSnapshot

get /incomeSnapshot

Headers

HTTP status code 200

Body

HTTP status code 400

Body

HTTP status code 401

HTTP status code 403

HTTP status code 404

HTTP status code 405

HTTP status code 500

post /incomeSnapshot

Headers

Body

HTTP status code 201

Body

HTTP status code 400

Body

HTTP status code 401

HTTP status code 403

HTTP status code 404

HTTP status code 405

HTTP status code 500

/incomeScenario

get /incomeScenario

Headers