Skip to content
/
Create loan

Create loan

Request

Add a new loan.

Security
oauth2(Required scopes: loan:create) or bearerAuth or apiKeyHeader
Path
personIdstring(AnyId)^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+$write-onlyrequired

A Borrower's unique identifier, tied to a person or a business. Can be Peach or a lender's external identifier.

Query
validateboolean

Validate the contact through an external API. This is only used for addresses currently.

Default:true
Bodyapplication/jsonrequired
Any of:

Represents a loan. A loan always belongs to a borrower, and most of the interactions between a lender and a borrower are associated with a particular loan.

timestampsobject

DEPRECATED The fields in this object will not affect the loan.

typestring
Value:"installment"
loanTypeIdstringrequired

The loan type identifier. This is created specifically for each lender's loan product by Peach.

additionalBorrowersArray of objects or null
declineReasonobject or null

The reason(s) why the loan application or the draw request was declined.

externalIdstring or null, non-empty

A lender's identifier for a loan or a draw.

After the object is successfully created, a lender can use ID or externalId identifiers to fetch the object.

To fetch the object using externalId you need to add ext- to the URL.

Note: Don't add ext- to the identifier value. For example: if the external identifier is ABCDE, then pass externalId=ACBCE and NOT ext-ABCDE when creating the object.

metaDataobject or null(MetaData)

Store any type of key/value pairs in the form of a JSON dictionary.

chargedOffReasonstring or null

The reason for loan charge off. Can be updated via the Update Loan endpoint when the loan status is chargedOff.

term means the loan was charged off per loan type configuration after X days overdue.

fraudulent means the loan was charged off for fraudulent reason. If the loan is reported to one or more credit bureaus, the system will automatically send a special request to each bureau to delete the tradeline due to confirmed fraud. This is the only reason that the system will automatically trigger a request to delete the tradeline. For other reasons, if you need to delete the tradeline please call the Delete from credit reporting endpoint or use an agent tool.

bankruptcy means the loan was charged off because of bankruptcy.

legal means the loan was charged off because of some legal reason.

Enum:"term""fraudulent""bankruptcy""legal"
mainBorrowerIdstring or null

The identifier of the main borrower of the loan

migrationobject(Migration)

Loan migration details. This structure should be used for loans that are migrated from another system to Peach. To migrate a loan (see migration guidance for full details):

  1. Create a new loan in pending or originated status. The loan must be in originated before proceeding to the next step.
  2. Call relevant endpoints to create past payments, refunds, etc.
  3. Call Migrate loan endpoint.
additionalPeopleArray of objects(PersonLoan)write-only

For loans with multiple people attached, use this field to add additional people. You do not need to include the main borrower, who will be created from the url parameter.

atOriginationobject(Installment)

This object contains loan details and terms as they were shown to a borrower at origination.

isClosedboolean

Indicates whether the loan with multiple advances is closed. If true and the loan type installment with multiple advances, new Advances cannot be created, and the advance schedule cannot be updated.

muteLoanNoticesboolean

Indicates whether the system should stop/pause sending loan related notices to the borrower. Set to true if you want to mute all loan related notices (e.g. loanDetails. autopayEnabled, paymentFailed, etc.) Keep in mind that it will also stop all notices related to the loan that are sent from Peach Agent Portal by an agent. Note: this is not the only attribute that can stop notices from being sent. Compliance Guard and Cases Do Not Interact can also block communications.

nicknamestring or null

The loan's nickname. Nickname is a friendly name of the loan and is displayed in the UI. Nickname is different from loan ID. Nickname can be changed by a borrower.

servicedBystring(LoanServicer)required

The entity type that services the loan.

creditor, thirdPartyServicer - means that the loan is serviced on the Peach platform.

debtCollectionAgency - means that the loan is no longer serviced on the Peach platform. The loan can be still visible in Borrower Portal. To clarify, the loan is not deleted from the Peach platform.

Enum:"creditor""thirdPartyServicer""debtCollectionAgency"
statusstring(LoanStatus)required

The current status of the loan. New loans must be created in pending, originated or declined status.

pending - the loan is in the application stage. Loan atOrigination details and terms can be changed (via API).

originated - the loan was signed by the borrower and originated by the lender. Loan atOrigination details cannot be changed. Originated loans do not start accruing interest until activated.

declined - an application was declined. This is a terminal state.

active - the loan is active. Most loans are expected to be active.

frozen - the loan is temporarily frozen. The loan will not accrue any interest, no payments can be processed, and no notifications are sent to the borrower.

accelerated - the loan was accelerated. The loan will not accrue any additional interest and the entire balance is due.

chargedOff - the loan was charged off.

paidOff - the loan was successfully paid off.

canceled - the loan was canceled. Canceled loans are not shown in UI. This is a terminal state.

Enum:"pending""originated""declined""active""frozen""accelerated""chargedOff""paidOff""canceled"
POST
/people/{personId}/loans
curl -i -X POST \
  'https://sandboxapi.peach.finance/api/people/{personId}/loans?validate=true' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "timestamps": {
      "acceleratedAt": "2019-08-24T14:15:22Z",
      "activatedAt": "2019-08-24T14:15:22Z",
      "canceledAt": "2019-08-24T14:15:22Z",
      "chargedOffAt": "2019-08-24T14:15:22Z",
      "closedAt": "2019-08-24T14:15:22Z",
      "frozenAt": "2019-08-24T14:15:22Z",
      "migratedAt": "2019-08-24T14:15:22Z",
      "originatedAt": "2019-08-24T14:15:22Z",
      "paidOffAt": "2019-08-24T14:15:22Z",
      "startedAt": "2019-08-24T14:15:22Z"
    },
    "type": "installment",
    "loanTypeId": "string",
    "additionalBorrowers": [
      {
        "id": "string",
        "relationType": "coBorrower"
      }
    ],
    "declineReason": {
      "mainExternalReasonCode": "string",
      "mainScriptForRep": "string",
      "mainText": "string",
      "subReasons": [
        {
          "externalReasonCode": "string",
          "reasonText": "string",
          "scriptForRep": "string"
        }
      ]
    },
    "externalId": "string",
    "metaData": {},
    "assetType": "personalClosedEndUnsecured",
    "chargedOffReason": "term",
    "mainBorrowerId": "string",
    "migration": {
      "activatedDate": "2019-08-24",
      "activatedTimeOfDay": {
        "hour": 0,
        "minute": 0,
        "second": 0
      },
      "creditReporting": {
        "dateClosed": "2019-08-24",
        "dateOfFirstDelinquency": "2019-08-24",
        "dateOpened": "2019-08-24",
        "k2Segment": {
          "purchasedFromName": "string"
        },
        "l1Segment": {
          "changeIndicator": "1",
          "oldConsumerAccountNumber": "string"
        },
        "paymentHistoryProfile": "stringstringstringstring"
      },
      "migrationStatus": "nonMigrated"
    },
    "additionalPeople": [
      {
        "loanRelationType": "coBorrower",
        "personId": "string"
      }
    ],
    "atOrigination": {
      "advanceSchedule": [
        {
          "advanceDate": "2019-08-24",
          "advanceDetails": {
            "categoryId": "string",
            "description": "Advance",
            "merchantId": "string",
            "merchantName": "string",
            "metadata": {},
            "pointOfSaleType": "online"
          },
          "advanceTimeOfDay": {
            "hour": 0,
            "minute": 0,
            "second": 0
          },
          "amount": 0.1,
          "externalId": "string",
          "metadata": {},
          "status": "scheduled"
        }
      ],
      "amountFinanced": 0.1,
      "aprEffective": 0.1,
      "aprNominal": 0.1,
      "bufferToPushOutSchedule": 0.1,
      "discountProgramIds": [
        0
      ],
      "downPaymentAmount": 0.1,
      "duration": 0,
      "enforcedEndDate": "2019-08-24",
      "expectedPayments": [
        {
          "amount": 0.1,
          "date": "2019-08-24",
          "dynamicFeeDetails": {
            "chargeDate": "2019-08-24",
            "chargeTimeOfDay": {
              "hour": 0,
              "minute": 0,
              "second": 0
            },
            "dynamicFeeTypeId": "string"
          },
          "interestAmount": 0.1,
          "interestBeforeDiscountAmount": 0.1,
          "isForcedAmount": false,
          "paymentType": "periodicPayment",
          "principalAmount": 0.1,
          "unroundedInterestAmount": "string",
          "unroundedInterestBeforeDiscountAmount": "string",
          "unroundedPrincipalAmount": "string"
        }
      ],
      "fees": {
        "dynamicFees": [
          {
            "apiName": "string",
            "dynamicFeeTypeId": "string",
            "feeAmount": 0.1,
            "feeCapAmount": 0.1
          }
        ],
        "originationFeeAmount": 0.1,
        "serviceFeeAmount": 0.1,
        "serviceFeeCapAmount": 0.1,
        "totalOtherFeesAmount": 0.1
      },
      "interestRates": [
        {
          "days": 0,
          "interestType": "absolute",
          "rate": 0.1
        }
      ],
      "investors": [
        {
          "investorId": "string",
          "metro2": {
            "reportK2Segment": false
          },
          "share": 0.1,
          "effectiveDate": "2019-08-24"
        }
      ],
      "itemsOrServicesFinanced": "string",
      "mdr": {
        "mdrRate": 0.1,
        "amortizationPeriod": 0,
        "isAmortized": true,
        "mdrAmount": 0.1
      },
      "merchantId": "string",
      "originatingCreditorName": "string",
      "originationLicense": "nationalBank",
      "paymentFrequency": "weekly",
      "periodicPaymentAmount": 0.1,
      "personAddress": {
        "POBox": "string",
        "addressLine1": "string",
        "addressLine2": "string",
        "city": "string",
        "country": "string",
        "countyOrRegion": "string",
        "postalCode": "string",
        "state": "strin"
      },
      "personAddressId": "string",
      "principalAmount": 0.1,
      "promoRates": [
        {
          "days": 0,
          "rate": 0.1
        }
      ],
      "rateCaps": [
        {
          "days": 0,
          "maxRate": 0,
          "rateCapReason": "MLA"
        }
      ],
      "skipCreditReporting": false,
      "specificDays": [
        "string"
      ],
      "totalDiscountAmount": 0.1,
      "totalInterestAmount": 0.1,
      "totalInterestCapAmount": 0.1,
      "promoPrograms": [
        {
          "disqualifyOverdueDays": 0,
          "externalId": "string",
          "metaData": {},
          "promoDurationDays": 0,
          "promoEndDate": "2019-08-24",
          "promoGracePeriodDays": 0,
          "promoStartDate": "2019-08-24",
          "promoTypeId": "string",
          "status": "pending"
        }
      ]
    },
    "isClosed": true,
    "muteLoanNotices": true,
    "nickname": "string",
    "servicedBy": "creditor",
    "status": "pending"
  }'

Responses

Success

Bodyapplication/json
messagestring

Description of the server action or error.

statusinteger

HTTP status code.

dataInstallment (object) or Line of Credit (object)(Loan)
Any of:

Represents a loan. A loan always belongs to a borrower, and most of the interactions between a lender and a borrower are associated with a particular loan.

Response
{
  "message": "string",
  "status": 0,
  "data": {
    "id": "string",
    "loanTypeId": "string",
    "additionalBorrowers": [ … ],
    "assetDisplayName": "string",
    "cancellationReason": "technicalIssue",
    "declineReason": { … },
    "displayId": "string",
    "endDate": "2019-08-24",
    "externalId": "string",
    "labels": [ … ],
    "metaData": {},
    "timestamps": { … },
    "assetType": "personalClosedEndUnsecured",
    "chargedOffReason": "term",
    "companyId": "string",
    "mainBorrowerId": "string",
    "migration": { … },
    "amountsValidation": { … },
    "aprEffectiveAtActivation": 0.1,
    "aprNominalAtActivation": 0.1,
    "atActivation": { … },
    "atOrigination": { … },
    "current": { … },
    "isClosed": true,
    "muteLoanNotices": true,
    "nickname": "string",
    "object": "installment",
    "ratesValidation": { … },
    "servicedBy": "creditor",
    "status": "pending",
    "type": "installment"
  }
}