Submitting Contacts

Contacts enter VayaFlow through the submission API endpoint. When a contact is submitted, it goes through a multi-step processing pipeline.

API Submission

Submit a contact using the POST /api/v1/contacts/submit endpoint:

curl -X POST https://api.vayaflow.com/api/v1/contacts/submit \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "playbookId": "cmp_abc123",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane@example.com",
    "phone": "+15559876543",
    "address": {
      "street": "123 Main St",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "90210"
    }
  }'

Request Body

The schema uses strict validation — unknown fields are rejected.

Required Fields

Field	Type	Description
`playbookId`	string	The playbook to submit the contact to
`firstName`	string	Contact first name (trimmed, title-cased). Required for new contacts, optional when `contactId` is provided
`lastName`	string	Contact last name (trimmed, title-cased). Required for new contacts, optional when `contactId` is provided
`email`	string	Email address (lowercased). Required for new contacts, optional when `contactId` is provided
`phone`	string	Phone number, minimum 10 digits. Required for new contacts, optional when `contactId` is provided

Optional Fields

Field	Type	Description
`contactId`	string	Existing contact ID. When provided, the contact's existing data is used and the contact is re-submitted through the qualification engine. Contact fields become optional
`address`	object	See Address below
`dateOfBirth`	string	Format: `YYYY-MM-DD`
`country`	string	2-letter uppercase ISO code (e.g., `US`, `CA`)
`questionnaire`	object or array	See Questionnaire below. Defaults to `{}`
`customFields`	object	Arbitrary key-value pairs
`attribution`	object	See Attribution below
`compliance`	object	See Compliance below
`files`	array	See Files below
`isTest`	boolean	Flag as a test record (kept out of live lists, no pixel firing; do-not-contact and deduplication checks still run). Test-ness is never inferred from a name or email.
`timezone`	string	IANA timezone string (e.g., `America/New_York`)
`notes`	string	Free-text notes

Address

All address fields are required when address is provided, except unit and country.

Field	Type	Description
`street`	string	Street address
`unit`	string	Unit/apartment number (optional)
`city`	string	City
`state`	string	2-letter uppercase state code (e.g., `CA`, `NY`)
`zip`	string	5 or 9 digit ZIP code (e.g., `90210` or `90210-1234`)
`country`	string	2-letter uppercase ISO code. Defaults to `US` (optional)

Questionnaire

Accepts two formats:

Object format — keys are mapped to question labels via your field library. If a key doesn't exist in the library, the key name is used as the label.

{
  "dob": "1990-01-15",
  "injury_type": "car_accident"
}

Array format — you provide the question labels directly.

[
  { "key": "dob", "question": "Date of Birth", "answer": "1990-01-15" },
  { "key": "injury_type", "question": "Type of Injury", "answer": "car_accident" }
]

Field	Type	Description
`key`	string	Field identifier (required)
`question`	string	Display label for the field (required)
`answer`	any	The answer value (required)

Attribution

Track marketing source and ad platform data. The attribution structure mirrors the internal Contact type directly.

Field	Type	Description
`params`	object	All tracking parameters — UTMs, custom URL params, etc. Stored as-is on the contact. Defaults to `{}`
`captureUrl`	string	URL where the contact was captured
`referrer`	string	Referring URL
`ipAddress`	string	Contact's IP address (auto-captured from request if not provided)
`userAgent`	string	Contact's browser user agent (auto-captured from request if not provided)
`gclid`	string	Google Ads click ID
`gbraid`	string	Google Ads app click ID
`wbraid`	string	Google Ads web-to-app click ID
`fbclid`	string	Facebook click ID
`fbc`	string	Facebook browser cookie
`fbp`	string	Facebook pixel cookie
`ttclid`	string	TikTok click ID
`ttp`	string	TikTok pixel cookie
`msclkid`	string	Microsoft Ads click ID
`tblci`	string	Taboola click ID
`adPlatform`	string	Ad platform name (auto-detected from click IDs if not provided)
`capturePlatform`	string	Capture platform name

Example attribution object:

{
  "params": {
    "utm_source": "facebook",
    "utm_medium": "paid_social",
    "utm_campaign": "spring_2024",
    "custom_tracking_id": "abc123"
  },
  "fbclid": "fbclid_xyz789",
  "captureUrl": "https://example.com/landing"
}

Compliance

TCPA consent and verification data.

Field	Type	Description
`tcpaConsent`	boolean	Whether TCPA consent was given
`tcpaConsentTimestamp`	string	ISO 8601 datetime of consent
`tcpaConsentMethod`	string	One of: `checkbox`, `signature`, `sms_optin`, `voice_recording`
`tcpaLanguage`	string	TCPA consent language shown to the contact
`trustedFormCertId`	string	TrustedForm certificate ID
`trustedFormCertUrl`	string	TrustedForm certificate URL
`jornayaLeadId`	string	Jornaya LeadiD token
`privacyPolicyUrl`	string	Privacy policy URL shown to the contact
`termsUrl`	string	Terms of service URL shown to the contact
`customFields`	object	Additional compliance key-value data

Files

Attach file references to the contact.

Field	Type	Description
`sourceKey`	string	Identifier for the file source (required)
`fileUrl`	string	URL where the file is hosted (required)
`type`	string	File type/category
`metadata`	object	Additional file metadata

Processing Pipeline

When a contact is submitted, the qualification engine processes it through these steps:

Routing Rules — Evaluate which playbooks match the contact's data
Disqualification Conditionals — Check for hard DQ conditions (e.g., excluded states)
Dynamic Keys — Apply dynamic field transformations
Required Fields — Verify all required fields are present
Field Qualification — AI-powered validation of field values
Payload Building — Construct the delivery payload
Delivery — Send to the playbook's endpoints
Fallback — If rejected, try fallback playbooks

Response

A successful submission returns:

{
  "success": true,
  "contactId": "contact_abc123",
  "submissionId": "sub_def456",
  "submissionNumber": 1,
  "message": "Contact submitted for processing",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

The contact will be processed asynchronously. Use the Get Contact Details endpoint to check the status.

Submitting Contacts

On this page