Skip Navigation
Log In Sign Up

Create a Loan

·

Create a new loan by sending a POST request to the loans endpoint.

Request

POST https://tupel.com/api/loans/

Authentication

This endpoint requires basic authentication with your Organization ID and API Key.

Request Body Parameters

  • entity string Required
    The UID of the entity (borrower) for which the loan is being created. Maximum length: 12 characters.

  • currency string Required
    Three-letter ISO currency code. Supported values: USD, EUR, GBP, or other accepted currency codes.

  • principal decimal Required
    The amount to be loaned. Must be a positive number with up to 2 decimal places.

  • pay_at timestamp Required
    The date and time when the loan should be paid out to the recipient. Format: ISO 8601 (e.g., 2023-04-01T12:00:00Z).

  • due_at timestamp Required
    The date and time when the loan is due to be paid back. Format: ISO 8601 (e.g., 2023-10-01T23:59:59Z).

  • recipient string Required
    The UID of the recipient where loan funds will be sent. Must be a valid recipient UID.

  • payment_method string Required
    The UID of the payment method to be used for repayments. Must be a valid payment method UID.

  • installments integer Optional
    Number of installments for repayment. Default: 1.

  • reference string Optional
    Additional reference information for your internal tracking. Default: empty string. Maximum length: 50 characters. Must match pattern: ^[0-9A-Za-z]+(?: [0-9A-Za-z]+)*

Notes

  • The interest rate (rate) are determined by your organization's configuration, the entity's credit risk and volume.
  • When installments is greater than 1, the system will automatically create a repayment schedule in the installments array.
  • The loan status will initially be set to PENDING and will transition to OPEN once the funds are disbursed on the pay_at date.
  • All timestamps should be provided in UTC timezone.

Example Request

curl -X POST https://tupel.com/api/loans/ \
  -u <YOUR_ORG_ID>:<YOUR_API_KEY> \
  -H "Content-Type: application/json" \
  -d '{
    "entity": "7Ba9c2E4f",
    "currency": "USD",
    "principal": "50000.00",
    "pay_at": "2023-04-01T12:00:00Z",
    "due_at": "2023-10-01T23:59:59Z",
    "recipient": "Ab3D9f2c",
    "payment_method": "2qP3oN4m",
    "installments": 4,
    "reference": "2023 Expansion"
  }'

Response

A successful request returns a 200 OK status code and a complete Loan in the response body.

Error Responses

Code Description
401 Authentication failed. Check your Organization ID and API Key.
403 Insufficient permissions to create loans.
422 Validation error. The request contains invalid or missing required parameters.

Example Error Response

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "entity"],
      "msg": "Field required"
    }
  ]
}