Unlike retrieving a specific anticipation, this endpoint returns a paginated list of anticipations found based on the provided filters.

Listing anticipations is useful for tracking the lifecycle of anticipations created in the account, monitoring status changes, and performing financial reconciliation processes related to receivables anticipation.

When to use

This endpoint is recommended when your integration needs to:

• Retrieve multiple anticipations in a consolidated manner.
• Monitor anticipations created for payments or installments.
• Filter anticipations by status.
• Identify anticipations that have been credited, debited, denied, or canceled.
• Synchronize anticipation information with financial systems, ERPs, or internal reconciliation processes.

Unlike the individual anticipation retrieval endpoint, this resource allows you to retrieve multiple anticipations in a single request.

Most relevant parameters

Although all parameters are documented in the technical reference for the endpoint, some have a direct impact on query behavior.

Available statuses

The status filter allows querying anticipations in specific states.

Example:

GET /v3/anticipations?status=PENDING

How filters work

Filters can be used to restrict the results returned by the API.

Some examples:

Retrieve pending anticipations:

GET /v3/anticipations?status=PENDING

Retrieve anticipations for a specific payment:

GET /v3/anticipations?payment=pay_123456

Retrieve anticipations for a specific installment:

GET /v3/anticipations?installment=ins_123456

When multiple filters are provided, only records matching all specified criteria will be returned.

Pagination

The response is paginated and may contain only part of the available records.

To navigate through large volumes of data, use the following parameters:

• offset
• limit

Example:

GET /v3/anticipations?limit=100&offset=100

📘

Important

Integrations that perform periodic synchronizations should iterate through all available pages to ensure complete retrieval of anticipations.

Query example

Request

GET /v3/anticipations?status=CREDITED&limit=50

Example scenario

In this example, the API will return only anticipations whose amounts have already been credited to the account.

This type of query is frequently used in financial reconciliation processes to identify completed anticipations.

Best practices

• Use filters whenever possible to reduce the volume of returned data.
• Prefer incremental queries instead of repeatedly querying the entire history.
• Implement pagination for accounts with a large volume of anticipations.
• Consider that an anticipation's status may change over time.
• Store returned identifiers internally to facilitate future individual queries.

🚧

Attention

The returned status represents the anticipation state at the time of the query and may change later as a result of the financial processing of the operation.

Common errors

No results found

This may occur when the provided filters do not match any records.

Incomplete pagination

This occurs when only the first page is queried while additional records are available.

Incompatible filters

Specific combinations of filters may significantly reduce the number of returned results.

Next steps

Depending on your integration needs, the following content may complement your implementation:

• Retrieve a specific anticipation.
• Request an anticipation.
• Retrieve payments.
• Retrieve installment payments.
• Financial reconciliation.
• Retrieve financial statement.

📘

Important

GET requests to this endpoint must be sent with an empty body. If a request is sent with a populated body, the API may return a 403 Forbidden error.