Add SI Request

Queue a Segmentation Intelligence action for a contact

POST /apis/v2/public/crm/addSIRequest

Creates a Segmentation Intelligence request for a contact. SI requests are queued actions that tell SI to perform a specific engagement — such as sending a keep-warm email, triggering a form-based follow-up, or recording an engagement signal that influences future decisions.

Requires a valid `api_key` and `developer_secret` in the JSON request body. Requests must originate from a whitelisted IP address.

Parameters

Name	In	Type	Required	Description
`api_key`	body	`string`	Yes	Your Zyntro API key
`developer_secret`	body	`string`	Yes	Your developer secret (zdk_XXX). Issued during developer onboarding.
`org_id`	body	`string`	Yes	Your organization UUID
`contact_id`	body	`string`	Yes	The UUID of the contact to create the SI request for
`sir_flag`	body	`string`	Yes	The type of SI action to queue. Must be one of: `keep_warm`, `form_action_email`, `form_action_sms`, `form_action_call`, `engagement_signal`
`sir_context`	body	`string`	Yes	Context or description for the SI request. Helps SI understand the intent behind the action.
`sir_planned_dt`	body	`string`	Yes	When the action should be executed. Format: `YYYY-MM-DD HH:MM:SS`
`sir_channel`	body	`string`	Yes	The communication channel. Must be one of: `email`, `sms`, `phone`, `social-media`, `other`
`sir_status`	body	`string`	No	Initial status of the request. Default: `Pending`

Info: This endpoint does not require a `member_id` or `brand_id` — only `api_key`, `org_id`, and `contact_id` are needed for identity scoping.

SI Request Flags

Flag	What It Does	Example Use Case
`keep_warm`	Schedules a nurturing touchpoint to maintain engagement	A prospect has not been contacted in 14 days — queue a check-in email
`form_action_email`	Triggers an email action as a follow-up to a form submission	A lead filled out a pricing form — send them the pricing PDF
`form_action_sms`	Triggers an SMS action after a form submission	A webinar registrant signed up — send SMS confirmation
`form_action_call`	Triggers a call action after a form submission	A high-value lead requested a callback — queue an outbound call
`engagement_signal`	Records an external engagement signal that influences SI scoring	A contact attended an industry event — log it as a buying signal

Request Body

Content-Type: application/json

Example

json

{
    "org_id": "YOUR_ORG_ID",
    "api_key": "YOUR_API_KEY",
    "sir_flag": "keep_warm",
    "contact_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "sir_channel": "email",
    "sir_context": "Contact has not been engaged in 14 days. Send a personalized check-in email referencing their interest in the enterprise plan.",
    "sir_planned_dt": "2026-04-05 09:00:00",
    "developer_secret": "YOUR_DEVELOPER_SECRET"
}

Code Samples

bash

curl -X POST https://app.zyntrohq.com/apis/v2/public/crm/addSIRequest \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "developer_secret": "YOUR_DEVELOPER_SECRET",
    "org_id": "YOUR_ORG_ID",
    "contact_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "sir_flag": "keep_warm",
    "sir_context": "No engagement in 14 days. Send check-in email.",
    "sir_planned_dt": "2026-04-05 09:00:00",
    "sir_channel": "email"
  }'

Response

200 SI request created

json

{
    "data": {
        "sir_id": 456,
        "sir_flag": "keep_warm",
        "contact_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "sir_channel": "email",
        "sir_planned_dt": "2026-04-05 09:00:00"
    },
    "status": "success"
}

200 Error response

json

{
    "data": [
        "Missing or invalid sir_flag. Allowed: keep_warm, form_action_email, form_action_sms, form_action_call, engagement_signal"
    ],
    "status": "error"
}

Errors

Code	Message	Resolution
`MISSING_API_KEY`	Missing API Key The `api_key` field is missing.	Include your API key.
`INVALID_API_KEY`	Invalid API Key No active user matches the key.	Verify your key.
`IP_NOT_WHITELISTED`	IP address not whitelisted The request originated from an IP not in the key's allowed list.	Contact your client to add your IP to the developer key whitelist.
`INVALID_DEVELOPER_SECRET`	Invalid developer_secret The developer secret does not match any active key.	Verify your developer secret. If lost, have your client revoke and reissue the key.
`MISSING_DEVELOPER_SECRET`	Missing developer_secret The `developer_secret` field is missing or empty.	Include your developer secret in the request body. This is issued during developer onboarding.
`MISSING_FIELDS`	Missing org_id / contact_id / sir_context / sir_planned_dt A required field is missing.	Include all required fields.
`INVALID_FLAG`	Missing or invalid sir_flag The sir_flag value is not one of the allowed options.	Use: `keep_warm`, `form_action_email`, `form_action_sms`, `form_action_call`, or `engagement_signal`
`INVALID_CHANNEL`	Missing or invalid sir_channel The sir_channel value is not recognized.	Use: `email`, `sms`, `phone`, `social-media`, or `other`
`NOT_FOUND`	Contact not found in this organization No contact with that ID exists in the organization.	Verify the contact_id.

4 min read Updated May 26, 2026

Navigation

Add SI Request

Parameters

SI Request Flags

Request Body

Example

Code Samples

Response

Errors