API

Using API you may interact with the PaperSurvey.io service programmatically.Please create at least one survey and have the documents uploaded, so you could see the response body interactively.

Show API key:

Authorization

To authorize, you should provide Authorization header with Bearer your_api_key value

Validation errors

If there are validation errors with the request, you will get a response with 422 status code with a list of errors.

Survey API

Create, update or retrieve a list of surveys in your user account.

HTTP Method	Endpoint & Response	Description	Parameters
GET	https://api.papersurvey.io/surveys Response: Survey [ ... ] 68 items	Retrieve all surveys.	None
POST	https://api.papersurvey.io/surveys Response: New Survey { ... } 74 items	Create a survey.	label - required, name of the survey language - optional, default: en, (available: am, ar, hy, my, cn, hr, cs, nl, en, fa, fr, de, el, hu, id, it, ja, km, ko, lt, no, pl, pt, ro, ru, es, sw, tl, th, bo, tr, vi)
GET	https://api.papersurvey.io/surveys/:survey Response: Survey { ... } 74 items	Get a survey with questions	survey - required, survey id Note: to retrieve a multi-language survey, you should provide `X-Language` header. (e.g. provide X-Language = es, if you'd like to retrieve Spanish translations)
PUT	https://api.papersurvey.io/surveys/:survey Response: Updated survey { ... } 74 items	Update a survey and questions	Survey, You should provide a modified survey from the above endpoint. Your request body must include all the existing form fields. { ... } 74 items align_left - bool, Align choice grid questions to the left-side allow_non_unique - bool, Allow non unique identifiers bold - bool, Questions should appear in bold checkmark_size - int, Checkmark size (1 - 3.5x3.5 mm, 2 - 4.0x4.0 mm, 3 - 4.5x4.5 mm, 5 - 5.0x5.0 mm, 6 - 5.5x5.5 mm, 7 - 6.0x6.0 mm) cover_custom - bool, Include a custom Cover page cover_custom_text - string, Text for custom Cover page. `cover_custom` should be set to true, to use the text font - string, Font (choose from: american_typewriter, andika, arial, avenir, avenir_next, chalkboard, comic_sans, courier, futura, gill_sans, helvetica, lmodern, lato, league_gothic, lg, menlo, monaco, noteworthy, noto, noto_serif, open_sans, roboto, tahoma, times, verdana) heading_font - string, Heading Font (choose from: american_typewriter, andika, arial, avenir, avenir_next, chalkboard, comic_sans, courier, futura, gill_sans, helvetica, lmodern, lato, league_gothic, lg, menlo, monaco, noteworthy, noto, noto_serif, open_sans, roboto, tahoma, times, verdana) font_size - int, Font size in pt units. min: 9, max: 14 footer_left - string, Override Footer left position with text footer_left - string, Override Footer left position with text footer_right - string, Override Footer right position with text force_stamping - bool, Uniquely mark single-page surveys grading - bool, Enable Grading functionality h_margin - int, Left & Right page margin in mm v_margin - int, Top page margin in mm heading_fg - string, Heading text color heading_bg - string, Heading background color hyphenate - bool, Text hyphenation label - string, Survey name language - string, Default survey language (Available: am, ar, hy, my, cn, hr, cs, nl, en, fa, fr, de, el, hu, id, it, ja, km, ko, lt, no, pl, pt, ro, ru, es, sw, tl, th, bo, tr, vi) languages - array, Additional survey languages low_quality - bool, Reduced recognition tolerance mode - int, Recognition mode (1 - Check or fill the box to respond, 2 - Check to respond, fill to unmark) pdf_formdata - bool, PDF Form fields prefill_mode - string, Pre-fill mode (default - Form fields visible and editable, disabled - Form fields visible but not editable, hidden - Form fields hidden from display) prefilled_submit_only - bool, Pre-fill links only remove_header - bool, Remove filling instructions in the footer remove_help - bool, Remove default help text spacing - int, Spacing between questions in mm text_height - double, Textbox height in cm upload_pdf_single - bool, Disable unique page marking versioning - bool, Advanced versioning web_surveys - bool, Web surveys active web_survey_slug - string, web surveys slug web_css - string, Custom CSS for web surveys questions - array, List of questions. If not provided or null, questions will not be updated. If you provide an empty array, it will remove all of the questions type - string, question type (in: single_choice, multiple_choice, range, nps, group_single_choice, group_multiple_choice, number, date, open_response_line, open_response_area, signature, heading, text_block, page_break, divider, vertical_space, column, repeater name - string, question label helper_text - string, helper text hidden - bool, enable/disable question to be shown. other_field - bool, Include "other" field. other_label - bool, Custom "other" label. options - array, list of options for group_single_choice, group_multiple_choice, single_choice, multiple_choice questions. name - string, option label number - string, numeric value groups - array, list of subquestions for group_single_choice, group_multiple_choice questions. name - string, question label reverse - bool, custom attribute for Range question label_left - string, custom attribute for Range/NPS question label_right - string, custom attribute for Range/NPS question columns - int, custom attribute for column/date/heading/divider question decimal - bool, custom attribute for number question fit - bool, custom attribute for open_response_line/number/column/group_multiple_choice/group_single_choice/range/nps question height - double, custom attribute range_count - int, custom attribute for column/repeater/range/nps question recognition - string, custom attribute for open_response_line/open_response_area/number question underline - bool, custom attribute for heading/divider question weight - custom attribute for quiz functionality export_name - string, Exporting Column Header export_values - string, Exporting Cell Values (null - default, numeric - numeric value, text - actual answer) Note: you should provide `X-Language` header for updating multi-language survey. (e.g. if you would like to adjust the translations for Spanish questions, provide X-Language = es)
POST	https://api.papersurvey.io/surveys/:survey/duplicate Response: Newly created survey { ... } 74 items	Duplicate a survey.	survey - required, survey id
DELETE	https://api.papersurvey.io/surveys/:survey Response: 200 OK	Delete a survey and all responses permanently.	survey - required, survey id
DELETE	https://api.papersurvey.io/surveys/:survey/clear Response: 200 OK	Clear survey responses permanently.	survey - required, survey id

Preview API

Preview a draft how the survey looks in PDF.

HTTP Method	Endpoint	Description	Parameters
GET	https://api.papersurvey.io/surveys/:survey/versions/latest/preview Response: PDF	Generates a preview for the currently setup survey	version - Version id or string `latest` locale - Generate a preview for specific locale (applicable to multi-language surveys)
GET	https://api.papersurvey.io/surveys/:survey/versions/:version/preview Response: PDF	Preview an existing paper survey version	version - int, required - version id

Version API

Create a printable survey version. This should be called when you made some changes to a survey and ready to print it.

HTTP Method	Endpoint	Description	Parameters
GET	https://api.papersurvey.io/surveys/:survey/versions Response: array of Survey Versions [ ... ] 1 item	Retrieve all survey versions.	survey - required, survey id
POST	https://api.papersurvey.io/surveys/:survey/versions Response: Survey Version { ... } 7 items	Create a new version.	survey - required, survey id label - optional, set an optional version label (if advanced versioning is enabled) language - required (only if advanced versioning is enabled and there are multiple languages)
PUT	https://api.papersurvey.io/surveys/:survey/versions/:version Response: Survey Version { ... } 7 items	Update a label for version	survey - required, survey id version - required, version id label - update optional version label (useful only if advanced versioning is enabled)

Print API

Generate printable copies. You must provide survey version to print, created with API above.

HTTP Method	Endpoint	Description	Parameters
GET	https://api.papersurvey.io/surveys/:survey/versions/:version/print Response: 200, PDF Response: 422, when you must use an endpoint below instead to make copies.	Get single printable copy (only for single-page surveys or when unique survey marking is disabled) You may also check if the stamping is available by checking 'stamp' property on Version object	survey - required, survey id version - required, version id
POST	https://api.papersurvey.io/surveys/:survey/versions/:version/print Response: 200 OK	Generate printable copies This method is available when 'stamp' property on Version object is 'true'. (By default for multi-page surveys. To disable stamping and use the above method set `upload_pdf_single` Survey property to true)	survey - required, survey id version - required, version id count - number of copies to generate, integer (min: 1, max: 5000) duplex - boolean, insert blank page for duplex printing where applicable. identifiers - custom form identifiers, string, separated with commas. Optional. method - required, in: `email`, `callback` email - sends an email with generated PDF file. callback_url - sends a POST request (`file` input name) with a PDF file to your provided URL. callback_url - url, required when method is `callback`. email - email, required when method is `email`, provide an email address where to send the copies.

Upload API

Upload and retrieve uploaded files.

HTTP Method	Endpoint	Description	Parameters
GET	https://api.papersurvey.io/documents Response: array of Documents [ ... ] 15 items	Retrieves all uploaded documents in all surveys. You may use https://api.papersurvey.io/surveys/:survey/documents endpoint to retrieve documents for a specific survey	None
POST	https://api.papersurvey.io/documents Response: Uploaded documents { ... } 17 items	Store a new file. You should provide the file as 'file' parameter in request body. The uploaded document will be stored and put on a queue to be processed.	file - required, accepted mime types: PDF/TIFF/JPEG/PNG
DELETE	https://api.papersurvey.io/documents/:id Response: 200 OK	Delete an uploaded file and remove all data.	id - Document id

Data API

Using Responses API you may retrieve results of the processed responses.

HTTP Method	Endpoint	Description	Parameters
GET	https://api.papersurvey.io/surveys/:survey/entries Response: array of Entries [ ... ] 1 item	Retrieve all responses for a given survey.	survey - required, survey id document - optional, provide Document id to retrieve responses for specific document only. from - optional, unix timestamp, only retrieve responses created/updated after the given date.
GET	https://api.papersurvey.io/surveys/:survey/entries/questions Response: array of Questions [ ... ] 28 items	Retrieve all fillable survey questions (may be useful with the endpoint above).	survey - required, survey id
GET	https://api.papersurvey.io/surveys/:survey/export.csv Response: CSV file	Download a data export in CSV file format. Tip: You may use this to easily connect the survey to your BI (Business intelligence) software	survey - required, survey id document - optional, provide Document id to retrieve responses for specific document only. hide_links - optional bool, Do not include link column in the data export. hide_notes - optional bool, Do not include notes column in the data export.
GET	https://api.papersurvey.io/surveys/:survey/export.json Response: JSON response	Paginated and simplified JSON export. Tip: You may use this to easily connect the survey data to your BI (Business intelligence) software for large datasets	survey - required, survey id document - optional, provide Document id to retrieve responses for specific document only. page - provide a page number to retrieve.
GET	https://api.papersurvey.io/surveys/:survey/export.xlsx Response: Excel file	Download a data export in Excel file format.	survey - required, survey id document - optional, provide Document id to retrieve responses for specific document only. hide_links - optional bool, Do not include link column in the data export. hide_notes - optional bool, Do not include notes column in the data export.
GET	https://api.papersurvey.io/surveys/:survey/export.pdf Response: SPSS file	Download a data export in PDF file format.	survey - required, survey id date_from - optional, provide start date (Y-m-d) format. date_to - optional, provide end date (Y-m-d) format. filters - optional, filter by question e.g. {"question_id": ["answer", "or this answer"]}
GET	https://api.papersurvey.io/surveys/:survey/export.sav Response: SPSS file	Download a data export in SPSS file format.	survey - required, survey id document - optional, provide Document id to retrieve responses for specific document only. hide_links - optional bool, Do not include link column in the data export. hide_notes - optional bool, Do not include notes column in the data export.

Webhook API

Programmatically add or remove Webhooks after creating a new survey.

HTTP Method	Endpoint	Description	Parameters
GET	https://api.papersurvey.io/hooks Response: array of Webhooks [ ... ] 4 items	Retrieve all webhooks.
POST	https://api.papersurvey.io/webhooks/ Response: webhook { ... } 5 items	Create a new webhook.	survey_id - required, survey id. target_url - required, url address where to POST response.
DELETE	https://api.papersurvey.io/webhooks/:id Response: 200 OK	Remove a webhook.	id - webhook id.

Tip: You may also provide authorization token via ?api_token=your_api_key parameter for simplicity. Do not expose your authentication token publicly!

e.g. api.papersurvey.io/surveys?api_token=your_api_key

Community

New Connector: Papersurvey.io Connector

API