> 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/guias/conversion-funnel.md). # Conversion funnel This guide documents the relationship between the stages of the proposal conversion funnel and the status of each proposal. Use it as a reference to build reports, dashboards, and re-engagement actions from the data exposed by the API. When a metric cannot be identified by status alone, there is a note indicating that it must be cross-referenced with the **credit analysis reason** (field `analysis_status_code` from the API). The complete table of reasons is available in the section [Credit analysis reasons](#motivos-da-analise-de-credito). *** ## Proposal lifecycle The proposal goes through a sequence of statuses as it advances through the flow. The official order is maintained in the database. For the full transition diagram, see [Status machine](/api-reference/apis-en/guias/status-machine.md). ### Main flow — proposal advances to disbursement | Status | Meaning | | --------------------------------- | --------------------------------------- | | `CREATED` | Proposal created (CPF + basic data) | | `CONTACT_PENDING` | Waiting for email/phone to be filled in | | `TOKEN_SENT` | SMS token sent | | `TOKEN_VALIDATED` | Token validated | | `CONSENT_RECEIVED` | Consent to consult received | | `CREDIT_ANALYSIS_IN_PROGRESS` | Credit analysis in progress | | `CREDIT_CHECK_COMPLETED` | Credit engine returned offers | | `OFFER_SELECTED` | Customer chose an offer | | `PRE_ACCEPTED` | Pre-acceptance confirmed | | `BANK_DATA_SUBMITTED` | Bank details sent | | `CONTRACT_GENERATION_IN_PROGRESS` | Contract generation in progress | | `CONTRACT_GENERATED` | Contract generated | | `AWAITING_SIGNATURE` | Waiting for digital signature | | `SIGNED` | Contract signed | | `PENDING_ANALYSIS` | Waiting for antifraud analysis | | `ANALYSIS_APPROVED` | Approved in antifraud analysis | | `DISBURSED` | Credit disbursed ✅ | ### Recoverable technical failures | Status | When it occurs | | -------------------------------- | --------------------------------------------------------------------------------- | | `DATAPREV_FAILED_AWAITING_RETRY` | Technical failure in Dataprev/Celcoin — eligible for automatic reprocessing | | `CREDIT_ANALYSIS_FAILED` | Technical failure in the analysis (without business-rule rejection) | | `CONTRACT_GENERATION_FAILED` | Technical failure when generating the contract — allows another attempt | | `DISBURSEMENT_FAILED` | Disbursement failure due to a problem with bank details — customer can correct it | ### Rejections due to business rule or antifraud | Status | When it occurs | | ------------------- | ------------------------------------------- | | `ANALYSIS_REPROVED` | Rejected by the antifraud team | | `SIGNATURE_FAILED` | Invalid identity or signature not completed | ### Terminal states Proposals in these states can no longer advance — to try again, a new proposal must be created. * `CANCELED` * `CANCELLED_BY_USER` * `REJECTED` * `EXPIRED` * `ERROR` *** ## Funnel metrics by stage Each funnel stage corresponds to a specific set of proposal statuses. When a metric depends on additional information beyond the status, the note indicates how to obtain the exact separation. ### Stage 0 — Lead engagement | Metric | How to identify | Note | | ----------------------- | --------------------------------------------------------------------------------------- | ---- | | **Leads received** | All proposals created in the period | — | | **Engaged customers** | Proposals that **are not** in the statuses `CREATED`, `CONTACT_PENDING` or `TOKEN_SENT` | — | | **Unengaged customers** | Proposals in the statuses `CREATED`, `CONTACT_PENDING` or `TOKEN_SENT` | — | | **% Engagement** | Calculation: `engaged / leads received` | — | ### Stage 1 — Eligibility filters | Metric | How to identify | Note | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Leads eligible for analysis** | Calculation: `engaged − out of profile` | — | | **Out of profile (total)** | Proposals in `REJECTED` by eligibility reason plus technical failures in `DATAPREV_FAILED_AWAITING_RETRY` and `CREDIT_ANALYSIS_FAILED` | ⚠️ Different reasons end in the same status `REJECTED`. The exact separation of this group requires the [credit analysis reason](/api-reference/apis-en/queries/get-proposals-by-id.md) | | **Not CLT** | Proposals in the status `REJECTED` | ⚠️ This group shares the status `REJECTED` with other rejections. The separation requires the [credit analysis reason](/api-reference/apis-en/queries/get-proposals-by-id.md) — applicable reasons: `NO_DATA_DATAPREV`, `NOT_AUTHORIZED_DATAPREV`, `CPF_EMPLOYER`, `EMPLOYER_IN_JUDICIAL_RECOVERY` | | **No margin** | Proposals in the status `REJECTED` | ⚠️ This group shares the status `REJECTED` with other rejections. The separation requires the [credit analysis reason](/api-reference/apis-en/queries/get-proposals-by-id.md) — applicable reason: `NO_AVAILABLE_MARGIN` | | **Dataprev failure** | Proposals in the statuses `DATAPREV_FAILED_AWAITING_RETRY`, `CREDIT_ANALYSIS_FAILED` or `REJECTED` | ⚠️ The status `CREDIT_ANALYSIS_FAILED` is shared with other technical failures. The exact separation requires the [credit analysis reason](/api-reference/apis-en/queries/get-proposals-by-id.md) — applicable reason: `FAILED_DATAPREV` | ### Stage 2 — Credit analysis | Metric | How to identify | Note | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Sent for credit analysis** | Proposals starting from the status `CREDIT_ANALYSIS_IN_PROGRESS`, including later ones in the flow and those rejected by the credit engine (`REJECTED`) | ⚠️ The official count uses the [credit analysis reason](/api-reference/apis-en/queries/get-proposals-by-id.md) (any proposal evaluated by the engine). Approximating by status alone results in a set larger than the real one | | **Proposals rejected in credit** | Proposals in the status `REJECTED` | ⚠️ The status `REJECTED` is shared with "out of profile" and some Dataprev failures. The exact separation requires the [credit analysis reason](/api-reference/apis-en/queries/get-proposals-by-id.md) — applicable reasons: `REJECTED`, `ERROR`, `CREDIT_ENGINE_ERROR` | | **Proposals approved in credit** | Proposals in the statuses between `CREDIT_CHECK_COMPLETED` and `DISBURSED` (inclusive) | Reasonable approximation by status. The official metric uses the [credit analysis reason](/api-reference/apis-en/queries/get-proposals-by-id.md) — applicable reason: `APPROVED` | | **% Approval** | Calculation: `approved / sent for analysis` | — | ### Stage 3 — Contracts | Metric | How to identify | Note | | ---------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | **Contracts generated** | Proposals in the statuses `CONTRACT_GENERATED` or `AWAITING_SIGNATURE` | — | | **Waiting for signature** | Proposals in the statuses `CONTRACT_GENERATED` or `AWAITING_SIGNATURE` | — | | **Waiting for antifraud analysis** | Proposals in the status `PENDING_ANALYSIS` | — | | **Antifraud approved** | Proposals starting from the status `ANALYSIS_APPROVED` (any later status in the flow) | The official count is based on the result of the antifraud analysis. This set of statuses is equivalent to the same group | | **Antifraud rejected** | Proposals in the status `ANALYSIS_REPROVED` | — | ### Stage 4 — Disbursement | Metric | How to identify | Note | | ----------------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------- | | **Credit paid out to the customer** | Proposals in the status `DISBURSED` with contract actually issued | — | | **Financed volume** | Sum of principal amount + insurance amount of paid proposals | — | | **Average ticket** | Average financed amount per issued contract | Metric calculated over contracts, not over proposal status | | **Average rate** | Weighted average interest rate of issued contracts | Metric calculated over contracts, not over proposal status | | **Average term** | Weighted average term of issued contracts | Metric calculated over contracts, not over proposal status | | **% Paid / approved** | Calculation: `credit paid / approved proposals` | — | | **% Paid / leads** | Calculation: `credit paid / leads received` | — | *** ## Credit analysis reasons Complete table of the possible values of the **credit analysis reason** (field `analysis_status_code`). These values are available in the API response ([Find proposal by ID](/api-reference/apis-en/queries/get-proposals-by-id.md)). | Code | Friendly message | Category | Description | | ------------------------------- | --------------------------------------- | --------------- | -------------------------------------------------------------------------- | | `APPROVED` | Approved | Success | Proposal approved and offer generated successfully | | `NO_AVAILABLE_MARGIN` | Customer does not have available margin | Rejection | Customer does not have available payroll-deduction margin balance | | `NOT_AUTHORIZED_DATAPREV` | Customer does not have available margin | Rejection | Customer was not authorized by Dataprev (no authorized products) | | `NOT_WHITELISTED` | Rejected | Rejection | CPF is not on the authorized whitelist | | `CPF_EMPLOYER` | Rejected | Rejection | Employer's CNPJ is actually a CPF (irregular) | | `REJECTED` | Rejected | Rejection | Proposal rejected by the credit engine (credit policy) | | `EMPLOYER_IN_JUDICIAL_RECOVERY` | Company in judicial recovery | Rejection | Employer company is undergoing judicial recovery | | `BLACKLISTED` | Blocked CPF | Rejection | CPF found on the blacklist and blocked for credit analysis | | `FAILED_DATAPREV` | Dataprev consultation failure | Technical error | Technical failure when consulting Dataprev system (timeout or HTTP error) | | `ERROR` | Dataprev consultation failure | Technical error | Generic unclassified error during analysis | | `CREDIT_ENGINE_ERROR` | Dataprev consultation failure | Technical error | Credit engine error (timeout, provider failure) | | `NOT_ANALYZED` | Incomplete proposal | Pending | Proposal has not yet gone through credit analysis | | `NO_DATA_DATAPREV` | Customer is not CLT | Information | Customer not found in Dataprev (does not have CLT employment relationship) | ### Meaning of the categories | Category | What it represents | | ------------------- | ----------------------------------------------------------------------------------------- | | **Success** | Proposal approved — proceeds through the normal flow | | **Rejection** | Proposal rejected by business rule or credit policy — terminal state | | **Technical error** | Failure in external system (Dataprev, credit engine) — may be automatically reprocessed | | **Pending** | Proposal has not yet been evaluated by the engine | | **Information** | Indicates a customer characteristic (e.g., not CLT) without necessarily blocking the flow | *** ## Summary — metrics that depend on the analysis reason The metrics below share the final status `REJECTED` with other cases and, therefore, require cross-referencing with the **credit analysis reason** to be separated accurately. | Metric | Applicable reasons (`analysis_status_code`) | | ------------------ | ------------------------------------------------------------------------------------------------------------------- | | Not CLT | `NO_DATA_DATAPREV`, `NOT_AUTHORIZED_DATAPREV`, `CPF_EMPLOYER`, `EMPLOYER_IN_JUDICIAL_RECOVERY` | | No margin | `NO_AVAILABLE_MARGIN` | | Rejected in credit | `REJECTED`, `ERROR`, `CREDIT_ENGINE_ERROR` | | Dataprev failure | `FAILED_DATAPREV` (may be in the statuses `DATAPREV_FAILED_AWAITING_RETRY`, `CREDIT_ANALYSIS_FAILED` or `REJECTED`) | | Sent for analysis | any value filled in `analysis_status_code` | | Approved in credit | `APPROVED` | > 📎 The analysis reason is available as the field `analysis_status_code` in the API response — see [Find proposal by ID](/api-reference/apis-en/queries/get-proposals-by-id.md). *** ## Re-engagement of open proposals Segmentation suggestion for re-engagement actions, grouped by communication intent. | Segment | Proposals in the statuses | Suggested message | | -------------------------------------- | ------------------------------------------------------------------------ | -------------------------------------------- | | Unengaged | `CREATED`, `CONTACT_PENDING`, `TOKEN_SENT` | "Continue where you left off" | | Engaged, recoverable technical failure | `DATAPREV_FAILED_AWAITING_RETRY`, `CREDIT_ANALYSIS_FAILED` | "Try again — we had a failure" | | Has an offer, did not choose | `CREDIT_CHECK_COMPLETED` | "See the credit offer we released" | | Chose, stopped halfway | `OFFER_SELECTED`, `PRE_ACCEPTED`, `BANK_DATA_SUBMITTED` | "You're almost there — finish your contract" | | Contract ready, not signed | `CONTRACT_GENERATED`, `AWAITING_SIGNATURE`, `CONTRACT_GENERATION_FAILED` | "Your contract is ready — sign it" | | Almost received the credit | `DISBURSEMENT_FAILED` | "Update your bank details" | ### Who should not be contacted | Reason | Proposals in the statuses | | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | | Terminal state — requires a new proposal | `REJECTED`, `EXPIRED`, `CANCELED`, `CANCELLED_BY_USER`, `ERROR`, `ANALYSIS_REPROVED`, `SIGNATURE_FAILED` | | Being processed internally — wait for completion | `CREDIT_ANALYSIS_IN_PROGRESS`, `CONTRACT_GENERATION_IN_PROGRESS`, `SIGNED`, `PENDING_ANALYSIS`, `ANALYSIS_APPROVED` | --- # 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/guias/conversion-funnel.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.