> ## Documentation Index
> Fetch the complete documentation index at: https://docs.introw.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Nudge partners at scale via the API
> Post comments on partners, deals, tasks, submissions, and payouts from your own systems or an agent to nudge partners on the channels they already use.
> The reason partners go quiet is rarely that nobody knew. The signal is usually sitting in a query somewhere: this deal has not moved in three weeks, this certification lapsed, this order form was never signed. What is missing is a way to turn that signal into a nudge that reaches the partner without somebody writing the message.
The [Create a comment](/general/collaboration-overview) endpoint is that path. One call posts a comment on a partner, a deal, a task, a submission, or a payout, and the partner is notified through whichever channel they already use, email, Slack, or Microsoft Teams. Ten thousand partners is ten thousand calls, not ten thousand emails.
## What you'll achieve
Any system, script, or agent in your stack able to follow up with partners on the record itself, attributed to a real person on your team, notifying the partner where they already work, and with the reply landing back in the same thread.
## Before you start
Create an API key with the **Collaboration - Write** permission. See [Create and manage API keys](./create-and-manage-api-keys).
Comments are posted as a real person, not as "the system". Pick the team member the follow-up should appear to come from, usually the partner manager, and have their email ready.
A non-internal comment notifies the partner through the channels you have configured. Confirm those are the channels you want before you send at volume, see [Control who gets notified](/features/engagement/notifications/guides/control-who-gets-notified).
## Watch it
## Steps
### Post your first comment
Every comment lands on a partner's timeline. What you additionally target decides which record it hangs off: a deal or ticket (`crmObjectId` + `crmObjectType`), a task (`taskId`), a form submission (`formSubmissionId`), a commission payout (`commissionPayoutId`), or the partner alone (`partnerId`). Pass at least one.
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://api.introw.io/api/v1/comments" \
-H "x-api-key: $INTROW_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"comment": "This deal has been in **Proposal** for 21 days. Can you confirm the next step before Friday?",
"authorEmail": "alex@vendor.example",
"crmObjectId": "9840193344",
"crmObjectType": "DEAL"
}'
```
You never pass a room or a portal id. The collaboration space is resolved from the target for you.
`crmObjectType` is case-insensitive and takes whatever your CRM calls the object, so a Salesforce query can forward `Opportunity`, `Account`, or `Case` straight through and a HubSpot one can send `Deal`, `Company`, or `Ticket`. Introw resolves them to the same records, which means no type mapping in your script. Only custom objects need their exact API name, such as `Partner_Program__c`, because there is no standard equivalent to translate to.
`comment` accepts Markdown, and the formatting carries onto the partner portal timeline: `**bold**`, `*italic*`, `[links](url)`, blank-line paragraphs, and `-` or `1.` lists. HTML fragments are accepted too, so content you already generate can be forwarded as-is. A short, specific ask outperforms a templated reminder, and Markdown is what lets you write one.
The response returns a `threadId`. Pass it back as `threadId` on your next call and the follow-up joins the same thread instead of starting a new one, so a chase sequence reads as one conversation rather than four disconnected pings.
### Attribute it to the right partner
`partnerId` accepts the Introw partner id **or** the partner's CRM external id, so you can drive the loop straight off your CRM export without a mapping table.
When you target a deal or ticket that is already attributed to a partner, you can omit `partnerId` entirely. If the object is not attributed, the call returns `422 CRM_OBJECT_NOT_LINKED`, so pass `partnerId` explicitly for those.
### Keep a comment to your own team
Send `"isInternal": true` and the comment stays on the record for your team only: hidden from every partner-facing surface and silent on notifications. Use it when your systems should annotate a record without talking to the partner, for example writing a risk score or a churn signal onto the deal.
Internal comments require `authorEmail` to be one of **your** team members. A partner portal member can never author one. A comment on a payout the partner cannot see yet is kept internal automatically, whatever you send, so figures never leak ahead of the release.
## Patterns worth copying
Query the deals that broke your own definition of stalled (stage age, missing next step, no activity), then post one comment per deal targeting `crmObjectId`. Because the nudge lands on the deal, the partner opens the deal to reply, not an inbox. When your rule is simply "days in stage", the no-code [Sleeping deal notification](/features/engagement/notifications/guides/nudge-stalled-deals) already does this without any code, so reach for the API when the rule is yours.
An agent that reviews your pipeline can decide who needs a nudge and post the comment itself, as a named team member, with the reply visible to that human in the same thread. The judgment is automated; the accountability is not. Pair it with [Introw's MCP server](/features/developer/mcp) when you want the agent reading Introw as well as writing to it.
Right after [submitting a form via the API](/features/forms/sharing-submitting/guides/submit-a-form-via-the-api), pass the returned submission id as `formSubmissionId` and comment with what happens next and by when. Partners stop asking whether the registration arrived, and the SLA is on the record.
Have your billing system comment on the payout when it is scheduled (`commissionPayoutId`), and your provisioning system comment on the deal when the account goes live. The partner hears it from the record they already track, instead of a status email from a system they have never heard of.
Target `taskId` to chase an overdue onboarding step, or `partnerId` to reach a partner whose certification is about to lapse. Same call, different target.
## Verify it worked
Open the partner in [Partners](https://app.introw.io/partners) and check their timeline: the comment is there, attributed to the person in `authorEmail`, with your Markdown rendered. On the partner side it appears on the record in their portal and arrives on their configured channel. A comment sent with `isInternal` shows on your timeline marked internal and nowhere partner-facing.
## Limits & gotchas
This is a nudge API, not a logging API: every non-internal comment reaches a person, so treat volume as outbound volume. Comments cap at 20,000 characters and the endpoint takes no attachments. `authorEmail` must resolve to a team member or to a portal member of that same partner, otherwise the call returns `422 AUTHOR_NOT_FOUND`.
## Troubleshooting
* **`403 Forbidden`** - the key lacks `collaborate:write`.
* **`422 AUTHOR_NOT_FOUND`** - the email is not a team member, nor a portal member of the partner being commented on.
* **`422 INTERNAL_AUTHOR_FORBIDDEN`** - `isInternal` was set for a partner-side author.
* **`422 CRM_OBJECT_NOT_LINKED`** - the deal or ticket is not attributed to a partner. Send `partnerId` too.
* **`422 VALIDATION_ERROR`** - no target was sent, or `crmObjectId` came without `crmObjectType`.
* **The partner never heard about it** - check whether the comment came back with `isInternal: true`, and confirm their notification channel in [Channels](/features/engagement/channels).
## Related
The full request, response, target, and error reference.
The no-code version, configured on a pipeline.
The same thread, worked by hand in the app.
Create the submission you are commenting on.