RPI integration guide

This article outlines the steps required for Lucid Marketplace Supply Partners to transition from using Cost Per Interview (CPI) based metrics to Revenue Per Interview (RPI) based metrics. Your Account Team will notify you of the date by which you are required to transition to RPI based metrics. On the deprecation date CPI related metrics and functionality will be removed from the Supply APIs, entry links, redirects and reporting.

RPI related properties will be added to API response models and request arguments. The new models and new arguments in the developer documentation section detail each of the changes. The remaining sections of this Guide detail the steps a supply partner should take to update their integrations to use these new properties.

Note that CPI related response properties and request arguments (cpi, CPI, QuotaCPI, TargetCCPI, EPC) will continue to be supported until the CPI deprecation date shared with you by your Cint Account Team. After the CPI deprecation date, the CPI properties will be removed from all APIs and Supply Partners will be expected to use RPI data to calculate payment amounts for completes.

You will need to prepare your databases to store the new RPI and RPC (Revenue Per Click) data. If you are using legacy Supply APIs, you will begin to see RPI-related properties immediately following the release. Partners using Feed (formerly known as On-Time Supply) Opportunities will begin to see the new data once they have restarted their subscription. To restart a subscription, use the POST create Opportunities subscription endpoint to post a new subscription. After you reset your subscription, you should see the new RPI properties in the response and can begin storing them.

Example of opportunities model response:

{
      "survey_id": 12345678,
      "survey_name": "My Great Survey",
      "account_name": "Sample_Account",
      "buyer_id": 12345,
      "country_language": "eng_us",
      "industry": "other",
      "study_type": "adhoc",
      "bid_length_of_interview": 5,
      "bid_incidence": 50,
      "collects_pii": false,
      "survey_group_ids": [1258951],
      "is_live": true,
      "survey_quota_calc_type": "completes",
      "is_only_supplier_in_group": true,
      "revenue_per_interview": {
        "value": 1.35,
        "currency_code": "USD"
      },
      "total_client_entrants": 480,
      "total_remaining": 46,
      "completion_percentage": 0.15824915,
      "conversion": 0.39166668,
      "overall_completes": 188,
      "mobile_conversion": 0.28,
      "revenue_per_click": 0.35,
      "length_of_interview": 3,
      "termination_length_of_interview": 2,
      "relationship_type": "open",
      "respondent_pids": [],
      "message_reason": "new",
      "px_buyer_message": [
        "some-example-text",
        "another-tag"
      ],

If you are using a CPI-related filter on an opportunities subscription or list filtered Marketplace surveys requests, you will also need to update your opportunities subscription or filtered Marketplace surveys API requests to transition to the appropriate RPI argument, as in the example below.

Example opportunities POST request with RPI argument:

 {
      "callback": "https://wwww.callback.com/url",
      "include_quotas": true,
      "opportunities": [
          {
              "revenue_per_interview": {
                  "gte": 1
              },
              "country_language": {
                  "in": [
                      "eng_us",
                      "eng_gb"
                  ]
              },
              "study_type": {
                  "eq": "adhoc"
              }
          }

Example list filtered marketplace request with RPI argument:

https://api.samplicio.us/Supply/v1/Surveys/AllOfferwall?CountryLanguageID=11,74&SupplierCod e=1234&CollectsPII=1&RPIGTE=1

Example redirect with RPI parameter:

https://example.com/success?pid=test001&mid=000123&rpi=1.25&marketplacestatus=3&clientstatus=10&surveyid=4235483&hash=ZklmcHWI0jnRj7Y0OvYHDaDJUyo=1

We will not be adding RPC data to the show statistics request, and will be deprecating EPC from this API alongside the wider CPI functionality removal. If you are using this endpoint to retrieve EPC data and would like to begin to receive RPC data, you must use an Opportunities subscription to do so.  

Consuming RPI from redirects

To capture RPI data from your completion redirects, the parameter &RPI=[%REVENUE%] will need to be included in your complete redirect. As a standard, your account team will handle this addition to your default completion redirect and confirm its implementation. However, if you're creating your own redirects using the POST create a link API, remember to include this parameter in your complete redirect when making the request.

The CPI (cost) parameter will remain on your completion redirect until you confirm transition to RPI, or the deprecation deadline has arrived. At either point, we will no longer populate the CPI parameter. If you are creating your own redirects, please remove CPI once you have transitioned to RPI.

Example redirect with RPI parameter:

https://example.com/success?pid=test001&mid=000123&rpi=1.25&marketplacestatus=3&clientstatus=10&surveyid=4235483&hash=ZklmcHWI0jnRj7Y0OvYHDaDJUyo=1

Updating integration logic

If you have internal logic built around CPI data, you will need to make the relevant system adjustments, which may include:

• Removing logic that adjusts the completion revenue value to deduct Cint commission. It's important to note that, for now, there will be no changes to the Lucid Measurement pricing model or the revenue commission rate. We will still utilize the &ProofCPI parameter on your redirects, representing the gross amount. Therefore, it's necessary to maintain the existing logic to deduct your commission
  from this value.

• If collecting reconciliation cost, remove the logic that adjusts the cost value to deduct Cint commission.

• Updating internal earnings per click (EPC) calculations to include RPI data.

• Changing yield management algorithms that incorporate CPI information to be RPI data.

• Transition any quality measures logic, which sets CPI thresholds based on a respondent quality/risk score, to work off RPI data.

Requirements for link integrated partners

Updating entry links to use RPI

If you are using the cos parameter to set a minimum CPI filter, you will need to update your entry links to remove cos and include the parameter "rev". Including the rev parameter and value you will be setting the minimum net value you would like to earn from a survey complete.

Example entry link with rev parameter:

https://www.samplicio.us/s/default.aspx?sid=ac0da46e-ae93-474a-adb1-e19cd686623c&pid=TestUser001&clid=9&maid=20018c3d-40e9-4f50-869345a31ef196d4&42=45&43=2&45=70130&mid=testUserMID&loi=15&rev=0.50&hash=5zpxlhmiHB0UhFFuLTiO0-h9Jmc

Consuming RPI from redirects

To capture RPI data from your completion redirects, parameter &RPI=[%REVENUE%] will need to be included in your complete redirect. As a standard, your account team will handle this addition to your default completion redirect and confirm its implementation.

The CPI (cost) parameter will remain on your completion redirect until you confirm transition to RPI, or the deprecation deadline has arrived. At either point, we will no longer populate the CPI parameter, and your account team will remove it from the redirect.

Example redirect with RPI parameter:

https://example.com/success?pid=test001&mid=000123&sur=1234567&l=10&rpi=1.50&hash=RiNPoR2Bu4ZqhGXQrcK6IL2BcRElctks

Updating integration logic

If you have internal logic built around CPI data, where you automatically remove your commission rate from the completion value included on your complete redirect, you will no longer need to apply this calculation to the RPI data received. It's important to note that, for now, there will be no changes to the Lucid Measurement pricing model or the revenue commission rate. We will still use the &ProofCPI parameter on your redirects, which represents the gross amount. Therefore, it's necessary to maintain the existing logic to deduct your commission from this value.

Additional requirements for all supply partners

Tracking media measurement (MM) activity

The MM pricing model and revenue commission rate will remain unchanged for now. Continue to track MM complete data through your Supplier redirects, using parameter &ProofCPI to collect the gross payout, including Cint commission. Please keep in place any logic to deduct your commission value from the MM complete data ingested via the ProofCPI parameter on your redirects.

Consuming RPI for reconciled completes

If you are collecting cost (CPI, cost) information related to reconciliations via:

• Respondent outcomes

• Marketplace UI report, ID reconciliation

• Email subscription report “Fulcrum supplier reconciliation”.

You will need to transition to using RPI data. Whilst you are making the transition, CPI details (CPI and cost) will remain present up until the deprecation date. At this point, CPI information will be removed.

Example respondent outcomes response, including RPI:

{
        "respondent_id": "XXXXX-XXXX",
        "parent_session_id": "XXXXX-XXXX",
        "panelist_id": "XXXXX-XXXX",
        "session_id": "XXXXX-XXXX",
        "marketplace_status": 3,
        "client_status": 11,
        "entry_date": "2019-09-18T19:29:18.119Z",
        "last_date": "2019-09-18T19:29:18.119Z",
        "survey_id": 100001,
        "revenue_per_interview": {
          "value": 1.25,
          "currency_code": "USD"
        },
        "study_type": "adhoc",
        "buyer_id": 109 
    }

Reporting changes

Updated versions of our reports will show CPI and CPI-based metrics such as EPC and GMV, along with RPI and RPI-based metrics, once the RPI feature moves to general availability. During the beta phase, these reports can be provided by the Integration Manager upon request. After the deprecation of CPI, these reports will be updated again to include only RPI-based metrics, with all CPI-based metrics being removed. The table below illustrates the field names you can expect to see before and after CPI deprecation.

The Supplier CPI Tranches dashboard in the Supplier Portal will not be modified, instead we will be creating a new report called Supplier RPI Tranches. Following CPI deprecation, the Supplier CPI Tranches dashboard will be removed from the Supplier Portal.  

Go-live checklist

This go-live checklist summarizes the above information and helps you ensure you’ve implemented all required tasks to transition to RPI and avoid functional gaps when we deprecate CPI.

API integrated partners

1. Consume RPI and RPC data from our APIs:

   • Consume and use RPI and RPC data from our APIs, and disable the collection of CPI and EPC information.

2. Consuming RPI from redirects:

   • Ensure your completion redirects are set up to include RPI data, replacing CPI (cost) data.

   • There should be no change in how you collect MM activity; we will continue to send the gross payout information via the parameter “ProofCPI”.

3. Update integration logic:

   • Remove any existing automation that could deduct commission from the confirmed RPI value.

   • Replace CPI with RPI in any yield management decisions and internal EPC calculations.

4. RPI-based metrics reporting:

   • Consume RPI-based metrics from our reporting, including:

     • Marketplace reports: completes, sample sold, and ID reconciliation.

     • Email subscription report: FulcrumSupplierReconciliation.

Link integrated partners

1. Update entry links:

   • Update entry links to replace the “cos” parameter with “rev”.

2. Consuming RPI from redirects:

   • Ensure your completion redirects are set up to include RPI data, replacing CPI (c) data.

   • There should be no change in how you collect MM activity; we will continue to send the gross payout information via the parameter “ProofCPI”.

3. Update integration logic:

   • Remove any existing automation that could deduct commission from the confirmed RPI value.

4. RPI-based metrics reporting:

   • Consume RPI-based metrics from our reporting, including:

     • Marketplace reports: completes, sample sold, and ID reconciliation.

     • Email subscription report: FulcrumSupplierReconciliation.

Developer documentation

Changelog

Change 1: New “RPI” properties for Feed (formerly OTS)

The RPI properties names differ between those uses for Feed and legacy supply API models.

Change 2: New “RPI” property for Opportunities

Change 3: New RPI properties for legacy supply API responses models

Change 4: New arguments added to some Feed (OTS) and Legacy Supply API requests

New models

New model 1: RPI model for Opportunities

Example:

"revenue_per_interview": {
    "value": "2.73",
    "currency_code": "USD"
}

New model 2: RPI model for respondent outcomes

Example:

"rpi": {
    "value": "2.73",
    "currency_code": "USD"
}

New model 3: RPI model for surveys, show an allocated survey, show quotas, entry links, sessions

Example:

"RPI": {
    "value": "2.73",
    "CurrencyCode": "USD"
}

New arguments