API Endpoint

Definition

This API endpoint allows you to fetch the top RapidoReach surveys for a given user in real time.

Request

POST https://www.rapidoreach.com/getallsurveys-api

Headers

Header	Description	Required
X-RapidoReach-Api-Key	Authentication API Key (App key can be found from app credentials page)	true

Parameters

Send a JSON payload in the request body. The service will create or update the respondent profile when it receives new data.

Root parameters

Parameter	Description	Required
UserId	Unique user identifier within your system. This value is used to create the RapidoReach respondent if one does not exist.	true
AppId	Placement ID from the publisher dashboard.	true
IpAddress	Current public IP address for the respondent.	true
City	Respondent city.	true
CountryLanguageCode	Respondent locale in the form LANG-CC (for example ENG-US, ENG-IN).	true
DateOfBirth	Date of birth in YYYY-MM-DD format.	false (recommended for profiling)
Gender	Respondent gender. Use M for male and F for female.	false
ZipCode	Respondent postal / ZIP code.	false
gps_id	Stable device fingerprint you capture for the user. Supplying this improves fraud prevention and de-duplication.	false (recommended)
PublisherProfiling	Array of partner-specific profiling responses collected on your side. See below for the payload shape.	false

You can also submit the payload using the camelCase publisherProfiling key. For backwards compatibility, the legacy ProfilingResponses / profilingResponses keys are mapped to the same behaviour.

Publisher profiling payload

When you have already collected partner profiling answers from the user, send them in the following structure. The backend will validate the values against the partner catalog and upsert them on the respondent profile.

{
  "PublisherProfiling": [
    {
      "partnerCode": "YOURSURVEYS",
      "countryLanguageCode": "ENG-US",
      "responses": [
        {
          "questionId": "AGE",
          "answerIds": ["25-34"]
        },
        {
          "questionId": "HOUSEHOLD_INCOME",
          "answerIds": ["50K-75K", "75K-100K"]
        }
      ]
    }
  ]
}

Each entry targets a specific survey partner (partnerCode) and locale (countryLanguageCode). Answers are upserted, so repeated calls with the same question overwrite the stored values.

Examples

cURL

curl --location --request POST 'https://www.rapidoreach.com/getallsurveys-api' \
  --header 'X-RapidoReach-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "UserId": "someUserIdofYourApp",
    "AppId": "X2Qz4ddj1",
    "IpAddress": "106.213.81.42",
    "City": "New York",
    "CountryLanguageCode": "ENG-US",
    "DateOfBirth": "1993-01-21",
    "Gender": "M",
    "ZipCode": "10001",
    "gps_id": "example-device-fingerprint"
  }'

Success model

Successful response is a JSON array of survey objects with the properties given below.

Property	Type	Description	Required
SurveyNumber	string	Rapidoreach survey identifier.	true
SurveyUrl	string	Survey entry link you should redirect the user to. The link already contains the correct tracking parameters.	true
Reward	number	Reward for your user in your virtual currency.	true
LOI	number	Length of interview in minutes.	true
MatchingPercentage	integer	Estimated conversion rate (%).	true
vc_name	string	Name of the virtual currency configured for the placement.	true
Link	string	Canonical RapidoReach link slug (/surveylink/create/...). Provided for reference; use SurveyUrl for traffic.	true
ProvidedBy	string	Always RAPIDOREACH for this API.	true
CPI	number	Reward in USD before your virtual currency conversion.	true
Survey	object	Metadata from the upstream supplier (e.g. BidLengthOfInterview, SurveyName).	true

Error model

Error response is a JSON object with the properties given below.

Property	Type	Description	Required
Errors	array	API errors in array it includes a list of all possible error messages	false
Info	array	any other info description	false
Data	array of objects	Error messages providing further error details	false
ErrorCode	string	Error code	true

Examples

Success (200) Bad Request (400) Internal Server Error (500)

[
  {
    "ProvidedBy": "RAPIDOREACH",
    "Reward": 59,
    "SurveyNumber": "37146073",
    "vc_name": "CB1234",
    "CPI": 1.18,
    "LOI": 10,
    "Link": "/surveylink/create/YOURSURVEYS/37146073?i=63f1f51e59c927d429b1730b&enc=9d1ea09722600c0395d70ba621a9c3cbb3d9b18b",
    "Survey": {
      "BidLengthOfInterview": 10,
      "SurveyName": "Other study"
    },
    "MatchingPercentage": 100,
    "SurveyUrl": "https://www.rapidoreach.com/ofw/api-surveys/?api_respondent_id=testapi001-X2Qz5dxNX-763fab1b7c822cd9d69bc870a0bc831b&cpi=1.18&loi=10&surveynumber=37146073&providedby=YOURSURVEYS&i=63f1f51e59c927d429b1730b&enc=9d1ea09722600c0395d70ba621a9c3cbb3d9b18b"
  },
  {
    "ProvidedBy": "RAPIDOREACH",
    "Reward": 94,
    "SurveyNumber": "37146770",
    "vc_name": "CB1234",
    "CPI": 1.88,
    "LOI": 20,
    "Link": "/surveylink/create/YOURSURVEYS/37146770?i=63f1f51e59c927d429b1730b&enc=fefb47ac5b6e4ff07411888282cd318e4e2d0596",
    "Survey": {
      "BidLengthOfInterview": 20,
      "SurveyName": "Let us know what you think"
    },
    "MatchingPercentage": 100,
    "SurveyUrl": "https://www.rapidoreach.com/ofw/api-surveys/?api_respondent_id=testapi001-X2Qz5dxNX-763fab1b7c822cd9d69bc870a0bc831b&cpi=1.88&loi=20&surveynumber=37146770&providedby=YOURSURVEYS&i=63f1f51e59c927d429b1730b&enc=fefb47ac5b6e4ff07411888282cd318e4e2d0596"
  }
]

Pass User Profile Data

Profiler data parameters represent user answers for given questions used as survey qualifications. You do not have to pass these, as we will collect this data as needed. If you would like to initially pass data for a user, please see the full list of profiler data parameters to get all supported parameters and their value options per language.

INFO

All profiler data parameters other than the ones listed as required above are optional and can be omitted in the request.