> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # List Transfers > Use this endpoint to retrieve a paginated list of transfers. You can filter by ledger, type, status, reconciliation status, date range, and amount range. The default limit is 50 items, with a maximum of 200. Only returns transfers belonging to the same organization. ## OpenAPI ````yaml /pt/openapi/v3-current/ted.yaml get /v1/transfers openapi: 3.0.3 info: title: Bank Transfer (TED) Plugin API description: >- Complete API for Brazilian bank transfers (TED OUT, TED IN, P2P) through the Lerian platform, including transfer initiation, processing, status tracking, cancellation, and returns. version: 3.4.0 servers: - url: https://api.example.com description: >- Replace the example host with the URL provided during environment onboarding. security: - BearerAuth: [] - OAuth2ClientCredentials: - api - OAuth2Password: - api tags: - name: Transfers API description: >- Endpoints for initiating, processing, tracking, cancelling, and returning transfers. - name: Webhooks description: >- Endpoints for registering and managing tenant-scoped webhook subscriptions for transfer events. - name: Webhook DLQ description: Endpoints for inspecting and retrying webhook dead-letter queue messages. paths: /v1/transfers: get: tags: - Transfers API summary: List Transfers description: >- Use this endpoint to retrieve a paginated list of transfers. You can filter by ledger, type, status, reconciliation status, date range, and amount range. The default limit is 50 items, with a maximum of 200. Only returns transfers belonging to the same organization. operationId: listTransfers parameters: - $ref: '#/components/parameters/XOrganizationId' - name: ledgerId in: query description: >- Filter results by Midaz ledger, inside the `X-Organization-Id` scope. It matches the ledger that the transfer is filed under (the payer's ledger) or, on a P2P between two ledgers, the recipient's ledger. The filter applies to the page and to `totalCount`. A blank value applies no filter. A malformed UUID or the all-zeroes UUID returns `400 BTF-0001`. schema: type: string format: uuid - name: type in: query description: >- Filter results by transfer type. `TED_IN` does not select the customer credits that carry a `TED_IN_STR` type, nor the cross-core credits and returns received from the other core of your institution, which carry `CROSS_CORE_IN`. `CROSS_CORE` selects the cross-core TEDs sent. schema: $ref: '#/components/schemas/TransferType' - name: status in: query description: Filter results by transfer status. schema: $ref: '#/components/schemas/TransferStatus' - name: reconciliationStatus in: query description: >- Filter results by reconciliation status. `MANUAL_REVIEW` also selects the transfers stored as `EXHAUSTED`. schema: type: string enum: - AWAITING - RESOLVED - REVERSING - REVERTED - MANUAL_REVIEW - name: createdFrom in: query description: The start of the date range filter in RFC3339 format. schema: type: string format: date-time - name: createdTo in: query description: The end of the date range filter in RFC3339 format. schema: type: string format: date-time - name: minAmount in: query description: >- The minimum transfer amount to include in the results. Must be 0 or greater. schema: type: number format: decimal minimum: 0 - name: maxAmount in: query description: >- The maximum transfer amount to include in the results. This filter has no upper bound. schema: type: number format: decimal minimum: 0 - name: limit in: query description: Maximum number of transfers to return. schema: type: integer minimum: 1 maximum: 200 default: 50 - name: offset in: query description: Number of transfers to skip. schema: type: integer minimum: 0 default: 0 - name: sortDirection in: query description: Sort direction for results ordered by createdAt. schema: type: string enum: - asc - desc default: desc responses: '200': description: >- Indicates that the request was successful and the matching transfers are returned. content: application/json: schema: $ref: '#/components/schemas/TransferList' examples: list: summary: Paginated transfers value: items: - transferId: 019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d type: TED_OUT status: COMPLETED organizationId: 019c96a0-0a98-7287-9a31-786e0809c769 ledgerId: 019c96a0-0b10-7c2d-8e3f-4a5b6c7d8e9f senderAccountId: 019c96a0-0c0c-7221-8cf3-13313fb60081 amount: 1000.5 feeAmount: 1.5 totalAmount: 1002 createdAt: '2026-02-01T18:30:00Z' updatedAt: '2026-02-01T18:35:00Z' - transferId: 019c96a0-ab20-7def-a1b2-1f2a3b4c5d6e type: TED_IN status: COMPLETED organizationId: 019c96a0-0a98-7287-9a31-786e0809c769 ledgerId: 019c96a0-0b10-7c2d-8e3f-4a5b6c7d8e9f senderAccountId: 019c96a0-7e5a-7b3c-9d8e-2f1a0b3c4d5e amount: 500 feeAmount: 0 totalAmount: 500 createdAt: '2026-02-01T19:00:00Z' updatedAt: '2026-02-01T19:05:00Z' pagination: limit: 50 offset: 0 returned: 2 totalCount: 2 hasNextPage: false '400': $ref: '#/components/responses/InvalidFilter' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: >- BTF-0404: `X-Organization-Id` names an organization that this tenant does not operate. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDocument' '429': $ref: '#/components/responses/RateLimitExceeded' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' components: parameters: XOrganizationId: name: X-Organization-Id in: header required: true description: >- Midaz organization scope for the request, used for downstream CRM, Fees, and Midaz calls. Required on org-scoped transfer routes in every deployment mode; a missing or non-UUID value returns 400. This is not the tenant identifier — tenantId is derived from the bearer JWT or authenticated context, never from this header. Background workers (TED IN poller, reconciliation) have no request header and, in single-tenant mode, fall back to the deployment's `ORGANIZATION_ID` env. schema: type: string format: uuid example: 019c96a0-0a98-7287-9a31-786e0809c769 schemas: TransferType: type: string enum: - TED_OUT - TED_IN - TED_IN_STR0005 - TED_IN_STR0007 - TED_IN_STR0029 - TED_IN_STR0034 - TED_IN_STR0037 - TED_IN_STR0041 - TED_IN_STR0051 - P2P - CROSS_CORE - CROSS_CORE_IN description: >- The type of transfer. TED_OUT is an outgoing transfer to an external bank via JD SPB; the voluntary return of a TED IN is also a TED_OUT. TED_IN is an incoming transfer from an external bank. Each TED_IN_STR type is an incoming customer credit received as that STR message, for example TED_IN_STR0041 for an INSS payroll loan received as STR0041R2. P2P is a peer-to-peer transfer within the same institution (same ISPB). CROSS_CORE is a TED to an account that the other core of your institution holds, sent through the JD Courier. CROSS_CORE_IN is a cross-core credit, or the return of a cross-core TED, received from the other core. example: TED_OUT TransferStatus: type: string enum: - CREATED - PENDING - PROCESSING - COMPLETED - REJECTED - FAILED - CANCELLED - RECEIVED description: >- The current status of the transfer. For TED OUT: CREATED → PENDING → PROCESSING → COMPLETED, REJECTED, or FAILED. For P2P: CREATED → PROCESSING → COMPLETED or FAILED (PENDING is an SPB-specific state and does not apply to P2P). Transfers can be CANCELLED while in CREATED or PENDING status. For TED IN: RECEIVED → PROCESSING → COMPLETED or FAILED. A COMPLETED TED IN can also transition to FAILED in the event of a chargeback. example: COMPLETED TransferList: type: object required: - items - pagination properties: items: type: array items: $ref: '#/components/schemas/TransferSummary' pagination: $ref: '#/components/schemas/PaginationInfo' ProblemDocument: type: object description: >- The RFC 9457 problem document that the service answers every error with, on `application/problem+json`. Route-specific members (for example `refusalCode`, `transactionId`, `ledgerStatus`, `systemplaneKey`) appear flat at the top level beside these. additionalProperties: true required: - type - title - status - detail - code - requestId - service - category properties: type: type: string description: >- A URI that names the error code: `https://errors.lerian.studio/v1/`. example: https://errors.lerian.studio/v1/BTF-0200 title: type: string description: The HTTP status text. example: Not Found status: type: integer description: The HTTP status code. example: 404 detail: type: string description: A human-readable explanation of this occurrence. example: transfer not found instance: type: string description: The trace ID of this request, when one was recorded. example: 4bf92f3577b34da6a3ce929d0e0e4736 errors: type: array description: Each rejected field. Present on field validation errors only. items: type: object properties: message: type: string description: Why the value was rejected. example: transferId must be a valid UUID location: type: string description: 'Where the value sits: `body.` or `query.`.' example: body.senderAccountId code: type: string description: The stable BTF error code. example: BTF-0200 upstream: type: object description: >- The error that an upstream provider (JD SPB, Midaz) reported. Absent unless surfaced. properties: code: type: string description: The provider's own error code, verbatim. example: AAC90 message: type: string description: The provider's own error message, bounded. example: Assinatura invalida requestId: type: string description: The request correlation ID. Present even when empty. example: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f service: type: string description: The system that produced the error. example: plugin category: type: string description: The machine-readable error category. example: deterministic TransferSummary: type: object required: - transferId - type - status - organizationId - ledgerId - senderAccountId - amount - feeAmount - totalAmount - createdAt - updatedAt properties: transferId: type: string format: uuid example: 770e8400-e29b-41d4-a716-446655440003 type: $ref: '#/components/schemas/TransferType' status: $ref: '#/components/schemas/TransferStatus' reconciliationStatus: type: string enum: - AWAITING - RESOLVED - REVERSING - REVERTED - EXHAUSTED - MANUAL_REVIEW description: >- The reconciliation state of the transfer, as stored. `EXHAUSTED` has the same meaning as `MANUAL_REVIEW`. Absent on a transfer that never entered reconciliation. example: MANUAL_REVIEW organizationId: type: string format: uuid description: >- The Midaz organization that the transfer is filed under. It equals the `X-Organization-Id` of the request. example: 019c96a0-0a98-7287-9a31-786e0809c769 ledgerId: type: string format: uuid description: >- The Midaz ledger that the transfer is filed under. On a P2P between two ledgers, the payer's ledger. Always present. The all-zeroes UUID means that the scope is unrepaired. See Repair Transfer Ledger Scope. example: 019c96a0-0b10-7c2d-8e3f-4a5b6c7d8e9f recipientLedgerId: type: string format: uuid description: >- The recipient's Midaz ledger on a P2P between two ledgers of one organization. Absent on a P2P inside one ledger and on every TED. example: 0190a0e2-7b1c-7d3e-9f40-5a6b7c8d9e03 ledgerGroupId: type: string format: uuid description: >- The Midaz ledger group that a P2P between two ledgers posted as. Absent before the posting, when the expiry recovery completed the transfer, and on a P2P return. example: 0190a0e2-7b1c-7d3e-9f40-5a6b7c8d9e10 originalTransferId: type: string format: uuid description: >- On a return, the transfer that it returns. A `TED_IN` devolution refund names the TED OUT that it compensates, a `TED_OUT` voluntary return names the TED IN that it sends back, and a `P2P` return names the P2P that it reverses. On a TED IN return and a P2P return, `recipient` carries only the ISPB. Read the counterparty from the original transfer. example: 770e8400-e29b-41d4-a716-446655440001 devolutionCode: type: string description: >- BACEN devolution reason code, present only when the transfer is a devolution. example: '18' senderAccountId: type: string format: uuid description: >- UUID of the sender account. For TED IN, a synthetic identifier derived from the sender's document. example: 019c96a0-0c0c-7221-8cf3-13313fb60081 recipientAccountId: type: string format: uuid description: >- UUID of the recipient account, when the recipient is represented as a Midaz account. example: 019c96a0-ac10-7efa-b1c2-2a3b4c5d6e7f midazTransactionId: type: string format: uuid description: The corresponding Midaz ledger transaction ID, when one exists. example: 019c96a0-ac10-7efa-b1c2-2a3b4c5d6e7f amount: type: number format: decimal example: 1000.5 feeAmount: type: number format: decimal example: 1.5 totalAmount: type: number format: decimal description: >- The amount debited from the sender's account: the transfer amount plus any fee charged on top. For TED IN, the gross amount received. example: 1002 createdAt: type: string format: date-time example: '2026-02-01T15:30:00Z' updatedAt: type: string format: date-time description: Timestamp of the last status transition for this transfer. example: '2026-02-01T15:35:00Z' PaginationInfo: type: object required: - limit - offset - returned - totalCount - hasNextPage properties: limit: type: integer description: Maximum number of items requested. example: 50 offset: type: integer description: Number of items skipped. example: 0 returned: type: integer description: Number of items returned in this response. example: 2 totalCount: type: integer minimum: 0 description: The total number of matching items. example: 123 hasNextPage: type: boolean description: Whether there are more items beyond the current page. example: false responses: InvalidFilter: description: Indicates that one or more filter parameters are invalid. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDocument' examples: invalidDateRange: summary: Invalid date range value: type: https://errors.lerian.studio/v1/BTF-0001 title: Bad Request status: 400 detail: createdFrom must be less than or equal to createdTo code: BTF-0001 category: deterministic requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f service: plugin Unauthorized: description: Indicates that the request is missing a valid authentication token. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDocument' examples: unauthorized: summary: Missing authorization value: type: https://errors.lerian.studio/v1/BTF-0401 title: Unauthorized status: 401 detail: Missing Token code: BTF-0401 category: plugin requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f service: plugin Forbidden: description: >- Indicates that the caller is authenticated but lacks permission for this operation. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDocument' examples: permissionDenied: summary: Caller lacks permission value: type: https://errors.lerian.studio/v1/BTF-0405 title: Forbidden status: 403 detail: >- the credential is not allowed to perform transfers:create on this request code: BTF-0405 category: plugin requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f service: plugin RateLimitExceeded: description: >- Indicates that the rate limit has been exceeded. Retry after the number of seconds specified in the Retry-After header. headers: Retry-After: description: Seconds until rate limit resets schema: type: integer example: 60 content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDocument' examples: rateLimitExceeded: summary: Too many requests value: type: https://errors.lerian.studio/v1/BTF-0429 title: Too Many Requests status: 429 detail: Rate limit exceeded code: BTF-0429 category: rate_limit requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f service: plugin description: > Rate-limit responses use the dedicated `BTF-0429` code with the `rate_limit` category. Clients should back off using the HTTP status `429` and the `Retry-After` header. InternalServerError: description: Indicates that an unexpected internal error occurred. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDocument' examples: internalError: summary: Internal error value: type: https://errors.lerian.studio/v1/BTF-9000 title: Internal Server Error status: 500 detail: Internal server error code: BTF-9000 category: plugin requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f service: plugin ServiceUnavailable: description: >- Indicates that a dependency of this service is unavailable or is not configured in this deployment. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDocument' examples: repositoryUnavailable: summary: Repository unavailable value: type: https://errors.lerian.studio/v1/BTF-9008 title: Service Unavailable status: 503 detail: transfer repository unavailable code: BTF-9008 category: transient requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f service: plugin dlqInspectorUnavailable: summary: DLQ inspector not configured value: type: https://errors.lerian.studio/v1/BTF-9005 title: Service Unavailable status: 503 detail: DLQ inspector is not configured code: BTF-9005 category: deterministic requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f service: plugin securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- JWT Bearer token authentication. The tenantId is derived from the bearer token or authenticated request context and is not supplied through X-Organization-Id. OAuth2ClientCredentials: type: oauth2 flows: clientCredentials: tokenUrl: /v1/login/oauth/access_token scopes: api: TED transfer API access OAuth2Password: type: oauth2 flows: password: tokenUrl: /v1/login/oauth/access_token scopes: api: TED transfer API access ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.