Via API

To integrate your CRM with Patagon, we need you to provide access to your lead data through your API. This documentation describes the information we require and how we can consume it from your system.

Key Idea: Patagon needs to pull lead data from your CRM/API to process it within our platform.

How It Works

There are two main integration models:

Option 1 — Push (Client → Patagon)

• You send lead data directly to our endpoints

• We authenticate using your API Key

• We process and store the data inside Patagon’s CRM

Option 2 — Pull (Patagon → Client)

• You provide us with access to your API

• We periodically request new or updated leads

• We sync the data with our system

This documentation focuses on the information we need to receive from your system.

---

To Establish the Integration, We Need:

1. Access Information

• Your API endpoint(s) (base URLs)

• Authentication credentials (API Key, OAuth, JWT, etc.)

• API documentation (if available)

• Sandbox / staging environment (for initial testing)

2. Rate Limit Details

• Request limits per minute/hour

• Retry policy for errors

• Scheduled maintenance windows (if any)

3. Technical Contact

• Technical point of contact on your side

• Support channel (email, Slack, etc.)

---

Authentication & Security

Supported Authentication Methods

Patagon can connect to your system using:

Preferred:

• Bearer Token (API Key)

• OAuth 2.0 (Client Credentials or Authorization Code)

Also supported:

• Basic Authentication

• JWT (JSON Web Tokens)

• Custom Headers

Security Requirements

All connections must use HTTPS/TLS.

We will need to know:

• Authentication method used

• Token/credential format

• Token expiration time (if applicable)

• Token refresh workflow

Authentication Example

If your API uses a Bearer Token, our requests will follow this format:

GET https://seu-crm.com/api/v1/leads
Authorization: Bearer {TOKEN_PROVIDED_BY_YOU}

---

🔗 Endpoints We Need to Consume

To enable a complete integration, your API must expose the following endpoints:

1. List Leads (Required)

Endpoint to fetch leads, preferably with pagination and date filters.

GET /api/v1/leads

Recommended parameters:

• page or offset — Pagination control

• limit or per_page — Items per page

• updated_since — Filter by last update

• created_since — Filter by creation date

Example request:

GET /api/v1/leads?limit=100&updated_since=2025-10-28T00:00:00Z

2. Get Lead by ID (Recommended)

GET /api/v1/leads/{lead_id}

3. Webhooks for Notifications (Optional)

If your system supports webhooks, we can receive real-time notifications when:

• A new lead is created

• A lead is updated

• A lead is deleted

Expected format:

POST https://api.patagon.ai/webhooks/leads
Content-Type: application/json
{
  "event": "lead.created",
  "timestamp": "2025-10-28T13:20:41Z",
  "data": {
    "id": "lead_123",
    "tf_firstname": "Maria",
    ...
  }
}

Webhooks are optional but recommended for real-time sync.

---

🏷️ Field Mapping

Below are examples of fields Patagon needs to receive from your CRM. Field mapping will be finalized during the technical kickoff.

Field (External Name)	Patagon Internal Name	Type	Required	Description
First Name	tf_firstname	string	✅	Only the lead’s first name
Phone	phone	string	✅	Preferably E.164 format
Referrer	tf_referrer	string	❌	Who referred the lead
Objective / JTBD	rf_objective	enum/string	⚠️	Lead’s main goal
Gender	tf_gender	enum/string	❌	Gender identification
Age	tf_age	number	❌	Age in years (integer)

Don’t worry about naming conventions — we handle all field mapping.

Examples:

• first_name → tf_firstname

• contact_phone → phone

• goal → rf_objective

---

🛠️ 🛠️ Sample API Responses

Example 1: Lead List

Request:

GET /api/v1/leads?limit=2&updated_since=2025-10-28T00:00:00Z
Authorization: Bearer {your_token}

Expected Response:

{
  "data": [
    {
      "id": "lead_123",
      "first_name": "Maria",
      "phone": "[phone]",
      "goal": "Travel to the Moon",
      "gender": "Female",
      "age": 32,
      "referred_by": "Ana",
      "created_at": "2025-10-28T10:30:00Z",
      "updated_at": "2025-10-28T13:20:41Z"
    },
    {
      "id": "lead_456",
      "first_name": "João",
      "phone": "[phone]",
      "goal": "Other",
      "gender": null,
      "age": null,
      "referred_by": null,
      "created_at": "2025-10-28T11:15:00Z",
      "updated_at": "2025-10-28T11:15:00Z"
    }
  ],
  "pagination": {
    "total": 150,
    "page": 1,
    "per_page": 2,
    "next_page": 2
  }
}

Format may vary — as long as lead data and pagination info are present.

Example 2: Individual Lead

Request:

GET /api/v1/leads/lead_123
Authorization: Bearer {your_token}

Expected Response:

{
  "id": "lead_123",
  "first_name": "Maria",
  "phone": "[phone]",
  "goal": "Travel to the Moon",
  "gender": "Female",
  "age": 32,
  "referred_by": "Ana",
  "created_at": "2025-10-28T10:30:00Z",
  "updated_at": "2025-10-28T13:20:41Z"
}

---

🚫 Error Handling

A robust API integration depends on correct HTTP status codes. Here’s how we handle them:

Code	When to Use	How Patagon Handles It
200	Successful request	Process normally
400	Invalid parameters	Adjust parameters and retry
401	Authentication failure	Notify client to renew credentials
404	Resource not found	Log and skip
429	Rate limit exceeded	Wait and retry with exponential backoff
500–599	Server error	Automatic retry with backoff

---

Sensitive Data

Patagon is fully compliant with LGPD/GDPR. All received data is:

• Transmitted via HTTPS/TLS

• Stored with encryption

• Accessed only by authorized systems

• Retained according to the agreed privacy policy

---

FAQ — Frequently Asked Questions

How often will Patagon query our API?

The frequency is defined during the technical kickoff. It typically ranges from every 5 to 30 minutes, always respecting your API’s rate limits.

Do you store all data or only references?

We store the mapped fields required to process leads inside our CRM. All storage details are reviewed during the kickoff.

What happens if our API becomes unavailable?

We have an automatic retry system with alerts. Once your API is available again, synchronization resumes without intervention.

Do we need to build a new API?

No. If your CRM already provides an API, we can usually connect directly. If not, we can explore alternatives such as webhooks or iPaaS connectors.

How long does the integration take?

Typically 1–2 weeks after the technical kickoff, depending on the complexity of your setup.