> 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/queries/get-proposals.md).

# List Proposals

**GET** `/proposals`

Lists proposals with filters and pagination. Proposals are automatically filtered by the source of the authentication token.

## Query Parameters

| Parameter      | Type    | Required | Description                                     | Default           | Example            |
| -------------- | ------- | :------: | ----------------------------------------------- | ----------------- | ------------------ |
| `page`         | integer |    No    | Page number                                     | `1`               | `1`                |
| `limit`        | integer |    No    | Items per page (max: 100)                       | `10`              | `20`               |
| `cpf`          | string  |    No    | Filter by CPF (partial search)                  | -                 | `12345678909`      |
| `full_name`    | string  |    No    | Filter by name (partial search)                 | -                 | `John`             |
| `status`       | string  |    No    | Filter by status (multiple separated by commas) | -                 | `SIGNED,DISBURSED` |
| `email`        | string  |    No    | Filter by email (partial search)                | -                 | `john@example.com` |
| `phone`        | string  |    No    | Filter by phone (partial search)                | -                 | `11999999999`      |
| `bank_code`    | string  |    No    | Filter by bank code                             | -                 | `001`              |
| `created_from` | string  |    No    | Initial creation date (`YYYY-MM-DD`)            | -                 | `2025-01-01`       |
| `created_to`   | string  |    No    | Final creation date (`YYYY-MM-DD`)              | -                 | `2025-12-31`       |
| `updated_from` | string  |    No    | Initial update date (`YYYY-MM-DD`)              | -                 | `2025-01-01`       |
| `updated_to`   | string  |    No    | Final update date (`YYYY-MM-DD`)                | -                 | `2025-12-31`       |
| `sort`         | string  |    No    | Sorting (`field:direction`)                     | `created_at:desc` | `updated_at:asc`   |

### Sort Values

| Value             | Description                        |
| ----------------- | ---------------------------------- |
| `created_at:asc`  | Creation date ascending            |
| `created_at:desc` | Creation date descending (default) |
| `updated_at:asc`  | Update date ascending              |
| `updated_at:desc` | Update date descending             |
| `full_name:asc`   | Name alphabetically A-Z            |
| `full_name:desc`  | Name alphabetically Z-A            |

## Request Examples

```http
# Basic listing with pagination
GET /proposals?page=1&limit=20

# Filter by status (multiple)
GET /proposals?status=SIGNED,DISBURSED,PENDING_ANALYSIS

# Filter by creation period
GET /proposals?created_from=2025-01-01&created_to=2025-01-31

# Filter by update period (useful for incremental syncs)
GET /proposals?updated_from=2025-01-01&updated_to=2025-01-31

# Search by partial CPF
GET /proposals?cpf=12345

# Combination of filters
GET /proposals?page=1&limit=10&status=CONTRACT_GENERATED&created_from=2025-01-01&sort=created_at:desc
```

## Success Response (200 OK)

```json
{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "cpf": "12345678909",
      "full_name": "JOHN DOE",
      "birth_date": "1985-03-15",
      "email": "john@example.com",
      "phone": "+5511999999999",
      "status": "DISBURSED",
      "status_detail": {
        "code": "DISBURSED",
        "name": "Disbursed",
        "description": "Credit was disbursed to the provided account",
        "order": 18
      },
      "bank_code": "001",
      "agency": "1234",
      "account": "56789",
      "account_type": "checking_account",
      "origin": "EXAMPLE_ORIGIN",
      "selected_offer": {
        "id": "offer-uuid-123",
        "principal_amount": 10000.00,
        "installments": 24,
        "installment_amount": 520.50
      },
      "created_at": "2025-01-10T10:30:00.000Z",
      "updated_at": "2025-01-14T15:45:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 45,
    "totalPages": 5,
    "hasNext": true,
    "hasPrev": false
  },
  "filters": {
    "status": "DISBURSED",
    "created_from": "2025-01-01"
  }
}
```

### Fields of Each Proposal (`data[]`)

| Field               | Type              | Description                                     |
| ------------------- | ----------------- | ----------------------------------------------- |
| `id`                | string (UUID)     | Proposal ID                                     |
| `cpf`               | string            | Customer CPF                                    |
| `full_name`         | string            | Full name                                       |
| `birth_date`        | string            | Date of birth                                   |
| `email`             | string            | Email                                           |
| `phone`             | string            | Phone                                           |
| `status`            | string            | Current status                                  |
| `status_detail`     | object            | Status details (code, name, description, order) |
| `bank_code`         | string            | Bank code                                       |
| `agency`            | string            | Branch                                          |
| `account`           | string            | Account                                         |
| `account_type`      | string            | Account type                                    |
| `origin`            | string            | Originator code                                 |
| `user_redirect_url` | string            | Signature URL (if applicable)                   |
| `selected_offer`    | object            | Selected offer summary                          |
| `created_at`        | string (ISO 8601) | Creation date                                   |
| `updated_at`        | string (ISO 8601) | Update date                                     |

### Pagination (`pagination`)

| Field        | Type    | Description                                |
| ------------ | ------- | ------------------------------------------ |
| `page`       | integer | Current page                               |
| `limit`      | integer | Items per page                             |
| `total`      | integer | Total records                              |
| `totalPages` | integer | Total pages                                |
| `hasNext`    | boolean | Indicates whether there is a next page     |
| `hasPrev`    | boolean | Indicates whether there is a previous page |


---

# 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/queries/get-proposals.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.