Building the Integration
In order for your system to effectively setup projects, get feasibility, launch projects, monitor them, adjust in field and then finally invoice please make sure that you go through this document to understand each process. Use this guide in conjunction with our API reference for more detailed examples
Step 1: Mapping to Dynata data endpoints
The first step towards building the integration is to integrate with Dynata’s data endpoints and map it into your system.
Get the list of all countries and languages we support.
After getting the list of countries and languages, get the list of all Dynata attributes that you can target on. You can either map these to your list of attributes or use the endpoint to show the dynata attributes to your end user.
Additionally get the list of Dynata surveyTopics, studyRequirements and studyTypes using Get Study Metadata endpoint. A
surveyTopic is a mandatory field for setting up the project so make sure you are choosing the right
surveyTopic for the survey for us to field effectively. An incorrectly chosen
surveyTopic can lead to surveys being rejected from fielding.
Get the list of Supplier Sources available for your account. Note that additional supplier source has to be configured for your account so please get in touch with your Account Manager if you want to access supplier sources other than Dynata.
Step 2: Setup your survey start links and survey redirects
Next step is to configure your survey URLS to append Dynata URL parameters that will uniquely identify the respondent session going into the survey. More information on this can be found in Start & End Links
Step 3: Setting up a project
Create Project endpoint to setup a project. A project needs to have at least one
line item for the call to succeed. As soon as you create the project the project goes to a
PROVISIONED state which means that the project is setup in Dynata.
Step 4: Feasibility & Pricing
After creating the project, use the
Feasibility & Pricing endpoint to get the latest feasibility & price for each line item of the project. The response will also contain a field called
expiry until when the feasibility response is active. After the expiry, you will have to request another feasibility to be able to buy the project.
Depending on the complexity of your quotas computing feasibility can take longer. In most scenarios the feasibility
status=READY and the counts are available. In the scenario where feasibility is not computed yet, we respond back with a
Processing state, our recommendation is to wait for
2-3 secs and call the API again to get the latest state. Please reach out to us if you are constantly seeing the feasibility status as
PROCESSING, and we can help out.
Before you go to the next step verify that the feasibility
totalCount > 0. If the
totalCount = 0, it means that we dont have any feasibility for the targeting you selected and we cannot fulfill this order through API. Please reach out to us in this scenario and an expert can help you out.
Step 5: Buy Project
Once the feasibility is good and you agree with the
costPerInterview, you can launch the project by calling the
Buy Project endpoint. At this point we mandate that you provide to us the line items you wish to buy and the
Buying a project line item puts the line item state as
AWAITING_APPROVAL meaning that the line item will now be reviewed before it will field any traffic.
Please see the section on Survey Auditing to know more on the
AWAITING_APPROVAL process and why that is important.
Step 6: Line Item Live
During the audit process there can be the following 2 outcomes:
QA_APPROVED- Line Item has been approved and will move to
REJECTED- There are issues with your setup and it needs to be fixed. Please see your email to see the exact reasons on why the line item was
REJECTED. If you follow our guidelines on Survey Content then we expect that your surveys will go live without any issues.
Step 7: Analyzing Field Progress
After your project and line items have gone live you can see the field progress by calling the
Get Project Report endpoint.
Step 8: Adjusting Field work
You can manage the field work by doing any of the following:
Pause Line Item- Pauses fielding on the line item
Launch Line Item- Launches a paused line item again and starts sending traffic
Close Line Item- Closes the line item for any further fielding. This is the final state of the line item
Rebalance counts of existing quotaCells- Once a line item is live you can change the counts of individual quotaCells wihtin a
Quota plan. This allows you to either increase/decrease a particular quota.
Step 9: Handling Repricing
In some scenarios during fielding we may change the price of the line item based on its field performance. The way we act on any repricing that happens in field are:
- Pause the line item for sending additional respondents
- Send an email with the new price and the reasons for the price change
- Trigger an event with the new price and the changed stats and information
It is essential that you integrate with the
Events API to receive those repricing changes and can act accordingly.
We can optionally auto reprice the line item unto a percentage of the initial costPerInterview. Please get in touch with us and we can configure this for your account.
Step 10: Fielding Complete & Project Close
During fielding we will automatically mark your project as
COMPLETE once all the completes have been delivered, or you can optionally trigger
Close Project API to close out the project.
A project in
COMPLETE state will automatically move to
CLOSED state in 7 days.
Step 11: Invoicing & Billing
After your project moves to the
CLOSED state, after a few days it will automatically move to
INVOICED state. At this point your account billing contact will receive the invoice via email or you can integrate with the
Get Invoice PDF API to download a generated invoice PDF.
For any types of reconciliations please integrate with the
Reconciliation API. You can also directly reach out to your Dynata account manager for any adjustments.
All invoice adjustments will be reviewed on a case by case basis.