How to use Wequity's API?

Designed to streamline survey management, this API automates the processing of PDFs, survey autofilling, and status monitoring. It serves as an end-to-end solution for efficiently managing surveys from document processing to collecting responses.

Disclaimer: While all underlying data pipelines are intended for production, the API itself is in beta mode and may contain minor inconsistencies. Any feedback is welcome.

1. Verify Access: Ensure API connectivity with a GET request to the base URL using your credentials.

2. File Upload: Use a POST request to upload your documents. Expect roughly 30 minutes for every 500 documents.

3. Upload Check: Confirm file uploads by viewing them with a POST request to the View Uploaded Files endpoint.

4. Start Questionnaires: Initiate questionnaire pre-filling one at a time with a POST request, estimating 20 minutes for 100 questionnaires.

5. Monitor Progress: Check pre-filling status and wait for completion, typically 3-6 hours for 100 questionnaires, using the Get Pre-filling Status & Results POST request.

6. View Results: Access the outcomes by sending a POST request to Get Pre-filling Status & Results.

7. Review: Examine the results for accuracy and completeness.

💡 For detailed OpenAPI schemas, including other potential status codes, please refer to the section below titled OpenAPI definition.

To verify your access to the API, query this GET endpoint. All endpoints are protected by Api Key authentication.

An Api Key will be provided.

• ✅ Example response

  {
  	"status": "ok",
  	"questions_asked": 200,
  	"questions_remaining": 9800,
  	"pdf_documents_uploaded": 100,
  	"pdf_documents_remaining": 900,
  	"last_update_dt": "2024-04-03T23:59:07.874796+00:00"
  }
  

  Parameter	type	Description
  status	integer	The status of the request, typically indicating success or failure
  questions_asked	integer	The total number of questions asked across all surveys launched with these credentials.
  questions_remaining	integer	The number of questions that can still be asked with the current credits. For more information on credit allocation and policies, please consult the Wequity Team.
  pdf_documents_uploaded	integer	The total number of PDF documents uploaded using these credentials.
  pdf_documents_remaining	integer	The number of PDF documents that can be uploaded with the current credits. For more details on credit usage and limits, reach out to the Wequity Team.
  last_update_dt	string, date-time	date and time of the last operation that used credits.

  💡 Note: Within the context of this test, the credits and quotas are primarily implemented to prevent any unintended or excessive consecutive requests. Should you have any inquiries or require further clarification about these limitations, do not hesitate to contact the Wequity Team.

• 🐍 Query using Python

  Below is an example of how to query such an endpoint using Python.

  import requests
  
  YOUR_API_KEY = "<your_api_key>"
  headers = {"Content-Type" : "application/json", "Api-Key" : YOUR_API_KEY}
  url = "<https://erp-ai-assistant-prod-api-jybetmkkea-ew.a.run.app/api/v1>"
  endpoint = "..." #See endpoints listed below
  body = {...} #See body examples with required and optional parameters listed below
  results = requests.post(f"{url}{endpoint}", headers=headers, json=body).json()
  print(results)
  

• ✨ Example query

  {
  "pdfs" : [
   {
    "name": "example.pdf",
    "url": "<https://example.pdf>",
    "tag" : "Example Tag"
    },
    {
    "name": "example2.pdf",
    "url": "<https://example2.pdf>",
    "tag" : "Example Tag 2"
    }
   ]
  }
  

  Parameter	Type	Required	Description	Default
  pdfs	array[object]	Yes	Array of PDF documents to index.
  name	string	Yes	The name of the document. It should end with .pdf
  url	string, uri	Yes	Reference to the link where the document is publicly available. It should start with https://
  tag	string	No	A tag attached to the document. If a tag requires changing, you will need to reindex the PDF. Note that this tag parameter can be set at the same dictionary level as the pdfs parameter. In this case, this tag will be assigned to all PDFs without any specific tag assigned.	null

  💡 If a document with an identical name exists, the new document will override it unless the content is the same. In case of identical content, only the tag will be updated.

• ✅ Example response

  {
  	"n_docs": 2,
  }
  

  Parameter	type	Description
  n_docs	integer	The amount of pdfs that are being processed

  💡 Note : This response only confirms that the request has been processed and that the documents are being indexed. It does not mean these documents are Ready. To verify their status, please refer to the /pdf_documents/status endpoint.

• ✨ Example query

  {
  "document_status": ["Ready", "Processing"]
  "tags" : ["Example Tag", "Example Tag 2"]
  }
  

• ✅ Example response

  {
  	"n_ready": 1,
  	"n_processing": 1,
  	"n_error": 0,
  	"pdfs_status": [
  		{
  			"name": "example.pdf",
  			"status": "Ready",
  			"launched_dt": "2024-03-27T17:45:58.115549+00:00",
  			"indexed_dt": "2024-03-27T17:47:27.899483+00:00",
  			"tag": "Example Tag"
  		},
  		{
  			"name": "example2.pdf",
  			"status": "Processing",
  			"launched_dt": "2024-03-27T17:45:58.115549+00:00",
  			"indexed_dt": null,
  			"tag": "Example Tag 2"
  	]
  }
  

  Parameter	type	Description
  n_ready	integer	Number of documents ready to be queried.
  n_processing	integer	Number of documents still being processed.
  n_error	integer	Number of documents for which an error has been encountered. If this occurs, please find and attempt to re-index the document. If the error persists, it may be due to a corrupted document or other internal error.
  status	string	The status of each document, which can be Ready, Processing, or Error.
  launched_dt	string, date-time	Date and time of the indexing query (UTC).
  indexed_dt	string, date-time	Date and time when the document has been fully processed. None if not Ready (UTC).

• ✨ Example query

  {
      "tags": [
          [
              "Example Tag",
              "Example Tag 2"
          ],
          "Example Tag"
      ],
      "document_names": [
          "example3.pdf"
      ],
      "survey_name_prefix": "Sample Survey",
      "questions": [
          {
              "question": "Does your company have a policy regarding labor practices or human rights issues?",
              "output_choices": [
                  "No policies",
                  "Employees health and safety",
                  "Working Conditions",
                  "Labor Relations",
                  "Career Management",
                  "Child and Forced Labor",
                  "Discrimination & Harassment",
                  "External stakeholder human rights",
                  "Topics other than those mentioned above"
              ],
              "multiple_answers": true
          },
          {
              "question": "Does your company health & safety policy also cover activities carried out by your subcontractors?",
              "output_choices": [
                  "Yes",
                  "No",
                  "No subcontractors working on the company premises or on construction sites",
                  "Do not know"
              ],
              "multiple_answers": false
          }
      ]
  }
  
  

  Parameter	Type	Required	Description	Default
  document_names	array[string]	No	A array of documents used as a knowledge base to answer survey questions. If null, the tags parameter should be provided.	null
  survey_name_prefix	string	No	In addition to a unique ID (uuid) that will be created automatically, a name will be assigned to the surveys for easier identification. This survey_name_prefix will be followed by the array of tags used to build the knowledge base, as well as the launch timestamp in order to create the final name.	”survey”
  tags	array[string]	No	A array of tags. Documents assigned to these tags will be added to the knowledge base, in addition to any documents provided in 'document_names'. Note that each item in the array will initiate a different survey. Each item can also be a array of multiple tags, meaning all documents with these tags will be grouped for the same survey.

  For example, given "tags": [["Example Tag", "Example Tag 2"], "Example Tag"], 2 surveys will be launched: One with all documents tagged as Example Tag or Example Tag 2 plus example3.pdf (in this case, example.pdf, example2.pdf, and example3.pdf). The second survey will include all documents tagged as Example Tag and example3.pdf(in this case, example.pdf and example3.pdf).

  All surveys will contain the same questions, only the knowledge base used will differ. | null | | questions | array[object] | Yes | A array of question objects. | | | {question} | string | Yes | The question as text (max. length of 500 chars) | | | {output_choices} | array[string] | No | If provided, the answer will be one of these output choices, if possible. (From 2 to 20 items, each choice with a max. length of 200 chars). | null | | {multiple_answers} | boolean | No | It indicates whether the answer is a unique choice or an array of choices from the output_choices array. Can not be true if output_choices is provided. | false |

  💡 To launch surveys with different sets of questions, you will need to query this endpoint multiple times.

• ✅ Example response

  {
  	"total_questions": 4,
  	"total_surveys": 2,
  	"surveys_info": [
  		{
  			"n_questions": 2,
  			"n_pdfs": 3,
  			"survey_name": "Sample Survey_Example Tag_Example Tag 2_03_28_2024_22_56_58",
  			"survey_id": "902badc0-e3ec-46f9-915b-2bb7fd615245"
  		},
  		{
  			"n_questions": 2,
  			"n_pdfs": 2,
  			"survey_name": "Sample Survey_Example Tag_03_28_2024_22_56_58",
  			"survey_id": "2342ba123-e5fc-4zf9-915b-3eb7fb7fd622c"
  		}
  	],
  	"survey_ids": [
  		"902badc0-e3ec-46f9-915b-2bb7fd615245",
  		"2342ba123-e5fc-4zf9-915b-3eb7fb7fd622c"
  	]
  }
  

  Parameter	Type	Description
  total_questions	integer	Total number of questions answered across all surveys
  total_surveys	integer	Number of surveys launched (equal to the size of the tags array provided)
  survey_info	array[object]	Array of surveys with detailed information
  {n_questions}	integer	Number of questions answered in each survey (should be the same for all listed surveys)
  {n_pdfs}	integer	Size of the knowledge base used to fill out this survey
  {survey_name}	string	Name of the survey for easier identification
  {survey_id}	string, uuid	Auto-generated UUID of the survey (this UUID will be needed to get the survey status and the answers to the questions)
  survey_ids	array[string]	Array of all survey_ids. This array will be especially useful to get the status of the surveys just launched and the answers to the questions. See the /suvey_autofills/status endpoint below.

  💡 Note: This response only confirms that the request has been processed and that the surveys are being autofilled. To verify their status and fetch the answers, please refer to the /survey_autofills/status endpoint.

• ✨ Example query

  {
      "survey_ids": [
          "902badc0-e3ec-46f9-915b-2bb7fd615245",
          "2342ba123-e5fc-4zf9-915b-3eb7fb7fd622c"
      ],
      "survey_name_prefix":  "Sample Survey",
      "include_answers": true,
      "done_surveys_only": false,
      "sharing_email" : "example@test.com"
  }
  

  Parameter	Type	Required	Description	Default
  survey_ids	array[string]	No	This is an array of survey ids to fetch status from, and potentially fetch answers. If set to null, all surveys that have been launched will be considered.	null
  survey_name_prefix	string	No	This will retrieve all surveys with a name starting with this string. It's a convenient method to retrieve results from a batch you previously launched using a survey_name_prefix (see /survey_autofills/status endpoint). If null, it will consider all surveys. This can be added to the survey_ids array (OR operation). In the above example, it's unnecessary to mention both, as they point to the same surveys, unless another batch of surveys was previously launched using the same survey_name_prefix parameters.	null
  include_answers	boolean	No	To avoid noise and excessively large responses, this flag can be set to false. In this case, only the status and metadata of the surveys will be retrieved, excluding the results and answers to the questions. If set to true , survey_ids or survey_prefix_name should be provided in order to avoid too long response.	false
  survey_status	array[string]	No	Only surveys with one of these autofill statuses will be retrieved. By default, all statuses are considered.	["Done", "Autofilling", "Dispatching", "Error"]
  sharing_email	string, email	No	If this parameter is provided, a Google Sheet containing all results (questions/answers with survey IDs) will be created and shared with the specified email address. If it is set to null, no Google Sheet will be created. A new sheet is created every time this call is made. This parameter can be used in conjunction with include_answers=false if the goal is to limit the size of the response while having access to the results. If set to true , survey_ids or survey_prefix_name should be provided in order to avoid creating a sheet too heavy. Note: The email must be associated with a Google account that you can access.	null

  💡 When launching surveys, it may be useful to save the array of survey_ids that are autogenerated to use when querying this endpoint. You can freely query this endpoint with include_answers=false and survey_ids=null to fetch the array of surveys, including survey_name and survey_id. This will help you obtain the correct survey_ids array to enter as input.

• ✅ Example response

  {
  	"last_update_dt": "2024-03-28 23:45:42.535654+00:00",
  	"total_surveys": 2,
  	"progress_surveys": 0.5,
  	"survey_errors": 0,
  	"total_questions": 4,
  	"progress_questions": 0.75,
  	"found_rate": 0.66,
  	"total_questions_error": 0,
  	"link_to_results": "<https://docs.google.com/spreadsheets/d/><gsheet_id>/edit"
  	"qa_results": [
  		{
  			"survey_id" : "902badc0-e3ec-46f9-915b-2bb7fd615245",
  			"survey_name": "Sample Survey_Example Tag_Example Tag 2_03_28_2024_22_56_58",
  			"launch_dt": "2024-03-28 22:57:44.555693+00:00",
  			"finish_dt": "2024-03-28 23:45:42.535654+00:00",
  			"total_questions": 2,
  			"error": 0,
  			"autofill_status": "Done",
  			"progress": 1.0,
  			"found_rate": 1.0,
  			"document_queried": [
  				"example.pdf",
  				"example2.pdf",
  				"example3.pdf"
  			],
  			"questions_error": 0,
  			"qa_data": [
  				{	
  					"question": "Does your company have a policy regarding sustainable/responsible procurement? ('No policy', 'Suppliers/subcontractors and Environmental issues', 'Suppliers/subcontractors and Labor practices (Human resources, Human Rights)', 'Others (please specify)', 'Do not know')",
  					"answers": ["Suppliers/subcontractors and Environmental issues", "Suppliers/subcontractors and Labor practices (Human resources, Human Rights)"],
  					"rationale_and_sources": "EDF has a policy regarding sustainable/responsible procurement, as it has initiatives focused on environmental issues like Circular Economy principles, waste management, and resource productivity. Additionally, the company has a policy that incorporates labor practices and human rights, with a supplier policy that includes CSR clauses, self-assessments aligned with UN Global Compact principles, and a commitment to responsible procurement. These details are found in two reports: EDF-SBU-Highlights_2.pdf and edf-urd-annual-financial-report-2022-en.pdf.\\n\\nSources :\\n- EDF-SBU-Highlights_2.pdf : approx page(s) 17, 21, 23.\\n- edf-urd-annual-financial-report-2022-en.pdf : approx page(s) 196, 197, 220, 221, 222, 223, 225, 284, 290, 291.\\n- Our environmental contribution _ Sustainable business progress update _ EDF.pdf : approx page(s) 1, 2, 3, 4, 5.",
  					"confidence_level": "Medium",
  					"answered": true,
  					"answered_datetime": "2024-03-28 23:43:02.274561+00",
  					"error": false,
  					"error_message": null,
  					"additional_guidance": null,
  					"sources" : [
  						{"document_name" : "EDF-SBU-Highlights_2.pdf", "pages" : [17, 21, 23]},
  						{"document_name" : "edf-urd-annual-financial-report-2022-en.pdf", "pages" : [196, 197, 220, 221, 222, 223, 225, 284, 290, 291]},
  						{"document_name" : "Our environmental contribution _ Sustainable business progress update _ EDF.pdf ", "pages" : [1, 2, 3, 4, 5]},
  					]
  				},
  				{	"question": "Has your company implemented a formal policy covering any of the following topics? ('No policy', 'Anti-corruption and bribery', 'Conflict of interest', 'Fraud', 'Money laundering', 'Anti-competitive practices', 'Responsible marketing', 'Information security', 'Others (please specify)')",
  					"answers": ["Anti-corruption and bribery", "Conflict of interest", "Fraud", "Money laundering", "Anti-competitive practices", "Responsible marketing"]
  					"rationale_and_sources": "The company has formal policies on Anti-corruption and bribery, Conflict of interest, Fraud, Money laundering, and Anti-competitive practices, as reported in the 'edf-urd-annual-financial-report-2022-en.pdf'. This report details the Ethics and compliance programs, mentioning the Ethics and Compliance code of conduct with risk prevention measures in these areas and processes for fraud detection. It also refers to the company's focus on ethical procurement, environmental legislation compliance, and socio-economic contributions, which hints at Responsible marketing. While Information security is not explicitly mentioned, data protection issues are addressed as part of the compliance with regulations. The 'EDF-SBU-Highlights_2.pdf' report reflects similar policies, such as measures against bribery, fraud, and anti-competitive practices, and points to a Responsible marketing policy.\\n\\nSources :\\n- EDF-SBU-Highlights_2.pdf : approx page(s) 6, 15, 20, 21.\\n- edf-urd-annual-financial-report-2022-en.pdf : approx page(s) 98, 99, 110, 192, 193, 196, 204, 221, 223, 224, 249, 252, 273, 274, 277, 281, 283, 290, 291, 312, 326, 327, 597, 601.",
  					"confidence_level": "High",
  					"answered": true,
  					"answered_dt": "2024-03-28 23:22:59.583740+00",
  					"error": false,
  					"error_message": null,
  					"additional_guidance": null,
  					"sources" : [
  						{"document_name" : "EDF-SBU-Highlights_2.pdf", "pages" : [6, 15, 20, 21]},
  						{"document_name" : "edf-urd-annual-financial-report-2022-en.pdf", "pages" : [98, 99, 110, 192, 193, 196, 204, 221, 223, 224, 249, 252, 273, 274, 277, 281, 283, 290, 291, 312, 326, 327, 597, 601]}
  					]
  				},
  				}
  		},
  		{ 
  		  "survey_id" : "2342ba123-e5fc-4zf9-915b-3eb7fb7fd622c",
  			"survey_name": "Sample Survey_Example Tag_03_28_2024_22_56_58",
  			"launch_dt": "2024-03-28 22:57:44.555693+00:00",
  			"finish_dt": null,
  			"total_questions": 2,
  			"error": 0,
  			"autofill_status": "Autofilling",
  			"progress": 0.5,
  			"found_rate": 0.0,
  			"document_queried": [
  				"example.pdf",
  				"example3.pdf"
  			],
  			"questions_error": 0,
  			"qa_data": [
  				{					
  					"question": "Does your company have a policy regarding sustainable/responsible procurement? ('No policy', 'Suppliers/subcontractors and Environmental issues', 'Suppliers/subcontractors and Labor practices (Human resources, Human Rights)', 'Others (please specify)', 'Do not know')",
  					"answers": null,
  					"rationale_and_sources": "Information not found or not provided",
  					"confidence_level": "Answer not found",
  					"answered": false,
  					"answered_dt": "2024-03-28 23:43:02.274561+00",
  					"error": false,
  					"error_message": null,
  					"additional_guidance": "To further refine the answer, one might seek the most recent policy documents or internal human resources guidelines that provide details on the implementation and effectiveness of these measures. Ensuring the most up-to-date information may involve checking for more recent reports or updates to the company's ESG strategies and policies.",
  					"sources" : []
  				}
  		}
  }
  

  Parameter	Type	Description
  last_update_time	string, date-time	Time of the last update (UTC).
  total_surveys	integer	The number of surveys included in this report.
  progress_surveys	number, float	The ratio of completed surveys (Done or Error) to the total number of surveys, from 0 to 1. Note that a survey is considered Done when all questions have been processed.
  survey_errors	integer	The number of surveys considered as Error.
  total_questions	integer	The total number of questions across all queried surveys.
  progress_questions	number, float	The ratio of processed questions to the total number of questions, from 0.0 to 1.0. Always 1.0 if done_surveys_only is set to true.
  found_rate	number, float	The ratio of questions for which an answer has been found to the number of already processed questions (Note: not over the total number of questions) across all surveys, from 0 to 1.
  total_questions_error	integer	The count of questions that encountered errors accros all surveys
  link_to_results	string, uri	This is the link to the Google Sheet that contains the results (refer to qa_results). This sheet is shared exclusively with the email address provided in the gsheet_sharing_email parameter.
  qa_results	array[object]	A array where each items gives detailed information about a specific survey.
  {launch_dt}	string, date-time	Time when the survey was launched (UTC)
  {finish_dt}	string, date-time	Time when the survey was fully completed (UTC). null if still processing.
  {total_questions}	integer	The number of questions within all queried surveys
  {autofill_status}	string	The status of the survey. Can be Autofilling, Done, or Error. Always Done if only_surveys_done is set to true. The status may also be Dispatching. During this phase, further details won't be accessible until the task is processed and dispatched to the appropriate instance. This typically occurs swiftly.
  {progress}	number, float	The ratio of processed questions within this survey, from 0.0 to 1.0. Always 1.0 if done_surveys_only is set to true.
  {found_rate}	number, float	The ratio of questions for which an answer has been found to the number of already processed questions within this survey
  {document_queried}	array[string]	Array of documents used as a knowledge base for this survey
  {questions_error}	integer	The count of questions that encountered errors within this survey. See error and error_message field in answers for more details.
  {qa_data}	array[object]	Array of information regarding the question and its answer. null if include_answers=false. Non processed questions won’t appear in this list.
  {{question}}	string	The initial question with its potential output choices.
  {{answers}}	array[string]	The array of answers to the question. If multiple_answers is set to false, the array will contain only one item (if not null). If output_choices has been specified, all items should be part of the given output_choices, if possible.
  {{rationale_and_sources}}	string	Explanation of the answer, including if possible the sources (document name(s) and page(s)).
  {{confidence_level}}	string	The level of confidence in the answer. Can be Answer not found Low, Medium or High.
  {{answered}}	boolean	Boolean indicating whether an answer has been found. If no answer is found, many fields will be null and confidence_level will be Answer not found but this boolean is the easiest way of asserting whether the answer has been found or not.
  {{answered_dt}}	string, date-time	The time when the question was answered (UTC).
  {{error}}	boolean	A boolean value indicating if an error occurred. If an error is present, answered will be set to false, answer will be null, and confidence_level will be set to Answer not found.
  {{error_message}}	string	More details about the error, if possible. null if error=false
  {{additional_guidance}}	string	This provides additional guidance on how to refine and improve answers. If an answer isn't found, it can potentially lead you to one. This is for guidance purposes only.
  {{sources}}	array[object]	Structured array of the sources mentioned in rationale_and_sources . This is an array of object containing the document name and the relevant pages, where the first page of the document is 1.

  💡 Questions are processed in batches and results are uploaded in the same manner. As a result, progress updates may sometimes appear sudden.

  • The page numbers mentioned in the sources are intended for a computer to read. This means that the first page of the PDF is considered as 1, which might be different from the number a human reader would see at the bottom of the page.

  ⛔ Error Handling: A survey is considered to have an error if at least one batch or too many questions encounter issues. Even if flagged as Error, a survey may still contain some answers. Feel free to rerun the survey and if the error persists, contact the Wequity team. If last_update_dt does not update anymore, it's possible that all surveys have been completed. If the progress is not at 100%, some surveys may be stuck in Autofilling. Although measures are in place to prevent this, if such an issue is encountered, please contact the Wequity team.

openapi: 3.0.0
info:
  title: Survey Autofilling API
  description: Comprehensive API for document and knowledge base management and automated survey autofilling.
  version: 1.0.0
servers:
  - url: '<https://erp-ai-assistant-prod-api-jybetmkkea-ew.a.run.app/api/v1>'
    description: Production server
security:
	- ApiKeyAuth: [] 
paths:
	/status:
    get:
      summary: Check API status
      description: Returns the current status of the API and the remaining credits.
      operationId: getStatus
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: API is operational.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          description: Unauthorized - Api-Key incorrect.
        '403':
          description: Forbidden - Not authenticated, Api-Key header missing.
        '500':
          description: Internal Server Error - The server encountered an unexpected condition.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                
  /pdf_documents:
    post:
      summary: Uploading files
      description: This endpoint uploads PDFs. Only PDFs marked as 'Ready' can be queried. Documents can receive tags for easier identification and to facilitate survey launches. PDFs tagged similarly are typically queried together in the same survey.
      operationId: uploadPdfs
      tags:
        - PDF Management
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                pdfs:
                  type: array
                  uniqueItems: true
                  minItems: 1 
                  items:
                    $ref: '#/components/schemas/PdfDocument'
                  required: true
      responses:
        '200':
          description: PDFs are being processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PdfDocumentUploadResponse'
        '400':
			    description: Bad Request - The request could not be understood by the server due to malformed syntax.
			    content:
			      application/json:
			        schema:
			          $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - 'Api-Key' incorrect.
        '403':
          description: Forbidden - Not authenticated, Api-Key header missing.
        '429':
				  description: Too Many Requests - The request has been rejected due to quota exceeded or rate limit reached. Please contact Wequity Team for rate limits and quota information.
				  content:
				    application/json:
				      schema:
				        $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /pdf_documents/status:
    post:
      summary: View uploaded files
      description: This endpoint is used to list the PDFs ready to be queried and to get the status of the PDFs that are being processed.
      operationId: listIndexedPdfs
      tags:
        - PDF Management
      security:
        - ApiKeyAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                document_status:
                  type: array
				          items:
				            type: string
				            enum:
				              - Ready
				              - Processing
				              - Error
				          description: An array of statuses as strings, where each string must be one of the predefined values. Only documents with one of these statuses will be queried. Consider all document statuses by default.
	                default : ["Ready", "Processing", "Error"]
                tags:
                  type: array
                  uniqueItems: true
                  items:
                    type: string
                  description: Array of tags for filtering the documents.
      responses:
        '200':
          description: Array of PDFs status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PdfDocumentListResponse'
        '400':
			    description: Bad Request - The request could not be understood by the server due to malformed syntax.
			    content:
			      application/json:
			        schema:
			          $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Api-Key incorrect.
        '403':
          description: Forbidden - Not authenticated, 'Api-Key' header missing.
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

/survey_autofills:
    post:
      summary: Launch pre-filling of a questionnaire
      description: This endpoint initiates the pre-filling of a questionnaire.
      operationId: launchSurveyAutofill
      tags:
        - Survey Management
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              anyOf:
	              - required: ["document_names", "questions"]
	              - required: ["tags", "questions"]
              properties:
                tags:
                  type: array
                  uniqueItems: true
                  items:
                    oneOf:
                      - type: string
                      - type: array
                        items:
                          type: string
                  description: >
                    A array of tags or a array of lists of tags. Each item initiates a different survey.
                    Documents associated with these tags, along with those provided in 'document_names', will form the knowledge base for each survey.
                document_names:
                  type: array
                  items:
                    type: string
                  description: A array of document names to be included in the knowledge base.
                survey_name_prefix:
                  type: string
                  maxLength : 50
                  description: A prefix for survey names for easier identification, followed by tags and the launch timestamp.
                questions:
                  type: array
                  items:
                    $ref: '#/components/schemas/Question'
      responses:
        '200':
          description: Surveys launched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SurveyLaunchResponse'
        '400':
			    description: Bad Request - The request could not be understood by the server due to malformed syntax.
			    content:
			      application/json:
			        schema:
			          $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Api-Key incorrect.
        '403':
          description: Forbidden - Not authenticated, 'Api-Key' header missing.
        '429':
				  description: Too Many Requests - The request has been rejected due to quota exceeded or rate limit reached. Please contact Wequity Team for rate limits and quota information.
				  content:
				    application/json:
				      schema:
				        $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

	/survey_autofills/status:
    post:
      summary: Get pre-filling status & results
      description: This endpoint retrieves the status and results of previously initiated questionnaires.
      operationId: getSurveyAutofillStatus
      tags:
        - Survey Management
      security:
        - ApiKeyAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                survey_ids:
                  type: array
                  items:
                    type: string
                    format : uuid
                  description: Array of survey UUIDs to fetch status from. If null, all surveys will be considered.
                survey_name_prefix:
                  type: string
                  description: Retrieve surveys with names starting with this string. Acts as an OR operation with survey_ids.
                include_answers:
                  type: boolean
                  description: If false, only the status and metadata of the surveys are retrieved, excluding the results and answers.
	                default : false
                survey_status:
                  type: array
				          items:
				            type: string
				            enum:
				              - Done
				              - Autofilling
				              - Dispatching
				              - Error
				          description: An array of statuses as strings, where each string must be one of the predefined values. Only surveys with one of these autofill statuses will be queried. Consider all surveys statuses by default.
	                default : ["Done", "Autofilling", "Dispatching", "Error"]
                sharing_email:
                  type: string
                  description: If provided, a Google Sheet with all results is created and shared with this email. Null to not create a sheet.
						  if:
					      anyOf:
					        - properties:
					            sharing_email:
					              minLength: 1
					        - properties:
					            include_answers:
					              const: true
					    then:
					      oneOf:
					        - required: ["survey_ids"]
					          properties:
					            survey_ids:
					              minItems: 1
					        - required: ["survey_prefix_name"]
					          properties:
					            survey_prefix_name:
					              minLength: 1
							          
      responses:
        '200':
          description: Survey status and results successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SurveyStatusResponse'
        '400':
			    description: Bad Request - The request could not be understood by the server due to malformed syntax.
			    content:
			      application/json:
			        schema:
			          $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Api-Key incorrect.
        '403':
          description: Forbidden - Not authenticated, 'Api-Key' header missing.
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKeyAuth: []

components:
	securitySchemes:
	    ApiKeyAuth:
	      type: apiKey
	      in: header
	      name: Api-Key
  schemas:
		StatusResponse:
		  type: object
		  properties:
		    status:
		      type: string
		      example: "ok"
		      description: The status of the request, typically indicating success or failure.
		    questions_asked:
		      type: integer
		      description: The total number of questions asked across all surveys launched with these credentials.
		    questions_remaining:
		      type: integer
		      description: The number of questions that can still be asked with the current credits. For more information on credit allocation and policies, please consult the Wequity Team.
		    pdf_documents_uploaded:
		      type: integer
		      description: The total number of PDF documents uploaded using these credentials.
		    pdf_documents_remaining:
		      type: integer
		      description: The number of PDF documents that can be uploaded with the current credits. For more details on credit usage and limits, reach out to the Wequity Team.
		    last_update_dt:
		      type: string
		      format: date-time
		      nullable : true
		      description: The date and time of the last operation that used credits. Null if no operation yet.
          
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: A brief, human-readable message about the error.
                 
    PdfDocument:
      type: object
      properties:
        name:
          type: string
          description: The unique name of the document. It should end with .pdf. If a document exists with the same name, it will be overwritten.
          pattern: '.*\\.pdf
apos;
          required : true
        url:
          type: string
          description: Reference to the link where the document is publicly available. It should start with https://.
          pattern: '^https://.*'
          required : true
        tag:
          type: string
          description: A tag attached to the document. If a tag requires changing, you will need to reindex the PDF.
          
    PdfDocumentUploadResponse:
      type: object
      properties:
        n_docs:
          type: integer
          description: The amount of PDFs that are being processed.
          
		PdfDocumentListResponse:
		  type: object
		  description: Response object containing information about PDFs.
		  properties:
		    n_ready:
		      type: integer
		      description: Number of PDFs in 'Ready' status.
		    n_processing:
		      type: integer
		      description: Number of PDFs in 'Processing' status.
		    n_error:
		      type: integer
		      description: Number of PDFs in 'Error' status.
		    pdfs_status:
		      type: array
		      description: Array of PDFs status.
		      items:
		        $ref: '#/components/schemas/PdfStatus'

		PdfDocumentStatus:
		  type: object
		  description: Status information about a PDF.
		  properties:
		    name:
		      type: string
		      description: Name of the PDF.
		    status:
		      type: string
		      description: Status of the PDF.
		      enum :
		        - Ready
		        - Error
		        - Processing
		    launched_dt:
		      type: string
		      format: date-time
		      description: Date and time when the PDF was launched.
		    indexed_dt:
		      type: string
		      format: date-time
		      description: Date and time when the PDF was indexed.
		      nullable: true
		    tag:
		      type: string
		      description: Tag associated with the PDF.
		      nullable : true

		Question:
		  type: object
		  description: Information about a survey question.
		  properties:
		    question:
		      type: string
		      description: The question text.
		      maxLength : 500
		      required: true
		    output_choices:
		      type: array
		      minItems : 2
		      maxItems : 30
		      description: Array of choices for the answer to the question (if any).
		      items:
		        type: string
		        maxLength : 400
		    multiple_answers:
		      type: boolean
		      description: Indicates if multiple answers are allowed for the question.
		      default : False
		  if:
		    properties:
		      multiple_answers:
		        const: true
		  then:
		    properties:
		      output_choices:
		        minItems: 2
		        nullable: false

		SurveyLaunchResponse:
		  type: object
		  description: Response object after launching a survey.
		  properties:
		    total_questions:
		      type: integer
		      description: Total number of questions in the survey.
		    total_surveys:
		      type: integer
		      description: Total number of surveys launched.
		    surveys_info:
		      type: array
		      description: Information about each launched survey.
		      items:
		        $ref: '#/components/schemas/SurveyInfo'
		    survey_ids:
		      type: array
		      description: Array of survey IDs.
		      items:
		        type: string
		        format : uuid
		        readOnly : true

		SurveyInfo:
		  type: object
		  description: Information about a survey.
		  properties:
		    n_questions:
		      type: integer
		      description: Number of questions in the survey.
		    n_pdfs:
		      type: integer
		      description: Number of PDFs in the survey.
		    survey_name:
		      type: string
		      description: Name of the survey.
		    survey_id:
		      type: string
		      format : uuid
		      description: UUID of the survey.
		      readOnly : true
		      

		SurveyStatusResponse:
		  type: object
		  description: Response object containing status information about surveys.
		  properties:
		    last_update_dt:
		      type: string
		      format: date-time
		      nullable : true
		      description: Date and time of the last update. Null if empty result.
		    total_surveys:
		      type: integer
		      description: Total number of surveys.
		    progress_surveys:
		      type: string
		      format : float
		      description: Progress of surveys (as a percentage).
		      example : 0.99
		    survey_errors:
		      type: integer
		      description: Number of survey errors.
		    total_questions:
		      type: integer
		      description: Total number of questions.
		    progress_questions:
		      type: number
		      format : float
		      description: Progress of questions (as a percentage).
		      example : 0.97
		    found_rate:
		      type: number
		      format : float
		      description: Rate of finding answers (as a percentage).
		      example : 0.82
		    total_questions_error:
		      type: integer
		      description: Number of questions with errors.
		    link_to_results:
		      type: string
		      format: uri
		      description: Link to survey results.
		    qa_results:
		      type: array
		      description: Results of survey QA.
		      items:
		        $ref: '#/components/schemas/SurveyQA'

		SurveyQA:
		  type: object
		  description: QA results of a survey.
		  properties:
			  survey_id:
		      type: string
		      format : uuid
		      description: UUID of the survey.
		    survey_name:
		      type: string
		      description: Name of the survey.
		    launch_dt:
		      type: string
		      format: date-time
		      description: Date and time when the survey was launched.
		    finish_dt:
		      type: string
		      format: date-time
		      description: Date and time when the survey was finished. null if status is 'Processing'.
		      nullable: true
		    total_questions:
		      type: integer
		      description: Total number of questions in the survey.
		    error:
		      type: integer
		      description: Number of errors encountered.
		    autofill_status:
		      type: string
		      description: Status of autofill process.
		      enum :
		        - Dispatching
		        - Processing
		        - Done
		        - Error
		    progress:
		      type: string
		      format : float
		      description: Progress of the survey (as a percentage).
		      example : 1.0
		    found_rate:
		      type: number
		      format : float
		      description: Rate of finding answers (as a percentage).
		      example : 0.84
		    document_queried:
		      type: array
		      description: Array of queried documents.
		      items:
		        type: string
		    questions_error:
		      type: integer
		      description: Number of questions with errors.
		    qa_data:
		      type: array
		      description: Array of answers.
		      items:
		        $ref: '#/components/schemas/QAData'
		      nullable: true

	
		QAData:
		  type: object
		  description: Answer to a survey question.
		  properties:
		    question:
		      type: string
		      description: The question.
		    answers:
		      type: array
		      items :
			      type : string
		      description: The array of answers to the question. If multiple_answers is set to false, the array will contain only one item (if not null). If mutliple_answers is set to true, all items should be part of the given output_choices, if possible.
		      nullable: true
		    rationale_and_sources:
		      type: string
		      description: Rationale and sources for the answer.
		      nullable : true
		    confidence_level:
		      type: string
		      description: Confidence level of the answer. If the answer is not found, the confidence level is non applicable and will be 'Answer not found'.
		      enum :
		        - Low
		        - Medium
		        - High
		        - Answer not found
		    answered:
		      type: boolean
		      description: Indicates if the question was answered.
		    answered_dt:
		      type: string
		      format: date-time
		      description: Date and time when the question was answered.
		      nullable: true
		    error:
		      type: boolean
		      description: Indicates if an error occurred while answering the question.
		    error_message:
		      type: string
		      description: Error message, if applicable.
		      nullable: true
		    additional_guidance :
			    type : string
			    description : This provides additional guidance on how to refine and improve answers. If an answer isn't found, it can potentially lead you to one. This is for guidance purposes only.
			    nullable : true
			  sources :
				  type : array
				  items : 
		        $ref: '#/components/schemas/AnswersSources'
		        
		AnswersSources:
			type: object
		  description: Sources for the relevant documents and pages where the answer was found.
		  properties:
		    document_name: 
			    type : string
			    description : Name of the source document.
			  pages :
				  type : array
				  description : Relevant pages within the document where first page of the document is 1.
				  items :
					  type : integer