> 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/readme.md).

# Introduction to the Bull API

Everything you need to integrate your platform with Bull and originate private payroll-deducted loan offers, from identity validation to the digitally signed contract.

{% hint style="info" %}
Press <kbd>⌘K</kbd> (macOS) or <kbd>Ctrl+K</kbd> (Windows) to search for any endpoint or concept in this documentation.
{% endhint %}

## <mark style="color:$primary;">Getting started</mark>

Follow this sequence to make your first origination:<br>

1. **Obtain credentials**: request `client_id` and `client_secret` from the Bull integration team
2. **Authenticate**: generate a JWT token via OAuth2 Client Credentials ([see Authentication](/api-reference/apis-en/guias/authentication.md))
3. **Create a proposal**: follow the [Proposal Flow](/api-reference/apis-en/guias/proposal-flow.md) to originate your first proposal
4. **Configure webhooks**: receive real-time status change notifications ([see Webhooks](/api-reference/apis-en/guias/webhooks.md))

## <mark style="color:$primary;">Environments and base URLs</mark>

| ENVIRONMENT    | BASE URL                                  | USE                     |
| -------------- | ----------------------------------------- | ----------------------- |
| **Production** | `https://api.bullcredtech.com/v1`         | Real operations         |
| **Staging**    | `https://api.staging.bullcredtech.com/v1` | Development and testing |

## <mark style="color:$primary;">Data format</mark>

* **Content-Type**: `application/json`
* **Charset**: UTF-8
* **Date Format**: ISO 8601 (`YYYY-MM-DD` or `YYYY-MM-DDTHH:mm:ss.sssZ`)

### <mark style="color:$primary;">Required headers</mark>

Include these headers in all requests:

```http
Content-Type: application/json
Accept: application/json
Authorization: Bearer {access_token}
```

## <mark style="color:$primary;">Origination flow: 7 steps</mark>

The process follows a mandatory sequence. Steps marked as optional can be skipped.

<table><thead><tr><th width="105">And</th><th>STEP</th><th>ENDPOINT</th><th>DESCRIPTION</th></tr></thead><tbody><tr><td><mark style="color:$primary;"><strong>1</strong></mark></td><td><strong>Start proposal</strong></td><td><code>POST /proposals/start</code></td><td>Create proposal with CPF, name and date of birth</td></tr><tr><td><mark style="color:$primary;"><strong>2</strong></mark></td><td><strong>Send contact</strong></td><td><code>POST /proposals/{id}/contact</code></td><td>Send email and phone (triggers SMS)</td></tr><tr><td><mark style="color:$primary;"><strong>3</strong></mark></td><td><strong>Validate token</strong></td><td><code>POST /proposals/{id}/contact/validate-token</code></td><td>Validate SMS code</td></tr><tr><td><mark style="color:$info;"><strong>3.1</strong> (optional)</mark></td><td><strong>Token resend</strong></td><td><code>POST /proposals/{id}/contact/resend-token/whatsapp</code></td><td>Resend code via WhatsApp</td></tr><tr><td><mark style="color:$info;"><strong>3.2</strong> (optional)</mark></td><td><strong>Token resend</strong></td><td><code>POST /proposals/{id}/contact/resend-token</code></td><td>Resend code via SMS</td></tr><tr><td><mark style="color:$primary;"><strong>4</strong></mark></td><td><strong>Credit analysis</strong></td><td><code>POST /proposals/{id}/credit-analysis</code></td><td>Request credit analysis</td></tr><tr><td>4<mark style="color:$info;"><strong>.1</strong> (optional)</mark></td><td><strong>Adjust offer</strong></td><td><code>POST /proposals/{id}/simulate</code></td><td>Adjust amount and/or term</td></tr><tr><td><mark style="color:$primary;"><strong>5</strong></mark></td><td><strong>Pre-acceptance</strong></td><td><code>POST /proposals/{id}/pre-accept</code></td><td>Accept selected offer</td></tr><tr><td><mark style="color:$primary;"><strong>6</strong></mark></td><td><strong>Bank details</strong></td><td><code>POST /proposals/{id}/banking-data</code></td><td>Provide bank details for disbursement</td></tr><tr><td><mark style="color:$primary;"><strong>7</strong></mark></td><td><strong>Generate contract</strong></td><td><code>POST /proposals/{id}/contract</code></td><td>Generate contract and start digital signing</td></tr></tbody></table>

## <mark style="color:$primary;">Query endpoints</mark>

| ENDPOINT                               | DESCRIPTION                            |
| -------------------------------------- | -------------------------------------- |
| `GET /proposals`                       | List proposals with filters            |
| `GET /proposals/{id}`                  | Full details of a proposal             |
| `GET /proposals/statistics`            | Proposal statistics                    |
| `GET /proposals/{id}/contract/status`  | Contract and digital signature status  |
| `GET /proposals/{id}/analysis-data`    | Data and result of the credit analysis |
| `GET /proposals/{id}/message-timeline` | History of SMS/email sends             |

## <mark style="color:$primary;">Asynchronous processing</mark>

The credit analysis endpoints (`/credit-analysis`) and contract generation (`/contract`) are asynchronous. Use webhooks to receive the result; polling works but is not recommended.<br>

* `202 Accepted` → Processing started, result not yet available
* `409 Conflict` → Called during processing, wait for the result
* Webhook → Recommended way, receive the result as soon as it is ready

{% hint style="warning" %}
**Maintenance window**

Margin inquiry systems (Dataprev) become unavailable between the days **20 (10 PM)** and **23 (6 AM)** of each month. Avoid generating contracts during this period or implement error handling for this case.
{% 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/readme.md?ask=<question>&goal=<endgoal>
```

`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.