> ## 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.

# Get incoming TED

> Returns the current state of an incoming TED: `status`, the amount received and credited, the sender, the recipient (with `recipient.accountId` when the account was found), the regulatory deadline (`slaDeadlineAt`, 60 minutes after `interbankSettledAt`), and, when applicable, the manual review reason (`reviewReason`) or the return code (`returnCode`).

States: `RECEIVED` (decision in progress), `CREDITED` (credited to the customer), `RECORDED` (the institution's own account), `MANUAL_REVIEW` (waits for an operator), `RETURN_REQUESTED` (return sent to the STR), and `RETURNED` (return confirmed). If the STR refuses a return, the TED goes back to `MANUAL_REVIEW` with `reviewReason` filled in.

You only see TEDs that your institution received. For the sequence of transitions, use `GET /v1/incoming-transfers/{incomingTransferId}/timeline`.



## OpenAPI

````yaml /pt/openapi/v3-current/ted-lerian.yaml get /v1/incoming-transfers/{incomingTransferId}
openapi: 3.1.0
info:
  description: >-
    API of **TED Lerian**, the interface over Lerian SPB. Your institution uses
    it to send TEDs, make internal transfers, track incoming TEDs, and operate
    returns, queues, and policy on its Midaz ledger. The [API
    overview](/pt/reference/interfaces/ted-lerian/ted-lerian-api-overview) gives
    the concepts, the roles, and the conventions.
  title: TED Lerian API
  version: v1.0.0
servers:
  - url: https://api.example.com
    description: >-
      Replace the example host with the URL provided during environment
      onboarding.
security:
  - BearerAuth: []
tags:
  - description: >-
      Outgoing TEDs and internal transfers: fee quote, creation, query,
      timeline, and cancellation. Every integration starts here.
    name: Transfers
  - description: >-
      Incoming TEDs from other institutions: query, timeline, and operator
      actions (full return and manual review resolution).
    name: Incoming Transfers
  - description: >-
      STR participant list, to resolve COMPE code ↔ ISPB and validate the
      destination bank before you create a transfer.
    name: Participants
  - description: >-
      Back office: operations queue, inconsistency findings between the ledger
      and the STR, reviews of rail facts, held returns, and manual unblock with
      evidence.
    name: Reconciliation
  - description: >-
      Operations dashboard: daily aggregates, regulatory deadlines (30/60/60
      min), and the closing balance that the STR reported.
    name: Operations
  - description: >-
      Institution configuration (editor): operating window and cut-off, usage
      limits, holiday calendar, and ISPB → organization bindings.
    name: Policy
paths:
  /v1/incoming-transfers/{incomingTransferId}:
    get:
      tags:
        - Incoming Transfers
      summary: Get incoming TED
      description: >-
        Returns the current state of an incoming TED: `status`, the amount
        received and credited, the sender, the recipient (with
        `recipient.accountId` when the account was found), the regulatory
        deadline (`slaDeadlineAt`, 60 minutes after `interbankSettledAt`), and,
        when applicable, the manual review reason (`reviewReason`) or the return
        code (`returnCode`).


        States: `RECEIVED` (decision in progress), `CREDITED` (credited to the
        customer), `RECORDED` (the institution's own account), `MANUAL_REVIEW`
        (waits for an operator), `RETURN_REQUESTED` (return sent to the STR),
        and `RETURNED` (return confirmed). If the STR refuses a return, the TED
        goes back to `MANUAL_REVIEW` with `reviewReason` filled in.


        You only see TEDs that your institution received. For the sequence of
        transitions, use `GET
        /v1/incoming-transfers/{incomingTransferId}/timeline`.
      operationId: getIncomingTransfer
      parameters:
        - description: Identifier of the incoming TED
          in: path
          name: incomingTransferId
          required: true
          schema:
            description: Identifier of the incoming TED
            format: uuid
            type: string
        - $ref: '#/components/parameters/XRequestId'
      responses:
        '200':
          content:
            application/json:
              example:
                amount: '1500.00'
                createdAt: '2026-10-22T14:10:03Z'
                creditedAmount: '1500.00'
                creditedAt: '2026-10-22T14:10:09Z'
                description: Supplier payment
                feeAmount: '0.00'
                incomingTransferId: a7d3e9f1-2b4c-4d6e-8f0a-1b3c5d7e9f0a
                interbankSettledAt: '2026-10-22T14:10:03Z'
                kind: CLIENT
                numCtrlStr: STR20261022000000123
                nuop: '87654321202610220000123'
                organizationId: 0f1e2d3c-4b5a-4968-8776-655443322110
                purposeCode: '00010'
                recipient:
                  accountId: 3c5e7a9b-1d2f-4a6c-8e0b-2d4f6a8c0e1f
                  agency: '0001'
                  bankAccount: '0001111222'
                  bankAccountType: CACC
                  bankId: '12345678'
                  document: '98765432100'
                  name: João Pereira
                sender:
                  agency: '1234'
                  bankAccount: '0001234567'
                  bankAccountType: CACC
                  bankId: '87654321'
                  document: '12345678901'
                  name: Maria da Silva
                slaDeadlineAt: '2026-10-22T15:10:03Z'
                status: CREDITED
                updatedAt: '2026-10-22T14:10:09Z'
              schema:
                $ref: '#/components/schemas/IncomingTransferResponse'
          description: Incoming TED found, in its current status.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
        '401':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: 'Not authenticated: token missing, invalid, or expired (`TED-0070`).'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: >-
            No permission: the token's role does not authorize this action, or
            the product license is not valid for the organization (`TED-0071`).
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: >-
            Resource does not exist in this institution, or the identifier is
            not in UUID format (`TED-0010`).
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: >-
            Parameter outside the declared format (for example, a `date` that is
            not YYYY-MM-DD): framework validation, with no TED code.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: >-
            Unexpected failure (`TED-9000`). If it continues, contact support
            and give the `X-Request-Id` of the response.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
        '503':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: >-
            Organization scope not configured for this installation
            (`TED-0080`): the read fails closed until the configuration exists.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
components:
  parameters:
    XRequestId:
      description: >-
        Correlation identifier of this request (UUID). Optional: when you omit
        it, or when the value is not a well-formed UUID, the platform creates a
        UUID and returns it in the X-Request-Id header of the response. The
        resolved identifier goes to the logs, spans, and audit events of this
        request. Keep it to open a support ticket.
      in: header
      name: X-Request-Id
      schema:
        format: uuid
        type: string
  schemas:
    IncomingTransferResponse:
      additionalProperties: false
      description: >-
        An incoming TED from another institution: amount, parties, regulatory
        credit deadline, and the state of the credit to the recipient.
        `status=MANUAL_REVIEW` with `reviewReason` indicates that the operation
        needs a human decision.
      properties:
        amount:
          description: Amount in BRL as a decimal string with two decimal places.
          examples:
            - '1500.00'
          pattern: ^(0\.(0[1-9]|[1-9][0-9])|[1-9][0-9]{0,11}\.[0-9]{2})$
          type: string
        createdAt:
          description: Time (UTC) when this service recorded the TED.
          format: date-time
          type: string
        creditedAmount:
          description: >-
            Amount actually credited to the recipient (amount − feeAmount), in
            BRL. Present from CREDITED onward.
          examples:
            - '1500.00'
          pattern: ^(0|[1-9][0-9]{0,11})\.[0-9]{2}$
          type: string
        creditedAt:
          description: Time (UTC) of the credit to the recipient.
          format: date-time
          type: string
        description:
          description: Description given by the sender.
          type: string
        feeAmount:
          description: Fee applied to the credit, in BRL (0.00 when exempt).
          examples:
            - '0.00'
          pattern: ^(0|[1-9][0-9]{0,11})\.[0-9]{2}$
          type: string
        incomingTransferId:
          description: Identifier of the incoming TED. Use it in queries and actions.
          format: uuid
          type: string
        interbankSettledAt:
          description: >-
            Interbank settlement reported by the STR (start of the 60-min
            deadline)
          format: date-time
          type: string
        kind:
          description: Credit to a customer or to the institution's own account
          enum:
            - CLIENT
            - INSTITUTION
          type: string
        numCtrlStr:
          description: Entry identifier assigned by the STR (20 characters).
          pattern: ^[A-Za-z0-9]{20}$
          type: string
        nuop:
          description: Unique operation number on the rail (ISPB[8]+AAAAMMDD[8]+SEQ[7])
          pattern: ^[0-9]{23}$
          type: string
        organizationId:
          description: Organization resolved through the ISPB→organization binding
          format: uuid
          type: string
        purposeCode:
          description: Purpose code sent by the sender (FinlddCli, 5 digits).
          examples:
            - '00010'
          pattern: ^[0-9]{5}$
          type: string
        recipient:
          $ref: '#/components/schemas/IncomingPartyResponse'
          description: >-
            Recipient in your own institution; accountId is present when the
            account was found.
        returnCode:
          description: >-
            Official return reason (CodDevTransf) of the active return, when
            there is one.
          examples:
            - '3'
          pattern: ^[0-9]{1,2}$
          type: string
        returnedAt:
          description: Instant (UTC) when the STR confirmed the return.
          format: date-time
          type: string
        reviewReason:
          description: >-
            Reason for the manual review, when status=MANUAL_REVIEW. From the
            credit decision: ISPB_BINDING_UNRESOLVED, ACCOUNT_NOT_FOUND,
            ACCOUNT_INACTIVE, HOLDER_MISMATCH, ACCOUNT_TYPE_INCOMPATIBLE,
            ENRICHMENT_INCOMPLETE, RAIL_INDETERMINATE, LEDGER_INDETERMINATE,
            REGISTRY_INDETERMINATE. From the return cycle:
            RETURN_REFUSED_BY_STR, RETURN_REQUEST_MALFORMED,
            RETURN_CODE_UNMAPPED, RETURN_REJECTED_BY_STR.
          type: string
        sender:
          $ref: '#/components/schemas/IncomingPartyResponse'
          description: Sender, at another institution.
        slaDeadlineAt:
          description: >-
            Regulatory deadline to credit or return: interbankSettledAt + 60 min
            (UTC).
          format: date-time
          type: string
        status:
          description: >-
            Current state: RECEIVED (received from the STR, credit decision in
            progress) → CREDITED (credited to the customer), RECORDED (the
            institution's own account, terminal), or MANUAL_REVIEW (waits for an
            operator; see reviewReason); RETURN_REQUESTED (return sent to the
            STR) → RETURNED (confirmed, terminal). If the STR refuses a return,
            the TED goes back to MANUAL_REVIEW with reviewReason filled in.
          enum:
            - RECEIVED
            - CREDITED
            - RECORDED
            - RETURN_REQUESTED
            - RETURNED
            - MANUAL_REVIEW
          type: string
        updatedAt:
          description: Timestamp (UTC) of the last update to the record.
          format: date-time
          type: string
      required:
        - incomingTransferId
        - status
        - nuop
        - amount
        - sender
        - recipient
        - interbankSettledAt
        - slaDeadlineAt
        - createdAt
        - updatedAt
      type: object
    Detail:
      additionalProperties: true
      description: >-
        Standard error body (RFC 9457, `application/problem+json`) for every
        `/v1` operation. Use `code` (TED-NNNN) to handle the error in code,
        `detail` for the readable message, and `errors` for the invalid fields
        of a 422. The `X-Request-Id` of the response identifies the occurrence
        for support.
      properties:
        code:
          description: >-
            Stable, machine-readable domain error code scoped to the emitting
            service (format: <SERVICE>-NNNN).
          type: string
        detail:
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem.
          examples:
            - Property foo is required but is missing.
          type: string
        errors:
          description: Optional list of individual error details
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type:
            - array
            - 'null'
        instance:
          description: >-
            A URI reference that identifies the specific occurrence of the
            problem.
          examples:
            - https://example.com/error-log/abc123
          format: uri
          type: string
        status:
          description: HTTP status code
          examples:
            - 400
          format: int64
          type: integer
        title:
          description: >-
            A short, human-readable summary of the problem type. This value
            should not change between occurrences of the error.
          examples:
            - Bad Request
          type: string
        type:
          default: about:blank
          description: A URI reference to human-readable documentation for the error.
          examples:
            - https://example.com/errors/example
          format: uri
          type: string
        upstream:
          $ref: '#/components/schemas/Upstream'
          description: >-
            RFC 9457 extension member: the error a proxied third-party provider
            reported. Absent unless the emitting service explicitly surfaced
            one.
      type: object
    IncomingPartyResponse:
      additionalProperties: false
      description: >-
        One of the parties of the incoming TED. For the recipient, `accountId`
        is only filled in after the account is found in the institution. Until
        then, only the bank data received from the STR is available.
      properties:
        accountId:
          description: >-
            Account in the institution's own ledger. Present only when the
            recipient was already found.
          format: uuid
          type: string
        agency:
          description: Branch.
          type: string
        bankAccount:
          description: Account number.
          type: string
        bankAccountType:
          description: >-
            Account type: CACC (checking), SVGS (savings), SLRY (salary), or
            TRAN (payment).
          enum:
            - CACC
            - SVGS
            - SLRY
            - TRAN
          type: string
        bankId:
          description: >-
            ISPB of the institution (8 digits). Always present. Empty string
            when unknown.
          pattern: ^[0-9]{8}$
          type: string
        document:
          description: CPF (11 digits) or CNPJ (14 digits), digits only.
          examples:
            - '12345678901'
          pattern: ^([0-9]{11}|[0-9]{14})$
          type: string
        name:
          description: Name of the party, not truncated.
          type: string
      required:
        - bankId
      type: object
    ErrorDetail:
      additionalProperties: false
      description: >-
        An invalid field inside a validation error: where it is (`location`),
        what is wrong (`message`), and the value received.
      properties:
        location:
          description: >-
            Where the error occurred, e.g. 'body.items[3].tags' or
            'path.thing-id'
          type: string
        message:
          description: Error message text
          type: string
        value:
          description: The value at the given location
      type: object
    Upstream:
      additionalProperties: false
      description: >-
        Error reported by an upstream system (ledger or rail), when the service
        chooses to expose it. Absent in most errors.
      properties:
        code:
          description: The upstream provider's own error code, verbatim.
          examples:
            - E4001
          type: string
        message:
          description: >-
            The upstream provider's own error message, verbatim (bounded, never
            its raw response body).
          examples:
            - account not found at provider
          type: string
      type: object
  headers:
    XRequestId:
      description: >-
        Echo of the request X-Request-Id: the value that the client sent, or the
        UUID that the platform generated when the client sent none. Present in
        every response, success or error.
      schema:
        format: uuid
        type: string
  securitySchemes:
    BearerAuth:
      bearerFormat: JWT
      description: >-
        JWT token that the Lerian Access Manager issues for your institution.
        Send it in `Authorization: Bearer <token>` on every call (except the
        public health probes). The tenant never comes from the body, the query,
        or the path. Each operation requires a role with the matching permission
        (see the API overview). Without it, 403 `TED-0071`. Missing, invalid, or
        expired token: 401 `TED-0070`.
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.