TrueValidate API

REST endpoints for creating, reading and updating TrueValidate projects using JSON payloads.

Base URL: https://tvapi.survalidate.com
Method: All endpoints use POST
Content-Type: application/json
Authentication: Send your key as apikey in the JSON body of every request.

The {{ID}} placeholder. Anywhere a URL contains {{ID}}, TrueValidate substitutes the respondent's ID. Add it to your redirect URLs to receive the ID back.

Endpoint summary

Endpoint	Purpose	Required fields
`/listprojects`	List the last 100 projects	`apikey`
`/createproject`	Create a project with your company defaults	`apikey`, `project_id`
`/getproject`	Get a project's full configuration	`apikey`, `project_id`
`/editproject`	Update any or all project settings	`apikey`, `project_id`
`/getrecord`	Get a panelist's record for a project	`apikey`, `project_id`, `paid`

1. List all projects

Retrieves a list of the last 100 projects.

POSThttps://tvapi.survalidate.com/listprojects

Request

JSON

{
  "apikey": "<API_KEY>"
}

Response

200 OK

{
  "success": "1",
  "data": [
    {
      "project_id": "1245",
      "tvlink": "https://tv.survalidate.com/s/wdhfiwdbfdiwfbdwicbdwic/{{ID}}",
      "status": "Active"
    },
    {
      "project_id": "1246",
      "tvlink": "https://tv.survalidate.com/s/wdhfiwdbfdiwfbdwicb234/{{ID}}",
      "status": "Active"
    }
  ]
}

2. Create project

Creates a new project using your company's default setup.

POSThttps://tvapi.survalidate.com/createproject

Body parameters

Parameter	Requirement	Format
`apikey`	Required	Your API key
`project_id`	Required	Unique. Alphanumeric, max 20 characters.

All other inputs are optional and accept the same values as Edit project. Any setting you don't send follows the configuration on your company default page.

Request examples

Every other setting uses your company defaults.

JSON

{
  "apikey": "<API_KEY>",
  "project_id": "7181"
}

Any Edit project parameter can be sent at creation. Anything left out uses your company defaults.

JSON

{
  "apikey": "<API_KEY>",
  "project_id": "7182",
  "project_label": "Q4 Accounting Study",
  "forcevalidate": "On",
  "validated_url": "https://yoursite.com/complete?id={{ID}}",
  "failed_validation_url": "https://yoursite.com/fail?id={{ID}}",
  "step1": "linkedin",
  "step2": "imagepuzzle",
  "honeypot": "On"
}

Response

201 Created

{
  "success": "1",
  "message": "Project Inserted Successfully",
  "project_id": "7181",
  "tvlink": "https://tv.survalidate.com/s/wdhfiwdbfdiwfbdwicbdwic/{{ID}}"
}

3. Get project info by ID

Retrieves the full configuration for a specific project ID.

POSThttps://tvapi.survalidate.com/getproject

Body parameters

Parameter	Requirement	Format
`apikey`	Required	Your API key
`project_id`	Required	String

Request

JSON

{
  "apikey": "<API_KEY>",
  "project_id": "ProjectNameHere"
}

Response

200 OK

{
  "project_id": "ProjectNameHere",
  "tvlink": "https://tv.survalidate.com/s/NmQ4MDhmMzVhYVJha23432432/{{ID}}",
  "project_label": "",
  "status": "Active",
  "forcevalidate": "ON",
  "prepage": {
    "prepage": "OFF"
  },
  "redirect_urls": {
    "validated_url": "https://bizpinion.com/truevalidate/{{ID}}-VALID",
    "failed_validation_url": "https://bizpinion.com/truevalidate/{{ID}}-FAILED",
    "bypassed_url": "https://bizpinion.com/truevalidate/{{ID}}-BYPASSED"
  },
  "digital_fingerprinting": {
    "digital_fingerprinting": "ON",
    "sv_mode": 3,
    "thresholds": {
      "sv_score": 0,
      "dupe_score": 95,
      "fraud_score": 50
    },
    "country_check": {
      "accepted_countries": [],
      "rejected_countries": []
    }
  },
  "steps": {
    "step1": {
      "step1": "linkedin",
      "honeypot": "ON"
    },
    "step2": "imagepuzzle"
  },
  "modifiedby": "Demo",
  "modified": "2026-09-14 10:39:40"
}

A step that uses linkedin is returned as an object that also carries the honeypot setting. All other steps are returned as plain strings.

4. Edit project

Updates any or all of an existing project's settings. Parameters you omit stay unchanged unless a rule below says otherwise.

POSThttps://tvapi.survalidate.com/editproject

Project parameters

Parameter	Requirement	Accepted values	Description & rules
`apikey`	Required	String	Your API authentication key.
`project_id`	Required	ID / String	The target project identifier.
`project_label`	Optional	String / blank	Omitted: the existing label stays. Sent blank: the existing label is cleared.
`status`	Optional	`Active`, `Inactive`	Sets the project status.
`forcevalidate`	Optional	`On`, `Off`	Toggles force validation. Requires the respondent to pass all tasks.
`prepage`	Optional	`On`, `Off`	Toggles the pre-page, which shows the respondent which tasks they'll complete and the optional `amount`.
`amount`	Conditionalprepage = On	Numeric	Incentive amount shown on the pre-page.
`currency`	Conditionalprepage = On	3-letter code: `USD`, `EUR`, `GBP`, `INR`, `JPY`, `AUD`, `CAD`	Currency for `amount`.
`validated_url`	Optional	Valid redirect URL	Used when the respondent passes. Add `{{ID}}` to receive your ID back.
`failed_validation_url`	Optional	Valid redirect URL	Used when the respondent fails. Add `{{ID}}` to receive your ID back.
`bypassed_url`	Optional	Valid redirect URL	Used when the respondent bypasses. Add `{{ID}}` to receive your ID back. Not used when `forcevalidate` is On.
`step1` `step2` `step3`	Optional	`linkedin`, `imagepuzzle`, `audioverify`	No step data sent: steps are unchanged. Each step must have a unique value. `step1` must be set before `step2`, and `step2` before `step3`. Sending only `step1` erases `step2` and `step3`.
`honeypot`	Conditionala step = linkedin	`On`, `Off`	Only takes effect when at least one configured step is `linkedin`.

SV block parameters

Every parameter in this table requires digital_fingerprinting = On.

Parameter	Requirement	Accepted values	Description & rules
`digital_fingerprinting`	Optionalmaster switch	`On`, `Off`	Master switch for the SV block. Setting it to On without any other SV values resets all SV settings to their defaults.
`accepted_countries`	Conditional	2-letter country codes, comma-separated	Default: blank. Example: `US,IN,PH`. Cleared if no data is passed. A country can't appear in both lists.
`rejected_countries`	Conditional	2-letter country codes, comma-separated	Default: blank. Example: `CA,GB,DE`. Cleared if no data is passed. A country can't appear in both lists.
`sv_mode`	Conditional	`1`, `2`, `3`	Default: 3. 1: Custom. Lets you set the score thresholds below. 2: Default settings. 3: Check only. Records activity without blocking users on this page.
`sv_score`	Conditionalsv_mode = 1	0 to 100	Default: 0. Custom SV score threshold.
`dupe_score`	Conditionalsv_mode = 1	0 to 100	Default: 95. Custom duplicate score threshold.
`fraud_score`	Conditionalsv_mode = 1	0 to 100	Default: 50. Custom fraud score threshold.

Request examples

Send only the fields you want to change. Pick a common task:

Only the label changes. Everything you leave out stays as it is.

JSON

{
  "apikey": "<API_KEY>",
  "project_id": "aK8mP2vX9z",
  "project_label": "changinglabel"
}

Pause a project by setting it to Inactive. Send Active to turn it back on.

JSON

{
  "apikey": "<API_KEY>",
  "project_id": "aK8mP2vX9z",
  "status": "Inactive"
}

amount and currency are only accepted when prepage is On.

JSON

{
  "apikey": "<API_KEY>",
  "project_id": "aK8mP2vX9z",
  "prepage": "On",
  "amount": 5.0,
  "currency": "USD"
}

Add {{ID}} anywhere in each URL to receive the respondent's ID back.

JSON

{
  "apikey": "<API_KEY>",
  "project_id": "aK8mP2vX9z",
  "validated_url": "https://yoursite.com/complete?id={{ID}}",
  "failed_validation_url": "https://yoursite.com/fail?id={{ID}}",
  "bypassed_url": "https://yoursite.com/bypass?id={{ID}}"
}

Steps must be filled in order with no repeats. honeypot applies here because one step is linkedin.

JSON

{
  "apikey": "<API_KEY>",
  "project_id": "aK8mP2vX9z",
  "step1": "imagepuzzle",
  "step2": "audioverify",
  "step3": "linkedin",
  "honeypot": "On"
}

Respondents must pass every step. bypassed_url is not used while this is On.

JSON

{
  "apikey": "<API_KEY>",
  "project_id": "aK8mP2vX9z",
  "forcevalidate": "On"
}

sv_mode 1 unlocks the three score thresholds. Country lists are cleared when they aren't sent, so include them on every SV update.

JSON

{
  "apikey": "<API_KEY>",
  "project_id": "aK8mP2vX9z",
  "digital_fingerprinting": "On",
  "sv_mode": 1,
  "sv_score": 0,
  "dupe_score": 7,
  "fraud_score": 50,
  "accepted_countries": "US,IN,PH",
  "rejected_countries": ""
}

JSON

{
  "apikey": "<API_KEY>",
  "project_id": "aK8mP2vX9z",
  "digital_fingerprinting": "Off"
}

Every editable setting in one request.

JSON

{
  "apikey": "<API_KEY>",
  "project_id": "aK8mP2vX9z",
  "project_label": "changinglabel",
  "status": "Active",
  "forcevalidate": "On",
  "prepage": "On",
  "amount": 500.0,
  "currency": "INR",
  "validated_url": "https://bizpinion.com/ok/{{ID}}",
  "failed_validation_url": "https://bizpinion.com/fail/{{ID}}",
  "bypassed_url": "https://bizpinion.com/by/{{ID}}",
  "step1": "imagepuzzle",
  "step2": "audioverify",
  "step3": "linkedin",
  "honeypot": "On",
  "digital_fingerprinting": "On",
  "sv_mode": 1,
  "sv_score": 0,
  "dupe_score": 7,
  "fraud_score": 50,
  "accepted_countries": "",
  "rejected_countries": ""
}

Response

Every edit returns the project's full configuration after the change. The updated array lists only the fields that changed. This example is the response to Change label.

200 OK

{
  "project_id": "aK8mP2vX9z",
  "tvlink": "https://tv.survalidate.com/s/NmQ4MDhmMzVhYWFLOG1Q2343243/{{ID}}",
  "project_label": "changinglabel",
  "status": "Active",
  "forcevalidate": "ON",
  "prepage": {
    "prepage": "ON",
    "amount": "500.00",
    "currency": "INR"
  },
  "redirect_urls": {
    "validated_url": "https://bizpinion.com/ok/{{ID}}",
    "failed_validation_url": "https://bizpinion.com/fail/{{ID}}",
    "bypassed_url": "https://bizpinion.com/by/{{ID}}"
  },
  "digital_fingerprinting": {
    "digital_fingerprinting": "ON",
    "sv_mode": 1,
    "thresholds": {
      "sv_score": 0,
      "dupe_score": 7,
      "fraud_score": 50
    },
    "country_check": {
      "accepted_countries": [],
      "rejected_countries": []
    }
  },
  "steps": {
    "step1": "imagepuzzle",
    "step2": "audioverify",
    "step3": {
      "step3": "linkedin",
      "honeypot": "ON"
    }
  },
  "updated": [
    "project_label"
  ]
}

5. Get panelist info by ID

Retrieves a panelist's validation record for a project.

POSThttps://tvapi.survalidate.com/getrecord

Body parameters

Parameter	Requirement	Format
`apikey`	Required	Your API key
`project_id`	Required	String
`paid`	Required	String. The panelist ID you passed in place of `{{ID}}` on the TrueValidate link.

Request

JSON

{
  "apikey": "<API_KEY>",
  "project_id": "prj138",
  "paid": "89798"
}

Response

200 OK

{
  "success": 1,
  "data": [
    {
      "project_id": "prj138",
      "paid": "89798",
      "created": "2026-09-14 10:39:44",
      "status": "Refused",
      "last_point": "LinkedIn",
      "linkedin_verification": "-",
      "audio_verification": "",
      "image_puzzle": "Pending",
      "country_mobile": "US",
      "is_mobile": "N",
      "dfp_score": "8*",
      "dfp_dupe_score": 0,
      "dfp_fraud_score": 15
    }
  ]
}

Response fields

Field	Type	Description
`project_id`	String	The project the record belongs to.
`paid`	String	The panelist ID you requested.
`created`	Datetime	When the panelist entered TrueValidate.
`status`	String	The panelist's overall validation status, e.g. `Refused`.
`last_point`	String	The last check the panelist reached.
`linkedin_verification`	String	Result of the LinkedIn step.
`audio_verification`	String	Result of the audio verification step.
`image_puzzle`	String	Result of the image puzzle step, e.g. `Pending`.
`country_mobile`	String	2-letter country code detected for the panelist.
`is_mobile`	String	`Y` if the panelist used a mobile device, `N` if not.
`dfp_score`	String	SV (digital fingerprinting) score. Returned as text and may include a trailing `*`.
`dfp_dupe_score`	Number	Duplicate score.
`dfp_fraud_score`	Number	Fraud score.

Standard error responses

These error messages apply to every endpoint when a request fails.

Project / identity

Trigger	Message
apikey missing or invalid	Wrong API Key error (401)
Missing project_id	project_id not given (400)
Unknown or invalid project_id	Wrong project_id (400)
Missing paid (/getrecord)	Paid is not given
project_label too long or badly formatted	Given project label is too long or in wrong format

Core settings

Trigger	Message
Invalid status	Given Status is in wrong format
Invalid forcevalidate	Given forcevalidate is in wrong format
Invalid prepage	Given prepage is in wrong format

Pre-page amount / currency

Trigger	Message
amount or currency sent without prepage = On	You need prepage variable on to set currency or amount
prepage = On but amount or currency invalid or blank	If Prepage is On we need currency and amount in valid format

Digital fingerprinting

Trigger	Message
Invalid digital_fingerprinting	Given digital_fingerprinting is in wrong format
Invalid sv_mode	Given sv_mode is in wrong format
Threshold out of range	Given thresholds are in wrong format

Country check

Trigger	Message
Invalid accepted_countries	Given accepted_countries is in wrong format
Invalid rejected_countries	Given rejected_countries is in wrong format
Same code in both lists	Duplicate country codes found in accepted_countries and rejected_countries

Verification steps

Trigger	Message
step2 set without step1	Step 2 cannot be filled unless Step 1 is filled.
step3 set without step1 and step2	Step 3 cannot be filled unless both Step 1 and Step 2 are filled.
Invalid value in a step	Step1 is in wrong format / Step2 is in wrong format / Step3 is in wrong format
Same value in multiple steps	Duplicate value found: <value> cannot be used in multiple steps.

Redirect URLs

Trigger	Message
Invalid validated_url	validated_url is in wrong format
Invalid failed_validation_url	failed_validation_url is in wrong format

TrueValidate API Reference