Lead API

This page documents the partner-facing Lead workflow for API v1: submit a prospect (lead) with profile, finance information, and free-form search metadata.

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 lead	POST	/v1/lead

2. Create Lead

Creates a lead attached to the authenticated partner organization.

POST /v1/lead

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

{
  "profile": {
    "gender": 2,
    "firstName": "Lea",
    "lastName": "Martin",
    "phoneNumber": "+33699887766",
    "email": "simon.huet-test@yopmail.com"
  },
  "financeInformation": {
    "status": 5,
    "monthlyIncome": 2800
  },
  "metadata": {
    "key1": "value1",
    "exempleData": "LD-20260630-001"
  }
}

3. Request Body

Field	Type	Required	Description
profile	object	Yes	Prospect identity and contact details.
financeInformation	object	No	Prospect professional and income details.
metadata	object (map)	No	Free-form key/value pairs used as search criteria.

3.1 profile

Field	Type	Required	Description
gender	integer	Yes	Prospect gender. 0 none, 1 men, 2 women.
firstName	string	Yes	Prospect first name.
lastName	string	Yes	Prospect last name.
phoneNumber	string	Yes	Phone number in international format (e.g. +33699887766).
email	string	Yes	Valid email address. Invalid emails are rejected.

3.2 financeInformation

Field	Type	Required	Description
status	integer	No	Professional status. See Professional status reference.
monthlyIncome	number	No	Net monthly income of the prospect.

3.3 metadata

A map of string keys to string values. Use it to store your own external references and search criteria (for example a CRM identifier). All entries are stored as-is and returned on the created lead.

{
  "key1": "value1",
  "exempleData": "LD-20260630-001"
}

4. Response

On success the endpoint returns HTTP 201 Created with the persisted lead, including the generated id, the resolved organization, and the submitted profile, finance information, and metadata.

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

5. Professional Status Reference

The financeInformation.status field accepts the following integer codes.

Code	Situation
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
13	Alternant
14	Retraité
15	Recherche d’emploi

6. Reference

Common business errors

Most business validation failures are returned as HTTP 400.

Code	Meaning
E0000	Lead could not be created (generic API error).
E0015	Unauthorized, invalid payload, or invalid email.
E0059	Organization does not exist.