Contact Lifecycle

A contact represents a person in the system. When a contact is submitted, it goes through a multi-step processing pipeline that evaluates, qualifies, and delivers it to the appropriate playbook endpoint.

Entry Points

Contacts enter VayaFlow through three paths:

• API Submission — External systems submit contacts via POST /api/v1/contacts/submit with contact data and a target playbook ID
• CSV Import — Bulk import contacts from a CSV file through the import wizard
• Manual Create — Add a single contact from the Contacts page using the Add Contact button (requires playbook, name, email, and phone)

API-submitted and manually-created contacts are processed through the qualification engine immediately. Imported contacts are created with a new status and are not automatically processed.

Contact vs. Submission

VayaFlow separates person-level data from delivery-attempt data:

• Contact — The person record. Contains contact info, questionnaire answers, notes, attribution, compliance data, and flags. One contact exists per person.
• Submission — A single delivery attempt. Contains the playbook snapshot, qualification result, routing decisions, posting result, and journey events. One contact can have multiple submissions (original + reposts).

This separation means a contact's contact info stays consistent even when reposted to different playbooks.

Processing Pipeline

When a contact is submitted via the API, the qualification engine processes it through these steps in order:

1. Routing Rules — Evaluate which playbooks match the contact's data based on configured conditions (e.g., state, age, questionnaire answers)
2. First Submission Actions — If the matched playbook has a pre-delivery action (voice AI, SMS, human review, webhook), the contact pauses at pending_action until the action completes
3. Disqualification Conditionals — Check for hard disqualification conditions (e.g., excluded states, age ranges)
4. Dynamic Keys — Apply field transformations and computed values before delivery
5. Required Fields — Verify all fields required by the delivery endpoint are present
6. Field Qualification — AI-powered validation of individual field values against endpoint requirements
7. Payload Building — Construct the delivery payload using the endpoint's field configuration
8. Delivery — Send the payload to the playbook's delivery endpoint(s)
9. Fallback — If delivery fails or the contact is rejected, try configured fallback playbooks

Status Flow

A typical contact progresses through statuses like this:

new/pending → processing → qualified → delivered → accepted

With first submission actions:

pending → processing → pending_action → [voice/sms interaction] → qualified → delivered

With fallback:

pending → processing → qualified → failed → [fallback] → delivered

See Contact Statuses for the complete status reference.

Deduplication

When a contact is submitted, VayaFlow checks for existing contacts with the same email or phone number. If a match is found:

• The contact is flagged with isDuplicate: true
• The duplicate status may be set depending on playbook configuration
• Deduplication is checked within the playbook scope

Reposting

A contact can be reposted to a different playbook after its initial submission. Reposting creates a new submission under the same contact record. The contact tracks all playbooks it has been submitted to in the repostedTo array.

Reposting can be triggered:

• Manually — From the contact detail page via the Repost action
• Automatically — Via fallback playbook configuration when initial delivery fails
• Via API — Using the POST /api/v1/contacts/{contactId}/repost endpoint