> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.anzi.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Update credit status

> Updates the credit status and outstanding principal of a guarantee.

<Note>
  Claims in Anzi are automatically managed through credit status updates. If you
  want to make a claim, you must update the credit status to CLAIM\_GUARANTEE.
</Note>

### Business rules

* You cannot update a credit that:
  * already has a claim or is in the "claim guarantee" step, or
  * has a guarantee in a terminal state (CLOSED, CANCELED, NOVATED, or REVOKED).

<Note>
  You must provide `creditPrincipalOutstanding` and `creditLastPaymentDate` when the outstanding balance has changed or when the credit status has changed (e.g., to DELINQUENT, CLAIM\_GUARANTEE, etc.).
</Note>

* Outstanding balance (`creditPrincipalOutstanding`):
  * Cannot be higher than the last recorded outstanding balance (when there is a previous outstanding balance recorded).
  * Cannot be higher than the original loan amount.
  * Cannot be negative.

* Last payment date (`creditLastPaymentDate`):
  * If you provide it, it must be after the day the loan was disbursed.
  * If a last payment was already recorded, the new date cannot be earlier than the previously recorded date.
  * It cannot be a future date.

* Coupled fields rule (both-or-none):
  * If you provide `creditLastPaymentDate`, you must also provide `creditPrincipalOutstanding`.
  * If you provide `creditPrincipalOutstanding`, you must also provide `creditLastPaymentDate`.

* Revoked status (`REVOKED`):
  * Only allowed when no payments have been reported on the credit (i.e., the outstanding principal equals the original loan amount).

* Update frequency:
  * You can only update the credit status once per calendar day (evaluated in the license timezone).

### Guarantee Value (`guaranteeValue`)

This field is **required** when your license is configured with variable portfolio premiums paid by installment amount. Specifically, all four conditions must be true:

| License field                    | Required value       |
| -------------------------------- | -------------------- |
| `type`                           | `FIRST_LOSS` (1)     |
| `installmentsEnabled`            | `true`               |
| `isPremiumReportedByCollections` | `true`               |
| `installmentStrategy`            | `INSTALLMENT_AMOUNT` |

When these conditions are met:

* You **must** include `guaranteeValue` in every credit status update.
* `guaranteeValue` **cannot be negative** regardless of the status.
* The reported value represents the premium amount for the current period and will be accumulated in `pendingPremiumsValue` until it is collected through payment consolidation.

If your license does **not** meet all four conditions above, `guaranteeValue` is ignored and can be omitted.

For a full list of error codes, causes, and resolution steps, see [Credit Status Error Codes](/core-concepts/errors-credit-status).


## OpenAPI

````yaml /openapi.yaml put /guarantees/credit-status
openapi: 3.0.3
info:
  title: Anzi Backend API
  version: 1.0.0
  description: |
    API reference for Anzi. This spec is scoped to the Organizations module.
servers:
  - url: https://sandbox-api.anzi.finance/v1
    description: Sanbox
  - url: https://api.anzi.finance/v1
    description: Production
security: []
tags:
  - name: Licenses
    description: Operational licenses
  - name: Users
    description: Manage users and API keys
  - name: Claims
    description: Manage claims
paths:
  /guarantees/credit-status:
    put:
      tags:
        - Guarantees
      summary: Update credit status
      description: Updates the credit status and outstanding principal of a guarantee.
      parameters:
        - in: query
          name: license
          required: true
          schema:
            type: string
          description: License UID
        - in: query
          name: uid
          required: true
          schema:
            type: string
          description: Guarantee UID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCreditStatusDto'
            examples:
              example:
                value:
                  status: CURRENT
                  creditPrincipalOutstanding: 12500
                  creditLastPaymentDate: '2025-09-10T00:00:00.000Z'
                  guaranteeValue: 15000
      responses:
        '200':
          description: Credit status updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GuaranteeEntity'
              examples:
                example:
                  value:
                    uid: b4c2d1e3-9a8f-4b7d-86e1-2f3a4c5b6d7e
                    tokenId: 987654321
                    coverage: 25000
                    disbursementDate: '2025-09-05T00:00:00.000Z'
                    dueDate: '2026-12-04T23:59:59.999Z'
                    status: 2
                    premiumStatus: 2
                    premium: 1750
                    principalName: Empresa XYZ SAS
                    promissoryNoteId: PN-0001-XYZ
                    loanPaymentDueDate: '2025-12-05T23:59:59.999Z'
                    loanAmount: 50000
                    type: 0
                    premiumPercentage: 3.5
                    coveragePercentage: 50
                    externalReference: CR-000001-XYZ
                    isNovation: false
                    creditStatus: 0
                    creditStatusUpdatedAt: '2025-09-02T10:30:00.000Z'
                    creditPrincipalOutstanding: 12500
                    creditLastPaymentDate: '2025-09-10T00:00:00.000Z'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GE_01:
                  summary: Generic bad request
                  value:
                    code: GE_01
                    message: Bad Request
                GUA_44:
                  summary: Guarantee already has a claim or was novated
                  value:
                    code: GUA_44
                    message: >-
                      Guarantee already has an associated claim or has been
                      novated
                GUA_45:
                  summary: >-
                    Credit status is terminal (CLAIM_GUARANTEE, NOVATED,
                    REVOKED, or PAID)
                  value:
                    code: GUA_45
                    message: >-
                      Cannot update credit status because it is already in
                      CLAIM_GUARANTEE, NOVATED, REVOKED, or PAID state. These
                      states are final and cannot be modified.
                GUA_46:
                  summary: New outstanding exceeds current outstanding
                  value:
                    code: GUA_46
                    message: >-
                      The new outstanding amount cannot be greater than the
                      current outstanding amount. Please enter a value equal to
                      or less than the current outstanding amount.
                GUA_47:
                  summary: Outstanding exceeds loan amount
                  value:
                    code: GUA_47
                    message: >-
                      The outstanding amount cannot exceed the loan amount.
                      Please enter a value equal to or less than the original
                      loan amount of the guarantee.
                GUA_48:
                  summary: Negative outstanding amount
                  value:
                    code: GUA_48
                    message: >-
                      The outstanding amount cannot be negative. Please enter a
                      positive number or zero to represent the remaining
                      balance.
                GUA_49:
                  summary: Last payment date before disbursement date
                  value:
                    code: GUA_49
                    message: >-
                      The last payment date must be after the disbursement date.
                      Please select a date that occurs after the loan was
                      disbursed.
                GUA_50:
                  summary: Last payment date before previously recorded date
                  value:
                    code: GUA_50
                    message: >-
                      The new last payment date must be more recent than the
                      currently recorded last payment date. Please select a
                      later date.
                GUA_51:
                  summary: Last payment date in the future
                  value:
                    code: GUA_51
                    message: >-
                      The last payment date cannot be in the future. Please
                      select a date that is today or earlier.
                GUA_55:
                  summary: Credit status already updated today
                  value:
                    code: GUA_55
                    message: The guarantee was already updated
                GUA_62:
                  summary: Invalid credit status value
                  value:
                    code: GUA_62
                    message: Invalid loan status. Please use one of the valid statuses.
                GUA_63:
                  summary: Missing last payment date when outstanding changes
                  value:
                    code: GUA_63
                    message: >-
                      Incomplete payment update: last payment date is required
                      when the outstanding amount changes.
                GUA_64:
                  summary: Missing outstanding when last payment date changes
                  value:
                    code: GUA_64
                    message: >-
                      Incomplete payment update: outstanding amount is required
                      when the last payment date changes.
                GUA_73:
                  summary: Invalid or malformed date
                  value:
                    code: GUA_73
                    message: >-
                      Invalid or malformed date value. The provided date could
                      not be parsed. Please use a valid date format (e.g.,
                      YYYY-MM-DD).
                GUA_74:
                  summary: Missing guaranteeValue for variable premium license
                  value:
                    code: GUA_74
                    message: >-
                      For variable premium licenses, please include the
                      guarantee value in the update.
                GUA_75:
                  summary: Negative guaranteeValue
                  value:
                    code: GUA_75
                    message: Guarantee value cannot be negative.
                GUA_78:
                  summary: Cannot revoke guarantee with payments
                  value:
                    code: GUA_78
                    message: >-
                      Cannot revoke a guarantee that has already received
                      payments. The credit status can only be set to REVOKED
                      when no payments have been reported.
        '401':
          description: Unauthorized (invalid API key)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                AUTH_01:
                  value:
                    code: AUTH_01
                    message: Invalid API Key
        '404':
          description: Guarantee or license not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GUA_10:
                  value:
                    code: GUA_10
                    message: Guarantee not found
                LI_00:
                  value:
                    code: LI_00
                    message: License Not Found
      security:
        - apiKeyAuth: []
components:
  schemas:
    UpdateCreditStatusDto:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          enum:
            - CURRENT
            - DELINQUENT
            - CLAIM_GUARANTEE
            - NOVATED
            - PAID
            - REVOKED
          description: New credit status to set for the guarantee.
        creditPrincipalOutstanding:
          type: number
          minimum: 0
          description: >-
            Outstanding principal amount of the credit as of the borrower’s last
            payment date.
        creditLastPaymentDate:
          type: string
          format: date-time
          description: Last payment date (ISO 8601).
        guaranteeValue:
          type: number
          nullable: true
          minimum: 0
          description: >
            The premium amount collected by the client for the current billing
            cycle.

            **Required** when ALL of the following license conditions are met:

            - `license.type` = `FIRST_LOSS` (1)

            - `license.installmentsEnabled` = `true`

            - `license.isPremiumReportedByCollections` = `true`

            - `license.installmentStrategy` = `INSTALLMENT_AMOUNT`


            **Validation rules:**

            - Cannot be negative regardless of status.


            When not required by the license configuration, this field is
            ignored.
    GuaranteeEntity:
      type: object
      properties:
        uid:
          type: string
          description: Unique identifier of the guarantee.
        tokenId:
          type: number
          description: Numeric identifier assigned to the guarantee token.
        coverage:
          type: number
          description: >-
            Maximum amount payable if the linked loan defaults. For guarantees
            created under FIRST LOSS licenses (license.type = FIRST_LOSS),
            coverage depends exclusively on the amount the user has in their own
            reserve fund (wallet).
        disbursementDate:
          type: string
          format: date-time
          description: Date and time when the credit was disbursed.
        claimDate:
          type: string
          format: date-time
          nullable: true
          description: >-
            Date and time when a claim was registered for this guarantee (if
            any).
        dueDate:
          type: string
          format: date-time
          description: Guarantee due date.
        status:
          type: integer
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
            - 7
            - 8
            - 9
            - 10
          description: >-
            0=PENDING_ACTIVATION, 1=VALIDATING_PREMIUM_PAYMENT, 2=COVERING,
            3=PENDING_CLAIM, 4=CLAIM_APPROVED, 5=PAYING_GUARANTEE, 6=CLOSED,
            7=CLAIM_REJECTED, 8=CANCELED, 9=NOVATED, 10=REVOKED
        creditStatus:
          type: integer
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
            - 5
          description: >-
            0=CURRENT, 1=DELINQUENT, 2=CLAIM_GUARANTEE, 3=NOVATED, 4=PAID,
            5=REVOKED
        creditStatusUpdatedAt:
          type: string
          format: date-time
          description: Timestamp of the last update to creditStatus.
        creditPrincipalOutstanding:
          type: number
          description: >-
            Outstanding principal amount of the credit as of the borrower’s last
            payment date.
        creditLastPaymentDate:
          type: string
          format: date-time
          nullable: true
          description: Date and time of the last credit payment (if any).
        premiumStatus:
          type: integer
          enum:
            - 0
            - 1
            - 2
          description: 0=PENDING, 1=PROCESSING, 2=PAID
        premium:
          type: number
          description: Premium amount charged for the guarantee (monetary value).
        principalName:
          type: string
          description: Borrower or principal name associated with the credit.
        loanPaymentDueDate:
          type: string
          format: date-time
          description: >-
            Date and time when the loan payment is/was completed by the
            borrower.
        loanAmount:
          type: number
          description: Original loan principal amount linked to this guarantee.
        type:
          type: integer
          enum:
            - 0
            - 1
          description: >-
            0 = SURETY, 1 = FIRST_LOSS. License type under which this guarantee
            was created.
        premiumPercentage:
          type: number
          description: Percentage applied to the loan amount to compute the premium.
        coveragePercentage:
          type: number
          description: >-
            Percentage of the principal amount that is covered by the guarantee.
            For guarantees created under FIRST LOSS licenses (license.type =
            FIRST_LOSS), coverage is equal the loan amount but it depends
            exclusively on the amount the user has in their own reserve fund
            (wallet).
        externalReference:
          type: string
          description: >-
            Unique credit reference in your system used to identify the
            guarantee.
        isNovation:
          type: boolean
          description: >-
            Indicates if this guarantee results from a novation of a prior
            guarantee.
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

````