Batch Approval

When the assignment configuration requires manual approval, a batch approved in eligibility waits for the decision of the consultant (pending_consultant_approval) and/or the manager (pending_manager_approval). This endpoint records that decision: approve or deny the batch.

Available on

Profile	Host	Required permission
Manager	manager-api	Write
Consultant	consultant-api	Batches

Base URL for each host: Environments (Hosts).

The assignor calls the same endpoint through assignor-api to close insertion, but cannot send approved or denied (TRC000059).

Who decides in each status

Batch status	Manager	Consultant
pending_consultant_approval	Can deny (denied) or reopen (pending_assets_insertion). Cannot approve.	Can approve, deny or reopen.
pending_manager_approval	Can approve, deny or reopen.	Cannot act (TRC000087).

The same decision can be made in the Manager Portal or the Consultant Portal.

Where am I in the flow?

This step happens after the batch eligibility. You receive a webhook with status pending_consultant_approval or pending_manager_approval indicating that the batch is awaiting a decision. To remove assets before approving, see Removing Assets from the Batch.

Request

ENDPOINT

/trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}

METHOD

PUT

Path params

Parameter	Type	Description
assignment_external_id	string	The external_id provided when the batch was created.

Request Body — Approval

{
    "assignment_status": "approved",
    "disbursement_account_key": "764746ce-a530-4a71-af66-3f7c879627df",
    "number_of_approved_assets": 45,
    "assignment_total_value": 150000.00
}

Request Body — Denial

{
    "assignment_status": "denied",
    "denial_reason": {
        "reason_type": "manager",
        "denial_reason": "Concentração por sacado acima do limite do fundo"
    }
}

Body attributes

Field	Type	Required	Description
assignment_status	string	required	approved approves the batch; denied denies it.
disbursement_account_key	string	optional	Approval only. Key (UUID) of the assignor account that will receive the payment, among the accounts registered in assignor onboarding. If omitted, the assignor's default account is used. Refused when the batch already has a disbursement account defined or when the assignment contract fixes another account.
transfer_type	string	optional	Approval only. Payment method to the assignor: pix or wire_transfer. If omitted, the batch's or the assignment configuration's method applies.
number_of_approved_assets	integer	optional	Approval only. Number of approved assets you expect in the batch. If sent, assignment_total_value is also required, and both are checked against the batch before approving. Use it to make sure you approve exactly what you analyzed. The check only runs on the approval that closes the decision: when the consultant's approval moves the batch to pending_manager_approval, both fields are ignored.
assignment_total_value	number	optional	Approval only. Total batch amount you expect, in reais. Sent together with number_of_approved_assets.
denial_reason	object	optional	Denial only. Reason for the denial: reason_type (required inside the object; use manager or consultant) and denial_reason (free text). It is recorded in status_events[].denial_reason and status_events[].denial_metadata in Batch Retrieval.

Response

STATUS

200

Response Body — Approval

{
    "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
    "status": "waiting_assets_to_formalize",
    "number_of_approved_assets": 45,
    "assignment_total_value": 150000.00
}

Response Body — Denial

{
    "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
    "status": "denied"
}

Response attributes

Field	Type	Description
assignment_key	string	Unique batch identifier (UUID).
external_id	string	External batch key provided by the partner.
status	string	New batch status. On approval: pending_manager_approval (the consultant approved and the manager still has to approve), pending_assets_registry (configurations with asset registration) or waiting_assets_to_formalize. On denial: denied.
number_of_approved_assets	integer	Approval only. Number of approved assets in the batch. It is 0 when the batch moves on to the manager.
assignment_total_value	number	Approval only. Total assignment amount, in reais.

Final approval without webhook

When the approval takes the batch to pending_assets_registry or waiting_assets_to_formalize, no batch webhook is sent for that transition: use the status in the response. The next batch webhook arrives at the following step (assignment term, custody or payment). The transition to pending_manager_approval generates a webhook as usual.

A denied batch (denied) does not return to the pipeline through the API. At the day's accounting closing it moves to discarded.

Errors

Status	Code	When it happens
400	TRC000024	The batch is not in a status that accepts this decision (for example, already approved or still in eligibility). Check Batch Retrieval.
400	TRC000087	The manager tried to approve a batch in pending_consultant_approval, or the consultant tried to act on a batch in pending_manager_approval.
400	TRC000059	The assignor sent approved or denied.
400	TRC000095	Only one of number_of_approved_assets and assignment_total_value was sent.
400	TRC000096	assignment_total_value does not match the current batch amount.
400	TRC000097	number_of_approved_assets does not match the number of approved assets.
400	TRC000118	disbursement_account_key was sent, but the batch already has a disbursement account defined.
400	TRC000149	The assignor discounts exceed the limit allowed for the batch.
400	TRC000185	disbursement_account_key differs from the account fixed in the assignment contract.
422	TRC000186	The disbursement account fixed in the assignment contract is no longer active in the assignor's registration. Contact the integration team.
404	TRC000018	No batch with this external_id in this assignment configuration.
404	TRC000116	disbursement_account_key does not match any assignor account.

Authentication, permission and host errors: see API Errors.

Next steps

After approval, the flow continues automatically:

1. Asset registration and formalization — according to the registration type of the assignment configuration.
2. Assignment Term — the term is generated and sent for signature. You receive a webhook with status pending_assignment_term_signature. The document can be retrieved via Assignment Documents.
3. Payment — after signature, the system pays the assignor. A webhook with status pending_payment is sent.
4. Portfolio inclusion — the assets are added to the fund's portfolio and the batch is completed with status completed.