Contract retrieval

Read calls for expense contracts:

Retrieve contract by key: one contract, with status history and download links.
List fund contracts and across all funds: paginated lists, with filters.
Contract summary: number of contracts per status.
Amendment history: the original contract and its amendments.

Retrieve contract by key

Returns the contract with its status history and the links to download the document and the attachments.

Available on

Profile	Host	Required permission
Manager	`manager-api`	Read
Consultant	`consultant-api`	Read Expense Contracts

Base URL for each host: Environments (Hosts).

ENDPOINT

/expense_contract/fund_class/{fund_class_key}/contract/{contract_key}

METHOD

GET

Path parameters

Parameter	Type	Description
`fund_class_key`	string	Fund class key (UUID).
`contract_key`	string	Contract key (UUID).

Response

STATUS

200

The contract, in the structure described in contract attributes, with the additional fields below.

Response excerpt
{
    "contract_key": "3f2b8c1e-7d4a-4e9b-9a61-0c5d2e8f4b17",
    "status": "in_manual_analysis",
    "ai_analysis": {
        "ai_analysis_key": "7c8d9e0f-1a2b-4c3d-9e4f-5a6b7c8d9e0f",
        "status": "valid",
        "analysis_result": {
            "document_numbers": {
                "fund_class": "33.444.555/0001-81",
                "vendor": "44.555.666/0001-81"
            },
            "expense_types": ["audit_tax"],
            "expiration_date": "2027-12-31",
            "recurrences": [
                {
                    "expense_type": "audit_tax",
                    "amount": 2500.0,
                    "start_date": "2027-01-01",
                    "end_date": "2027-12-31",
                    "periodicity": "monthly"
                }
            ],
            "prohibited_clauses": []
        }
    },
    "attachments": [
        {
            "attachment_key": "d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f7a",
            "status": "active",
            "created_at": "2026-11-09T14:20:11.004512",
            "download_url": "https://<link-temporario-de-download>"
        }
    ],
    "status_events": [
        {
            "status": "created",
            "event_datetime": "2026-11-09T14:03:22.498765",
            "author_type": "qitech",
            "author_name": null
        },
        {
            "status": "pending_submission",
            "event_datetime": "2026-11-09T14:03:22.498901",
            "author_type": "qitech",
            "author_name": null
        },
        {
            "status": "sent_to_analysis",
            "event_datetime": "2026-11-09T14:10:05.120034",
            "author_type": "qitech",
            "author_name": null
        },
        {
            "status": "in_manual_analysis",
            "event_datetime": "2026-11-09T14:11:40.774210",
            "author_type": "qitech",
            "author_name": null
        }
    ],
    "download_url": "https://<link-temporario-de-download>",
    "signed_download_url": null
}

Field	Type	Description
`status_events`	array	Status changes. Each item has `status`, `event_datetime`, `author_type` and `author_name`. See authorship below.
`download_url`	string	URL to download the contract document, valid for 24 hours. Before submission for review, it points to the last uploaded file; afterwards, to the frozen document. It is filled in even if no file has been uploaded.
`signed_download_url`	string	URL to download the signed document, valid for 24 hours, or `null` while it does not exist.
`attachments[].download_url`	string	URL to download each attachment, valid for 24 hours.
`ai_analysis.analysis_result`	object	Data read from the document: `document_numbers` (`fund_class`, `vendor`), `expense_types`, `expiration_date`, `recurrences` and `prohibited_clauses`. `null` while the reading has not finished or when it fails.

Authorship in status_events:

author_type manager or consultant, with the name in author_name: action taken by a portal user.
author_type qitech, with author_name: null: all other cases, including API calls with an integration key.

ai_analysis.status: inconclusive indicates a mismatch between the document and the contract data. The QI Tech review makes the decision.

List fund contracts

Lists the contracts of one fund, with filters and pagination.

Available on

Profile	Host	Required permission
Manager	`manager-api`	Read
Consultant	`consultant-api`	Read Expense Contracts

Base URL for each host: Environments (Hosts).

ENDPOINT

/expense_contract/fund_class/{fund_class_key}/contracts

METHOD

GET

Path parameters

Parameter	Type	Description
`fund_class_key`	string	Fund class key (UUID).

Query parameters

Parameter	Type	Required	Description
`status`	string	No	Contract status. Accepts several comma-separated values. An unknown value does not return an error and matches no contract.
`expense_type`	string	No	Contracts that declare this expense type.
`vendor_key`	string	No	Contracts of this vendor.
`termination_status`	string	No	Contracts with a termination request in this status: `pending_analysis`, `approved` or `reproved`.
`limit`	integer	No	Items per page, from `1` to `100`. Default: `10`.
`page`	integer	No	Page, starting at `0`. Default: `0`.

Response

STATUS

200

Response body
{
    "data": [],
    "limit": 10,
    "page": 0,
    "is_last_page": true,
    "total": 0
}

Each item in data is a contract in the structure of contract attributes, without status_events or download links. total is the number of contracts matching the filters.

The list runs from the most recent contract to the oldest and shows each version of the chain as a separate item: the replaced contract (amended), the rejected or canceled amendments and the amendment in force. In an amendment, amended_contract_key gives the contract it replaces.

List contracts across all funds

Lists the contracts of all of the manager's funds. For a consultant, only the funds in which it has the Read Expense Contracts permission.

Accepts the same filters and returns the same response as the fund list. The additional fund_class_key parameter restricts it to one fund; a fund outside that scope returns an empty list.

ENDPOINT

/expense_contract/contracts

METHOD

GET

Permission: Manager (manager-api): Read. Consultant (consultant-api): active integration; the result only includes the funds where it has Read Expense Contracts.

Contract summary

Counts the contracts created in the period, grouped by current status.

ENDPOINT

/expense_contract/contracts/summary

METHOD

GET

Permission: Manager (manager-api): Read. Consultant (consultant-api): active integration; the result only includes the funds where it has Read Expense Contracts.

Parameter	Type	Required	Description
`fund_class_key`	string	No	Restricts to one fund.
`date_range_start`	string	No	Start of the creation period, `YYYY-MM-DD`.
`date_range_end`	string	No	End of the creation period, `YYYY-MM-DD`.

Without both dates, the period runs from the first day of the current month until today. A date sent on its own is ignored.
The fund scope is the same as in the all-funds list. A fund_class_key outside it returns zeroed counts.

Response body
{
    "period": {
        "start": "2026-11-01",
        "end": "2026-11-09"
    },
    "contracts": {
        "total": 7,
        "pending_submission": 2,
        "pending_vendor_approval": 0,
        "sent_to_analysis": 1,
        "in_compliance_analysis": 0,
        "in_manual_analysis": 1,
        "pending_manager_approval": 0,
        "pending_signature": 1,
        "active": 2,
        "expired": 0,
        "amended": 0,
        "reproved": 0,
        "canceled": 0
    }
}

Amendment history

Returns the original contract and every amendment in the chain, from oldest to most recent. Works from any contract in the chain.

ENDPOINT

/expense_contract/fund_class/{fund_class_key}/contract/{contract_key}/history

METHOD

GET

Permission: Manager (manager-api): Read. Consultant (consultant-api): Read Expense Contracts.

The response is {"data": [...]}, without pagination, with contracts in the structure of contract attributes.

Errors

Status	`code`	When it happens
400	`QIT000010`	`limit`, `page` or a date in the wrong format.
400	`ECT000067`	Summary: `date_range_start` later than `date_range_end`.
404	`ECT000005`	The fund class does not exist or you do not have access to it.
404	`ECT000009`	The contract does not exist in this fund class.
404	`ECT000001`	All-funds list or summary: the manager or consultant is not yet registered in the contract service.

Authentication, permission and host errors: see API Errors.

Retrieve contract by key​

Path parameters​

Response​

List fund contracts​

Path parameters​

Query parameters​

Response​

List contracts across all funds​

Contract summary​

Amendment history​

Errors​

Retrieve contract by key

Path parameters

Response

List fund contracts

Path parameters

Query parameters

Response

List contracts across all funds

Contract summary

Amendment history

Errors