> For the complete documentation index, see [llms.txt](https://docs.bullcredtech.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bullcredtech.com/api-reference/apis-en/proposal-flow/post-proposals-simulate.md). # 4.3. Simulate offers **POST** `/proposals/{proposalId}/simulate` Generates and stores personalized credit offers for the proposal based on the limits approved in the credit analysis. The generated offers are linked to the proposal and can be selected in pre-acceptance. {% hint style="info" %} **Available after Credit Analysis** This endpoint can only be called after the credit analysis is completed (`CREDIT_CHECK_COMPLETED` or subsequent statuses such as `OFFER_SELECTED`, `PRE_ACCEPTED`, `BANK_DATA_SUBMITTED`). {% endhint %} ## URL Parameters | Parameter | Type | Description | | ------------ | ------------- | ----------- | | `proposalId` | string (UUID) | Proposal ID | ## Simulation Modes This endpoint operates in **2 distinct modes** (provide only one of the fields per request): | Mode | Field | Description | | ---------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------- | | **Mode 1 — By Term** | `installments` | Enter the desired number of installments and receive the maximum financeable amount with the installment within the limit | | **Mode 2 — By Amount** | `loan_amount` | Enter the desired amount and receive the available term options | ## Request Body | Field | Type | Required | Description | Example | | -------------- | ------- | :-----------: | ---------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `installments` | number | Conditional\* | Desired number of installments (Mode 1) | `12` | | `loan_amount` | number | Conditional\* | Desired loan amount in R$ (Mode 2) | `10000` | | `insured` | boolean | No | Simulate with loan protection insurance (default: `false`). Only has an effect if the partner has insurance configured by the Bull team. | `false` | \*Provide only one of the two fields per request. ## Request Examples ### Mode 1 — By Term (without insurance) ```json { "installments": 12 } ``` ### Mode 1 — By Term (with insurance) ```json { "installments": 12, "insured": true } ``` ### Mode 2 — By Amount (without insurance) ```json { "loan_amount": 10000 } ``` ### Mode 2 — By Amount (with insurance) ```json { "loan_amount": 10000, "insured": true } ``` ## Success Response (200 OK) ```json { "simulation_mode": "BY_INSTALLMENTS", "proposal_id": "99afc6ce-4720-4746-9cf6-0a23e85cdf75", "product_id": "d82b9334-0cdf-494c-b414-d12b356e54e6", "product_name": "Private Payroll Loan", "total_offers": 1, "message": "Simulation completed successfully", "offers": [ { "id": "a69660f8-2309-4a55-a0c6-e6a701a04a67", "proposal_id": "99afc6ce-4720-4746-9cf6-0a23e85cdf75", "offer_type": "STANDARD", "status": "ACTIVE", "description": "Payroll-Deducted Credit Offer", "principal_amount": 25153.66, "interest_rate": 4.99, "annual_interest_rate": 79.3805, "installments": 12, "installment_amount": 2327.96, "total_amount": 27935.52, "iof_amount": 497.87, "tac_amount": 0, "insurance_amount": 0, "first_due_date": "2025-12-21T00:00:00.000Z", "final_due_date": "2026-11-21T00:00:00.000Z", "expires_at": "2025-10-20T20:45:19.204Z", "priority": 1, "is_available": true, "created_at": "2025-10-13T20:45:19.204Z", "updated_at": "2025-10-13T20:45:19.204Z" } ] } ``` ### Response Fields | Field | Type | Description | | ----------------- | ------------- | ------------------------------------------------ | | `simulation_mode` | string | Mode used: `BY_INSTALLMENTS` or `BY_LOAN_AMOUNT` | | `proposal_id` | string (UUID) | Proposal ID | | `product_id` | string (UUID) | Product ID used | | `product_name` | string | Product name | | `total_offers` | number | Number of offers generated | | `message` | string | Informational message | | `offers` | array | List of generated and stored offers | ### Fields for Each Offer (`offers[]`) | Field | Type | Description | | ---------------------- | ----------------- | ------------------------------------------------------------- | | `id` | string (UUID) | **Offer ID** — use for selection in pre-acceptance | | `principal_amount` | number | Net amount to be credited to the client | | `interest_rate` | number | Monthly interest rate (%) | | `annual_interest_rate` | number | Annual interest rate (APR) | | `installments` | number | Number of installments | | `installment_amount` | number | Amount of each installment | | `total_amount` | number | Total amount to be paid | | `iof_amount` | number | IOF amount | | `insurance_amount` | number | Total payment protection insurance amount (0 if no insurance) | | `first_due_date` | string (ISO 8601) | Date of the first due date | | `final_due_date` | string (ISO 8601) | Date of the last due date | | `expires_at` | string (ISO 8601) | Offer validity | | `is_available` | boolean | Whether the offer is available for selection | ## Possible Errors | Code | Message | | ---- | ------------------------------------------------ | | 400 | Invalid parameters or outside the allowed limits | | 404 | Proposal not found | | 409 | Proposal in an invalid state for simulation | ## Notes * The generated offers are **stored in the database** and linked to the proposal — they are not just ephemeral simulations * Subsequent calls overwrite the previous offers * The value of `installment_amount` is calculated to be **within the available payroll-deduction margin** * The field `offer.id` returned must be used in the [pre-acceptance](/api-reference/apis-en/proposal-flow/post-proposals-pre-accept.md) via `selected_offer_id` * The field `insured: true` generates an offer with loan protection insurance included in the installment amount — **available only for partners with insurance configured by the Bull team**. If the partner does not have insurance enabled, the field is ignored and the simulation returns the standard offer {% hint style="success" %} **Next Step** Confirm the selected offer: [POST /proposals/{id}/pre-accept](/api-reference/apis-en/proposal-flow/post-proposals-pre-accept.md) {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.bullcredtech.com/api-reference/apis-en/proposal-flow/post-proposals-simulate.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.