Introductions API

Introduce a prospect to one of your advocates, the same as creating an introduction in the admin portal and pressing Send. The prospect gets your community’s introduction text right away, and when they reply, the conversation starts and appears in the Conversations API.

Requires the introductions:write permission.

Endpoint Returns
POST /api/v1/introductions Introduce a prospect to an advocate and send it

Create an introduction

Only these attributes are accepted; anything else is a 422 that names it.

Attribute Description
advocate_id The id of an active advocate, from the Advocates API.
prospect_id The id of a prospect with a phone number, from the Prospects API (create one first with POST /prospects if needed).
curl -X POST https://integrations.stokedhq.com/api/v1/introductions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{"data": {"type": "introductions", "attributes": {"advocate_id": "ADVOCATE_ID", "prospect_id": "PROSPECT_ID"}}}'

The response is 201 Created with the introduction: its id, status (active once sent), created_at, activated_at, and advocate and prospect relationships.

  • The text goes out at once. There is no draft step, so check the advocate before you send.
  • The prospect’s phone is marked verified. The introduction is a text, which only goes to a verified phone. As when an admin creates a prospect for an introduction, an unverified number is marked verified, recorded as verified by the API.
  • The introduction is credited to the admin who created the API key. If that admin has been deleted, the request is a 422; create a new key.
  • One introduction per pair. Introducing a prospect to an advocate they’ve already been introduced to is a 409, and meta.existing_id on the error is the existing introduction’s id.
  • An inactive or pending advocate, an unknown prospect, or a prospect without a phone number is a 422.

© 2024-2026 Stoked — Real conversations. Real trust.