{
  "aid": "swaggerhub.bebettor-dev:bebettor-api-1.2.1",
  "name": "beBettor API",
  "type": "Index",
  "description": "<p><strong>FOR PUBLIC USE ONLY.</strong></p>\n<h2>1. Overview</h2> <p>The beBettor API provides an automated and scalable solution for customer affordability screening. The data we provide helps our clients improve their customer interaction frameworks, develop deeper insights into their customers, design safer online experiences and make more informed business decisions.</p> <p>To learn more about our mission and approach, visit <a href=\"https://www.bebettor.com\" target=\"_blank\">www.bebettor.com</a>.</p> <p>The beBettor API provides the following core functionality:</p>\n<h3>Check</h3> <p>Performs an affordability screening based on the provided customer data.</p> <strong>Interaction flow:</strong> <ol>\n  <li><p>The client initiates a check by including the customer's personal data in the request body.</p></li>\n  <li><p>The beBettor API processes the request and returns the <em>checkId</em>, <em>score</em> and <em>flags</em>.</p></li>\n</ol> <br /> <p><img src=\"https://www.bebettor.com/assets/api-docs/api-schema-c1.png\" alt=\"API Interaction - Check\" /></p> <br />\n<h3>Report</h3> <p>Retrieves a report containing additional data points that complement the results of an initial check. These reports can be used to further support the <em>score</em> and <em>flags</em> returned during the check.</p> <strong>Interaction flow:</strong> <ol>\n  <li><p>The client sends a request to retrieve a report by including the <em>checkId</em> in the request.</p></li>\n  <li><p>The beBettor API returns a structured report containing multiple parameter groups with supporting data.</p></li>\n</ol> <br /> <p><img src=\"https://www.bebettor.com/assets/api-docs/api-schema-c2.png\" alt=\"API Interaction - Report\" /></p> <br />\n<h2>2. Environments</h2> <p>The beBettor API provides two distinct environments for integration. Use the <em>Test</em> environment to validate your integration before going live. Once your integration is complete and tested, switch to the <em>Production</em> environment to begin processing real customer data.</p> <table>\n  <thead>\n    <tr>\n      <th width=\"25%\">Environment</th>\n      <th>Endpoint URL</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>Test</td>\n      <td>https://sandbox-api.bebettor.com/affordability/v1</td>\n    </tr>\n    <tr>\n      <td>Production</td>\n      <td>https://api.bebettor.com/affordability/v1</td>\n    </tr>\n  </tbody>\n</table> <br />\n<h2>3. API Access</h2> <p>To start integrating with the beBettor API in either the <em>Test</em> or <em>Production</em> environment, the following configuration details are required.</p> <table>\n  <thead>\n    <tr>\n      <th width=\"25%\">Item</th>\n      <th>Description</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>Score Model</td>\n      <td>Some <em>check types</em> support more than one <em>score model</em>, which must be specified during integration. Let us know which <em>score model</em> you'd like to use and it will be applied to all of your requests.</td>\n    </tr>\n    <tr>\n      <td>API Key</td>\n      <td>Access to the beBettor API requires an API key, which will be provided to you prior to integration.</td>\n    </tr>\n  </tbody>\n</table> <br />\n<h2>4. Check Types</h2> <p>The table below outlines the three <em>check types</em> available through the beBettor API.</p> <table>\n  <thead>\n    <tr>\n      <th width=\"25%\">Check Type</th>\n      <th>Description</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>Financial Vulnerability</td>\n      <td>Screens the customer for signs of financial vulnerability and returns a <em>score</em> with associated risk <em>flags</em>.</td>\n    </tr>\n    <tr>\n      <td>Wealth</td>\n      <td>Estimates a customer's relative wealth ranking within the UK and returns a <em>wealth score</em> along with associated <em>flags</em>.</td>\n    </tr>\n    <tr>\n      <td>Discretionary Income</td>\n      <td>Estimates a customer's discretionary income and evaluates key risk indicators. Returns a <em>discretionary income score</em> along with associated risk <em>flags</em>.</td>\n    </tr>\n  </tbody>\n</table> <br />\n<h2>5. Customer Data</h2> <p>The table below outlines the customer personal data fields, including their type, format and constraints.</p> <table>\n  <thead>\n    <tr>\n      <th width=\"5%\">No</th>\n      <th width=\"20%\">Field Name</th>\n      <th width=\"25%\">Data Type</th>\n      <th>Format &amp; Constraints</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>1</td>\n      <td>customerId</td>\n      <td>String</td>\n      <td>Charset: printable ASCII<br />Min length: 1<br />Max length: 100</td>\n    </tr>\n    <tr>\n      <td>2</td>\n      <td>title</td>\n      <td>String</td>\n      <td>Enum: [ MR, MRS, MS, MISS, DR, PROF, SIR ]</td>\n    </tr>\n    <tr>\n      <td>3</td>\n      <td>firstName</td>\n      <td>String</td>\n      <td>Min length: 1<br />Max length: 100</td>\n    </tr>\n    <tr>\n      <td>4</td>\n      <td>lastName</td>\n      <td>String</td>\n      <td>Min length: 1<br />Max length: 100</td>\n    </tr>\n    <tr>\n      <td>5</td>\n      <td>gender</td>\n      <td>String</td>\n      <td>Enum: [ MALE, FEMALE, OTHER ]</td>\n    </tr>\n    <tr>\n      <td>6</td>\n      <td>dateOfBirth</td>\n      <td>String</td>\n      <td>Format: YYYY-MM-DD (RFC 3339)<br />Age must be ≥ 18</td>\n    </tr>\n    <tr>\n      <td>7</td>\n      <td>addressLine1</td>\n      <td>String</td>\n      <td>Min length: 1<br />Max length: 100</td>\n    </tr>\n    <tr>\n      <td>8</td>\n      <td>addressLine2</td>\n      <td>String</td>\n      <td>Min length: 1<br />Max length: 100</td>\n    </tr>\n    <tr>\n      <td>9</td>\n      <td>town</td>\n      <td>String</td>\n      <td>Min length: 1<br />Max length: 100</td>\n    </tr>\n    <tr>\n      <td>10</td>\n      <td>county</td>\n      <td>String</td>\n      <td>Min length: 1<br />Max length: 100</td>\n    </tr>\n    <tr>\n      <td>11</td>\n      <td>postcode</td>\n      <td>String</td>\n      <td>Valid UK postcode</td>\n    </tr>\n  </tbody>\n</table> <br />\n<p>The table below indicates which customer data fields are <strong>required</strong> for each <em>check type</em>. Please note that <strong>optional</strong> fields must either be set to <code>null</code> or excluded from the request. <strong>Empty strings are not allowed.</strong></p> <table>\n  <thead>\n    <tr>\n      <th width=\"5%\">No</th>\n      <th width=\"20%\">Field Name</th>\n      <th width=\"25%\">Financial Vulnerability Check</th>\n      <th width=\"25%\">Wealth Check</th>\n      <th>Discretionary Income Check</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>1</td>\n      <td>customerId</td>\n      <td><strong>Required</strong></td>\n      <td><strong>Required</strong></td>\n      <td><strong>Required</strong></td>\n    </tr>\n    <tr>\n      <td>2</td>\n      <td>title</td>\n      <td>Optional</td>\n      <td>Optional</td>\n      <td>Optional</td>\n    </tr>\n    <tr>\n      <td>3</td>\n      <td>firstName</td>\n      <td><strong>Required</strong></td>\n      <td>Optional</td>\n      <td><strong>Required</strong></td>\n    </tr>\n    <tr>\n      <td>4</td>\n      <td>lastName</td>\n      <td><strong>Required</strong></td>\n      <td>Optional</td>\n      <td><strong>Required</strong></td>\n    </tr>\n    <tr>\n      <td>5</td>\n      <td>gender</td>\n      <td>Optional</td>\n      <td>Optional</td>\n      <td>Optional</td>\n    </tr>\n    <tr>\n      <td>6</td>\n      <td>dateOfBirth</td>\n      <td><strong>Required</strong></td>\n      <td>Optional</td>\n      <td><strong>Required</strong></td>\n    </tr>\n    <tr>\n      <td>7</td>\n      <td>addressLine1</td>\n      <td><strong>Required</strong></td>\n      <td><strong>Required</strong></td>\n      <td><strong>Required</strong></td>\n    </tr>\n    <tr>\n      <td>8</td>\n      <td>addressLine2</td>\n      <td>Optional</td>\n      <td>Optional</td>\n      <td>Optional</td>\n    </tr>\n    <tr>\n      <td>9</td>\n      <td>town</td>\n      <td><strong>Required</strong></td>\n      <td>Optional</td>\n      <td><strong>Required</strong></td>\n    </tr>\n    <tr>\n      <td>10</td>\n      <td>county</td>\n      <td>Optional</td>\n      <td>Optional</td>\n      <td>Optional</td>\n    </tr>\n    <tr>\n      <td>11</td>\n      <td>postcode</td>\n      <td><strong>Required</strong></td>\n      <td><strong>Required</strong></td>\n      <td><strong>Required</strong></td>\n    </tr>\n  </tbody>\n</table> <br />\n<h2>6. Scores</h2> <p>A <em>score model</em> is selected by the client and pre-configured by beBettor during the API integration process. This model is applied by default to all check requests.</p>\n<h3>Financial Vulnerability Check</h3> <p>The <em>vulnerability score</em> indicates whether financial vulnerability is present.</p> <p>The table below outlines the currently supported <em>score models</em> and their associated <em>scores</em>.</p> <table>\n  <thead>\n    <tr>\n      <th width=\"25%\">Score Model</th>\n      <th>Possible Scores</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>GB:M2-VP</td>\n      <td>VULNERABLE, PASS</td>\n    </tr>\n    <tr>\n      <td>GB:M2-RAG</td>\n      <td>RED, AMBER, GREEN</td>\n    </tr>\n  </tbody>\n</table> <br />\n<h3>Wealth Check</h3> <p>The <em>wealth score</em> represents a customer's relative wealth ranking within the UK.</p> <p>The table below outlines the currently supported <em>score models</em> and their associated <em>scores</em>.</p> <table>\n  <thead>\n    <tr>\n      <th width=\"25%\">Score Model</th>\n      <th>Possible Scores</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>GB:J2</td>\n      <td>1, 2, 3, 4, 5, 6, 7, 8, 9, 10</td>\n    </tr>\n    <tr>\n      <td>GB:J3</td>\n      <td>1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20</td>\n    </tr>\n  </tbody>\n</table> <br />\n<h3>Discretionary Income Check</h3> <p>The <em>discretionary income score</em> provides an indication of an individual's affordability.</p> <p>The table below outlines the currently supported <em>score models</em> and their associated <em>scores</em>.</p> <table>\n  <thead>\n    <tr>\n      <th width=\"25%\">Score Model</th>\n      <th>Possible Scores</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>GB:V1</td>\n      <td>A, B, C, D, E, F</td>\n    </tr>\n    <tr>\n      <td>GB:V3</td>\n      <td>A, B, C, D</td>\n    </tr>\n    <tr>\n      <td>GB:V4</td>\n      <td>RED, AMBER, GREEN</td>\n    </tr>\n  </tbody>\n</table> <br />\n<h2>7. Flags</h2> <h3>Financial Vulnerability Check</h3> <p>Financial vulnerability <em>flags</em> indicate additional risk factors associated with the customer.</p> <p>The table below outlines the currently supported <em>flag models</em> and their associated <em>flags</em>.</p> <table>\n  <thead>\n    <tr>\n      <th width=\"25%\">Flags Model</th>\n      <th width=\"40%\">Flags</th>\n      <th>Description</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td rowspan=\"4\">GB:M2</td>\n      <td>INDIVIDUAL_INSOLVENCY_REGISTER_MATCH</td>\n      <td>This <em>flag</em> is triggered when there is a match on the <em>Individual Insolvency</em> register.</td>\n    </tr>\n    <tr>\n      <td>JUDGMENTS_ORDERS_FINES_REGISTER_MATCH</td>\n      <td>This <em>flag</em> is triggered when there is a match on the <em>Judgments, Orders and Fines</em> register.</td>\n    </tr>\n    <tr>\n      <td>LOW_INCOME_SOCIAL_HOUSING</td>\n      <td>This <em>flag</em> is triggered when there is a match on the <em>Social Housing</em> register and identifies the individual as having relatively low income.</td>\n    </tr>\n    <tr>\n      <td>RELATIVE_INCOME_RISK</td>\n      <td>This <em>flag</em> is triggered when the individual is identified as having a relatively low income.</td>\n    </tr>\n  </tbody>\n</table> <br />\n<h3>Wealth Check</h3> <p>Wealth <em>flags</em> indicate additional signs of high wealth associated with the customer.</p> <p>The table below outlines the currently supported <em>flag models</em> and their associated <em>flags</em>.</p> <table>\n  <thead>\n    <tr>\n      <th width=\"25%\">Flags Model</th>\n      <th width=\"40%\">Flag</th>\n      <th>Description</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td rowspan=\"1\">GB:J1</td>\n      <td>SUPER_AFFLUENCE</td>\n      <td>This <em>flag</em> is triggered when the individual is identified as being in the top 1% of wealth within the Great Britain population.</td>\n    </tr>\n  </tbody>\n</table> <br />\n<h3>Discretionary Income Check</h3> <p>Discretionary income <em>flags</em> indicate additional signs of financial risk or vulnerability associated with the customer.</p> <p>The table below outlines the currently supported <em>flag models</em> and their associated <em>flags</em>.</p> <table>\n  <thead>\n    <tr>\n      <th width=\"25%\">Flags Model</th>\n      <th width=\"40%\">Flags</th>\n      <th>Description</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td rowspan=\"3\">GB:V2</td>\n      <td>INDIVIDUAL_INSOLVENCY_REGISTER_MATCH</td>\n      <td>This <em>flag</em> is triggered when there is a match on the <em>Individual Insolvency</em> register.</td>\n    </tr>\n    <tr>\n      <td>SOCIAL_HOUSING_REGISTER_MATCH</td>\n      <td>This <em>flag</em> is triggered when there is a match on the <em>Social Housing</em> register.</td>\n    </tr>\n    <tr>\n      <td>AGE_UNDER_25</td>\n      <td>This <em>flag</em> is triggered when the individual is under 25 years of age.</td>\n    </tr>\n  </tbody>\n</table> <br />\n<h2>8. Reports</h2> <p>Reports provide additional supporting information for your checks and are organized into structured groups of parameters. Each parameter includes the following properties: <code>id</code>, <code>name</code>, <code>value</code> and <code>description</code>. These are defined by a specific <em>report model</em>, which is periodically updated by beBettor as part of ongoing service improvements. You can request a specific <em>report model</em> by setting the appropriate value in the HTTP <code>Accept</code> header. If this header is omitted or set to <code>*/*</code>, the latest available <em>report model</em> will be returned by default.</p> <p>beBettor will continue to support previous <em>report models</em> for a defined transition period after new versions are released. Advance notice will be given before deprecating any older <em>report models</em>. To maintain consistent integration and avoid unexpected changes to report structures, we recommend explicitly specifying the desired <em>report model</em> via the <code>Accept</code> header, rather than relying on the latest version by default.</p>\n<h3>Financial Vulnerability Check</h3> <p>The table below outlines the currently supported <em>report models</em>.</p> <table>\n  <thead>\n    <tr>\n      <th width=\"25%\">Report Model</th>\n      <th width=\"20%\">Status</th>\n      <th>Request Header <code>Accept</code> Value</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>GB:M2-20240521</td>\n      <td>Latest</td>\n      <td><code>application/vnd.report.gb.m2-20240521+json</code></td>\n    </tr>\n  </tbody>\n</table> <br />\n<h3>Wealth Check</h3> <p>Reports are currently not available for this <em>check type</em>.</p> <br />\n<h3>Discretionary Income Check</h3> <p>The table below outlines the currently supported <em>report models</em>.</p> <table>\n  <thead>\n    <tr>\n      <th width=\"25%\">Report Model</th>\n      <th width=\"20%\">Status</th>\n      <th>Request Header <code>Accept</code> Value</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>GB:V20211005</td>\n      <td>Latest</td>\n      <td><code>application/vnd.report.gb.v20211005+json</code></td>\n    </tr>\n  </tbody>\n</table> <br />\n<h2>9. API Usage</h2> <p>The default API request rate limit is <strong>5 requests per second</strong> for both <em>Test</em> and <em>Production</em> environments. Additionally, the <em>Test</em> environment includes a <strong>monthly quota limit of 500 requests</strong>. Custom rate and quota limits can be increased on request. Please contact us if you require adjustments to these defaults.</p> <p>If a client exceeds the allowed rate limit, the request will be throttled and returned with an HTTP <code>429 Too Many Requests</code> error response. Clients receiving throttling responses should implement appropriate retry logic. For more details, please refer to section &quot;10. Retry Policy&quot;.</p> <p>The table below outlines the current rate and quota limits for each environment.</p> <table>\n  <thead>\n    <tr>\n      <th width=\"25%\">Environment</th>\n      <th width=\"30%\">Rate Limit</th>\n      <th>Quota Limit</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>Test</td>\n      <td>5 requests per second</td>\n      <td>500 requests per month, starting on the 1st day</td>\n    </tr>\n    <tr>\n      <td>Production</td>\n      <td>5 requests per second</td>\n      <td>No limit</td>\n    </tr>\n  </tbody>\n</table> <br />\n<h2>10. Retry Policy</h2>\n<p>Errors may occur at different stages of an API request, such as due to network issues or temporary service downtime. To ensure reliability, client applications should implement a robust retry mechanism.</p> <p>A widely adopted strategy is <em>exponential backoff</em>, which increases the delay between retry attempts following consecutive failures. This approach reduces the risk of overwhelming the server during periods of high load and improves the likelihood of successful recovery. For implementation details, refer to external documentation or use libraries that implement <em>exponential backoff</em> logic.</p> <p>The table below outlines common HTTP status codes returned by the API and indicates whether the client should attempt a retry.</p> <table>\n  <thead>\n    <tr>\n      <th width=\"25%\">HTTP Status Code</th>\n      <th width=\"30%\">Meaning</th>\n      <th>Retry Required?</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>4xx</td>\n      <td>Client-side error</td>\n      <td>No</td>\n    </tr>\n    <tr>\n      <td>429</td>\n      <td>Too many requests. The request was throttled.</td>\n      <td>Yes</td>\n    </tr>\n    <tr>\n      <td>5xx</td>\n      <td>Server-side error</td>\n      <td>Yes</td>\n    </tr>\n  </tbody>\n</table> <br />\n<h2>11. Getting Started</h2> <hr /> <p>Below are example API requests for two commonly used tools: <strong>cURL</strong> and <strong>Postman</strong>. The <em>cURL</em> examples are provided as inline code snippets, while the <em>Postman collection</em> file is available for download via the link provided.</p> <h3>API Request Examples</h3> <p><strong>Perform a <em>Financial vulnerability check</em> using the provided customer data.</strong></p> <code>\n    curl -X POST \"https://sandbox-api.bebettor.com/affordability/v1/check\" \\<br />\n      -H \"Content-Type: application/json\" \\<br />\n      -H \"X-Api-Key: {{YOUR_API_KEY}}\" \\<br />\n      -H \"X-BB-Check-Type: VULNERABILITY\" \\<br />\n      -H \"X-BB-Score-Model: {{SCORE_MODEL}}\" \\<br />\n      -d '{\"customerId\":\"CID0001\",\"title\":\"MR\",\"firstName\":\"Joe\",\"lastName\":\"Bloggs\",\"gender\":\"MALE\",\"dateOfBirth\":\"1978-05-20\",\"address\":{\"addressLine1\":\"25 High Street\",\"addressLine2\":\"Flat 4\",\"town\":\"London\",\"county\":\"Greater London\",\"postcode\":\"WC2H 0AW\"}}'\n</code> <br />\n<p><strong>Perform a <em>Wealth check</em> using the provided customer data.</strong></p> <code>\n  curl -X POST \"https://sandbox-api.bebettor.com/affordability/v1/check\" \\<br />\n    -H \"Content-Type: application/json\" \\<br />\n    -H \"X-Api-Key: {{YOUR_API_KEY}}\" \\<br />\n    -H \"X-BB-Check-Type: WEALTH\" \\<br />\n    -H \"X-BB-Score-Model: {{SCORE_MODEL}}\" \\<br />\n    -d '{\"customerId\":\"CID0001\",\"address\":{\"addressLine1\":\"25 High Street\",\"addressLine2\":\"Flat 4\",\"town\":\"London\",\"county\":\"Greater London\",\"postcode\":\"WC2H 0AW\"}}'\n</code> <br />\n<p><strong>Perform a <em>Discretionary income check</em> using the provided customer data.</strong></p> <code>\n  curl -X POST \"https://sandbox-api.bebettor.com/affordability/v1/check\" \\<br />\n    -H \"Content-Type: application/json\" \\<br />\n    -H \"X-Api-Key: {{YOUR_API_KEY}}\" \\<br />\n    -H \"X-BB-Check-Type: DISCRETIONARY_INCOME\" \\<br />\n    -H \"X-BB-Score-Model: {{SCORE_MODEL}}\" \\<br />\n    -d '{\"customerId\":\"CID0001\",\"title\":\"MR\",\"firstName\":\"Joe\",\"lastName\":\"Bloggs\",\"gender\":\"MALE\",\"dateOfBirth\":\"1978-05-20\",\"address\":{\"addressLine1\":\"25 High Street\",\"addressLine2\":\"Flat 4\",\"town\":\"London\",\"county\":\"Greater London\",\"postcode\":\"WC2H 0AW\"}}'\n</code> <br />\n<p><strong>Retrieve a report.</strong></p> <code>\n  curl -X GET \"https://sandbox-api.bebettor.com/affordability/v1/report/{{CHECK_ID}}\" \\<br />\n    -H \"Content-Type: application/json\" \\<br />\n    -H \"X-Api-Key: {{YOUR_API_KEY}}\" \\<br />\n    -H \"Accept: {{REPORT_MODEL}}\"\n</code> <br />\n<p><strong>Search checks that match specific criteria.</strong></p> <code>\n  curl -X GET \"https://sandbox-api.bebettor.com/affordability/v1/search?checkType={{CHECK_TYPE}}&amp;checkDate={{CHECK_DATE}}&amp;checkId={{CHECK_ID}}&amp;customerId={{CUSTOMER_ID}}&amp;pageToken={{PAGE_TOKEN}}\" \\<br />\n    -H \"Content-Type: application/json\" \\<br />\n    -H \"X-Api-Key: {{YOUR_API_KEY}}\"\n</code> <br /> <br />\n<h3>Postman Collection</h3> <p>Get started with the beBettor API by downloading the <em>Postman collection</em> <a href=\"https://www.bebettor.com/assets/api-docs/bebettor-api-public.postman_collection.json\" target=\"_blank\">here</a>.</p> <br />\n<h2>12. API Error Handling</h2> <p>The table below outlines common API response errors, including their HTTP status codes, corresponding error codes and explanations to assist with troubleshooting and resolution.</p> <table>\n  <thead>\n    <tr>\n      <th width=\"25%\">HTTP Status Code</th>\n      <th width=\"30%\">Meaning</th>\n      <th>API Error Codes and Resolutions</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>400 (Bad Request)</td>\n      <td>The server cannot or will not process the request due to a client-side error (e.g., malformed syntax or invalid parameters).</td>\n      <td>\n        <strong>REQUEST_BODY_PARSE_ERROR</strong> - Ensure that your request body is valid JSON with correct syntax and structure.<br /><br />\n        <strong>REQUEST_INVALID</strong> - One or more request parameters are invalid. Review the API documentation for field-specific validation rules.\n      </td>\n    </tr>\n    <tr>\n      <td>401 (Unauthorized)</td>\n      <td>The request could not be completed because it lacks valid authentication credentials for the target resource.</td>\n      <td>\n        <strong>AUTHENTICATION_FAILED</strong> - Ensure that the <code>X-Api-Key</code> header contains the correct API key for the appropriate environment (<em>Test</em> or <em>Production</em>).\n      </td>\n    </tr>\n    <tr>\n      <td>403 (Forbidden)</td>\n      <td>The server understood the request but refuses to authorize it. This means the client's identity is known, but it does not have permission to access the requested resource.</td>\n      <td>\n        <strong>ACCESS_DENIED</strong> - Confirm that the API endpoint URL includes the correct resource path (e.g., <code>/v1/check</code>, <code>/v1/report</code>)\n      </td>\n    </tr>\n    <tr>\n      <td>404 (Not Found)</td>\n      <td>The server could not locate the requested resource. This typically indicates that the URL is incorrect or the resource does not exist.</td>\n      <td>\n        <strong>RESOURCE_NOT_FOUND</strong> - For <code>GET</code> requests to retrieve reports, ensure that the <code>checkId</code> included in the URL is valid and refers to an existing check.\n      </td>\n    </tr>\n    <tr>\n      <td>405 (Method Not Allowed)</td>\n      <td>The server recognizes the requested URL, but the HTTP method used (e.g., <code>GET</code>, <code>POST</code>, <code>PUT</code>, <code>DELETE</code>) is not supported for that resource.</td>\n      <td>\n        <strong>METHOD_NOT_SUPPORTED</strong> - Use the appropriate HTTP method (<code>GET</code> or <code>POST</code>) as specified in the API documentation for the given resource.\n      </td>\n    </tr>\n    <tr>\n      <td>406 (Not Acceptable)</td>\n      <td>The server is unable to generate a response that matches the content type criteria specified in the request's <code>Accept</code> header.</td>\n      <td>\n        <strong>NOT_ACCEPTABLE</strong> - When requesting a report, ensure the request includes an <code>Accept</code> header. Use <code>*/*</code> to receive the latest available version, or specify a particular version (e.g., <code>application/vnd.report.gb.m2-20240521+json</code>) to request a specific <em>report model</em>.\n      </td>\n    </tr>\n    <tr>\n      <td>415 (Unsupported Media Type)</td>\n      <td>The server refuses to process the request because the format of the request payload is not supported. This typically relates to the <code>Content-Type</code> header, which must accurately indicate the format of the request body so the server can parse it correctly.</td>\n      <td>\n        <strong>UNSUPPORTED_MEDIA_TYPE</strong> - Ensure that the <code>Content-Type</code> header is set to <code>application/json</code>, as this is the expected format for all request payloads sent to the beBettor API.\n      </td>\n    </tr>\n    <tr>\n      <td>422 (Unprocessable Entity)</td>\n      <td>The request was syntactically correct but contains invalid or logically inconsistent data that the server cannot process.</td>\n      <td>\n        <strong>POSTCODE_NOT_FOUND</strong> - The postcode format is valid but was not found in the UK postcode directory.<br /><br />\n        <strong>POSTCODE_NOT_COVERED</strong> - The postcode is valid but belongs to a region not supported by the <em>check type</em> (e.g., Channel Islands, UK overseas territories, or Northern Ireland).<br /><br />\n        <strong>PERSON_UNDER_18</strong> - The individual is under 18 years of age and is not eligible for affordability screening.\n      </td>\n    </tr>\n    <tr>\n      <td>429 (Too Many Requests)</td>\n      <td>The server has received too many requests from the client in a short period of time and is enforcing rate limits to maintain system stability and performance.</td>\n      <td>\n        <strong>QUOTA_EXCEEDED</strong> - You have exceeded your monthly request quota in the <em>Test</em> environment. Please contact us if you need to request an increased limit.<br /><br />\n        <strong>THROTTLED</strong> - You have exceeded the API rate limit (5 requests per second). Reduce the request rate to comply with the allowed limits.\n      </td>\n    </tr>\n    <tr>\n      <td>500 (Internal Server Error)</td>\n      <td>The server encountered an unexpected condition that prevented it from fulfilling the request. This is a generic error indicating a problem on the server side, not caused by the client.</td>\n      <td>\n        <strong>Internal Server Error</strong> - Retry the request using an <em>exponential backoff</em> strategy with a reasonable number of attempts. If the issue persists and there is no planned maintenance (check <a href=\"https://status.bebettor.com\" target=\"_blank\">status.bebettor.com</a>), please contact <a href=\"mailto:support@bebettor.com\">support@bebettor.com</a> for further assistance.\n      </td>\n    </tr>\n  </tbody>\n</table> <br />\n<h2>13. Frequently Asked Questions (FAQs)</h2> <h3>API</h3> <table>\n  <thead>\n    <tr>\n      <th width=\"40%\">Question</th>\n      <th>Answer</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>What is the maximum number of requests per second we can send?</td>\n      <td>The default rate limit is 5 requests per second for both <em>Test</em> and <em>Production</em> environments.</td>\n    </tr>\n    <tr>\n      <td>What is the average response time of the API?</td>\n      <td>The average response time is under 500 milliseconds (excluding network round-trip latency).</td>\n    </tr>\n    <tr>\n      <td>Are API requests and responses different for each check type?</td>\n      <td>The request and response formats are consistent across check types. Differences lie in the <em>score model</em>, <em>flags model</em>, and <em>report</em> content associated with each <em>check type</em>.</td>\n    </tr>\n    <tr>\n      <td>How do I switch between check types?</td>\n      <td>Set the HTTP header <code>X-BB-Check-Type</code> to the desired check type. Note: each type may require different mandatory or optional customer fields.</td>\n    </tr>\n    <tr>\n      <td>Which UK regions are supported?</td>\n      <td>All valid UK postcodes in England, Wales, Scotland, and Northern Ireland are supported. The <em>Wealth check</em> supports England, Wales and Scotland only.</td>\n    </tr>\n  </tbody>\n</table>\n<h3>Checks and Reports</h3> <table>\n  <thead>\n    <tr>\n      <th width=\"40%\">Question</th>\n      <th>Answer</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>What is the difference between a check and a report?</td>\n      <td>A check returns a <em>score</em> and <em>risk flags</em>. A report provides structured supporting data across multiple parameter groups. See the &quot;Report Appendix&quot; document for full details.</td>\n    </tr>\n    <tr>\n      <td>Do I need to conduct a check before requesting a report?</td>\n      <td>Yes. Reports can only be retrieved using the <em>checkId</em> returned from a completed <em>check</em>.</td>\n    </tr>\n  </tbody>\n</table>\n<h3>Integration Process</h3> <table>\n  <thead>\n    <tr>\n      <th width=\"40%\">Question</th>\n      <th>Answer</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>How do we begin integration?</td>\n      <td>You'll receive your API key from beBettor and can start integrating immediately.</td>\n    </tr>\n    <tr>\n      <td>Do you provide dummy/test data?</td>\n      <td>Yes. Upon request, we can provide dummy data to support your testing needs.</td>\n    </tr>\n    <tr>\n      <td>Who do we contact for technical support?</td>\n      <td>Reach out to our team at <a href=\"mailto:support@bebettor.com\">support@bebettor.com</a> for assistance.</td>\n    </tr>\n    <tr>\n      <td>How long does integration typically take?</td>\n      <td>Integration generally takes 1-2 weeks, depending on your team's resources and complexity of use cases.</td>\n    </tr>\n    <tr>\n      <td>How many requests are allowed during integration?</td>\n      <td>By default, you are granted 500 requests per month in the <em>Test</em> environment.</td>\n    </tr>\n  </tbody>\n</table>\n<h3>Customer Data</h3> <table>\n  <thead>\n    <tr>\n      <th width=\"40%\">Question</th>\n      <th>Answer</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>What is the purpose of the <em>customerId</em> field?</td>\n      <td>It's your internal identifier used for referencing users without exposing personal data. It is included in all responses and retained for troubleshooting.</td>\n    </tr>\n    <tr>\n      <td>Is it helpful to send gender data, even if it's optional?</td>\n      <td>Yes. Gender information can enhance score accuracy.</td>\n    </tr>\n    <tr>\n      <td>We collect titles but not gender. Is it still useful to send titles?</td>\n      <td>Yes. Titles help us infer gender when not explicitly provided.</td>\n    </tr>\n  </tbody>\n</table>\n<h3>Test Environment</h3> <table>\n  <thead>\n    <tr>\n      <th width=\"40%\">Question</th>\n      <th>Answer</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>Is the <em>Test</em> environment the same as <em>Production</em>?</td>\n      <td>Functionally - yes. The <em>Production</em> environment is faster and uses up-to-date datasets.</td>\n    </tr>\n    <tr>\n      <td>Can we use <em>scores</em> from the <em>Test</em> environment?</td>\n      <td>No. Test results are intended for internal development and testing only. They should not be used for real decision-making.</td>\n    </tr>\n    <tr>\n      <td>Can we retain <em>Test</em> environment access after integration?</td>\n      <td>Yes. You can continue using your <em>Test</em> credentials to validate system changes.</td>\n    </tr>\n  </tbody>\n</table>\n<h3>Production Environment</h3> <table>\n  <thead>\n    <tr>\n      <th width=\"40%\">Question</th>\n      <th>Answer</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>Do we need separate credentials for the <em>Production</em> environment?</td>\n      <td>Yes. <em>Test</em> and <em>Production</em> environments have distinct credentials.</td>\n    </tr>\n    <tr>\n      <td>What should we do during system downtime or maintenance?</td>\n      <td>Please queue your requests and resume once you receive confirmation that the system is back online. Maintenance windows will be announced in advance.</td>\n    </tr>\n  </tbody>\n</table>\n",
  "url": "https://raw.githubusercontent.com/jentic/jentic-public-apis/refs/heads/main/apis/openapi/swaggerhub.bebettor-dev/bebettor-api/1.2.1/apis.json",
  "tags": [
    "swaggerhub.bebettor-dev",
    "bebettor-api"
  ],
  "created": "2026-04-04",
  "modified": "2026-04-04",
  "specificationVersion": "0.19",
  "access": "3rd-Party",
  "maintainers": [
    {
      "FN": "Jentic",
      "X-github": "jentic",
      "url": "https://github.com/jentic"
    }
  ],
  "apis": [
    {
      "aid": "swaggerhub.bebettor-dev:bebettor-api-1.2.1",
      "name": "beBettor API",
      "description": "<p><strong>FOR PUBLIC USE ONLY.</strong></p>\n<h2>1. Overview</h2> <p>The beBettor API provides an automated and scalable solution for customer affordability screening. The data we provide helps our clients improve their customer interaction frameworks, develop deeper insights into their customers, design safer online experiences and make more informed business decisions.</p> <p>To learn more about our mission and approach, visit <a href=\"https://www.bebettor.com\" target=\"_blank\">www.bebettor.com</a>.</p> <p>The beBettor API provides the following core functionality:</p>\n<h3>Check</h3> <p>Performs an affordability screening based on the provided customer data.</p> <strong>Interaction flow:</strong> <ol>\n  <li><p>The client initiates a check by including the customer's personal data in the request body.</p></li>\n  <li><p>The beBettor API processes the request and returns the <em>checkId</em>, <em>score</em> and <em>flags</em>.</p></li>\n</ol> <br /> <p><img src=\"https://www.bebettor.com/assets/api-docs/api-schema-c1.png\" alt=\"API Interaction - Check\" /></p> <br />\n<h3>Report</h3> <p>Retrieves a report containing additional data points that complement the results of an initial check. These reports can be used to further support the <em>score</em> and <em>flags</em> returned during the check.</p> <strong>Interaction flow:</strong> <ol>\n  <li><p>The client sends a request to retrieve a report by including the <em>checkId</em> in the request.</p></li>\n  <li><p>The beBettor API returns a structured report containing multiple parameter groups with supporting data.</p></li>\n</ol> <br /> <p><img src=\"https://www.bebettor.com/assets/api-docs/api-schema-c2.png\" alt=\"API Interaction - Report\" /></p> <br />\n<h2>2. Environments</h2> <p>The beBettor API provides two distinct environments for integration. Use the <em>Test</em> environment to validate your integration before going live. Once your integration is complete and tested, switch to the <em>Production</em> environment to begin processing real customer data.</p> <table>\n  <thead>\n    <tr>\n      <th width=\"25%\">Environment</th>\n      <th>Endpoint URL</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>Test</td>\n      <td>https://sandbox-api.bebettor.com/affordability/v1</td>\n    </tr>\n    <tr>\n      <td>Production</td>\n      <td>https://api.bebettor.com/affordability/v1</td>\n    </tr>\n  </tbody>\n</table> <br />\n<h2>3. API Access</h2> <p>To start integrating with the beBettor API in either the <em>Test</em> or <em>Production</em> environment, the following configuration details are required.</p> <table>\n  <thead>\n    <tr>\n      <th width=\"25%\">Item</th>\n      <th>Description</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>Score Model</td>\n      <td>Some <em>check types</em> support more than one <em>score model</em>, which must be specified during integration. Let us know which <em>score model</em> you'd like to use and it will be applied to all of your requests.</td>\n    </tr>\n    <tr>\n      <td>API Key</td>\n      <td>Access to the beBettor API requires an API key, which will be provided to you prior to integration.</td>\n    </tr>\n  </tbody>\n</table> <br />\n<h2>4. Check Types</h2> <p>The table below outlines the three <em>check types</em> available through the beBettor API.</p> <table>\n  <thead>\n    <tr>\n      <th width=\"25%\">Check Type</th>\n      <th>Description</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>Financial Vulnerability</td>\n      <td>Screens the customer for signs of financial vulnerability and returns a <em>score</em> with associated risk <em>flags</em>.</td>\n    </tr>\n    <tr>\n      <td>Wealth</td>\n      <td>Estimates a customer's relative wealth ranking within the UK and returns a <em>wealth score</em> along with associated <em>flags</em>.</td>\n    </tr>\n    <tr>\n      <td>Discretionary Income</td>\n      <td>Estimates a customer's discretionary income and evaluates key risk indicators. Returns a <em>discretionary income score</em> along with associated risk <em>flags</em>.</td>\n    </tr>\n  </tbody>\n</table> <br />\n<h2>5. Customer Data</h2> <p>The table below outlines the customer personal data fields, including their type, format and constraints.</p> <table>\n  <thead>\n    <tr>\n      <th width=\"5%\">No</th>\n      <th width=\"20%\">Field Name</th>\n      <th width=\"25%\">Data Type</th>\n      <th>Format &amp; Constraints</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>1</td>\n      <td>customerId</td>\n      <td>String</td>\n      <td>Charset: printable ASCII<br />Min length: 1<br />Max length: 100</td>\n    </tr>\n    <tr>\n      <td>2</td>\n      <td>title</td>\n      <td>String</td>\n      <td>Enum: [ MR, MRS, MS, MISS, DR, PROF, SIR ]</td>\n    </tr>\n    <tr>\n      <td>3</td>\n      <td>firstName</td>\n      <td>String</td>\n      <td>Min length: 1<br />Max length: 100</td>\n    </tr>\n    <tr>\n      <td>4</td>\n      <td>lastName</td>\n      <td>String</td>\n      <td>Min length: 1<br />Max length: 100</td>\n    </tr>\n    <tr>\n      <td>5</td>\n      <td>gender</td>\n      <td>String</td>\n      <td>Enum: [ MALE, FEMALE, OTHER ]</td>\n    </tr>\n    <tr>\n      <td>6</td>\n      <td>dateOfBirth</td>\n      <td>String</td>\n      <td>Format: YYYY-MM-DD (RFC 3339)<br />Age must be ≥ 18</td>\n    </tr>\n    <tr>\n      <td>7</td>\n      <td>addressLine1</td>\n      <td>String</td>\n      <td>Min length: 1<br />Max length: 100</td>\n    </tr>\n    <tr>\n      <td>8</td>\n      <td>addressLine2</td>\n      <td>String</td>\n      <td>Min length: 1<br />Max length: 100</td>\n    </tr>\n    <tr>\n      <td>9</td>\n      <td>town</td>\n      <td>String</td>\n      <td>Min length: 1<br />Max length: 100</td>\n    </tr>\n    <tr>\n      <td>10</td>\n      <td>county</td>\n      <td>String</td>\n      <td>Min length: 1<br />Max length: 100</td>\n    </tr>\n    <tr>\n      <td>11</td>\n      <td>postcode</td>\n      <td>String</td>\n      <td>Valid UK postcode</td>\n    </tr>\n  </tbody>\n</table> <br />\n<p>The table below indicates which customer data fields are <strong>required</strong> for each <em>check type</em>. Please note that <strong>optional</strong> fields must either be set to <code>null</code> or excluded from the request. <strong>Empty strings are not allowed.</strong></p> <table>\n  <thead>\n    <tr>\n      <th width=\"5%\">No</th>\n      <th width=\"20%\">Field Name</th>\n      <th width=\"25%\">Financial Vulnerability Check</th>\n      <th width=\"25%\">Wealth Check</th>\n      <th>Discretionary Income Check</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>1</td>\n      <td>customerId</td>\n      <td><strong>Required</strong></td>\n      <td><strong>Required</strong></td>\n      <td><strong>Required</strong></td>\n    </tr>\n    <tr>\n      <td>2</td>\n      <td>title</td>\n      <td>Optional</td>\n      <td>Optional</td>\n      <td>Optional</td>\n    </tr>\n    <tr>\n      <td>3</td>\n      <td>firstName</td>\n      <td><strong>Required</strong></td>\n      <td>Optional</td>\n      <td><strong>Required</strong></td>\n    </tr>\n    <tr>\n      <td>4</td>\n      <td>lastName</td>\n      <td><strong>Required</strong></td>\n      <td>Optional</td>\n      <td><strong>Required</strong></td>\n    </tr>\n    <tr>\n      <td>5</td>\n      <td>gender</td>\n      <td>Optional</td>\n      <td>Optional</td>\n      <td>Optional</td>\n    </tr>\n    <tr>\n      <td>6</td>\n      <td>dateOfBirth</td>\n      <td><strong>Required</strong></td>\n      <td>Optional</td>\n      <td><strong>Required</strong></td>\n    </tr>\n    <tr>\n      <td>7</td>\n      <td>addressLine1</td>\n      <td><strong>Required</strong></td>\n      <td><strong>Required</strong></td>\n      <td><strong>Required</strong></td>\n    </tr>\n    <tr>\n      <td>8</td>\n      <td>addressLine2</td>\n      <td>Optional</td>\n      <td>Optional</td>\n      <td>Optional</td>\n    </tr>\n    <tr>\n      <td>9</td>\n      <td>town</td>\n      <td><strong>Required</strong></td>\n      <td>Optional</td>\n      <td><strong>Required</strong></td>\n    </tr>\n    <tr>\n      <td>10</td>\n      <td>county</td>\n      <td>Optional</td>\n      <td>Optional</td>\n      <td>Optional</td>\n    </tr>\n    <tr>\n      <td>11</td>\n      <td>postcode</td>\n      <td><strong>Required</strong></td>\n      <td><strong>Required</strong></td>\n      <td><strong>Required</strong></td>\n    </tr>\n  </tbody>\n</table> <br />\n<h2>6. Scores</h2> <p>A <em>score model</em> is selected by the client and pre-configured by beBettor during the API integration process. This model is applied by default to all check requests.</p>\n<h3>Financial Vulnerability Check</h3> <p>The <em>vulnerability score</em> indicates whether financial vulnerability is present.</p> <p>The table below outlines the currently supported <em>score models</em> and their associated <em>scores</em>.</p> <table>\n  <thead>\n    <tr>\n      <th width=\"25%\">Score Model</th>\n      <th>Possible Scores</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>GB:M2-VP</td>\n      <td>VULNERABLE, PASS</td>\n    </tr>\n    <tr>\n      <td>GB:M2-RAG</td>\n      <td>RED, AMBER, GREEN</td>\n    </tr>\n  </tbody>\n</table> <br />\n<h3>Wealth Check</h3> <p>The <em>wealth score</em> represents a customer's relative wealth ranking within the UK.</p> <p>The table below outlines the currently supported <em>score models</em> and their associated <em>scores</em>.</p> <table>\n  <thead>\n    <tr>\n      <th width=\"25%\">Score Model</th>\n      <th>Possible Scores</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>GB:J2</td>\n      <td>1, 2, 3, 4, 5, 6, 7, 8, 9, 10</td>\n    </tr>\n    <tr>\n      <td>GB:J3</td>\n      <td>1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20</td>\n    </tr>\n  </tbody>\n</table> <br />\n<h3>Discretionary Income Check</h3> <p>The <em>discretionary income score</em> provides an indication of an individual's affordability.</p> <p>The table below outlines the currently supported <em>score models</em> and their associated <em>scores</em>.</p> <table>\n  <thead>\n    <tr>\n      <th width=\"25%\">Score Model</th>\n      <th>Possible Scores</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>GB:V1</td>\n      <td>A, B, C, D, E, F</td>\n    </tr>\n    <tr>\n      <td>GB:V3</td>\n      <td>A, B, C, D</td>\n    </tr>\n    <tr>\n      <td>GB:V4</td>\n      <td>RED, AMBER, GREEN</td>\n    </tr>\n  </tbody>\n</table> <br />\n<h2>7. Flags</h2> <h3>Financial Vulnerability Check</h3> <p>Financial vulnerability <em>flags</em> indicate additional risk factors associated with the customer.</p> <p>The table below outlines the currently supported <em>flag models</em> and their associated <em>flags</em>.</p> <table>\n  <thead>\n    <tr>\n      <th width=\"25%\">Flags Model</th>\n      <th width=\"40%\">Flags</th>\n      <th>Description</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td rowspan=\"4\">GB:M2</td>\n      <td>INDIVIDUAL_INSOLVENCY_REGISTER_MATCH</td>\n      <td>This <em>flag</em> is triggered when there is a match on the <em>Individual Insolvency</em> register.</td>\n    </tr>\n    <tr>\n      <td>JUDGMENTS_ORDERS_FINES_REGISTER_MATCH</td>\n      <td>This <em>flag</em> is triggered when there is a match on the <em>Judgments, Orders and Fines</em> register.</td>\n    </tr>\n    <tr>\n      <td>LOW_INCOME_SOCIAL_HOUSING</td>\n      <td>This <em>flag</em> is triggered when there is a match on the <em>Social Housing</em> register and identifies the individual as having relatively low income.</td>\n    </tr>\n    <tr>\n      <td>RELATIVE_INCOME_RISK</td>\n      <td>This <em>flag</em> is triggered when the individual is identified as having a relatively low income.</td>\n    </tr>\n  </tbody>\n</table> <br />\n<h3>Wealth Check</h3> <p>Wealth <em>flags</em> indicate additional signs of high wealth associated with the customer.</p> <p>The table below outlines the currently supported <em>flag models</em> and their associated <em>flags</em>.</p> <table>\n  <thead>\n    <tr>\n      <th width=\"25%\">Flags Model</th>\n      <th width=\"40%\">Flag</th>\n      <th>Description</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td rowspan=\"1\">GB:J1</td>\n      <td>SUPER_AFFLUENCE</td>\n      <td>This <em>flag</em> is triggered when the individual is identified as being in the top 1% of wealth within the Great Britain population.</td>\n    </tr>\n  </tbody>\n</table> <br />\n<h3>Discretionary Income Check</h3> <p>Discretionary income <em>flags</em> indicate additional signs of financial risk or vulnerability associated with the customer.</p> <p>The table below outlines the currently supported <em>flag models</em> and their associated <em>flags</em>.</p> <table>\n  <thead>\n    <tr>\n      <th width=\"25%\">Flags Model</th>\n      <th width=\"40%\">Flags</th>\n      <th>Description</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td rowspan=\"3\">GB:V2</td>\n      <td>INDIVIDUAL_INSOLVENCY_REGISTER_MATCH</td>\n      <td>This <em>flag</em> is triggered when there is a match on the <em>Individual Insolvency</em> register.</td>\n    </tr>\n    <tr>\n      <td>SOCIAL_HOUSING_REGISTER_MATCH</td>\n      <td>This <em>flag</em> is triggered when there is a match on the <em>Social Housing</em> register.</td>\n    </tr>\n    <tr>\n      <td>AGE_UNDER_25</td>\n      <td>This <em>flag</em> is triggered when the individual is under 25 years of age.</td>\n    </tr>\n  </tbody>\n</table> <br />\n<h2>8. Reports</h2> <p>Reports provide additional supporting information for your checks and are organized into structured groups of parameters. Each parameter includes the following properties: <code>id</code>, <code>name</code>, <code>value</code> and <code>description</code>. These are defined by a specific <em>report model</em>, which is periodically updated by beBettor as part of ongoing service improvements. You can request a specific <em>report model</em> by setting the appropriate value in the HTTP <code>Accept</code> header. If this header is omitted or set to <code>*/*</code>, the latest available <em>report model</em> will be returned by default.</p> <p>beBettor will continue to support previous <em>report models</em> for a defined transition period after new versions are released. Advance notice will be given before deprecating any older <em>report models</em>. To maintain consistent integration and avoid unexpected changes to report structures, we recommend explicitly specifying the desired <em>report model</em> via the <code>Accept</code> header, rather than relying on the latest version by default.</p>\n<h3>Financial Vulnerability Check</h3> <p>The table below outlines the currently supported <em>report models</em>.</p> <table>\n  <thead>\n    <tr>\n      <th width=\"25%\">Report Model</th>\n      <th width=\"20%\">Status</th>\n      <th>Request Header <code>Accept</code> Value</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>GB:M2-20240521</td>\n      <td>Latest</td>\n      <td><code>application/vnd.report.gb.m2-20240521+json</code></td>\n    </tr>\n  </tbody>\n</table> <br />\n<h3>Wealth Check</h3> <p>Reports are currently not available for this <em>check type</em>.</p> <br />\n<h3>Discretionary Income Check</h3> <p>The table below outlines the currently supported <em>report models</em>.</p> <table>\n  <thead>\n    <tr>\n      <th width=\"25%\">Report Model</th>\n      <th width=\"20%\">Status</th>\n      <th>Request Header <code>Accept</code> Value</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>GB:V20211005</td>\n      <td>Latest</td>\n      <td><code>application/vnd.report.gb.v20211005+json</code></td>\n    </tr>\n  </tbody>\n</table> <br />\n<h2>9. API Usage</h2> <p>The default API request rate limit is <strong>5 requests per second</strong> for both <em>Test</em> and <em>Production</em> environments. Additionally, the <em>Test</em> environment includes a <strong>monthly quota limit of 500 requests</strong>. Custom rate and quota limits can be increased on request. Please contact us if you require adjustments to these defaults.</p> <p>If a client exceeds the allowed rate limit, the request will be throttled and returned with an HTTP <code>429 Too Many Requests</code> error response. Clients receiving throttling responses should implement appropriate retry logic. For more details, please refer to section &quot;10. Retry Policy&quot;.</p> <p>The table below outlines the current rate and quota limits for each environment.</p> <table>\n  <thead>\n    <tr>\n      <th width=\"25%\">Environment</th>\n      <th width=\"30%\">Rate Limit</th>\n      <th>Quota Limit</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>Test</td>\n      <td>5 requests per second</td>\n      <td>500 requests per month, starting on the 1st day</td>\n    </tr>\n    <tr>\n      <td>Production</td>\n      <td>5 requests per second</td>\n      <td>No limit</td>\n    </tr>\n  </tbody>\n</table> <br />\n<h2>10. Retry Policy</h2>\n<p>Errors may occur at different stages of an API request, such as due to network issues or temporary service downtime. To ensure reliability, client applications should implement a robust retry mechanism.</p> <p>A widely adopted strategy is <em>exponential backoff</em>, which increases the delay between retry attempts following consecutive failures. This approach reduces the risk of overwhelming the server during periods of high load and improves the likelihood of successful recovery. For implementation details, refer to external documentation or use libraries that implement <em>exponential backoff</em> logic.</p> <p>The table below outlines common HTTP status codes returned by the API and indicates whether the client should attempt a retry.</p> <table>\n  <thead>\n    <tr>\n      <th width=\"25%\">HTTP Status Code</th>\n      <th width=\"30%\">Meaning</th>\n      <th>Retry Required?</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>4xx</td>\n      <td>Client-side error</td>\n      <td>No</td>\n    </tr>\n    <tr>\n      <td>429</td>\n      <td>Too many requests. The request was throttled.</td>\n      <td>Yes</td>\n    </tr>\n    <tr>\n      <td>5xx</td>\n      <td>Server-side error</td>\n      <td>Yes</td>\n    </tr>\n  </tbody>\n</table> <br />\n<h2>11. Getting Started</h2> <hr /> <p>Below are example API requests for two commonly used tools: <strong>cURL</strong> and <strong>Postman</strong>. The <em>cURL</em> examples are provided as inline code snippets, while the <em>Postman collection</em> file is available for download via the link provided.</p> <h3>API Request Examples</h3> <p><strong>Perform a <em>Financial vulnerability check</em> using the provided customer data.</strong></p> <code>\n    curl -X POST \"https://sandbox-api.bebettor.com/affordability/v1/check\" \\<br />\n      -H \"Content-Type: application/json\" \\<br />\n      -H \"X-Api-Key: {{YOUR_API_KEY}}\" \\<br />\n      -H \"X-BB-Check-Type: VULNERABILITY\" \\<br />\n      -H \"X-BB-Score-Model: {{SCORE_MODEL}}\" \\<br />\n      -d '{\"customerId\":\"CID0001\",\"title\":\"MR\",\"firstName\":\"Joe\",\"lastName\":\"Bloggs\",\"gender\":\"MALE\",\"dateOfBirth\":\"1978-05-20\",\"address\":{\"addressLine1\":\"25 High Street\",\"addressLine2\":\"Flat 4\",\"town\":\"London\",\"county\":\"Greater London\",\"postcode\":\"WC2H 0AW\"}}'\n</code> <br />\n<p><strong>Perform a <em>Wealth check</em> using the provided customer data.</strong></p> <code>\n  curl -X POST \"https://sandbox-api.bebettor.com/affordability/v1/check\" \\<br />\n    -H \"Content-Type: application/json\" \\<br />\n    -H \"X-Api-Key: {{YOUR_API_KEY}}\" \\<br />\n    -H \"X-BB-Check-Type: WEALTH\" \\<br />\n    -H \"X-BB-Score-Model: {{SCORE_MODEL}}\" \\<br />\n    -d '{\"customerId\":\"CID0001\",\"address\":{\"addressLine1\":\"25 High Street\",\"addressLine2\":\"Flat 4\",\"town\":\"London\",\"county\":\"Greater London\",\"postcode\":\"WC2H 0AW\"}}'\n</code> <br />\n<p><strong>Perform a <em>Discretionary income check</em> using the provided customer data.</strong></p> <code>\n  curl -X POST \"https://sandbox-api.bebettor.com/affordability/v1/check\" \\<br />\n    -H \"Content-Type: application/json\" \\<br />\n    -H \"X-Api-Key: {{YOUR_API_KEY}}\" \\<br />\n    -H \"X-BB-Check-Type: DISCRETIONARY_INCOME\" \\<br />\n    -H \"X-BB-Score-Model: {{SCORE_MODEL}}\" \\<br />\n    -d '{\"customerId\":\"CID0001\",\"title\":\"MR\",\"firstName\":\"Joe\",\"lastName\":\"Bloggs\",\"gender\":\"MALE\",\"dateOfBirth\":\"1978-05-20\",\"address\":{\"addressLine1\":\"25 High Street\",\"addressLine2\":\"Flat 4\",\"town\":\"London\",\"county\":\"Greater London\",\"postcode\":\"WC2H 0AW\"}}'\n</code> <br />\n<p><strong>Retrieve a report.</strong></p> <code>\n  curl -X GET \"https://sandbox-api.bebettor.com/affordability/v1/report/{{CHECK_ID}}\" \\<br />\n    -H \"Content-Type: application/json\" \\<br />\n    -H \"X-Api-Key: {{YOUR_API_KEY}}\" \\<br />\n    -H \"Accept: {{REPORT_MODEL}}\"\n</code> <br />\n<p><strong>Search checks that match specific criteria.</strong></p> <code>\n  curl -X GET \"https://sandbox-api.bebettor.com/affordability/v1/search?checkType={{CHECK_TYPE}}&amp;checkDate={{CHECK_DATE}}&amp;checkId={{CHECK_ID}}&amp;customerId={{CUSTOMER_ID}}&amp;pageToken={{PAGE_TOKEN}}\" \\<br />\n    -H \"Content-Type: application/json\" \\<br />\n    -H \"X-Api-Key: {{YOUR_API_KEY}}\"\n</code> <br /> <br />\n<h3>Postman Collection</h3> <p>Get started with the beBettor API by downloading the <em>Postman collection</em> <a href=\"https://www.bebettor.com/assets/api-docs/bebettor-api-public.postman_collection.json\" target=\"_blank\">here</a>.</p> <br />\n<h2>12. API Error Handling</h2> <p>The table below outlines common API response errors, including their HTTP status codes, corresponding error codes and explanations to assist with troubleshooting and resolution.</p> <table>\n  <thead>\n    <tr>\n      <th width=\"25%\">HTTP Status Code</th>\n      <th width=\"30%\">Meaning</th>\n      <th>API Error Codes and Resolutions</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>400 (Bad Request)</td>\n      <td>The server cannot or will not process the request due to a client-side error (e.g., malformed syntax or invalid parameters).</td>\n      <td>\n        <strong>REQUEST_BODY_PARSE_ERROR</strong> - Ensure that your request body is valid JSON with correct syntax and structure.<br /><br />\n        <strong>REQUEST_INVALID</strong> - One or more request parameters are invalid. Review the API documentation for field-specific validation rules.\n      </td>\n    </tr>\n    <tr>\n      <td>401 (Unauthorized)</td>\n      <td>The request could not be completed because it lacks valid authentication credentials for the target resource.</td>\n      <td>\n        <strong>AUTHENTICATION_FAILED</strong> - Ensure that the <code>X-Api-Key</code> header contains the correct API key for the appropriate environment (<em>Test</em> or <em>Production</em>).\n      </td>\n    </tr>\n    <tr>\n      <td>403 (Forbidden)</td>\n      <td>The server understood the request but refuses to authorize it. This means the client's identity is known, but it does not have permission to access the requested resource.</td>\n      <td>\n        <strong>ACCESS_DENIED</strong> - Confirm that the API endpoint URL includes the correct resource path (e.g., <code>/v1/check</code>, <code>/v1/report</code>)\n      </td>\n    </tr>\n    <tr>\n      <td>404 (Not Found)</td>\n      <td>The server could not locate the requested resource. This typically indicates that the URL is incorrect or the resource does not exist.</td>\n      <td>\n        <strong>RESOURCE_NOT_FOUND</strong> - For <code>GET</code> requests to retrieve reports, ensure that the <code>checkId</code> included in the URL is valid and refers to an existing check.\n      </td>\n    </tr>\n    <tr>\n      <td>405 (Method Not Allowed)</td>\n      <td>The server recognizes the requested URL, but the HTTP method used (e.g., <code>GET</code>, <code>POST</code>, <code>PUT</code>, <code>DELETE</code>) is not supported for that resource.</td>\n      <td>\n        <strong>METHOD_NOT_SUPPORTED</strong> - Use the appropriate HTTP method (<code>GET</code> or <code>POST</code>) as specified in the API documentation for the given resource.\n      </td>\n    </tr>\n    <tr>\n      <td>406 (Not Acceptable)</td>\n      <td>The server is unable to generate a response that matches the content type criteria specified in the request's <code>Accept</code> header.</td>\n      <td>\n        <strong>NOT_ACCEPTABLE</strong> - When requesting a report, ensure the request includes an <code>Accept</code> header. Use <code>*/*</code> to receive the latest available version, or specify a particular version (e.g., <code>application/vnd.report.gb.m2-20240521+json</code>) to request a specific <em>report model</em>.\n      </td>\n    </tr>\n    <tr>\n      <td>415 (Unsupported Media Type)</td>\n      <td>The server refuses to process the request because the format of the request payload is not supported. This typically relates to the <code>Content-Type</code> header, which must accurately indicate the format of the request body so the server can parse it correctly.</td>\n      <td>\n        <strong>UNSUPPORTED_MEDIA_TYPE</strong> - Ensure that the <code>Content-Type</code> header is set to <code>application/json</code>, as this is the expected format for all request payloads sent to the beBettor API.\n      </td>\n    </tr>\n    <tr>\n      <td>422 (Unprocessable Entity)</td>\n      <td>The request was syntactically correct but contains invalid or logically inconsistent data that the server cannot process.</td>\n      <td>\n        <strong>POSTCODE_NOT_FOUND</strong> - The postcode format is valid but was not found in the UK postcode directory.<br /><br />\n        <strong>POSTCODE_NOT_COVERED</strong> - The postcode is valid but belongs to a region not supported by the <em>check type</em> (e.g., Channel Islands, UK overseas territories, or Northern Ireland).<br /><br />\n        <strong>PERSON_UNDER_18</strong> - The individual is under 18 years of age and is not eligible for affordability screening.\n      </td>\n    </tr>\n    <tr>\n      <td>429 (Too Many Requests)</td>\n      <td>The server has received too many requests from the client in a short period of time and is enforcing rate limits to maintain system stability and performance.</td>\n      <td>\n        <strong>QUOTA_EXCEEDED</strong> - You have exceeded your monthly request quota in the <em>Test</em> environment. Please contact us if you need to request an increased limit.<br /><br />\n        <strong>THROTTLED</strong> - You have exceeded the API rate limit (5 requests per second). Reduce the request rate to comply with the allowed limits.\n      </td>\n    </tr>\n    <tr>\n      <td>500 (Internal Server Error)</td>\n      <td>The server encountered an unexpected condition that prevented it from fulfilling the request. This is a generic error indicating a problem on the server side, not caused by the client.</td>\n      <td>\n        <strong>Internal Server Error</strong> - Retry the request using an <em>exponential backoff</em> strategy with a reasonable number of attempts. If the issue persists and there is no planned maintenance (check <a href=\"https://status.bebettor.com\" target=\"_blank\">status.bebettor.com</a>), please contact <a href=\"mailto:support@bebettor.com\">support@bebettor.com</a> for further assistance.\n      </td>\n    </tr>\n  </tbody>\n</table> <br />\n<h2>13. Frequently Asked Questions (FAQs)</h2> <h3>API</h3> <table>\n  <thead>\n    <tr>\n      <th width=\"40%\">Question</th>\n      <th>Answer</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>What is the maximum number of requests per second we can send?</td>\n      <td>The default rate limit is 5 requests per second for both <em>Test</em> and <em>Production</em> environments.</td>\n    </tr>\n    <tr>\n      <td>What is the average response time of the API?</td>\n      <td>The average response time is under 500 milliseconds (excluding network round-trip latency).</td>\n    </tr>\n    <tr>\n      <td>Are API requests and responses different for each check type?</td>\n      <td>The request and response formats are consistent across check types. Differences lie in the <em>score model</em>, <em>flags model</em>, and <em>report</em> content associated with each <em>check type</em>.</td>\n    </tr>\n    <tr>\n      <td>How do I switch between check types?</td>\n      <td>Set the HTTP header <code>X-BB-Check-Type</code> to the desired check type. Note: each type may require different mandatory or optional customer fields.</td>\n    </tr>\n    <tr>\n      <td>Which UK regions are supported?</td>\n      <td>All valid UK postcodes in England, Wales, Scotland, and Northern Ireland are supported. The <em>Wealth check</em> supports England, Wales and Scotland only.</td>\n    </tr>\n  </tbody>\n</table>\n<h3>Checks and Reports</h3> <table>\n  <thead>\n    <tr>\n      <th width=\"40%\">Question</th>\n      <th>Answer</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>What is the difference between a check and a report?</td>\n      <td>A check returns a <em>score</em> and <em>risk flags</em>. A report provides structured supporting data across multiple parameter groups. See the &quot;Report Appendix&quot; document for full details.</td>\n    </tr>\n    <tr>\n      <td>Do I need to conduct a check before requesting a report?</td>\n      <td>Yes. Reports can only be retrieved using the <em>checkId</em> returned from a completed <em>check</em>.</td>\n    </tr>\n  </tbody>\n</table>\n<h3>Integration Process</h3> <table>\n  <thead>\n    <tr>\n      <th width=\"40%\">Question</th>\n      <th>Answer</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>How do we begin integration?</td>\n      <td>You'll receive your API key from beBettor and can start integrating immediately.</td>\n    </tr>\n    <tr>\n      <td>Do you provide dummy/test data?</td>\n      <td>Yes. Upon request, we can provide dummy data to support your testing needs.</td>\n    </tr>\n    <tr>\n      <td>Who do we contact for technical support?</td>\n      <td>Reach out to our team at <a href=\"mailto:support@bebettor.com\">support@bebettor.com</a> for assistance.</td>\n    </tr>\n    <tr>\n      <td>How long does integration typically take?</td>\n      <td>Integration generally takes 1-2 weeks, depending on your team's resources and complexity of use cases.</td>\n    </tr>\n    <tr>\n      <td>How many requests are allowed during integration?</td>\n      <td>By default, you are granted 500 requests per month in the <em>Test</em> environment.</td>\n    </tr>\n  </tbody>\n</table>\n<h3>Customer Data</h3> <table>\n  <thead>\n    <tr>\n      <th width=\"40%\">Question</th>\n      <th>Answer</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>What is the purpose of the <em>customerId</em> field?</td>\n      <td>It's your internal identifier used for referencing users without exposing personal data. It is included in all responses and retained for troubleshooting.</td>\n    </tr>\n    <tr>\n      <td>Is it helpful to send gender data, even if it's optional?</td>\n      <td>Yes. Gender information can enhance score accuracy.</td>\n    </tr>\n    <tr>\n      <td>We collect titles but not gender. Is it still useful to send titles?</td>\n      <td>Yes. Titles help us infer gender when not explicitly provided.</td>\n    </tr>\n  </tbody>\n</table>\n<h3>Test Environment</h3> <table>\n  <thead>\n    <tr>\n      <th width=\"40%\">Question</th>\n      <th>Answer</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>Is the <em>Test</em> environment the same as <em>Production</em>?</td>\n      <td>Functionally - yes. The <em>Production</em> environment is faster and uses up-to-date datasets.</td>\n    </tr>\n    <tr>\n      <td>Can we use <em>scores</em> from the <em>Test</em> environment?</td>\n      <td>No. Test results are intended for internal development and testing only. They should not be used for real decision-making.</td>\n    </tr>\n    <tr>\n      <td>Can we retain <em>Test</em> environment access after integration?</td>\n      <td>Yes. You can continue using your <em>Test</em> credentials to validate system changes.</td>\n    </tr>\n  </tbody>\n</table>\n<h3>Production Environment</h3> <table>\n  <thead>\n    <tr>\n      <th width=\"40%\">Question</th>\n      <th>Answer</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>Do we need separate credentials for the <em>Production</em> environment?</td>\n      <td>Yes. <em>Test</em> and <em>Production</em> environments have distinct credentials.</td>\n    </tr>\n    <tr>\n      <td>What should we do during system downtime or maintenance?</td>\n      <td>Please queue your requests and resume once you receive confirmation that the system is back online. Maintenance windows will be announced in advance.</td>\n    </tr>\n  </tbody>\n</table>\n",
      "image": "",
      "baseURL": "https://api.bebettor.com/affordability/v1",
      "humanURL": "https://github.com/jentic/jentic-public-apis/tree/main/apis/openapi/swaggerhub.bebettor-dev/bebettor-api/1.2.1",
      "version": "1.2.1",
      "tags": [
        "swaggerhub.bebettor-dev",
        "bebettor-api"
      ],
      "properties": [
        {
          "type": "OpenAPI",
          "name": "OpenAPI definition",
          "url": "https://raw.githubusercontent.com/jentic/jentic-public-apis/refs/heads/main/apis/openapi/swaggerhub.bebettor-dev/bebettor-api/1.2.1/openapi.json",
          "mediaType": "application/openapi+json"
        },
        {
          "type": "GitHubRepo",
          "url": "https://github.com/jentic/jentic-public-apis/tree/main/apis/openapi/swaggerhub.bebettor-dev/bebettor-api/1.2.1"
        }
      ],
      "contact": [
        {
          "FN": "support@bebettor.com",
          "email": "support@bebettor.com"
        }
      ]
    }
  ]
}