Retrieve External Accounts Report

This endpoint retrieves a list of external financial accounts linked to users or agents within the Netevia banking system. It supports flexible filtering by profile, agent, bank name, account name, and active status. Pagination is built in via skip and take parameters to handle large datasets efficiently.

Endpoint

POST /Report/externalAccounts

Authentication

Bearer token required. Obtain via:

POST https://api.banking.netevia.dev/api/auth/v2

Include in header: Authorization: Bearer {token}
Token lifetime: 10 minutes. Refresh via POST /api/auth/refresh.

When to use

Use this endpoint when you need to audit or display the external accounts (linked via Finicity or Plaid) that are associated with one or more user profiles or agents. It is particularly useful for compliance reporting, account status monitoring, and verifying which external accounts have completed underwriting verification. Partners can call this endpoint periodically to reconcile external account linkages and detect accounts that have been deactivated or failed verification.

Request Body

{
  "name": null,
  "bankName": "Chase",
  "profileIds": [1042, 1087],
  "agentIds": null,
  "active": true,
  "skip": 0,
  "take": 25
}

Response

200 OK

Returns an array of external account objects.

[
  {
    "id": 3091,
    "agentId": 204,
    "name": "Business Checking",
    "status": "Active",
    "provider": "Plaid",
    "last4": "7823",
    "bankName": "Chase",
    "createdDate": "2024-03-15T10:22:30.000Z",
    "updatedDate": "2024-08-01T08:45:00.000Z",
    "financialAccountId": "fa_9a3b12cd-4e56-7f89-ab01-cd2345ef6789",
    "verificationState": 2,
    "verificationDate": "2024-03-16T14:00:00.000Z",
    "verificationMessage": "Micro-deposit verification successful.",
    "deletedAt": null
  },
  {
    "id": 3105,
    "agentId": 204,
    "name": "Savings Reserve",
    "status": "Active",
    "provider": "Finicity",
    "last4": "4411",
    "bankName": "Chase",
    "createdDate": "2024-05-20T09:10:00.000Z",
    "updatedDate": null,
    "financialAccountId": "fa_1c2d34ef-5678-90ab-cd12-ef3456789012",
    "verificationState": 1,
    "verificationDate": null,
    "verificationMessage": "Verification pending underwriting review.",
    "deletedAt": null
  }
]

Error Codes

Common Mistakes

• Omitting skip and take — both are required integers; omitting them will result in a 400 error.
• Passing an empty array [] for profileIds or agentIds instead of null when you do not want to filter by those fields; use null to indicate no filter.
• Expecting a single object response — the endpoint always returns an array, even when only one account matches.
• Confusing verificationState integer values — 2 means Verified, not 1; always map the enum before displaying to end users.
• Using stale tokens — the Bearer token expires after 10 minutes; refresh before making this call in long-running workflows.

Related Endpoints

• POST /api/auth/v2 — Obtain a Bearer token for authentication.
• POST /api/auth/refresh — Refresh an expiring Bearer token.
• POST /Report/financialAccounts — Retrieve a report of internal financial accounts.
• POST /ExternalAccount/link — Link a new external account via Finicity or Plaid.

Example

curl -X POST https://api.banking.netevia.dev/Report/externalAccounts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": null,
    "bankName": "Chase",
    "profileIds": [1042, 1087],
    "agentIds": null,
    "active": true,
    "skip": 0,
    "take": 25
  }'