# Credit Agency Configuration

## Overview

Each credit bureau connection requires a Credit Agency record in Peach. This configuration controls how files are generated, named, and transmitted.

## Credit Agency Object

Create a credit agency using the API endpoint `POST /companies/{companyId}/credit-agencies`:


```json
{
  "agencyName": "equifax",
  "country": "US",
  "dataFormat": "metro2",
  "nameFilePerAgencyConvention": true,
  "fileNamePrefix": "MYPREFIX",
  "uploadFrequency": "monthly",
  "specificDays": [1],
  "useLoanExternalId": true,
  "sftpHostname": "sftp.equifax.com:22",
  "sftpUsername": "yourcompany",
  "sftpPassword": "encrypted_password",
  "sftpCdDir": "/inbound",
  "encryptionMethod": "GPG",
  "publicKey": "-----BEGIN PGP PUBLIC KEY BLOCK-----...",
  "enrollExistingLoans": false,
  "copyKeysFrom": "CA-XXXX-XXXX"
}
```

## Field Reference

| Field | Type | Required | Description |
|  --- | --- | --- | --- |
| `agencyName` | string | Yes | Credit bureau identifier (see Agency Name Values below) |
| `country` | string | Yes | Country code (e.g., `US`) |
| `dataFormat` | string | Yes | Data format (`metro2`) |
| `nameFilePerAgencyConvention` | boolean | No | Use bureau-specific file naming convention |
| `fileNamePrefix` | string | Conditional | File name prefix (required for Experian when `nameFilePerAgencyConvention=true`) |
| `uploadFrequency` | string | Yes | Upload frequency (`monthly`, `weekly`, etc.) |
| `specificDays` | array | No | Specific days of month for upload (e.g., `[1]` for 1st of month) |
| `useLoanExternalId` | boolean | No | Use loan's `externalId` as Consumer Account Number |
| `sftpHostname` | string | Conditional | SFTP server hostname with optional port |
| `sftpUsername` | string | Conditional | SFTP username |
| `sftpPassword` | string | Conditional | SFTP password (for password authentication) |
| `sftpAccessMethod` | string | No | Authentication method: `usernamePassword` or `keys` (defaults to `usernamePassword`) |
| `sftpCdDir` | string | No | Directory to navigate to before upload |
| `encryptionMethod` | string | No | Encryption method (`GPG`) |
| `publicKey` | string | Conditional | PGP public key for file encryption |
| `enrollExistingLoans` | boolean | No | Automatically enroll existing active loans for credit reporting with this agency (default: `false`) |
| `copyKeysFrom` | string | No | Credit Agency ID to copy SSH keys from (e.g., `CA-XXXX-XXXX`) |


## Agency Name Values

| Value | Bureau |
|  --- | --- |
| `equifax` | Equifax |
| `experian` | Experian |
| `transUnion` | TransUnion |
| `innovis` | Innovis |


## SFTP Configuration

| Field | Description | Required |
|  --- | --- | --- |
| `sftpHostname` | SFTP server hostname (with optional port) | For lender-upload |
| `sftpUsername` | SFTP username | For lender-upload |
| `sftpPassword` | SFTP password (encrypted) | For password auth |
| `sftpAccessMethod` | `usernamePassword` or `keys` (defaults to `usernamePassword`) | No |
| `sftpCdDir` | Directory to change to before upload | Optional |
| `sftpSSHPeachPublicKey` | Peach's public key (generated) | For key auth |
| `sftpSSHPeachPrivateKey` | Peach's private key (generated) | For key auth |
| `copyKeysFrom` | Credit Agency ID to copy SSH keys from | Optional |


**Key-Based Authentication:** When `sftpAccessMethod` is set to `keys`, Peach generates an SSH key pair. The `copyKeysFrom` field allows you to reuse keys from an existing Credit Agency configuration instead of generating new ones.

## Encryption Configuration

| Field | Description |
|  --- | --- |
| `encryptionMethod` | Currently only `GPG` supported |
| `publicKey` | PGP public key for file encryption |


When encryption is enabled:

1. Metro 2 file is generated in plain text
2. File is encrypted using the provided public key
3. Encrypted file is uploaded to SFTP


## File Naming Options

**Standard Naming** (`nameFilePerAgencyConvention: false`):


```
{COMPANY_LEGAL_NAME}{COMPANY_ID}{AGENCY_NAME}{YYYYMMDD}.txt
```

Example: `ACMELENDINGLLCCPYL69X5Z1EQUIFAX20260101.txt`

**Equifax Convention** (`nameFilePerAgencyConvention: true`, Equifax): Same as standard naming.

**Experian Convention** (`nameFilePerAgencyConvention: true`, Experian):


```
{FILE_NAME_PREFIX}.{MMDDYYYY}.txt
```

Example: `MKFRT.01012026.txt`

Requires `fileNamePrefix` to be set.

**TransUnion Convention** (`nameFilePerAgencyConvention: true`, TransUnion): Same as standard naming.

## Account Identifier Configuration

| Setting | Behavior |
|  --- | --- |
| `useLoanExternalId: true` | Uses loan's `externalId` as Consumer Account Number |
| `useLoanExternalId: false` | Uses loan's Peach Public ID (e.g., `LN-JFU3-ER3S`) |


If `useLoanExternalId` is `true` but the loan has no `externalId`, falls back to Public ID.

## Loan Enrollment Options

| Setting | Behavior |
|  --- | --- |
| `enrollExistingLoans: true` | Automatically enrolls all existing active loans for credit reporting with this agency when the agency is created |
| `enrollExistingLoans: false` | Only new loans activated after agency creation will be enrolled (default) |


> **Note:** The `enrollExistingLoans` flag is only evaluated at agency creation time. It does not retroactively enroll loans if set to `true` on an update.