SmartGarant Guarantee API

This page documents the partner-facing SmartGarant Guarantee (GLI) workflow for API v3: pre-scoring, project creation, document management, validation request, and rental information.

Before You Start

Environment URLs, API key provisioning, and the global response envelope are centralized in Getting Started. Authentication flow is documented in Authentication. For the functional lifecycle, see GLII Process.

Canonical Endpoint Paths

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

1. Endpoint Summary

Operation	Method	Endpoint
Get a pre-scoring	POST	/v3/score
Create a project	POST	/v3/projects
Get projects	GET	/v3/projects
Get a project	GET	/v3/projects/{id}
Get required documents	GET	/v3/projects/{projectId}/required
Add documents	POST	/v3/projects/{id}/documents
Get project documents	GET	/v3/projects/{id}/documents
Delete a document	DELETE	/v3/projects/{id}/documents/{documentId}
Apply (request validation)	POST	/v3/projects/{id}/apply
Get eligibility certificate	GET	/v3/projects/{id}/documents/certificate
Add rental information	POST	/v3/projects/{id}/rent
Get project payment	GET	/v3/projects/{id}/payment
Get organization stats	GET	/v3/projects/stats

2. Get a Pre-Scoring

Returns the maximum guaranteed rent for a given financial profile, before creating a project.

POST /v3/score

POST /v3/score HTTP/1.1
Host: sandbox.api.smart-garant.fr
Authorization: Bearer {bearerToken}
Content-Type: application/json

{
  "finance": {
    "status": 1,
    "monthlyIncome": 1800
  }
}

3. Create a Project

Creates a guarantee project for a tenant.

POST /v3/projects

POST /v3/projects HTTP/1.1
Host: sandbox.api.smart-garant.fr
Authorization: Bearer {bearerToken}
Content-Type: application/json

{
  "profile": {
    "firstName": "Cyril",
    "lastName": "Blibi",
    "gender": 1,
    "dateOfBirth": "1986-01-02",
    "phone": {
      "phoneContryCode": "FR",
      "phoneOrigin": "0606060606",
      "phoneFormated": "+33606060606"
    },
    "email": "cyril.blibi@yopmail.com"
  },
  "finance": {
    "status": 1,
    "monthlyIncome": 1800
  },
  "metadata": {
    "source": "partner-api",
    "externalLeadId": "LD-20260630-001"
  }
}

3.1 Business Rules

1. The tenant status (finance.status) is required.
2. Below 250 € of rent (SmartGarant scoring), the project cannot be created (non-eligible).
3. If the tenant status is retired (14), put the income in retirementPensionAmount and not in monthlyIncome.
4. If the tenant status is student (12), a referent and the referent referentFinance are required.
5. A referent cannot be a student nor retired.
6. For CDD and interim statuses, contractPrecarious must be provided.

3.2 profile

Field	Description / Note	Required
gender	1 Homme, 2 Femme	true
firstName		true
lastName		true
email		true
dateOfBirth	Format yyyy-MM-dd	true
phone	{ "phoneOrigin": "0666666666", "phoneContryCode": "FR", "phoneFormated": "+33666666666" } — uses libphonenumber-js	true

3.3 finance (tenant finance)

Field	Description / Note	Required
status	See Status Types	true
contractPrecarious	Only for CDD and interim — 0 superior to 6 months, 1 inferior to 6 months, 2 trial period
monthlyIncome	Net monthly income of the tenant
bonusesAmount	Bonuses of the tenant
savingsAmount	Tenant savings
socialSecurityAmount	Tenant social security
familyAllowanceAmount	Family allowances / grants of the tenant
foodSupportAmount	Alimony of the tenant
landIncome	Land income of the tenant
unemploymentBenefit	Unemployment benefit of the tenant
maternityLeave	Maternity/paternity leave of the tenant
retirementPensionAmount	Net retirement pension of the tenant (retired only)

3.4 referent / referentFinance

Required only when the tenant finance.status is student (12). referentFinance follows the same structure as finance, and the referent status cannot be student or retired.

3.5 Status Types

Value	Status
0	Titulaire du public
1	CDI Public
2	CDD Public
3	Militaire
4	CDI privé
5	CDD privé
6	Intérimaire
7	Intermittent
8	Artisan / Commerçant
9	Auto-entrepreneur
10	Profession libérale
11	Chef d'entreprise
12	Étudiant
14	Retraité
15	Recherche d'emploi

3.6 Response Model

Field	Description
id	Unique project id
userId	Unique user id
status	See Project Status
createDate	Project creation date
score	Maximum guaranteed rent

3.7 Project Status

Value	Description
0	Documents pending / missing
1	Documents in validation, waiting for manager
2	Documents validated, waiting for rental information
3	Rental in validation, waiting for manager
4	Project validated, waiting for payment
5	Payment done, waiting for tenant signature
6	Tenant signature ok, waiting for owner signature
7	Project active — contract in progress
9	Project suspended (no follow-up or too old)
12	Contract will end at a defined date
13	Contract ended, no longer active
14	Project not eligible

3.8 Reuse a Project in the Partner Journey

POST /v3/projects creates a new project. SmartGarant does not automatically match a project created through the API with a new project started from the generic partner page. Starting both flows can therefore create two projects for the same tenant.

To avoid duplicates:

1. Store the returned id against the tenant in your system.
2. Store or rebuild the returned publicUrl for that project.
3. When the tenant resumes the journey, redirect them to that publicUrl instead of starting a new project from the generic partner page.
4. Reuse the same project id for subsequent API calls.

The tenant email address alone must not be used as an idempotency key.

4. Get Projects

GET /v3/projects

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

5. Get a Project

GET /v3/projects/{id}

6. Documents

6.1 Get Required Documents

Returns the list of expected documents for a project.

GET /v3/projects/{projectId}/required

6.2 Add a Document

Uploads one document as multipart/form-data. Send one file per request.

POST /v3/projects/{id}/documents

Form field	Type	Required	Description
file	binary	yes	JPEG, GIF, PNG, or PDF file; maximum size: 10 MB.
documentType	integer	yes	Document type expected by GET /v3/projects/{projectId}/required.

The project must be in status 0 (documents pending). Use the numeric document type returned by the required-documents endpoint; for example, 1 is an identity document and 2 is a tax notice.

POST /v3/projects/118c3582-c00d-49ed-a37d-5c6991c489e3/documents HTTP/1.1
Host: sandbox.api.smart-garant.fr
Authorization: ******
Content-Type: multipart/form-data; boundary=----SmartGarantBoundary

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

2
------SmartGarantBoundary
Content-Disposition: form-data; name="file"; filename="tax-notice.pdf"
Content-Type: application/pdf

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

JavaScript with Axios

When using FormData in a browser, do not set Content-Type manually: the browser adds the required boundary.

const input = document.querySelector('input[type="file"]');
const file = input.files[0];
const form = new FormData();

form.append('documentType', '2');
form.append('file', file);

const response = await axios.post(
  `https://sandbox.api.smart-garant.fr/v3/projects/${projectId}/documents`,
  form,
  {
    headers: {
      Authorization: `Bearer ${token}`,
    },
  },
);

6.3 Get Project Documents

GET /v3/projects/{id}/documents

6.4 Delete a Document

DELETE /v3/projects/{id}/documents/{documentId}

6.5 Get Eligibility Certificate

GET /v3/projects/{id}/documents/certificate

7. Apply — Request Validation

Requests verification of the uploaded documents.

POST /v3/projects/{id}/apply

8. Rental Information

Adds the rental information once documents are validated. The project must be in status 2.

POST /v3/projects/{id}/rent

POST /v3/projects/118c3582-c00d-49ed-a37d-5c6991c489e3/rent HTTP/1.1
Host: sandbox.api.smart-garant.fr
Authorization: ******
Content-Type: application/json

{
  "owner": {
    "firstName": "Jean-Pierre",
    "lastName": "Dupont",
    "email": "jean-pierre.dupont@example.com",
    "phone": {
      "phoneContryCode": "FR",
      "phoneFormated": "+33606060606"
    }
  },
  "ownerType": 1,
  "ownerOrganizationName": "Agence des Champs",
  "ownerAddress": {
    "country": "France",
    "zipCode": "75001",
    "city": "Paris",
    "address": "2365 rue des Champs"
  },
  "addressInformation": {
    "country": "France",
    "zipCode": "75002",
    "city": "Paris",
    "address": "1000 rue des Champs"
  },
  "rentAmount": 1005,
  "personalRentAmount": 600,
  "rentAlone": 1,
  "securityDeposit": 2000.50,
  "startLease": "2030-09-28",
  "bailType": 0
}

8.1 Request Fields

Field	Type	Required	Description
owner	object	yes	Owner contact. firstName, lastName, a valid email, and phone are required.
owner.phone.phoneContryCode	string	yes	ISO 3166-1 alpha-2 country code, for example FR. The spelling is part of the API contract.
owner.phone.phoneFormated	string	yes	International E.164 number, for example +33606060606. The spelling is part of the API contract.
ownerType	integer	yes	0: individual owner; 1: agency.
ownerOrganizationName	string	conditional	Organization name when the owner is an agency.
ownerAddress	object	yes	Owner address. country, zipCode, city, and address are required.
addressInformation	object	yes	Rented-property address. country, zipCode, city, and address are required.
rentAmount	number	yes	Total monthly rent including charges; must be greater than 0.
personalRentAmount	number	conditional	Tenant's share including charges; required and greater than 0 for flatsharing or a couple.
rentAlone	integer	yes	0: alone; 1: flatsharing; 2: couple.
securityDeposit	number	no	Security deposit amount.
startLease	string	yes	Lease start date in yyyy-MM-dd format; it cannot be in the past.
bailType	integer	yes	See Lease Types.
theoreticalEndLease	string	conditional	Expected end date; required for a mobility lease.

The guaranteed score must cover rentAmount when rentAlone is 0, or personalRentAmount when rentAlone is 1 or 2.

8.2 Lease Types

Value	Description
0	Classic three-year lease
1	Furnished or unfurnished one-year lease
2	Student lease
3	Standard six-year lease
4	Mobility lease of 1 to 10 months
5	Two-year lease

9. Payment

GET /v3/projects/{id}/payment

10. Organization Stats

Returns statistics for the authenticated organization.

GET /v3/projects/stats