Preparation

In other to proper access the API, a few of steps are required:

Access Token

A TOKEN is generated by alt.bank that uniquely identifies the partner.
This TOKEN will be a 64-character long string, containing alphanumeric characters and needs to be sent in the header of the HTTP request, with the key X-Partner-Auth. Example (curl):

curl
--header 'X-Partner-Auth: 532eaabd9574880dbf76b9b8cc00832c20a6ec113d682299550d7a6e0f345e25'

IP addresses whitelisting

To help protect the data exchanges, the partner should inform the list of IP addresses from which all requests from the API will be generated so that alt.bank can lock down the communications protocols to these predefined IP addresses.

Callback URL

The Underwriting API call is asynchronous and, as such, needs an endpoint to call back once the result is ready.
The partner must provide alt.bank with a URL callback endpoint for configuration prior to the utilization of the API. This full URL will be called with the result once the full pipeline finishes with success.

Request

To start the underwriting process, the partner needs to make a POST request to the following URL: https://ml-service-hub.ab-api-service.com/api/partner/credit/cards/underwritings
The body of the request follows this schema:

{  
  "customerUuid": "string",
  "cpf": "string",
  "costSavingEnabled": false
  "srd": {
    "grossIncome": 0,
    "housingSpends": 0,
    "cardSpends": 0,
    "loanSpends": 0,
    "address": {
      "street": "string",
      "number": "string",
      "complement": "string",
      "city": "string",
      "state": "string"
    },
    "occupation": "string",
    "desiredCreditLimit": 0
  }
}

Schema Description

The following is a description of each field in the request payload:

(mandatory) customerUuid is the unique identifier of your customer in your database. This field accepts any alphanumeric string, but we strongly recommend using a UUID.
(mandatory) cpf is the CPF of the customer you will be underwriting. This should be sent as an 11-digit numeric string without any special characters, such as dots or dashes.
(mandatory) costSavingEnabled is a boolean that marks whether to use our cost savings policy or not. If the cost savings policy is enabled, the CPF will not trigger all of the GUARD data sources. Instead a smaller number of less expensive queries are first made and only if the customer meets certain criteria (i.e., relatively lower risk) will all GUARD datasets be queried. If false (default), every customer will be evaluated by the model using all datasets.
srd is the reported information about the customer, and is composed of:
- (mandatory) grossIncome: the monthly gross income of the customer
- housingSpends: the monthly spends with mortgage, rent and other fees related to housing
- cardSpends: the monthly spends with credit cards
- loanSpends: all other monthly credit/financing products spends that are not credit card
- address: address of the customer
- occupation: Company Employee | Retired | Self-Employment | Public Sector | Multiple sources of income | Other
- desiredCreditLimit: is the credit line denominated in R$ that the customer desires for this credit card

IMPORTANT: while the majority of the customer-reported information is not mandatory, the more information that is shared, the more precise the outcome will be.

Response

After the full pipeline is executed, the response with the example schema below is sent as a POST request to the URL registered in the preparation stage.

{  
  "customerUuid": "XXXXXXXXXXXXXX",
  "started": "2014-06-25T00:00:00.000Z",
  "finished": "2014-06-25T00:00:00.000Z",
  "serviceType": "GUARD_SCORE",
  "response": {
    "costSavingEnabled": false
    "score": 0.015,
    "riskBand": 3,
    "limit": 500
  }
}

Schema Description

The following is a description of each field in the response payload:

customerUuid is the unique identifier of your customer in your database. This will have the same value that was sent in the request payload.
started is the datetime value of when the underwriting process started
finished is the datetime value of when the underwriting process finished
serviceType will always contain "GUARD_SCORE"
response is the actual result of the of the underwriting process as is composed of:
- costSavingEnabled: if cost saving policy was active or not
- score: our model's final score (can be -1 if cost-saving policy is active and is the customer is filtered out from having all data sources queried, or if the model cannot calculate the score)
- riskBand: the score based risk band (can be -1 if costsaving policy is active, or if the model cannot calculate the score)
- limit: in case of approval this is the initial credit line suggested, or zero if not approved (can be -1 if cost saving policy is active, or if the model cannot calculate the score)

Sandbox

To facilitate comprehensive testing of the API, a dedicated sandbox environment has been established. The mechanics for accessing the sandbox mirror those of the regular Production environment, with the sole distinction being the URL, which is designated as ml-service-hub.stg.ab-api-service.com.
It's also important to note that this sandbox environment requires the same preparation as the Production environment.

Within the sandbox, a set of three fabricated CPFs has been provisioned to emulate diverse testing scenarios:

41955366004: This CPF is engineered to trigger a rejection within the cost-saving funnel. It's crucial to note that this specific CPF will only yield the expected rejection outcome when the cost-savings flag is explicitly activated. Under this circumstance, a score of “-1” is returned.
14779111030: This CPF is designed to simulate a rejection within the standard operational flow. The anticipated response time for this CPF is approximately 10 seconds. [Under this circumstance, a score recommended credit limit of “0” is returned.]
39549600017: Conversely, this CPF is configured to result in an approval within the regular workflow. Similar to the previous CPF, the expected response time for this scenario is around 10 seconds. Under this circumstance, a score ranging between [ ] and [ ] is returned. [GUARD will also return a credit limit, defined as [a whole number above zero and denominated in R$]

These fabricated CPFs and the sandbox environment collectively provide a robust framework for developers and testers to rigorously evaluate the API's behavior under various conditions, ensuring its reliability and adherence to predefined business rules.