The Paradigm Gateway Vendor API Guide provides the opportunity for Vendors to integrate into Paradigm’s preferred network of high-quality sample providers. The purpose of this programmatic framework is to ensure efficient, effective, and real-time transmission of well-targeted sample to our clients’ surveys.
\nThis document outlines the Paradigm Gateway Framework, containing the suite API calls Paradigm’s Gateway expects to have available when launching a programmatic sample project. To integrate, Vendors must at minimum accommodate the following calls to viably integrate with the full project lifecycle.
\nAPIGateway supports only RESTful APIs and only HTTPS protocol is allowed. There should be a sandbox environment which can be used for integration testing with APIGateway system and it should not place any actual orders on successful API calls. All the API endpoints should be authenticated and credentials should not have a validation period. I.e. they should not expire after a certain time period.
\nThe required API endpoints include:
\nAPIGateway supports the following HTTP response status codes:
\nThis API allows Paradigm to run feasibility estimates for sample targets and automate the live bidding process to receive allocations to our surveys. This API requests and expects to receive estimated sample capacities and pricing matched to various scenarios of project specifications.
\nThe feasibility API should contain a distinguishable endpoint and it should accept the following parameters and feasibility should be calculated based on those values.
\nThe feasibility API parameters are given below:
\nThe supported device-types and languages are listed under
\n\n. If requiredN is specified in the payload, the feasibility should return values that are between 0 and requiredN or max completes should be returned.
\nThe feasibility should be calculated using the above parameters and the specific qualifications and the estimated completes that can be delivered should be returned as the response.
\nResponse should contain the following information:
\nIf there is any error in the request, the response should be in the corresponding 4xx status code and the response should contain the description for the error.
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"}]},"isInherited":true,"source":{"_postman_id":"e5652004-5b3c-4b7d-822f-4675440aab08","id":"e5652004-5b3c-4b7d-822f-4675440aab08","name":"Paradigm Vendor API Documentation","type":"collection"}},"urlObject":{"protocol":"https","path":["feasibility",""],"host":["base","url"],"query":[],"variable":[]}},"response":[{"id":"83d590aa-6b1d-4bf6-b8ec-3c644878d35d","name":"Feasibility API failure API call","originalRequest":{"method":"POST","header":[],"url":"https://base.url/feasibility/"},"status":"Unprocessable Entity (WebDAV) (RFC 4918)","code":422,"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n “errors”: [\r\n “Error message 1”,\r\n “Error message 2”,\r\n “Error message 3”\r\n ]\r\n}"},{"id":"e44fedf2-4f4a-459b-bfba-29f0439978e1","name":"Feasibility API Success API Call","originalRequest":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"country\": \"US\",\n \"loi\": 20,\n \"ir\": 15,\n \"fieldDays\": 1,\n \"deviceTypes\": [\n 1,\n 2,\n 3\n ],\n \"languageId\": 3,\n \"requiredN\": 100,\n \"qualifications\": [\n {\n \"id\": 2,\n \"value\": [\n \"1\",\n \"2\",\n \"10735\"\n ]\n },\n {\n \"id\": 1,\n \"value\": [\n \"18-99\"\n ]\n }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"https://base.url/feasibility/"},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n \"feasibility\": 100,\r\n \"cpi\": 3.5\r\n}\r\n"}],"_postman_id":"cd7d5689-1c5f-41ac-a593-2c04858c859b"}],"id":"849240eb-6ecd-4018-a77d-a200772c7d4f","description":"Feasibility related API's will be listed down here.
\n","_postman_id":"849240eb-6ecd-4018-a77d-a200772c7d4f","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"}]},"isInherited":true,"source":{"_postman_id":"e5652004-5b3c-4b7d-822f-4675440aab08","id":"e5652004-5b3c-4b7d-822f-4675440aab08","name":"Paradigm Vendor API Documentation","type":"collection"}}},{"name":"Project APIs","item":[{"name":"Create Project API","id":"c3eb4334-adef-4685-bb01-3b1780d84a62","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"url":"https://base.url/Project/","description":"Create project or campaign API should be an endpoint that supports an HTTP POST method.
\nOn calling this API the survey should be launched on the vendor’s side and it should return the created project Id (an identifier that can be later used to address this newly created project at the vendor’s end) OR the request payload should have a parameter that accepts a unique Identifier generated by Paradigm that will be used in the future to address the newly created project on the vendor side.
\nThe parameters that a project creation endpoint should accept are as follows:
\nThe supported Study-types, project-types and languages are listed under the
\n\n.
\nResponse should contain the following information:
\nThe projectId should be returned on successful launch (if a unique identifier is not requested on the API params).
\nErrors in the request if any should be listed in an array on the root of the response structure.
\nDeDupeTags Clarification: Whenever a Survey is created with dedupe tags, any previous respondent(s) from a Survey with a matching tag should be excluded from the new Survey. Additionally, when a new Survey is created with a dedupe tag, any existing active (not closed) Survey with a matching tag should exclude the new Survey's respondents.
\nLive URL Clarification: When a member of a panel has been selected to participate in a Survey, that respondent will be redirected to the survey url with a system unique ID which will be replaced on the placeholder '[ID]'. This respondent ID will be saved by the APIGateway system during redirection and it will be used to track the respondent, respondent transition and reconciliation process.
\nThe live link should include the respondent's unique session identifier [ID] tag for study and the respondent's unique alphanumeric ID tag [RespondentId]
to be included, e.g.
'http://www.survey.url/survey?surveyid=surv-eyun-ique-iden-tify-er16&seskey=[ID]&respondentid=[RespondentId]',
By default our redirect url has surveyId, seskey and respondentid query params. These values should not be altered and API call to create a survey should fail with a validation error if the surveyid, seskey or [ID],respondentid or [RespondentId] are not properly included in the survey url.
In addition to the parameters listed above, some links may include additional qualification parameters in the form \"&qualificationId=[qualificationId]\". When redirecting respondents, replace [qualificationId] with the actual option ID value, without the square brackets. For open-end qualifications (e.g., Age, Zip), replace [qualificationId] with the answer text. For multi-select qualifications, replace [qualificationId] with comma-separated option IDs.
\nExample:
If the qualification ID for Gender is 2, the parameter is represented as &2=[2].
If the selected option ID for Male is 1, the parameter should be returned as &2=1.
This API should be an HTTP GET supported endpoint that will pull the details of an already created project. The details of the pulled project should contain its current status, the estimated LOI, IR and all the other details that were provided upon project creation.
\nThe project current status will be in terms of Ids as an integer and the project statuses that are supported by the APIGateway system are as listed under the
\n\n.
\nThis API should accept the campaignId as its param and it should be a mandatory field. This API might be mainly used to get the current status of the survey.
\nIn the provided example, ‘12345’ is the projectId of the project which the details has to be retrieved.
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"}]},"isInherited":true,"source":{"_postman_id":"e5652004-5b3c-4b7d-822f-4675440aab08","id":"e5652004-5b3c-4b7d-822f-4675440aab08","name":"Paradigm Vendor API Documentation","type":"collection"}},"urlObject":{"protocol":"https","path":["project","12345"],"host":["base","url"],"query":[],"variable":[]}},"response":[{"id":"4c2c8c82-fae6-444c-a674-2e2e557441d3","name":"Get Project API Success API response","originalRequest":{"method":"GET","header":[],"url":"https://base.url/project/12345"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[],"cookie":[],"responseTime":null,"body":"{\r\n \"campaignId\": 12345,\r\n \"status\": 1,\r\n \"country\": \"US\",\r\n \"loi\": 20,\r\n \"ir\": 15,\r\n \"fieldDays\": 1,\r\n \"liveLink\": \"http://www.survey.url/survey?surveyid=surv-eyun-ique-iden-tify-er16&seskey=[ID]\",\r\n \"deviceTypes\": [1,2],\r\n \"studyType\": 1,\r\n \"projectType\": 2,\r\n \"languageId\": 3,\r\n \"qualifications\":[\r\n {\r\n \"id\": 2,\r\n \"value\": [\r\n \"1\",\r\n \"2\",\r\n \"10735\"\r\n ]\r\n },\r\n {\r\n \"id\": 1,\r\n \"value\": [\r\n \"18-99\"\r\n ]\r\n }\r\n ],\r\n \"cpi\": 3.5,\r\n \"requiredN\": 100,\r\n \"clientname\": \"User Testing\",\r\n \"clientcpi\": 2.50,\r\n \"dedupe\": [\"dupeT1\", \"dupeT2\"]\r\n}\r\n"},{"id":"ce15509e-1fa6-4f40-b04f-81429c5bdb65","name":"Get Project API invalid projectId response","originalRequest":{"method":"GET","header":[],"url":"https://base.url/project/12346"},"status":"Not Found","code":404,"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n “errors”: [\r\n “Error message 1”,\r\n “Error message 2”,\r\n “Error message 3”\r\n ]\r\n}"}],"_postman_id":"01d0cc43-5b7b-4d4d-8f34-491e2b99214d"},{"name":"Update Project API","id":"072b8ad4-4671-447c-b414-af34dfa9f034","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"PUT","header":[],"url":"https://base.url/project/12345","description":"The update project API should be of an endpoint that supports HTTP PUT protocol and allows for the edit or update of all parameters of a created project.
\nThis endpoint will mainly be used to change the current status of the launched survey along with occasional other parameter changes such as LOI, IR, CPI, limit and qualification update.
\nThe parameters that a project update endpoint should accept are as follows:
\nThe supported status, study-types, project-types and languages are listed under the Reference Libraries.\nThe response for this request can be in a 204 or 200 status code with the updated information. If the request fails, it should be in 4xx series status code and it should contain the description for the error.
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"}]},"isInherited":true,"source":{"_postman_id":"e5652004-5b3c-4b7d-822f-4675440aab08","id":"e5652004-5b3c-4b7d-822f-4675440aab08","name":"Paradigm Vendor API Documentation","type":"collection"}},"urlObject":{"protocol":"https","path":["project","12345"],"host":["base","url"],"query":[],"variable":[]}},"response":[{"id":"55f4d54c-c148-49ad-b2f1-3ceef3984a22","name":"Update project API Success responsse","originalRequest":{"method":"PUT","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"campaignId\": 12345,\n \"status\": 1,\n \"projectName\": \"Name\",\n \"country\": \"US\",\n \"liveLink\": \"http://www.survey.url/survey?surveyid=surv-eyun-ique-iden-tify-er16&seskey=[ID]&respondentid=[RespondentId]\",\n \"deviceTypes\": [\n 1,\n 2,\n 3\n ],\n \"studyType\": 1,\n \"projectType\": 2,\n \"languageId\": 3,\n \"loi\": 20,\n \"ir\": 15,\n \"fieldDays\": 1,\n \"qualifications\": [\n {\n \"id\": 2,\n \"value\": [\n \"1\",\n \"2\",\n \"10735\"\n ]\n },\n {\n \"id\": 1,\n \"value\": [\n \"18-25\",\"30\",\"40-45\",\"50\"\n ]\n }\n ],\n \"cpi\": 3.5,\n \"requiredN\": 100,\n \"dedupe\": [\n \"dupeT1\",\n \"dupeT2\"\n ],\n \"clientname\": \"User Testing\",\n \"clientcpi\": 15.50,\n \"inclusionIdentifiers\": []\n}","options":{"raw":{"language":"json"}}},"url":"https://base.url/project/12345"},"status":"No Content","code":204,"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":""},{"id":"9b160e65-7ba8-4855-b199-8ee151c11ed2","name":"Update project API failure API response","originalRequest":{"method":"PUT","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"campaignId\": 10025,\n \"status\": 4,\n \"projectName\": \"Name\",\n \"country\": \"US\",\n \"liveLink\": \"http://www.survey.url/survey?surveyid=surv-eyun-ique-iden-tify-er16&seskey=[ID]&respondentid=[RespondentId]\",\n \"deviceTypes\": [\n 3\n ],\n \"loi\": 20,\n \"ir\": 15,\n \"fieldDays\": 1,\n \"studyType\": 1,\n \"projectType\": 2,\n \"languageId\": 3,\n \"qualifications\": [\n {\n \"id\": 2,\n \"value\": [\n \"1\",\n \"2\",\n \"10735\"\n ]\n },\n {\n \"id\": 1,\n \"value\": [\n \"18-25\",\"30\",\"40-45\",\"50\"\n ]\n }\n ],\n \"cpi\": 3.5,\n \"requiredN\": 100,\n \"dedupe\": [\n \"dupeT1\",\n \"dupeT2\"\n ],\n \"clientname\": \"User Testing\",\n \"clientcpi\": 15.50,\n \"inclusionIdentifiers\": []\n}","options":{"raw":{"language":"json"}}},"url":"https://base.url/project/12346"},"status":"Unprocessable Entity (WebDAV) (RFC 4918)","code":422,"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n “errors”: [\r\n “Error message 1”,\r\n “Error message 2”,\r\n “Error message 3”\r\n ]\r\n}"}],"_postman_id":"072b8ad4-4671-447c-b414-af34dfa9f034"}],"id":"2b2609d8-b1e2-4f31-836e-6277a6ed3139","description":"All project APIs will be listed here.
\n","_postman_id":"2b2609d8-b1e2-4f31-836e-6277a6ed3139","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"}]},"isInherited":true,"source":{"_postman_id":"e5652004-5b3c-4b7d-822f-4675440aab08","id":"e5652004-5b3c-4b7d-822f-4675440aab08","name":"Paradigm Vendor API Documentation","type":"collection"}}},{"name":"Info Endpoint","item":[{"name":"Health Check","id":"af6b4d8a-45a4-4096-baea-f7c0b7d031e2","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://base.url/health/","description":"A simple GET request to the specific endpoint (/health), that will respond with the HTTP status 200 OK/503 Service Unavailable.\nWhen the system goes offline due to server issues, it may be related to a specific endpoint or API transaction caused by bugs in your application.
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"}]},"isInherited":true,"source":{"_postman_id":"e5652004-5b3c-4b7d-822f-4675440aab08","id":"e5652004-5b3c-4b7d-822f-4675440aab08","name":"Paradigm Vendor API Documentation","type":"collection"}},"urlObject":{"protocol":"https","path":["health",""],"host":["base","url"],"query":[],"variable":[]}},"response":[{"id":"d1140d2b-a90d-40d9-80b3-e079c27324a9","name":"Health check success","originalRequest":{"method":"GET","header":[],"url":"https://base.url/health/"},"status":"OK","code":200,"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":null},{"id":"a382c234-d2ca-4724-8a45-ab74693f094f","name":"Health check failure","originalRequest":{"method":"GET","header":[],"url":"https://base.url/health/"},"status":"Service Unavailable","code":503,"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":null}],"_postman_id":"af6b4d8a-45a4-4096-baea-f7c0b7d031e2"}],"id":"9418295a-7bcf-4c05-a6b4-7e949419b8bb","description":"To ensure Audience API is reachable.
\n","_postman_id":"9418295a-7bcf-4c05-a6b4-7e949419b8bb","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"}]},"isInherited":true,"source":{"_postman_id":"e5652004-5b3c-4b7d-822f-4675440aab08","id":"e5652004-5b3c-4b7d-822f-4675440aab08","name":"Paradigm Vendor API Documentation","type":"collection"}}},{"name":"Server-to-Server Redirect API","item":[{"name":"Respondent Transition API","id":"e0b734ad-5a04-4826-90dc-d2e16652b240","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":"https://base.url/respondents/transition","description":"After a respondent completes the survey, the respondent will be redirected back to the vendor's portal via a predefined URL. This URL should contain a place holder where the seskey (respondent unique key) should be placed. For example 'https://base.url/survey/return/[Id]' or 'https://base.url/survey/return?seskey=[Id]'.\nThrough that process, the vendor will receive information on the respondent's activity in the survey. As part of this handoff, the information should be passed via an API (server to server) to avoid exposure to manipulation.
\nThe status received via API call for a respondent should be the status of the record, independent of the URL that the respondent redirects to. As such, completion redirects that are received without a prior API call should not be considered as completes without off-line validation.
\nThis endpoint can be an HTTP POST protocol API that expects a dictionary of respondents and their status.
\nMandatory parameters that are required in this endpoint are provided below.
\nThe eligible statuses for a respondent will be passed as Status Ids and their corresponding descriptions are listed under Reference Libraries.
\nThe API should return a 204 status code on response and if there is an error in the request, the response should be in 4xx status code and it should contain the description for the error.
\nNote : When an S2S call fails due to any error , we will not block that respondent in DIG , but will be passing an additional parameter , EOT as 1, in the normal redirection link of the vendor .
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"}]},"isInherited":true,"source":{"_postman_id":"e5652004-5b3c-4b7d-822f-4675440aab08","id":"e5652004-5b3c-4b7d-822f-4675440aab08","name":"Paradigm Vendor API Documentation","type":"collection"}},"urlObject":{"protocol":"https","path":["respondents","transition"],"host":["base","url"],"query":[],"variable":[]}},"response":[{"id":"4204617f-3fa3-45ad-93a1-5da9ee85c14f","name":"Respondent Transition API Success API Call","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"seskey\": \"respo-ndent-uniqu-eGuid\",\n \"status\": 1\n}","options":{"raw":{"language":"json"}}},"url":"https://base.url/respondents/transition"},"status":"No Content","code":204,"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":""},{"id":"b42e3477-ad83-42d1-89d8-1a6c6ae8cd51","name":"Respondent Transition Failure API Call","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"seskey\": \"respo-ndent-uniqu-eGuid\",\n \"status\": 5,\n \"eot\":true\n}","options":{"raw":{"language":"json"}}},"url":"https://base.url/respondents/transition"},"status":"Unprocessable Entity","code":422,"_postman_previewlanguage":"text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n “errors”: [\r\n “Error message 1”,\r\n “Error message 2”,\r\n “Error message 3”\r\n ]\r\n}"}],"_postman_id":"e0b734ad-5a04-4826-90dc-d2e16652b240"}],"id":"7b55fce2-085a-4b55-af0e-c5442530a0de","description":"All vendor respondent transition APIs will be listed in this directory.
\n","event":[{"listen":"prerequest","script":{"id":"255ff486-ac2e-4211-a27d-5cd9f36442bf","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"5811255b-5cb1-4681-9979-a447c4c21a55","type":"text/javascript","exec":[""]}}],"_postman_id":"7b55fce2-085a-4b55-af0e-c5442530a0de","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"}]},"isInherited":true,"source":{"_postman_id":"e5652004-5b3c-4b7d-822f-4675440aab08","id":"e5652004-5b3c-4b7d-822f-4675440aab08","name":"Paradigm Vendor API Documentation","type":"collection"}}},{"name":"Reconciliation APIs","item":[{"name":"Reconciliation API (Optional)","id":"17cf15df-1928-4cfa-8a51-3163bef10e11","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"url":"https://base.url/reconciliation","description":"This is an optional endpoint.
\nIn the case where there is a need to update respondent response statuses at a later time, e.g. if there was a technical issue setting response status, or responses have been found to be bad quality after a survey data review, there should be an endpoint that helps in reconciling the respondent’s data.
\nThis endpoint can be an HTTP POST protocol API that expects an array of a dictionary of respondents and their updated status. One or more respondents should be allowed to be updated in a single API call.
\nMandatory parameters that are required in a reconciliation endpoint are given below.
\nThe supported respondent statuses are listed under the
\n\n.The API should return 204 status code on response and if there is an error in the request, the response should be in 4xx status code and it should contain the description for the error.
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"}]},"isInherited":true,"source":{"_postman_id":"e5652004-5b3c-4b7d-822f-4675440aab08","id":"e5652004-5b3c-4b7d-822f-4675440aab08","name":"Paradigm Vendor API Documentation","type":"collection"}},"urlObject":{"protocol":"https","path":["reconciliation"],"host":["base","url"],"query":[],"variable":[]}},"response":[{"id":"3d33ee0b-c327-429a-a117-0cc23d03529c","name":"Reconciliation API failure response","originalRequest":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"[\r\n {\r\n \"seskey\": \"\",\r\n \"status\": 0\r\n }\r\n]\r\n","options":{"raw":{"language":"json"}}},"url":"http://base.url/reconciliation"},"status":"Unprocessable Entity (WebDAV) (RFC 4918)","code":422,"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n “errors”: [\r\n “Error message 1”,\r\n “Error message 2”,\r\n “Error message 3”\r\n ]\r\n}"},{"id":"af5d42d6-64e5-4a11-9d06-352624d46df4","name":"Reconciliation API success API response","originalRequest":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"[\n {\n \"seskey\": \"04fe9a97-a579-43c5-bb1a-58ed29bf0a6a\",\n \"status\": 4\n }\n]","options":{"raw":{"language":"json"}}},"url":"http://base.url/reconciliation"},"status":"No Content","code":204,"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":""}],"_postman_id":"17cf15df-1928-4cfa-8a51-3163bef10e11"}],"id":"89cceca1-281e-44f8-b4d3-596b9764630e","description":"All vendor reconiliation APIs will be listed in this directory.
\n","event":[{"listen":"prerequest","script":{"id":"520b40ef-f555-4e9b-b861-9fc32f607b7a","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"70a82c31-70b2-436c-9c59-45dc4e42bf26","type":"text/javascript","exec":[""]}}],"_postman_id":"89cceca1-281e-44f8-b4d3-596b9764630e","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"}]},"isInherited":true,"source":{"_postman_id":"e5652004-5b3c-4b7d-822f-4675440aab08","id":"e5652004-5b3c-4b7d-822f-4675440aab08","name":"Paradigm Vendor API Documentation","type":"collection"}}},{"name":"Quota Details API","item":[{"name":"Quota Details API","id":"050736e1-c81e-419c-ab86-b20305ade1dc","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[{"warning":"This is a duplicate header and will be overridden by the Authorization header generated by Postman.","key":"Authorization","value":"This API is a HTTP GET supported endpoint that will pull the quota details of the survey created in PS-DI.
\nThe details of the quota contain fields like qualificationId, qualificationOptionId, clickN and completeN for the respective sub quota.
\nThis API accepts surveyId as its parameter and it is a mandatory field. This API might be mainly used to get the quota details of a survey in PS-DI.
\nIn the provided example, ‘334’ is the surveyId of the survey which the quota details have to be retrieved.
\nSome of the fields in the response json like qualificationId, qualificationOptionId are integer values. The master values of those fields supported in PS-DI will be exposed through Master API.
\nThe parameters that this endpoint should accept are as follows:
\n.The API should return 200 status code on response and if there is an error in the request, the response should be in 4xx status code and it should contain the description for the error.
\nFor Example if the qualification and options are as follows
\nThen If the quota allocation as follows
\nThen the quota API respose will be
\n{
\"subQuota\": [
{
\"qualificationId\": 6,
\"isCustomQualification\": false,
\"options\": [{ \"qualificationOptionId\": 34, \"qualificationOptionText\": \"\", \"clickN\": 50, \"completeN\": 20, \"remainingClicks\": 50, \"remainingCompletes\": 20, \"isPaused\": false}],
\"subQuotaGroup\": null,
\"clickReserve\": 0, \"completeReserve\": 0
},
{
\"qualificationId\": 2,
\"isCustomQualification\": false,
\"options\": null,
\"subQuotaGroup\": [{ \"groupId\": 2664, \"groupName\": \"MF\", \"clickN\": 150, \"completeN\": 50, \"remainingClicks\": 150, \"remainingCompletes\": 50,\"isPaused\": false,
\"subQuota\": [ { \"qualificationOptionId\": 1, \"qualificationOptionText\": \"\" },
{ \"qualificationOptionId\": 2, \"qualificationOptionText\": \"\" }]}],
\"clickReserve\": 0, \"completeReserve\": 0
}
],
\"linkedQuota\": {
\"linkedQuotaDetails\": [
{
\"clickN\": 150,
\"completeN\": 100,
\"isPaused\": false,
\"subQuota\": [ { \"qualificationId\": 6, \"qualificationOptionId\": 35, \"qualificationOptionText\": \"\", \"isCustomQualification\": false},
{ \"qualificationId\": 7, \"qualificationOptionId\": 48, \"qualificationOptionText\": \"\", \"isCustomQualification\": false} ],
\"remainingClicks\": 150, \"remainingCompletes\": 100
}
],
\"clickReserve\": 0, \"completeReserve\": 0
}
}
This API is a HTTP GET supported endpoint that allows vendors to fetch the minimal survey details. This api will fetch the following details.
\nAuthorization need to be passed as a header value. Vendors need to contact Paradigm for the Authorization value.
\nFields like client name, client cpi, total n, total completes, paradigm num, boost num are configurable. Vendors need to contact Paradigm for enabling these fields in their response json.
\nSome of the fields in the response json like project type, language Id, status are integer values. The master values of those fields supported in DIG will be exposed through Master API.
\n","urlObject":{"protocol":"https","path":["api","gateway","quota","survey-list"],"host":["base","url"],"query":[],"variable":[]}},"response":[{"id":"481e6df1-6420-450e-84d8-d6ef7e2cda56","name":"Survey List Success API call","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"This API is a HTTP GET supported endpoint that will pull the details of an already created survey in DIG.
\nThe details of the survey contains fields like project name, LOI, IR, qualifications and all the other details that were provided upon survey creation.
\nThis API accepts surveyId as its param and it is a mandatory field. This API might be mainly used to get the details of a survey in DIG.
\nIn the provided example, ‘12345’ is the surveyId of the survey which the details has to be retrieved.
\nAuthorization need to be passed as a header value. Vendors need to contact Paradigm for the Authorization value.
\nFields like client name, client cpi, total n, total completes, paradigm num, boost num are configurable. Vendors need to contact Paradigm for enabling these fields in their response json.
\nSome of the fields in the response json like project type, language Id, status are integer values. The master values of those fields supported in DIG will be exposed through Master API.
\n","urlObject":{"protocol":"https","path":["api","gateway","quota","survey-details"],"host":["base","url"],"query":[{"key":"surveyId","value":"12345"}],"variable":[]}},"response":[{"id":"897ec9cd-0869-4799-9e7a-248a885c4d0a","name":"Survey Detail Success API call","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"This API is a HTTP GET supported endpoint that will pull the master details in DIG.
\nThe response contains fields like device type, status, study type, language, project type ,questions and its corresponding options.
\nThis API accepts the countryISOCode as its param.
\nIn the provided example, 'US’ is the countryISOCode, the questions and options mapped to the country 'US' will be listed in the node name 'question' of the API response.
\nAuthorization need to be passed as a header value. Vendors need to contact Paradigm for the Authorization value.
\n","urlObject":{"protocol":"https","path":["api","gateway","quota","dig_maters"],"host":["base","url"],"query":[{"key":"countryISOCode","value":"US"}],"variable":[]}},"response":[{"id":"67d4a45a-c5b7-4cf0-a998-e877a144b2bf","name":"Master Success API call","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"Publish API's will be listed down here. These API provides live stats and information for all projects launched by DIG.
\n","_postman_id":"f0fa8039-286f-4abb-a03d-aec1a0995fc6","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"}]},"isInherited":true,"source":{"_postman_id":"e5652004-5b3c-4b7d-822f-4675440aab08","id":"e5652004-5b3c-4b7d-822f-4675440aab08","name":"Paradigm Vendor API Documentation","type":"collection"}}},{"name":"Reference Libraries","item":[],"id":"597c8c10-00a9-4f64-9de7-bcfbc08f7903","description":"This section contains the API reference libraries for Survey and Respondent statuses transmitted through the Paradigm Gateway API.
\nQualifications
\nFor respondent Qualifications to be mapped for our surveys, please refer to the linked Paradigm Vendor API Standard Qualifications sheet. We will be regularly updating the countries and targeting points that we service via API, through this link. The current countries supported include US, UK, FR, DE, IT, ES, CA, AU, CN, and BR, with many more coming soon!
\nProject Statuses
\nThe project statuses that are supported by the APIGateway system with their corresponding descriptions are listed below.
\nNote: The Draft status(Status Code 1) is obsolete and hence removed from the above list. The initial survey status should be \"Active\".
\nRespondent transition Statuses
\nThe respondent transition statuses that are supported by the API Gateway system and their corresponding descriptions are listed below.
\nRespondent reconciliation Statuses
\nThe respondent reconciliation statuses that are supported by the API Gateway system and their corresponding descriptions are listed below.
\nStudy Types
\nThe Study Types that are supported by the API Gateway system are listed below.
\nProject Types
\nThe Project Types that are supported by the API Gateway system are listed below.
\nDevice Types
\nThe Device Types that are supported by the API Gateway system are listed below.
\nLanguages
\nThe languages that are supported by the API Gateway system are listed below.
\n","event":[{"listen":"prerequest","script":{"id":"48304aee-6d21-42ae-afaa-ee33ec35ecd1","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"27ef785f-5414-46f0-9918-9e3bcf2d5368","type":"text/javascript","exec":[""]}}],"_postman_id":"597c8c10-00a9-4f64-9de7-bcfbc08f7903","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"}]},"isInherited":true,"source":{"_postman_id":"e5652004-5b3c-4b7d-822f-4675440aab08","id":"e5652004-5b3c-4b7d-822f-4675440aab08","name":"Paradigm Vendor API Documentation","type":"collection"}}},{"name":"Additional feature APIs","item":[{"name":"Get Respondent Status API","id":"463761fa-9474-4c10-b019-4c10e7db5af3","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://base.url/respondent/{projectId}/{sesskey}","description":"This is an optional endpoint. This should be an HTTP GET protocol API which expects project id and sesskey in the URL route.
\nMandatory parameters that are required in a this endpoint are given below.
\nThe API should return 200 status code on response with current status of the respondent and if the sesskey is invalid, the response should be in 404 status code
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"}]},"isInherited":true,"source":{"_postman_id":"e5652004-5b3c-4b7d-822f-4675440aab08","id":"e5652004-5b3c-4b7d-822f-4675440aab08","name":"Paradigm Vendor API Documentation","type":"collection"}},"urlObject":{"protocol":"https","path":["respondent","{projectId}","{sesskey}"],"host":["base","url"],"query":[],"variable":[]}},"response":[{"id":"6abca3ec-55f5-4ae3-8a61-d32c27a9f27d","name":"Get Respondent Status API failure response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text","disabled":true}],"url":"http://base.url/respondent/12345/key2"},"status":"Not Found","code":404,"_postman_previewlanguage":"text","header":[],"cookie":[],"responseTime":null,"body":""},{"id":"e4037105-2c66-4206-ae66-7cba70277a1f","name":"Get Respondent Status API success response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text","disabled":true}],"url":"http://base.url/respondent/12345/key1"},"status":"Success","code":200,"_postman_previewlanguage":"json","header":[],"cookie":[],"responseTime":null,"body":"{\n \"projectId\": 12345,\n \"sesskey\": \"key1\",\n \"status\": \"Complete\",\n \"statusId\": 1\n}"}],"_postman_id":"463761fa-9474-4c10-b019-4c10e7db5af3"}],"id":"8f953b9d-fba2-411c-bbdc-1fbd4ce943bb","description":"These are optional endpoints, which would help with respondent tracking, download survey reports etc
\n","event":[{"listen":"prerequest","script":{"id":"a8fc3e99-20a0-4e2d-b80b-4590bde7b08d","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"6cb9ae97-45d1-44da-8295-4428319f8330","type":"text/javascript","exec":[""]}}],"_postman_id":"8f953b9d-fba2-411c-bbdc-1fbd4ce943bb","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"}]},"isInherited":true,"source":{"_postman_id":"e5652004-5b3c-4b7d-822f-4675440aab08","id":"e5652004-5b3c-4b7d-822f-4675440aab08","name":"Paradigm Vendor API Documentation","type":"collection"}}},{"name":"Changelog","item":[],"id":"8fac12a6-533d-465b-8435-5fafa2ce1265","description":"April 28,2026
\nAdded qualification parameter support to Entry URL
Create Project
August 26, 2021
\nAge qualification's example value has updated in the
\n\n\nand
\n\n\"Example Request\".
\nAugust 8, 2021
\nUpdated the qualification node value from integer array to string array in
\n\n\nand
\n\nAdded two new optional fields Client Name and Client CPI in
\n\nand
\n\nAugust 4, 2021
\nAdded new fields in
\n\n(5 new fields) and
\n\n(12 new fields).
\nJune 29, 2021
\nAdded
\n\nto ensure Audience API is reachable.
\nJune 17, 2021
\nAdded
\n\nin vendor redirection link.This parameter will be sent as true if an S2S call fails.
\nJune 1, 2021
\nAdded Recontact
\n\n. This type provides the ability to include respondents based on participation in previous study. Respondents IDs should be added to the \"Inclusion Identifiers\" node during
\n\n.
\n","_postman_id":"8fac12a6-533d-465b-8435-5fafa2ce1265","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"}]},"isInherited":true,"source":{"_postman_id":"e5652004-5b3c-4b7d-822f-4675440aab08","id":"e5652004-5b3c-4b7d-822f-4675440aab08","name":"Paradigm Vendor API Documentation","type":"collection"}}}],"auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"}]}},"event":[{"listen":"prerequest","script":{"id":"8ba44860-60bc-45ba-8dda-3314c7bfe9bc","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"618921ff-1ca1-47e7-9c13-6c23a994c8a3","type":"text/javascript","exec":[""]}}]}