Claims API

This page documents the partner-facing Claim workflow for API v1: create and submit a claim, manage rental debts, manage tenant payments, and track financial statistics.

Before You Start

Environment URLs, API key provisioning, and global response envelope are centralized in Getting Started. Authentication flow is documented in Authentication.

Canonical Endpoint Paths

All endpoint paths on this page are documented without an extra service prefix and start directly with /v1.

1. Endpoint Summary

Operation	Method	Endpoint
Create claim	POST	/v1/projects/{projectId}/claims
Get claims	GET	/v1/claims
Get required documents	GET	/v1/claims/{claimId}/documents/required
Add document to claim	POST	/v1/claims/{claimId}/documents
Apply claim	POST	/v1/claims/{claimId}/apply
Get rental debts	GET	/v1/claims/{claimId}/rentaldebts
Get rental debts pending signature	GET	/v1/claims/{claimId}/rentaldebts/pending-signature
Add rental debt	POST	/v1/claims/{claimId}/rentaldebts
Update rental debt	PUT	/v1/claims/{claimId}/rentaldebts/{rentalDebtId}
Get payments	GET	/v1/claims/{claimId}/payments
Add payment	POST	/v1/claims/{claimId}/payments
Update payment	PUT	/v1/claims/{claimId}/payments/{paymentId}
Delete payment	DELETE	/v1/claims/{claimId}/payments/{paymentId}
Get claim stats	GET	/v1/claims/{claimId}/stats

ClaimStatus

Code	Status	Description
0	None	No status assigned
5	SimpleReminder	Friendly reminder before D+30
10	AwaitingDocuments	Claim file awaiting documents
20	ClaimToBeValidated	Claim file pending validation
30	Validated	Claim file validated
40	PaymentOrderToBeSent	Payment order to be sent
50	PaymentOrderRequestSent	Payment order request sent
60	PaymentOrderIssued	Payment order issued
70	RequestToBeSentLawyer	File to be sent to the lawyer
80	RequestSentLawyer	File sent to the lawyer
90	Hearing	Court hearing
100	Deliberation	Awaiting court decision
110	JudgmentIssued	Judgment issued
120	EvictionOrder	Order to vacate the premises
130	Eviction	Eviction in progress
131	Evicted	Tenant evicted, but payments are still ongoing
132	Amicable	Amicable procedure for a low rent amount
133	Ficoba	Tenant evicted, but recovery proceedings are still ongoing
140	Closed	Claim closed
150	Cancelled	Claim cancelled
160	Denied	Claim denied

RentalDebtStatus

Code	Status	Description
0	None	Unknown status
10	Virtual	Awaiting landlord declaration
11	PendingPreviousReceipt	Awaiting signature of the previous subrogation receipt
12	PendingPreviousPayment	Awaiting the previous payment
13	PendingClaimStatus	Awaiting claim validation
14	PendingPreviousBlocked	Awaiting resolution of the previous blocked item
20	PendingPayment	Awaiting payment
30	Blocked	Blocked due to missing documents, conflicting tenant information, or excessive rent increase
31	BlockedLateDeclaration	Blocked because the landlord is late with declarations
40	Paid	Fully paid
41	PartiallyPaid	Partially paid
42	OverPaid	Overpaid
50	NoActionRequired	No action required; the rent has been paid
60	VirtualPostLimitDate	Virtual status created after the deadline

2. Create Claim

Creates a claim attached to an existing project and initializes the first unpaid month.

POST /v1/projects/{projectId}/claims

POST /v1/projects/7688ec31-0713-4861-9167-125450baa854/claims HTTP/1.1
Host: sandbox.api.smart-garant.fr
Authorization: Bearer {bearerToken}
Content-Type: application/json

{
  "rentAmount": 266.00,
  "rentAmountReceived": 0.00,
  "rentAmountReceivedDate": null,
  "rentDueDate": "2026-01-01",
  "legalInfo": {
    "gender": 1,
    "firstName": "Frederic",
    "lastName": "JOLY",
    "email": "jules.dupont-test@yopmail.com",
    "phone": {
      "phoneContryCode": "FR",
      "phoneOrigin": "0606060606",
      "phoneFormated": "+33606060606"
    },
    "companyName": "Agence HUET Immobilier Nancy",
    "companyType": "SAS",
    "shareCapital": "2000",
    "address": {
      "country": "France",
      "address": "6, impasse des Roses",
      "zipCode": "62100",
      "city": "Calais",
      "additionalAddress": "2em etage"
    },
    "rCSCity": "Paris",
    "rCSNumber": "987645",
    "siren": "123456789"
  },
  "mainOwnerEmail": "gabriel.perrot@yopmail.com",
  "ownerEmailsBcc": [
    "paul.girard@yopmail.com"
  ],
  "metadata": {
    "externalReference": "CLAIM-2026-0001",
    "source": "test-free"
  }
}

3. Get Claims

Returns paginated claims for the authenticated partner.

GET /v1/claims

GET /v1/claims HTTP/1.1
Host: sandbox.api.smart-garant.fr
Authorization: Bearer {bearerToken}

4. Claim Documents

4.1 Get Required Documents

GET /v1/claims/{claimId}/documents/required

GET /v1/claims/0ddccb39-98ff-4d39-846a-4c4908de5033/documents/required HTTP/1.1
Host: sandbox.api.smart-garant.fr
Authorization: Bearer {bearerToken}

4.2 Add Document to Claim

POST /v1/claims/{claimId}/documents

---

POST /v1/claims/0ddccb39-98ff-4d39-846a-4c4908de5033/documents HTTP/1.1
Host: sandbox.api.smart-garant.fr
Authorization: Bearer {bearerToken}
Content-Type: multipart/form-data; boundary=----SmartGarantBoundary

------SmartGarantBoundary
Content-Disposition: form-data; name="documentType"

332
------SmartGarantBoundary
Content-Disposition: form-data; name="comment"

C'est un couple
------SmartGarantBoundary
Content-Disposition: form-data; name="file"; filename="Invoice-8CA1AE96-0072.pdf"
Content-Type: application/pdf

<binary content>
------SmartGarantBoundary--

Apply Requires Complete Documents

Always call required-documents first and upload missing items before apply. If required documents are missing, the claim is not applied.

5. Apply Claim

Submits the claim for SmartGarant review when the document set is complete.

POST /v1/claims/{claimId}/apply

POST /v1/claims/0ddccb39-98ff-4d39-846a-4c4908de5033/apply HTTP/1.1
Host: sandbox.api.smart-garant.fr
Authorization: Bearer {bearerToken}

6. Rental Debts

6.1 Get Rental Debts

GET /v1/claims/{claimId}/rentaldebts

GET /v1/claims/0ddccb39-98ff-4d39-846a-4c4908de5033/rentaldebts HTTP/1.1
Host: sandbox.api.smart-garant.fr
Authorization: Bearer {bearerToken}

6.2 Get Rental Debts Pending Signature

GET /v1/claims/{claimId}/rentaldebts/pending-signature

GET /v1/claims/0ddccb39-98ff-4d39-846a-4c4908de5033/rentaldebts/pending-signature HTTP/1.1
Host: sandbox.api.smart-garant.fr
Authorization: Bearer {bearerToken}

6.3 Add Rental Debt

POST /v1/claims/{claimId}/rentaldebts

POST /v1/claims/0ddccb39-98ff-4d39-846a-4c4908de5033/rentaldebts HTTP/1.1
Host: sandbox.api.smart-garant.fr
Authorization: Bearer {bearerToken}
Content-Type: application/json

{
  "rentAmount": 200.00,
  "rentAmountReceived": 100.00,
  "rentAmountReceivedDate": "2026-02-03",
  "rentDueDate": "2026-02-01"
}

6.4 Update Rental Debt

PUT /v1/claims/{claimId}/rentaldebts/{rentalDebtId}

PUT /v1/claims/0ddccb39-98ff-4d39-846a-4c4908de5033/rentaldebts/7a1ae42d-0cb0-49fe-9c72-6b7a537e9cd0 HTTP/1.1
Host: sandbox.api.smart-garant.fr
Authorization: Bearer {bearerToken}
Content-Type: application/json

{
  "rentDueDate": "2026-02-01",
  "rentAmount": 1000.00
}

No Rental Debt Delete Endpoint in v1

API v1 exposes rental debt list, add, and update endpoints. A dedicated rental debt delete endpoint is not part of this v1 contract.

7. Payments

7.1 Get Payments

GET /v1/claims/{claimId}/payments

GET /v1/claims/0ddccb39-98ff-4d39-846a-4c4908de5033/payments HTTP/1.1
Host: sandbox.api.smart-garant.fr
Authorization: Bearer {bearerToken}

7.2 Add Payment

POST /v1/claims/{claimId}/payments

POST /v1/claims/0ddccb39-98ff-4d39-846a-4c4908de5033/payments HTTP/1.1
Host: sandbox.api.smart-garant.fr
Authorization: Bearer {bearerToken}
Content-Type: application/json

{
  "amount": 10.00,
  "applyDate": "2026-01-12"
}

7.3 Update Payment

PUT /v1/claims/{claimId}/payments/{paymentId}

PUT /v1/claims/0ddccb39-98ff-4d39-846a-4c4908de5033/payments/0bc545bd-74a7-4df0-b183-1769954aa9c4 HTTP/1.1
Host: sandbox.api.smart-garant.fr
Authorization: Bearer {bearerToken}
Content-Type: application/json

{
  "amount": 399.00,
  "applyDate": "2026-07-05"
}

7.4 Delete Payment

DELETE /v1/claims/{claimId}/payments/{paymentId}

DELETE /v1/claims/0ddccb39-98ff-4d39-846a-4c4908de5033/payments/58bc1804-7b47-4e58-80d9-0008ec1b45ae HTTP/1.1
Host: sandbox.api.smart-garant.fr
Authorization: Bearer {bearerToken}

8. Claim Statistics

Returns claim-level financial counters and totals.

GET /v1/claims/{claimId}/stats

GET /v1/claims/0ddccb39-98ff-4d39-846a-4c4908de5033/stats HTTP/1.1
Host: sandbox.api.smart-garant.fr
Authorization: Bearer {bearerToken}

9. Webhooks

Claims lifecycle events are pushed to the webhook configured on your API key.

• Delivery method: POST
• Content type: application/json
• Idempotency key: event id

Typical event types:

• claim.created
• claim.updated
• rental_debt.created
• rental_debt.updated
• rental_debt.receipt.pending_signature
• rental_debt.receipt.signed

For webhook setup prerequisites, see Getting Started.

10. Reference

This section keeps only high-value quick references for Claim integrations.

Common business errors

Most business validation failures are returned as HTTP 400.

Code	Meaning
E0015	Unauthorized for the project or organization.
E0040	Project not found.
E0090	Invalid document type.
E0142	Missing file.
E0144	Unsupported file content type.
E0145	File size exceeds 10 MB.
E0176	The project already has an active claim.
E0177	Claim not found.
E0188	Declare the next month in chronological order.
E0193	Rental debt month not found.
E0200	Claim status does not allow this action.
E0201	Due date cannot be in the future.
E0212	Payment amount must be greater than 0.
E0225	Rental debt month cannot be changed.
E0233	Payment not found.

Status families

• Claim statuses include reminder, awaiting documents, to be validated, validated, and end states.
• Rental debt statuses include pending, blocked, paid, partially paid, and overpaid.
• Receipt statuses include pending signature and signed.

For response envelope format and requestId tracing, see Getting Started.