Skip to main content
PATCH
/
api
/
signals
/
leads
Update Signal Leads
curl --request PATCH \
  --url https://app.puffle.ai/api/signals/leads \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "items": [
    {
      "entityId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ]
}
'
{
  "updated": [
    "<string>"
  ],
  "errors": [
    {
      "id": "<string>",
      "error": "<string>"
    }
  ]
}
CLI: 
puffle signal lead update --items <items>

​
Overview

Sets the workflow status (new, contacted, dismissed) on one or more signal-derived entities (people or companies). The status is tracked per entity and is shared across every signal that references that entity, so updating once moves the lead’s state everywhere it appears. Use this when a user marks a lead as contacted after sending outreach or dismisses an entity from their funnel.

​
AI agent notes

Pass { items: [{ entityId, status }] }. entityId is the resolved entity UUID surfaced as entityId / personEntityId on the signal row and as the row id on GET /api/signals/leads. The response splits into updated (entity ids that succeeded) and errors (per-id failures — typically not_found for unknown or foreign ids).Status semantics. new is the default for fresh leads, contacted after outreach is sent, dismissed to remove from active workflows. Transitions are unrestricted — set any status from any prior state. There is no responded value: we have no inbox/reply-detection hook, so the status would be misleading.Cross-signal effect. Setting status on an entity surfaces as entityStatus / personEntityStatus on every signal returned by GET /api/signals that references the same entity.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
items
object[]
required
Required array length: 1 - 200 elements

Response

Per-item update outcomes.

​
updated
string[]
required
​
errors
object[]