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

Postal codes are validated against the country portion of CountryLanguageCode. Brazilian CEP values may be sent with or without the hyphen and are stored in NNNNN-NNN form. Panama accepts both legacy numeric codes and the current geolocated grid code.

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 responses use the standard RapidoReach reply envelope. ErrorCode is SUCCESS, and Data contains an array of survey objects with the properties 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

Opening a survey and fraud verification

Always send the respondent to SurveyUrl. Do not redirect users to an upstream supplier URL and do not build a URL from the internal Link value. The hosted SurveyUrl verifies the respondent, creates the final supplier link, and preserves RapidoReach completion and termination tracking.

Medium-risk respondents still receive a successful survey-list response. If additional verification is required, the hosted page displays it when the respondent opens SurveyUrl and automatically resumes that same survey after verification. A publisher therefore does not need to render RapidoReach CAPTCHA or OTP UI in its server-to-server API integration.

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

Common error codes:

ErrorCode	Meaning	Publisher action
INVALID_PROFILE	One or more profile fields are missing or invalid. Field-level details are returned in fieldErrors.	Correct the payload before retrying.
COUNTRY_LANGUAGE_UNSUPPORTED	The locale is well-formed but is not active in the RapidoReach locale catalog.	Select an active locale from the publisher dashboard or contact support to request a mapping.
FRAUD_BLOCKED	The respondent cannot access inventory because of elevated fraud risk.	Do not retry or send the user directly to a supplier.
NOT_FOUND	No surveys are currently available for the respondent.	Retry later.

Examples

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

{
  "Errors": [],
  "Info": [],
  "Data": [
    {
    "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"
    }
  ],
  "ErrorCode": "SUCCESS"
}

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.