Toucan

The Lead Management System API enables seamless creation, retrieval, and management of leads within the LMS Collections platform. It provides developers with programmatic access to core lead operations and user authentication, supporting efficient and scalable lead handling.

## Features
- Lead submission and management
- User authentication and authorization
- Dashboard analytics
- Notification system
- Report generation

## Architecture
The system consists of multiple microservices:
- **Lead Service**: Core lead management functionality
- **UAM Service**: User and access management
- **Config Service**: Product configuration management
- **Notify Service**: Notification management
- **Report Service**: Analytics and reporting


Lead Management System API

The Authentication APIs provide methods for user login, token management, and session handling. These APIs ensure secure access to protected resources by authenticating users with their credentials and managing access tokens and refresh tokens to maintain user sessions.

Authentication

Login a user with username and password to obtain access tokens.


Login

Refresh an access token using a valid refresh token. This endpoint generates a new access token when the current one expires, allowing continued API access without requiring user re-authentication.


Refresh access token

Register a new user in the system. This endpoint creates a new user account with the provided credentials and profile information. The username must be unique.


Sign up

TOTP verification login

Change password

The Leads APIs offer operations for managing and tracking leads. Users can create, update, retrieve, and analyze leads to streamline sales and marketing efforts. This tag includes endpoints for lead capture, qualification, and conversion processes.

Leads

Submit a new lead from a public form. This endpoint processes lead submissions with security validation through config signatures and optional captcha verification. The form data is validated against the product configuration and automatically scored based on defined rules.


Submit a new lead

Retrieves a specific lead by its unique identifier. Returns detailed information about the lead including form data, status, and metadata.

Get lead by ID

Retrieves all leads with comprehensive pagination, sorting, and filtering capabilities. Supports filtering by status, product code.

Get all leads

Update an existing lead's information.

**Request Parameters:**

| Name | In | Type | Required | Description | Example |
|------|----|------|----------|-------------|---------|
| leadId | path | string | Yes | Lead identifier | lead-123 |


Update lead

Update multiple leads at once.

**Request Body Fields:**

| Field | Type | Required | Description | Example |
|-------|------|----------|-------------|---------|
| leadIds | array | Yes | List of lead IDs to update | ["lead-1", "lead-2"] |
| updates | object | Yes | Updates to apply | {"status": "QUALIFIED"} |


Bulk update leads

The Analytics APIs provide access to dashboard statistics, data analysis, and visualizations. Users can retrieve detailed reports on system performance, user activity, and business metrics to gain actionable insights and optimize decision-making.

Analytics

Retrieves comprehensive dashboard statistics including lead counts, conversion rates, and performance metrics.

Get dashboard statistics

Retrieves the count of new leads for a specific time period (today, week, or month).

Get new leads count

Retrieves the top lead sources ranked by lead count, with an optional limit on the number of sources returned.

Get top lead sources

The Products APIs manage the configuration and details of products in your system. Users can create, update, and retrieve product information, pricing, and inventory levels, allowing for effective product management, cataloging, and distribution.

Products

Retrieves the render package for a product's lead form configuration. This is a public endpoint that provides form structure and styling information.

Get product configuration for SDK

Retrieves the complete product configuration including form fields, validation rules, and styling. This is an internal API endpoint requiring authentication.

Get product configuration by product code

Get all products

Creates a new product configuration with form schema, validation rules, and optional dictionaries for dropdown fields and lead scoring logic.

Create new product

Updates an existing product configuration including form schema, validation rules, dictionaries, and feature flags.

Update product configuration

The Reports APIs enable the generation and management of custom reports within the system. Users can create, retrieve, and analyze reports based on various parameters such as time periods, user actions, and system events, helping to inform business decisions.

Reports

Retrieve all available reports with pagination.

**Query Parameters:**

| Name | In | Type | Required | Description | Example |
|------|----|------|----------|-------------|---------|
| page | query | integer | No | Page number (0-based) | 0 |
| size | query | integer | No | Page size | 20 |
| type | query | string | No | Filter by report type | LEAD_ANALYTICS |


Get all reports

Generate a new report based on specified parameters.

**Request Body Fields:**

| Field | Type | Required | Description | Example |
|-------|------|----------|-------------|---------|
| name | string | Yes | Report name | Monthly Lead Report |
| type | string | Yes | Report type | LEAD_ANALYTICS |
| parameters | object | Yes | Report parameters | See example |


Generate new report

Retrieve a specific report by its ID.

**Request Parameters:**

| Name | In | Type | Required | Description | Example |
|------|----|------|----------|-------------|---------|
| reportId | path | string | Yes | Report identifier | report-123 |


Get report by ID

Delete a report from the system.

**Request Parameters:**

| Name | In | Type | Required | Description | Example |
|------|----|------|----------|-------------|---------|
| reportId | path | string | Yes | Report identifier | report-123 |


Delete report

Download a generated report in the specified format.

**Request Parameters:**

| Name | In | Type | Required | Description | Example |
|------|----|------|----------|-------------|---------|
| reportId | path | string | Yes | Report identifier | report-123 |
| format | query | string | No | Download format | PDF |


Download report

The Documents APIs manage the storage and retrieval of documents within the system. Users can upload, download, and manage documents related to leads, products, or other entities, facilitating efficient document management and retrieval.

Documents

Retrieve documents with pagination and filtering options.

**Query Parameters:**

| Name | In | Type | Required | Description | Example |
|------|----|------|----------|-------------|---------|
| page | query | integer | No | Page number (0-based) | 0 |
| size | query | integer | No | Page size | 20 |
| type | query | string | No | Filter by document type | CONTRACT |
| leadId | query | string | No | Filter by lead ID | lead-123 |


Get documents

Upload a new document to the system.

Supports multipart file uploads with optional folder and metadata.
Metadata can be provided as JSON.

**Form Fields (multipart/form-data):**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| file | file (binary) | Yes | Document file to upload |
| type | string | No | Document type (e.g., CONTRACT, IDENTITY_PROOF) |
| folder | string | No | Target storage folder/path |
| metadata | object | No | Arbitrary metadata (sent as JSON) |
| leadId | string | No | Associated lead ID |
| description | string | No | Document description |


Upload document

Retrieve a specific document by its ID.

**Request Parameters:**

| Name | In | Type | Required | Description | Example |
|------|----|------|----------|-------------|---------|
| documentId | path | string | Yes | Document identifier | doc-123 |


Get document by ID

Update an existing document. Supports either updating metadata via JSON
or replacing the file via multipart/form-data.

**Request Parameters:**

| Name | In | Type | Required | Description | Example |
|------|----|------|----------|-------------|---------|
| documentId | path | string | Yes | Document identifier | doc-123 |


Update document (file or metadata)

Delete a document from the system.

**Request Parameters:**

| Name | In | Type | Required | Description | Example |
|------|----|------|----------|-------------|---------|
| documentId | path | string | Yes | Document identifier | doc-123 |


Delete document

Download the actual document file.

**Request Parameters:**

| Name | In | Type | Required | Description | Example |
|------|----|------|----------|-------------|---------|
| documentId | path | string | Yes | Document identifier | doc-123 |


Download document

Default

Lead management system

Lead Service

UAM Service

Config Service

Notify Service

Report Service

<p class="slate-p " >The Reports APIs enable the generation and management of custom reports within the system. Users can create, retrieve, and analyze reports based on various parameters such as time periods, user actions, and system events, helping to inform business decisions.</p><p class="slate-p " ></p>

Sections

Download report

Header Parameters

Query Parameters

Path Parameters

Response

Response

Name	In	Type	Required	Description	Example
reportId	path	string	Yes	Report identifier	report-123
format	query	string	No	Download format	PDF