Opta API and Webhook Integration for Lead Sources

Before You Start

Your client (the Opta customer) will send you a URL with posting instructions specific to your campaign and source. These include your unique credentials, endpoint, required fields, and any campaign-level requirements like schedule windows, accepted zip codes, or accepted states.

Every campaign has its own posting instructions per source. If you're posting to multiple campaigns, you'll receive separate instructions for each. Required and optional fields may vary by customer and campaign.

Your posting instructions also include an Ask AI button in the top right corner. Use it to ask questions about your specific integration directly within the document.

Posting Methods

There are two ways to send leads to Opta: the JSON API (preferred) or a webhook.

JSON API (Preferred)

The JSON API is a structured POST request with a JSON payload. This is the preferred method for most integrations. Your posting instructions will include:

Endpoint (e.g., https://app.opta.io/ca/submit)
Headers including Content-Type: application/json (required) and Accept: application/json (optional)
Required fields with hardcoded values for your company ID, source ID, campaign ID, and authentication key
Lead fields like first name, last name, email, phone, address, city, state, and zip (may vary by customer)

Example request:

json

{   "compid": "YOUR_COMPANY_ID",   "sourceid": "YOUR_SOURCE_ID",   "campid": "YOUR_CAMPAIGN_ID",   "auth": "YOUR_AUTH_KEY",   "first": "John",   "last": "Doe",   "email": "[email protected]",   "phone": "5551234567",   "address": "123 Main St",   "city": "Los Angeles",   "state": "CA",   "zip": "90210",   "test": "true" }

Your posting instructions will list the exact field names, parameters, types, and descriptions for your specific campaign.

Webhook

The webhook method is best if your system can't send structured posts with specific parameter names, or if you're connecting a form. Your posting instructions will include a unique webhook URL (e.g., https://app.opta.io/webhook/your-unique-id) and a list of required fields.

With the webhook method, you send a test lead using your own parameter names. The Opta customer will then map your fields to theirs after receiving the test.

Setup steps:

Send a test request with sample data to your webhook URL using your own parameter names.
The Opta customer maps your fields after receiving the test.
Once mapping is complete, you're ready to send live leads.

Campaign Requirements

Your posting instructions include any requirements your leads must meet to be accepted. Leads that don't match will be rejected automatically. Requirements can include:

Schedule (e.g., Monday through Friday, 9 AM to 5 PM PT). Leads sent outside the schedule window will be rejected.
Zip codes with an include or exclude list. A downloadable CSV is available in your posting instructions.
States with an include or exclude list.

Check the Requirements tab of your posting instructions for the full list.

Sending Test Leads

Always send a test lead before going live. Set the test field to "true" in your payload.

Important: Always set test to "true" when testing. Test leads stop in Opta and do not post through to the customer's CRM, dialer, or any other downstream system. This prevents contacting leads who didn't give consent. Test leads also do not affect customer reporting. Never send test data without setting test to "true".

A successful test response looks like this:

json

{   "leadStatus": true,   "reason": "Test lead accepted. Update test=false once approved.",   "message": "",   "price": 0.00,   "testLead": true }

If your test is accepted, your client will confirm and approve you to go live. Once approved, change test to "false" to start sending live leads.

If you're using the JSON API, you can also use the built-in test form in your posting instructions under the Testing tab. Enter sample data and submit to see the response directly.

Webhook Test Success

json

{   "message": "Test webhook received successfully." }

Your webhook test was received. The Opta customer will map your fields and confirm when you're ready to go live.

Understanding Responses

All responses return a JSON object with the same structure.

Live Lead Accepted

json

{   "leadStatus": true,   "reason": "",   "message": "Success Lead = Accepted",   "price": 0.00 }

The lead passed all rules and was delivered. Use "leadStatus": true to track accepted leads in your system.

Lead Rejected

json

{   "leadStatus": false,   "reason": "Opta Reject",   "message": "Duplicate email",   "price": 0.00 }

The lead was rejected. The message field tells you why. See the full list of rejection reasons below.

Going Live Checklist

Confirm you received your posting instructions URL from your client.
Review the campaign requirements (schedule, zip codes, states).
Send a test lead with test set to "true".
Verify you received a successful test response ("leadStatus": true with "testLead": true, or "Test webhook received successfully." for webhooks).
Wait for your client to approve you.
Change test to "false" and begin sending live leads.

Need Help?

Reach out to your client (the Opta customer) for questions about your posting instructions, campaign requirements, or integration setup. You can also use the Ask AI button in your posting instructions to get answers about your specific integration.

Rejection Reasons

Here are the rejection reasons you may see in the message field of a rejected response.

Missing or Invalid Data

Reason	What it means
Missing {fields}	One or more required fields were not included or were empty (e.g., `Missing zip`).
Email format	The email address is not in a valid format.
Phone format	The phone number is not in a valid format.
Zip format	The zip code is not in a valid format.
URL format	A URL field is not in a valid format.
Email verification	The email address failed verification.
Address verification	The address failed verification.
Phone blocked	The phone number is blocked.
Email blocked	The email address is blocked.
Non-US IP	The lead's IP address is not from the US.
IP verification	The lead's IP address failed verification.

Targeting and Filters

Reason	What it means
State targeting	The lead's state is not in the campaign's accepted states.
Zip targeting	The lead's zip code is not in the campaign's accepted zip codes.
Condition: {filter-name}	The lead was rejected by a campaign condition.
Filter: {filter-name}	The lead was rejected by a campaign filter.

Duplicates

Reason	What it means
Duplicate email	The lead's email was already received within the duplicate detection window.
Duplicate phone	The lead's phone was already received within the duplicate detection window.

Budget and Schedule

Reason	What it means
{Period} cap	The source has hit its budget cap for the specified period (day, week, month, or total).
Campaign cap	The campaign has hit its overall budget cap.
Campaign schedule	The lead was sent outside the campaign's active hours.
Campaign period	The lead was sent outside the campaign's active date range.
Campaign inactive	The campaign is currently inactive.

Source and Authentication

Reason	What it means
Invalid source	The source ID is not recognized or not approved for this campaign.
Invalid auth	The authentication key is incorrect.
SubID blocked	The Sub ID is blocked for this campaign.
AffID blocked	The Affiliate ID is blocked for this campaign.

Compliance

Reason	What it means
Missing TrustedForm/Jornaya	A TrustedForm or Jornaya certificate is required but was not included.
TrustedForm format	The TrustedForm certificate URL is not in the correct format.
Jornaya format	The Jornaya token is not in the correct format.

What is Opta and how does it work?

How to Set Up and Manage Lead Sources