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

Use the 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 status=PROCESSING.

In 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 status=READY and 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 surveyURL and surveyTestURL.

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 LAUNCHED state automatically
  • 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:

  1. Pause Line Item - Pauses fielding on the line item
  2. Launch Line Item - Launches a paused line item again and starts sending traffic
  3. Close Line Item - Closes the line item for any further fielding. This is the final state of the line item
  4. 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:

  1. Pause the line item for sending additional respondents
  2. Send an email with the new price and the reasons for the price change
  3. 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.

Auto Repricing without pausing

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.

Invoice Adjustments

All invoice adjustments will be reviewed on a case by case basis.