External leads API Reference

Read lead delivery status

external_leads.delivery_statusread

Read the durable receipt for one external lead delivery, including contact id, attempts, controlled tags, timestamps and the latest bounded error. Read-only; sends nothing and changes nothing.

Parameters

Field	Type	Required	Description
provider	string	required	Stable lowercase integration slug, for example `trueshine`.
external_id	string	required	Stable lead id from the source system. Reuse it unchanged on every retry.

Example

curl -X POST https://app.chirply.io/api/v1/actions/external_leads.delivery_status \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "example",
    "external_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'

Test with your API key

Over MCP the same operation is the tool external_leads_delivery_status at https://app.chirply.io/api/mcp, same bearer token, same input.

Deliver external lead

external_leads.ingestwriteconfirm

Idempotently create or enrich one CRM lead from an authenticated external website. The provider plus external_id is a permanent delivery key: an identical retry returns the original receipt, while a changed payload is refused. Identity is deduplicated by email and normalized phone. Controlled site, form, service and channel tags are attached. This does not itself send email or SMS, but contact/tag automations already active in the account may run and can send real messages at the account's provider cost.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

Field	Type	Required	Description
provider	string	required	Stable lowercase integration slug, for example `trueshine`.
external_id	string	required	Stable lead id from the source system. Reuse it unchanged on every retry.
first_name	string	optional	Lead's given name, when known.
last_name	string	optional	Lead's family name, when known.
email	string (email)	optional	Lead email address. Used for deduplication before phone.
phone	string	optional	Lead phone number. Normalized before deduplication.
address	map of string → string	optional	Structured postal address fields such as line1, city, region and postal_code.
notes	string	optional	Human-readable project summary stored on a newly created contact.
attribution	map of string → string	optional	Sanitized first/last-touch attribution: UTM fields, click ids, landing paths, referrer hosts and timestamps. Default: {}
context	map of string → object	optional	Structured lead details such as form kind, service, budget, design choice and preferred contact method. Default: {}
tags	object	required	Bounded tag dimensions. Campaign names and click ids belong in attribution, not tags.
tags.site	string	required	Site slug used for the controlled Site tag, such as `true-shine`.
tags.form	string	required	Form slug used for the controlled Form tag, such as `instant-estimate`.
tags.service	string	optional	Optional service slug used for the controlled Service tag.
tags.channel	string	optional	Optional acquisition channel slug used for the controlled Channel tag.
consent	object	optional	Structured consent evidence. A CRM tag is never treated as consent.
consent.sms_marketing	boolean	required	Whether the person affirmatively opted into SMS marketing.
consent.captured_at	string (date-time)	optional	When consent was captured. Required when sms_marketing is true.
consent.disclosure_version	string	optional	Version or identifier of the disclosure shown to the person.

Example

curl -X POST https://app.chirply.io/api/v1/actions/external_leads.ingest \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "example",
    "external_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "tags": {
      "site": "example",
      "form": "example"
    }
  }'

Test with your API key

Over MCP the same operation is the tool external_leads_ingest at https://app.chirply.io/api/mcp, same bearer token, same input.