Credit card application decisioning API
Preapproval v2
PreApproval V2 provides an API set used to validate, submit, and supplement credit application data. These APIs are tailored, schema-driven, and real-time, designed to support the full lifecycle of credit applications under versioned credit policies.
Partners are required to send the entire population of credit applications through the PreApproval APIs, including those that are:
- Funded
- Approved but not accepted
- Denied
- Incomplete
- Withdrawn
- Prequalifications
Providing all application outcomes ensures that Cross River Bank (CRB) can perform the statistical analyses required under regulatory guidance. This complete dataset enables monitoring for potential disparities, supports model governance, and ensures compliance with Fair Banking and fair lending obligations.
Each endpoint includes a schemaId in the URL, representing the data model and validation rules agreed upon between CRB and the partner for that schema version. Schema updates are requested through the change management process (via Jira) and updated on our schema builder UI.
IMPORTANT To access the links below you must have the following IP addresses allowlisted:
Sandbox - 66.206.202.39 , 66.206.202.12
Production -66.206.202.62 , 66.206.202.15
Schema builder and data dictionary UI
The schema builder UI is an interface where partners can view and build together with Cross River, the data schema that will be used for their API, according to the partner-specific model. Each schema defines the required and optional fields for the Application Submission and dry-run APIs, including data types, validation rules, and field descriptions. Partners can use this interface to confirm their integration aligns with the agreed-upon schema before submitting applications under the finalized and approved schema.
Access to Schema UI
Schema UI URL: https://lendingappsandbox.crbcos.com/preapproval/schemas
Application UI: https://lendingappsandbox.crbcos.com/preapproval/applications
Gaining access to the Preapproval v2 Schema UI is done via self-service on Org management portalorg management. Your IT Manager should have Admin access, and must add the following to your user:
- Role: Lending Preapproval v2 ReadOnly
- Partner: Associate the partner created for Preapproval with your user
API suite
An application in Pav2, is identified by the partner's application_id, which should be unique for each application in the partner's system.
- Base URL for sandbox: https://lendingsandbox.crbcos.com/preapproval
- Base URL for production: https://lending.crbcos.com/preapproval
- API scope for sandbox is: CosLending:PreApproval:stg
- API scope for production is: CosLending:PreApproval:prd
API | Description |
|---|---|
POST /api/v2/applications/{Partner Schema ID} POST /api/v2/applications/{Partner Schema ID} | Post or update an application, including the final decision. You can call this multiple times, and we will only use the latest, according to application_id. |
POST /api/v2/applications/{Partner Schema ID}/dryrun | This is identical to the above API, but is used only to test the validations and not actually submit the application. |
Attachments by appIDPOST v2/applications/by-app-id/{application_id}/attachments | Post file attachments to an application. Attachments are sent in a zip file. |
Notes:
- During implementation, Cross River and the partner will agree on additional fields to be passed to Cross River based on the partner's unique operating model.
- Data types and schemas are available directly in the Schema UI, as well as descriptions and other goodies that will help you build your API integration.
- Partners should ultimately send their final decision when using the API.
- The integrations and rules that run when sending in the PreApproval API are informational. They do not change the status of the application automatically.
Integrations in PAV2
In PAV2, an integration is a configurable connection from a partner schema/application flow to another system or service. When a partner submits an application, PAV2 validates the application against the partner-specific JSON schema, loads the integrations configured for that schema, evaluates any “execute when” conditions, maps fields from the application into the integration’s expected parameters, and then executes the integration.
Integrations are intended to make PAV2 an orchestration point for lending workflows, rather than only a schema-validation and application-storage system. Examples can include compliance screening, loan origination, account/customer creation, decisioning, and reporting handoffs.
How integrations are configured
- Integration definition: There is a hard set of integrations available in Pav2. Over time, we will add more integrations and integration types for our partners.
- Integration configuration: CRB Users can configure the integration for a specific partner schema, map schema fields to the required integration parameters, and define when the integration should run.
- Validation: PAV2 validates mappings against the partner schema. Invalid configurations should show field-level validation errors; some type conversions may be allowed with warnings depending on the integration parameter rules.
- Enablement: Integrations are enabled for schemas only after the configuration is valid and follows the schema lifecycle / approval rules.
- Testing: Integrations should not run when running a dry-run, as this can incur unwanted costs and processes to be kicked off. To test connectivity and the integration, you may ask CRB to enable the integration temporarily in dry-run calls as well.
Runtime behavior
- Partner submits an application to PAV2.
- PAV2 authenticates the request and validates the payload against the relevant partner schema.
- If schema validation fails, PAV2 returns validation errors and does not run downstream integrations.
- If validation succeeds, PAV2 loads the enabled integrations for that partner schema and evaluates the "execute when" condition for each enabled integration.
- If the condition is true, Pav2 calls the integration and returns the result in the Submit Application API response. The responses are in the integration_results array.
Current and planned examples
- Internal list screening: Runs internal screening logic and returns compliance-related results.
- Arix loan origination: Maps PAV2 application fields into the Arix loan dictionary and calls Arix to create a loan, so that the partner does not need to maintain two separate data dictionaries. This replaces the need for Create and update a loan
- COS customer/account opening: Potential integration path for creating customers and accounts as part of credit card or embedded finance flows.
- Decisioning / data enrichment: Future integrations may include vendors such as 2nd- look decision vendors, credit bureau pulls, KYC/CIP, fraud, or other waterfall-style services.
Cross River rules on preapproval
When posting an application using the Preapproval API, Cross River can check the data against a set of regulatory rules and return the rule results in the API response. The response body includes rule results in the rule_results object, which includes information about the rule and the data used when running the rule. If one of the rules fails on Preapproval, you can assume it will also fail in Arix. Speak to your {{}}, if you would like rules to run in preapproval.
- Currently, there are no webhooks in preapproval.
- The results of the rules are returned synchronously in the response.
- Cross River Ops cannot manually override the result of a rule in pre-approval, as these results are purely informational for our partners to use.
- Pre-approval rules do not alter the status of an application in pre-approval sent in by an MPL.
The following is an example of a rule_results object that contains the Cross River Internal List Rule.
"rule_results": [
{
"status": "Success",
"rule_process_date": "2023-09-06",
"rule_results": [
{
"ruleId": "92bc95b5-fa3c-468a-b28b-b06800bdb9d7",
"version": "v1",
"ruleName": "Internal List Check",
"ruleDescription": "Borrower information should not be on Bank's Internal List",
"passed": true,
"data": "Anita Loan 693952XXX,Scrooge McDuck 014512994,UNONX7ENMOKLDCOXSEAUXW28SERFP3XNELOLPL2KOPNZCQ9N8Y )}k;b,)Sv8jco_78(yh^eu4|B:",
"resultInfo": null
}
]
}
]