Installment Requests

Create a new installment request v2

post

This endpoint creates a new installment request. New installment requests have the status of SUBMITTED.

Authorizations

JWT

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

school_namestring · min: 2 · max: 50Required

The school name

Example: مدارس جيل النموذجية

Responses

200

The installment request is created successfully

*/*

idstring · uuidOptional

redirect_urlstring · uriOptional

creation_datestring · date-timeOptional

400

1. INST-REQ-006: Customer phone number is already registered with another national ID
2. INST-REQ-008: Request can't be created because the user has a CUSTOMER_APPROVED request that needs to be completed.
3. INST-REQ-013: User has past due claims on a current plan, past due claims must all be paid before creating a new installment request
4. INST-REQ-014: Entity: {ID} doesn't belong to group: {ID}
5. INST-REQ-015: The entity: {ID} doesn't have an active contract
6. INST-REQ-016: The contract: {ID} doesn't have open balances
7. INST-REQ-017: The entity: {ID} balance is consumed
8. INST-REQ-018: Group has no entities

*/*

401

1. Access-001: Access is denied
2. Access-003: Invalid token

*/*

404

1. BR-002: Group {id} wasn't found
2. BR-002: Entity {id} wasn't found

*/*

406

Validation Errors

*/*

500

1. ERR-005: Unexpected Technical Runtime Error.

*/*

post

/v2/installment-requests

HTTPcURLJavaScriptPython

POST /v2/installment-requests HTTP/1.1
Host: api.sandbox.jeel.co
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 556

{
  "school_name": "مدارس جيل النموذجية",
  "customer": {
    "first_name": "الأول",
    "last_name": "الأخير",
    "phone_number": "550000000",
    "national_id": "1104448787",
    "email": "[email protected]"
  },
  "students": [
    {
      "national_id": "1104448787",
      "entity_id": "123e4567-e89b-12d3-a456-426614174000",
      "previous_costs": 1000,
      "academic_year": "text",
      "is_currently_enrolled": true,
      "reference_number": "1234567890",
      "name": "فهد",
      "cost": 25000,
      "grade": "text"
    }
  ],
  "urls": {
    "redirect_url": "https://website.com/jeel/confirm",
    "notification_url": "https://website.com/webhook/jeel"
  }
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "redirect_url": "https://example.com",
  "creation_date": "2026-03-22T13:43:51.792Z"
}

Calculate installment request details

post

This endpoint will calculate installment request, and check initial user eligibility

Authorizations

JWT

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

mobileNumberstringRequiredPattern: ^(5)([0-9]{8})$

costnumber · doubleRequired

Responses

200

OK

*/*

totalCostnumber · doubleOptional

installmentCostnumber · doubleOptional

downPaymentnumber · doubleOptional

numberOfInstallmentsinteger · int32Optional

lastInstallmentDatestring · dateOptional

eligiblebooleanOptional

401

1. Access-001: Access is denied
2. Access-003: Invalid token

*/*

406

BR-001: Input Validation

*/*

500

1. ERR-005: Unexpected Technical Runtime Error.

*/*

post

/v1/installment-requests/cost-calculation

HTTPcURLJavaScriptPython

POST /v1/installment-requests/cost-calculation HTTP/1.1
Host: api.sandbox.jeel.co
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 32

{
  "mobileNumber": "text",
  "cost": 1
}

{
  "totalCost": 1,
  "installmentCost": 1,
  "downPayment": 1,
  "numberOfInstallments": 1,
  "lastInstallmentDate": "2026-03-22",
  "eligible": true
}

Get an installment request by ID

get

Authorizations

JWT

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstring · uuidRequired

Responses

200

OK

*/*

idstringOptional

statusstring · enumOptionalPossible values:

redirectUrlstringOptional

notificationUrlstringOptional

creationDatestring · date-timeOptional

customerNationalIdstringOptional

401

1. Access-001: Access is denied
2. Access-003: Invalid token

*/*

403

The user is not the installment request's owner

*/*

404

BR-002: Installment request not found

*/*

get

/v1/installment-requests/{id}

HTTPcURLJavaScriptPython

GET /v1/installment-requests/{id} HTTP/1.1
Host: api.sandbox.jeel.co
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "text",
  "status": "SUBMITTED",
  "redirectUrl": "text",
  "notificationUrl": "text",
  "creationDate": "2026-03-22T13:43:51.792Z",
  "customerNationalId": "text",
  "approved_students": [
    {
      "beneficiaryNationalId": "text",
      "entityId": "text",
      "approvedAmount": 1
    }
  ]
}