Certificate API

This page documents the partner-facing Certificate workflow for API v3: verify a SmartGarant eligibility certificate and download the tenant certificate PDF.

Before You Start

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

1. Endpoint Summary

Operation	Method	Endpoint
Check certificate eligibility	GET	/v3/projects/certificate/check/{certificateCode}
Get tenant certificate PDF	GET	/v3/projects/{projectId}/documents/certificate

2. Where to Find the Certificate Code

The certificate code (Attestation n° SG-XXXXXXXX) is displayed at the top-right of the eligibility certificate document.

3. Check a Certificate

Verifies the authenticity and validity of a SmartGarant eligibility certificate from its code.

GET /v3/projects/certificate/check/{certificateCode}

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

Certificate Code Format

The {certificateCode} can be provided with the SG- prefix (SG-A460C602) or as the bare code (A460C602). The code is case-insensitive, so sg-a460c602 works too.

3.1 Success Response (200)

A valid certificate returns the tenant identity, the guaranteed score, and the associated projectId.

{
  "requestId": "32b69f8e-0015-490f-a3b8-9a3dafc27f68",
  "payload": {
    "projectId": "0364435d-4352-49a3-883e-1711a2dc4d69",
    "endDate": "13/02/2026",
    "score": "3648 €",
    "firstName": "Omar",
    "lastName": "SY",
    "isExpired": false,
    "status": 7
  },
  "resultStats": 32
}

Field	Type	Description
projectId	string (GUID)	Identifier of the project linked to the certificate.
endDate	string (dd/MM/yyyy)	Validity end date of the certificate.
score	string	Maximum guaranteed monthly rent.
firstName	string	Tenant first name.
lastName	string	Tenant last name.
isExpired	boolean	true when the certificate is past its validity date.
status	integer	Project status of the linked project.

3.2 Error Response (400)

An invalid or unavailable certificate returns error code E0047.

{
  "requestId": "fcb0a1c4-626a-4f45-9472-409b4414c8da",
  "error": {
    "errorCode": "E0047",
    "message": "Certificat not valid"
  },
  "resultStats": 24
}

4. Get the Tenant Certificate

Downloads the tenant certificate as a base64-encoded PDF. Use the projectId returned by the check endpoint above.

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

GET /v3/projects/0364435d-4352-49a3-883e-1711a2dc4d69/documents/certificate HTTP/1.1
Host: sandbox.api.smart-garant.fr
Authorization: Bearer {bearerToken}

4.1 Success Response (200)

{
  "requestId": "a4120e38-a76f-4c7a-9360-1e70e862af88",
  "payload": {
    "pdfBase64": "JVBERi0xLjcKJYGBgYEKCjMgMCBvYmoKPDwKL0ZpbHRlciAvRm........................",
    "fileName": "Attestation de garantie SmartGarant Omar SY.pdf"
  },
  "resultStats": 3397
}

Field	Type	Description
pdfBase64	string	Certificate PDF encoded in base64.
fileName	string	Suggested file name for the downloaded PDF.

5. Reference

Common business errors

Most business validation failures are returned as HTTP 400.

Code	Meaning
E0000	Certificate could not be retrieved (generic API error).
E0047	Certificate code is incorrect or the certificate is not valid.

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