API Call Flow

Buyer API – Call Flow

This document provides a complete overview of the Buyer API workflow to create, configure, validate, and launch a survey project (Job) on InnovateMR.

This is a project-driven integration, where your system is responsible for setting up demand, and InnovateMR handles respondent supply and delivery.

Overview

The Buyer API flow consists of the following major stages:

Job Creation (Project Setup)

Group Creation (Segmentation)

Targeting Setup

Quota Setup

Feasibility Validation

Project Launch (Go Live)

Monitoring & Optimization

End-to-End Flow

1. Create Job

API: Create Job

Create a new project (job) which acts as the top-level entity for the entire survey setup.
Key required fields include Name (Job Name), Project Manager / Sales Representative details, Start & End Dates, and Project Status.
Additional configurations like fingerprinting, duplicate checks (IP/PID), and security settings can also defined at this stage.

2. Create Group

API: Create Group

Create a group under a job to define a survey segment with its own targeting and quotas.
Key required fields include Group Name, sample size (N), Incidence Rate, LOI, Estimated Cost, Country, and Survey URLs (Live/Test).
You also define basic targeting like country, language, and device type at this stage.

3. (Optional) Fetch Metadata

API: Metadata / Mapping APIs

Retrieve platform-level metadata such as countries, languages, job types, group types, device types, and survey statuses required for configuration.
These values are used for mapping and standardizing inputs across job, group, and targeting setup.
This step ensures your system aligns with InnovateMR’s accepted values before applying targeting or quotas.

4. Set Targeting

API: Add Targeting

Define audience targeting criteria for a group using predefined survey questions and options.
Key required fields include GroupId (path param), QuestionId, and Options (selected values or ranges).
This step directly controls who qualifies for the survey and impacts feasibility and delivery.

5. Set Quotas (Optional)

API: Create Quotas

Define quotas within a group to control how completes are distributed across specific audience segments.
Key required fields include GroupId, Quota Title, N (sample size), and Conditions (targeting rules like age, gender, etc.).
This step ensures balanced sampling and prevents over-delivery for specific segments.

6. Check Feasibility

API: Feasibility

Evaluate whether the defined group targeting can achieve the required completes and timelines.
Key input typically includes GroupId along with targeting, LOI, IR, and sample size (N) to estimate available supply.
This step is critical to ensure your setup is deliverable before making the job live.

7. Optimize (If Needed)

API: Update Targeting / Update Quota / Update Group

Adjust targeting, quotas, or pricing based on feasibility results.
Repeat feasibility check until the setup is optimal.

8. Make Project Live

API: Update Job Status and Update Group Status

Activate the project by updating both Job and Group status to LIVE, enabling the survey to start receiving traffic.
Key required fields include JobId / GroupId and Status (LIVE) to move entities from draft to active state.
This step marks the transition from setup to active data collection.

9. Monitor Performance

API: Job Stats / Group Stats / Quota Stats

Track survey performance at job, group, and quota levels to monitor progress and delivery.
Key metrics include completes, conversion rates, incidence, and quota fulfillment status.
Monitoring helps in optimizing live projects for better results.

API Call Flow

Buyer API – Call Flow#

Overview#

End-to-End Flow#

1. Create Job#

2. Create Group#

3. (Optional) Fetch Metadata#

4. Set Targeting#

5. Set Quotas (Optional)#

6. Check Feasibility#

7. Optimize (If Needed)#

8. Make Project Live#

9. Monitor Performance#