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, andmeta.existing_idon the error is the existing introduction’sid. - An inactive or pending advocate, an unknown prospect, or a prospect without a phone number is a
422.