Leads & schedules

Overview

The capture resources expose two independent GET contracts. Leads returns contacts captured in forms and landing pages; Schedules returns appointment requests by unit. Both are read-only — there is no create, update or delete through this API — and share the same pagination, sorting and date rules.

General rules

Conventions shared by both capture resources. Base URL in the examples: /api2. Every query requires Authorization: Bearer {{token}}.

• Filters accept query string or JSON body on GET. When the same field exists in both, the query string value wins.
• Text filters (email, phone, name) are exact-match, case-insensitive. There is no partial search.
• Default pagination: page=1, limit=20. Max limit: 200. Use include_pagination=1 to receive total, last_page and has_next in the body.
• Dates use YYYY-MM-DD or YYYY-MM-DD HH:MM:SS. Invalid formats return 400.
• Sorting: use sort and direction (asc or desc). Default: sort=created_at, direction=desc.
• A lookup by id returns a single record; when there is no match, the response is 404.

Leads

Query of contacts captured in forms, landing pages and campaigns, with attribution data (UTMs), origin and linked coupon.

GET /api2/leads?page=1&limit=50&include_pagination=1&created_from=2026-06-01&created_to=2026-06-30&sort=created_at&direction=desc
Authorization: Bearer {{token}}

{
  "success": true,
  "page": 1,
  "limit": 50,
  "total": 1,
  "last_page": 1,
  "has_next": false,
  "leads": [
    {
      "id": 123,
      "store_id": 10,
      "name": "Maria Silva",
      "email": "[email protected]",
      "phone": "11999999999",
      "created_at": "2026-06-20 14:30:00",
      "utm_source": "google",
      "utm_medium": "cpc",
      "utm_campaign": "avaliacao",
      "utm_term": null,
      "utm_content": null,
      "origin": "landing_page",
      "coupon_id": 5,
      "coupon_used": "CAMPANHA_123",
      "promoters_name": "Promotor A"
    }
  ]
}

GET /api2/leads?id=123
Authorization: Bearer {{token}}

Schedules

Query of appointment requests by unit, with date and time, requested treatment, attribution (UTMs) and sync status with external systems. Available at /api2/schedules and the Portuguese alias /api2/agendamentos — both with the same contract.

GET /api2/schedules?page=1&limit=50&include_pagination=1&date_from=2026-06-01&date_to=2026-06-30&status_gester=1,3
Authorization: Bearer {{token}}

{
  "success": true,
  "page": 1,
  "limit": 50,
  "total": 1,
  "last_page": 1,
  "has_next": false,
  "schedules": [
    {
      "id": 456,
      "name": "Ana Costa",
      "email": "[email protected]",
      "phone": "11988888888",
      "date": "2026-06-25",
      "time": "15:00",
      "unity_id": 10,
      "treatment": "Free evaluation",
      "created_at": "2026-06-20 16:10:00",
      "utm_source": "instagram",
      "utm_medium": "social",
      "utm_campaign": "agenda",
      "utm_term": null,
      "utm_content": null,
      "origin": "C",
      "campanha_interna": "https://example.com/lp",
      "campanha_interna_id": null,
      "codigo_gester": "ABC123",
      "status_gester": 2,
      "status_gester_label": "Synced",
      "mensagem_erro_gester": null
    }
  ]
}

GET /api2/schedules?id=456
Authorization: Bearer {{token}}

Schedule sync status

The status_gester field reflects the schedule's sync stage with the external system. The status_gester_label field carries the human-readable description and mensagem_erro_gester details the failure when present.

Supported usage patterns

Tested and certified combinations for leads and schedules.

Integration recommendations

Consolidated best practices for n8n, CRM and BI flows that sync captures with the Yep Platform.

Recommended

• Use include_pagination=1 when the flow needs to iterate pages until has_next=false.
• For incremental loads, prefer windows by created_from/created_to and store the last processed timestamp in the flow itself to avoid duplicates.
• Combine limit=100 + include_pagination=1 + sort=created_at&direction=asc to paginate with a predictable stop criterion and order.
• Use store_id (leads) or unity_id (schedules) for deterministic results in multi-unit operations.

Avoid

• Expecting partial search by name, e-mail or phone — text filters are exact-match.
• Trying to create, update or delete captures through this API — the endpoints are read-only.
• Relying on implicit ordering across pages — always provide sort and direction.

Common errors