Campaigns: Trigger
Enrolls one recipient in a published, active automated campaign.
The campaign must have an API entry that leads to Email content. Provide the campaign UUID in the URL and the exact Knowledge Graph Entity ID in entityId.
Set either recipient.details with an email address or recipient.contact with a saved contact's complete name. The saved contact must belong to the same account and Entity. Use createContact only with inline details and Contacts write permission.
A successful response means the enrollment was accepted and queued; it does not confirm delivery. Retry temporary failures with the same requestId and unchanged body, increasing the delay between attempts. An accepted identical request returns the original invocation. This API has no invocation or run polling endpoints.
Obtain API entry IDs and input definitions from the person who configured the campaign. Set entryNodeId when there are multiple API entries. Inputs must match that entry's definitions. Unknown request fields and multiple recipient modes are invalid.
Possible errors include:
- INVALID_ARGUMENT for invalid recipient, Entity, entry, or input values.
- FAILED_PRECONDITION for an inactive campaign or a required contact that cannot be used.
- ALREADY_EXISTS when an accepted request ID is reused with a different body.
- ABORTED when the campaign changes while the request is being accepted. Retry the unchanged request.
- UNAVAILABLE while campaign activation is pending or a required service is unavailable.
Authorizations:
path Parameters
| account required | string External account ID, or |
| campaign required | string Yext-assigned resource UUID. |
query Parameters
| v required | string^[0-9]{8}$ Default: "20240401" API version date in YYYYMMDD format. Use one fixed date for your integration; supply this parameter once per request. |
Request Body schema: application/json
| requestId required | string Lowercase UUID identifying this enrollment within the account and campaign. Reuse the ID and unchanged request body when retrying. Use a new ID to enroll the recipient again. |
required | object (v1ApiRecipient) |
| createContact | boolean Save an inline recipient as a contact. Requires Contacts write permission. Creates a contact or reuses an active contact with the same Entity and email. Existing profile values and preferences are retained. Archived matches are rejected. Supported only with recipient.details; defaults to false. |
| entryNodeId | string API entry ID provided by the person who configured the campaign. Required when the published campaign has multiple API entries. Otherwise optional. |
| inputs | object |
| entityId required | string Exact Entity ID from Knowledge Graph, sent as a string. Do not substitute a Yext-assigned numeric ID or a complete Entity resource name. |
Responses
Request samples
- Payload
{- "requestId": "9d4ea8f0-a932-4c44-a27c-6cae4ecf1793",
- "entityId": "branch-nyc-001",
- "recipient": {
- "details": {
- "emailAddress": "alex.rivera@example.com",
- "firstName": "Alex",
- "lastName": "Rivera"
}
}, - "createContact": false,
- "inputs": { }
}Response samples
- 200
- default
{- "meta": {
- "uuid": "7b4b7f0f-17cf-4bec-81b0-97a729f25e54",
- "errors": [ ]
}, - "response": {
- "name": "accounts/514581/campaigns/019a1234-5678-7000-8000-000000000004/invocations/019a1234-5678-7000-8000-000000000009",
- "requestId": "9d4ea8f0-a932-4c44-a27c-6cae4ecf1793",
- "campaignRevision": "accounts/514581/campaigns/019a1234-5678-7000-8000-000000000004/revisions/019a1234-5678-7000-8000-000000000010",
- "entryNodeId": "api_entry",
- "campaignRun": "accounts/514581/campaigns/019a1234-5678-7000-8000-000000000004/runs/019a1234-5678-7000-8000-000000000011",
- "participant": "accounts/514581/campaigns/019a1234-5678-7000-8000-000000000004/runs/019a1234-5678-7000-8000-000000000011/participants/019a1234-5678-7000-8000-000000000012",
- "createTime": "2026-10-26T15:30:00Z"
}
}