Get Beneficiaries

curl --request GET \
  --url 'https://api.finhub.cloud/api/v2.1/fintrans/wal_abc123def456/beneficiaries?status=ACTIVE&limit=10' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'X-Tenant-ID: fh_api_finsei_ltd_7f957f77'
```text`n## Example Response

```json
{
  "data": [
    {
      "id": "ben_xyz789abc123",
      "partyType": "INDIVIDUAL_CUSTOMER",
      "firstName": "John",
      "lastName": "Doe",
      "shortName": "John Doe",
      "iban": "FR1420041010050500013M02606",
      "currency": "EUR",
      "country": "FR",
      "bicSwiftCode": "BNPAFRPP",
      "networkName": "SEPA",
      "bankName": "BNP Paribas",
      "status": "ACTIVE",
      "createdAt": "2025-01-23T12:00:00.000Z",
      "lastUsedAt": "2025-01-23T14:30:00.000Z"
    },
    {
      "id": "ben_def456ghi789",
      "partyType": "BUSINESS_CUSTOMER",
      "companyName": "Acme Corporation",
      "shortName": "Acme Corp",
      "iban": "DE89370400440532013000",
      "currency": "EUR",
      "country": "DE",
      "bicSwiftCode": "DEUTDEFF",
      "networkName": "SEPA",
      "bankName": "Deutsche Bank AG",
      "status": "ACTIVE",
      "createdAt": "2025-01-23T11:30:00.000Z",
      "lastUsedAt": null
    }
  ],
  "pagination": {
    "total": 2,
    "limit": 10,
    "offset": 0
  }
}
```text`n## Usage Examples

### Filter Active EUR Beneficiaries

```javascript
const response = await fetch(
  `${baseUrl}/api/v2.1/fintrans/${walletId}/beneficiaries?status=ACTIVE&currency=EUR`,
  {
    headers: {
      'Authorization': `Bearer ${token}`,
      'X-Tenant-ID': tenantId
    }
  }
);

const beneficiaries = await response.json();
```text`n### Get Business Beneficiaries Only

```javascript
const businessBeneficiaries = await getBeneficiaries({
  accountId: walletId,
  partyType: 'BUSINESS_CUSTOMER',
  status: 'ACTIVE'
});
```text`n### Paginated Results

```javascript
async function getAllBeneficiaries(walletId) {
  const allBeneficiaries = [];
  let offset = 0;
  const limit = 50;
  
  while (true) {
    const response = await getBeneficiaries({
      accountId: walletId,
      limit,
      offset
    });
    
    allBeneficiaries.push(...response.data);
    
    if (response.data.length < limit) {
      break;
    }
    
    offset += limit;
  }
  
  return allBeneficiaries;
}
```text`n## Integration with Transfers

Beneficiaries returned by this endpoint can be used for:

1. **Transfer Operations** - Select target for payments
2. **Payment Consents** - Define allowed recipients
3. **Transaction History** - Track payments by beneficiary
4. **Compliance Checks** - Validate against sanctions

### Example: Prepare Transfer to Beneficiary

```javascript
// Get beneficiaries
const beneficiaries = await getBeneficiaries(walletId);

// Select first active beneficiary
const targetBeneficiary = beneficiaries.data.find(b => 
  b.status === 'ACTIVE' && b.currency === 'EUR'
);

// Prepare transfer
const transfer = await prepareTransfer({
  sourceAccount: walletId,
  target: {
    iban: targetBeneficiary.iban,
    name: targetBeneficiary.shortName
  },
  amount: {
    value: "10000", // €100.00 in cents
    currency: "EUR"
  }
});
```text`n## Beneficiary Status Management

| Status | Description | Can be used for transfers |
|--------|-------------|---------------------------|
| ACTIVE | Verified and ready | Yes |
| INACTIVE | Temporarily disabled | No |
| PENDING | Awaiting verification | No |
| BLOCKED | Compliance blocked | No |

## PowerShell Script Example

```powershell
# Get list of beneficiaries for the wallet
try {
    # Use fintrans API endpoint
    $beneficiariesUrl = "$baseUrl/api/v2.1/fintrans/$walletId/beneficiaries"
    
    # Optional query parameters
    $queryParams = @(
        "page=0",
        "size=50",
        "sort=createdAt,desc"
    )
    $queryString = $queryParams -join "&"
    $fullUrl = "$beneficiariesUrl?$queryString"
    
    # Create headers with authentication
    $headers = @{
        "Authorization" = "Bearer $token"
        "Accept"        = "application/json"
        "X-Tenant-Id"   = $xTenantId
        "X-Session-Id"  = $sessionId
    }
    
    $beneficiariesResponse = Invoke-RestMethod -Uri $fullUrl -Method Get -Headers $headers
    
    if ($beneficiariesResponse.data) {
        Write-Host "Retrieved $($beneficiariesResponse.data.Count) beneficiaries" -ForegroundColor Green
        Write-Host "Total beneficiaries: $($beneficiariesResponse.totalElements)" -ForegroundColor Cyan
        
        # Display beneficiary details
        foreach ($beneficiary in $beneficiariesResponse.data) {
            Write-Host "`nBeneficiary: $($beneficiary.shortName)" -ForegroundColor Yellow
            Write-Host "  ID: $($beneficiary.id)" -ForegroundColor White
            Write-Host "  Type: $($beneficiary.partyType)" -ForegroundColor White
            Write-Host "  IBAN: $($beneficiary.iban)" -ForegroundColor White
            Write-Host "  Network: $($beneficiary.networkName)" -ForegroundColor White
            Write-Host "  Status: $($beneficiary.status)" -ForegroundColor White
            
            # Check restrictions if present
            if ($beneficiary.restrictions) {
                Write-Host "  Restrictions:" -ForegroundColor Magenta
                if ($beneficiary.restrictions.maxAmountPerTransaction) {
                    Write-Host "    Max per transaction: $($beneficiary.restrictions.maxAmountPerTransaction)" -ForegroundColor White
                }
                if ($beneficiary.restrictions.dailyLimit) {
                    Write-Host "    Daily limit: $($beneficiary.restrictions.dailyLimit)" -ForegroundColor White
                }
            }
        }
        
        # Filter by specific criteria
        $sepabeneficiaries = $beneficiariesResponse.data | Where-Object { $_.networkName -eq "SEPA" }
        Write-Host "`nSEPA beneficiaries count: $($sepabeneficiaries.Count)" -ForegroundColor Cyan
        
        # Save to file for reference
        $beneficiariesFile = "./beneficiaries_list_$(Get-Date -Format 'yyyyMMddHHmmss').json"
        $beneficiariesResponse | ConvertTo-Json -Depth 5 | Set-Content -Path $beneficiariesFile
        Write-Host "Beneficiaries saved to: $beneficiariesFile" -ForegroundColor Green
    }
    else {
        Write-Host "No beneficiaries found for wallet: $walletId" -ForegroundColor Yellow
    }
}
catch {
    Write-Host "Failed to retrieve beneficiaries: $($_.Exception.Message)" -ForegroundColor Red
    
    # Handle specific errors
    if ($_.Exception.Response.StatusCode -eq 404) {
        Write-Host "  Wallet not found or no access" -ForegroundColor Yellow
    }
    elseif ($_.Exception.Response.StatusCode -eq 403) {
        Write-Host "  Insufficient permissions to view beneficiaries" -ForegroundColor Yellow
    }
}
```text`n## Related Endpoints

- [Create Beneficiary](/latest/api-reference/v2.1/fintrans/create-beneficiary) - Add new beneficiary
- [Update Beneficiary](/latest/api-reference/v2.1/fintrans/update-beneficiary) - Modify beneficiary details
- [Delete Beneficiary](/latest/api-reference/v2.1/fintrans/delete-beneficiary) - Remove beneficiary
- [Allowed Operations](/latest/api-reference/v2.1/fintrans/allowed-operations) - Check available operations