bc-marketing-manage-form-entries

name: bc-marketing-manage-form-entries description: Use when staff search, filter, update, delete, or re-process existing academy FormEntry leads; do NOT use for creating leads, debugging storage_status failures, or public capture flows. requires: - breathecode-staff-api-index

Skill: Manage FormEntry Leads (Staff)

When to Use

• Use for searching, reading, updating, deleting, or re-processing existing academy FormEntry records.
• Use for listing won deals (GET /v1/marketing/academy/lead/won).
• Do NOT use for creating new leads — load bc-marketing-create-form-entry.
• Do NOT use for diagnosing storage_status / CRM failures — load bc-marketing-debug-form-entry.
• Do NOT use for attribution funnel analytics — load bc-monitoring-read-report-acquisition.

Concepts

• Field semantics (location, tags, automations, custom_fields, CRM requirements) live in bc-marketing-create-form-entry.
• storage_status diagnosis and retry guidance live in bc-marketing-debug-form-entry.
• When ActiveCampaign double sync is enabled, deal_status and ac_deal_* fields on GET may reflect salesperson CRM activity via reverse webhooks — not only staff PUT updates.
• Staff PUT triggers form_entry.changed platform webhook but does not auto re-push to CRM. Use process to retry CRM sync.

Workflow

1. Set headers on all /academy/ routes: Authorization: Token <token>, Academy: <academy_id>, optional Accept-Language (en, es) for translated errors.

2. Search or list leads with filters (GET /v1/marketing/academy/lead). Use start and end for date windows on created_at. Save lead id values from results.

3. Get one lead by id (GET /v1/marketing/academy/lead/<id>). Use FormEntryBigSerializer response for full diagnostics (storage_status, storage_status_text, ac_contact_id, ac_deal_*, deal_status).

4. Update lead fields (PUT /v1/marketing/academy/lead/<id> or PUT /v1/marketing/academy/lead?id=<id>). Does not auto-call CRM. If storage_status=ERROR, fix fields then go to Step 5.

5. Re-process CRM sync (PUT /v1/marketing/academy/lead/process?id=<id>). Use after fixing data or for staff-created leads that were never processed. Add sync=true to process immediately and return storage_status in the response (default is async queue). See debug skill for when not to call process (DUPLICATED).

6. Delete leads in bulk (DELETE /v1/marketing/academy/lead?id=<id1>,<id2>). Requires id query param.

7. List won leads (GET /v1/marketing/academy/lead/won) with read_won_lead capability. Supports same date and filter params as the main list.

Endpoints

All endpoints below require Authorization, Academy, and optional Accept-Language. Paths contain /academy/.

List filters

Example request — list leads by date and status

GET /v1/marketing/academy/lead?start=2026-04-01&end=2026-04-08&storage_status=ERROR&limit=20&offset=0
Authorization: Token <token>
Academy: 4

Example response — paginated list (subset)

{
  "count": 3,
  "first": null,
  "next": null,
  "previous": null,
  "last": null,
  "results": [
    {
      "id": 219384,
      "first_name": "Lucia",
      "last_name": "Mendez",
      "email": "lucia@example.com",
      "phone": "+34600000000",
      "course": "full-stack",
      "location": "barcelona-spain",
      "storage_status": "ERROR",
      "storage_status_text": "You need to specify tags for this entry",
      "deal_status": null,
      "created_at": "2026-04-03T15:29:11.532Z"
    }
  ]
}

Example request — get one lead

GET /v1/marketing/academy/lead/219384
Authorization: Token <token>
Academy: 4

Example response — single lead (subset)

{
  "id": 219384,
  "first_name": "Lucia",
  "last_name": "Mendez",
  "email": "lucia@example.com",
  "phone": "+34600000000",
  "course": "full-stack",
  "location": "barcelona-spain",
  "tags": "website-lead",
  "storage_status": "ERROR",
  "storage_status_text": "You need to specify tags for this entry",
  "ac_contact_id": null,
  "ac_deal_id": null,
  "deal_status": null,
  "won_at": null,
  "referral_key": "partner-acme-01",
  "utm_source": "facebook",
  "utm_campaign": "barcelona-bootcamp-q2",
  "custom_fields": {},
  "created_at": "2026-04-03T15:29:11.532Z",
  "updated_at": "2026-04-03T15:29:12.100Z"
}

Example request — update lead (fix tags before retry)

PUT /v1/marketing/academy/lead/219384
Authorization: Token <token>
Academy: 4
Content-Type: application/json

{
  "tags": "website-lead",
  "course": "full-stack"
}

Example response — update

Same shape as get-one response with updated fields.

Example request — re-process CRM

PUT /v1/marketing/academy/lead/process?id=219384
Authorization: Token <token>
Academy: 4

Example response — process queued

{
  "details": "1 leads added to the processing queue"
}

Poll GET /v1/marketing/academy/lead/219384 until storage_status is PERSISTED, DUPLICATED, or stable ERROR (skip polling when sync=true was used).

Example request — re-process CRM synchronously

PUT /v1/marketing/academy/lead/process?id=219384&sync=true
Authorization: Token <token>
Academy: 4

Example response — process sync

{
  "details": "1 leads processed",
  "results": [
    {
      "id": 219384,
      "storage_status": "PERSISTED",
      "storage_status_text": ""
    }
  ]
}

Example request — delete leads

DELETE /v1/marketing/academy/lead?id=219384,219385
Authorization: Token <token>
Academy: 4

Returns 204 No Content on success.

Example request — list won leads

GET /v1/marketing/academy/lead/won?start=2026-04-01&end=2026-04-30
Authorization: Token <token>
Academy: 4

Paginated list of leads with deal_status=WON.

Edge Cases

• Invalid filter values: returns empty results — do not assume a bug; verify filter spelling and academy scope.
• GET one wrong id: returns 404 with lead-not-found.
• PUT wrong id in bulk: returns 400 with lead-not-found if no matches.
• Delete without ?id=: returns 400 — bulk delete requires query param ids.
• storage_status=ERROR: load debug skill; read storage_status_text, fix fields, then process.
• storage_status=DUPLICATED: do not call process — intentional dedup within ~30 minutes.
• Date filter end caveat: end=2026-04-07 excludes leads created after midnight on April 7; use end=2026-04-08 to include all of April 7.

Checklist

1. Sent Authorization and Academy headers on every request.
2. Used correct date params (start/end, not started_at/ended_at).
3. Applied end date midnight caveat when filtering by last day.
4. Retrieved lead id before update, process, or delete.
5. Called process after staff create or after fixing ERROR leads (unless DUPLICATED).
6. Loaded debug skill if storage_status did not reach expected terminal state after process.