Tender API Endpoints: Analyze, Validate, History

TenderCheck AI exposes four tender endpoints, all mounted under /api/tenders. Every endpoint requires a valid JWT — supplied either as the token HttpOnly cookie or an Authorization: Bearer <token> header. File uploads use multipart/form-data; the server accepts only PDF documents up to 50 MB.

POST /api/tenders/analyze

Uploads a public tender document (pliego de condiciones) and runs AI analysis to extract all requirements. Returns a TenderAnalysis object with a populated requirements array. Auth required: Yes
Content-Type: multipart/form-data

Request fields

file

required

The tender PDF. Maximum size: 50 MB. Only application/pdf MIME type is accepted.

industry

string

Optional industry hint to guide AI extraction (e.g. "digital_services", "construction", "healthcare"). When omitted, the model infers context from the document.

curl example

curl -X POST https://tendercheckai.elecodes.online/api/tenders/analyze \
  -H "Authorization: Bearer <token>" \
  -F "file=@tender.pdf" \
  -F "industry=digital_services"

Success response — `201 Created`

{
  "id": "uuid",
  "userId": "user_uuid",
  "tenderTitle": "Extracted title from AI",
  "documentUrl": "",
  "status": "COMPLETED",
  "createdAt": "2025-01-15T10:00:00.000Z",
  "updatedAt": "2025-01-15T10:00:00.000Z",
  "requirements": [
    {
      "id": "req_uuid",
      "text": "El proveedor deberá contar con certificación ISO 27001",
      "type": "MANDATORY",
      "source": {
        "pageNumber": 5,
        "snippet": "...deberá contar con certificación..."
      },
      "keywords": ["ISO 27001", "certificación", "seguridad"],
      "confidence": 0.97
    }
  ],
  "results": [],
  "pageTexts": ["page 1 text...", "page 2 text..."]
}

documentUrl is always an empty string in the current release. The uploaded PDF is parsed in-memory and not persisted to storage — only the extracted analysis metadata, requirements, and validation results are saved to the database.

Error responses

Status	Reason
`400`	No file attached, non-PDF file type, or file exceeds 50 MB
`401`	Missing or invalid authentication token

POST /api/tenders/:id/validate-proposal

Uploads a vendor proposal PDF and validates it against the requirements extracted from a previously analyzed tender. Returns a ValidationResult for each requirement. Auth required: Yes
Content-Type: multipart/form-data

Path parameters

string

required

The UUID of the tender to validate against. Obtained from a prior /analyze response.

Request fields

file

required

The vendor proposal PDF to validate. Same constraints apply: PDF only, maximum 50 MB.

curl example

curl -X POST https://tendercheckai.elecodes.online/api/tenders/<tender_id>/validate-proposal \
  -H "Authorization: Bearer <token>" \
  -F "file=@proposal.pdf"

Success response — `200 OK`

{
  "status": "success",
  "results": [
    {
      "requirementId": "req_uuid",
      "status": "MET",
      "reasoning": "La oferta menciona certificación ISO 27001 válida hasta 2026",
      "confidence": 0.95,
      "evidence": {
        "text": "...ISO 27001...",
        "pageNumber": 3
      }
    }
  ]
}

ValidationStatus values

Each result’s status field is one of four values:

Value	Meaning
`MET`	The proposal clearly satisfies the requirement
`NOT_MET`	The proposal does not address the requirement
`PARTIALLY_MET`	The proposal partially addresses the requirement but gaps remain
`AMBIGUOUS`	The proposal contains conflicting or insufficient evidence to decide

Error responses

Status	Reason
`400`	No file attached or the PDF could not be parsed
`401`	Missing or invalid authentication token
`404`	No tender found with the given `id`

GET /api/tenders

Returns the analysis history for the currently authenticated user. The userId is read from the JWT — there are no query parameters. Auth required: Yes

curl example

curl https://tendercheckai.elecodes.online/api/tenders \
  -H "Authorization: Bearer <token>"

Success response — `200 OK`

An array of TenderAnalysis objects in the same shape as the /analyze response. The array is empty when the user has no prior analyses.

[
  {
    "id": "uuid",
    "userId": "user_uuid",
    "tenderTitle": "Licitación Pública No. 001-2025",
    "documentUrl": "",
    "status": "COMPLETED",
    "createdAt": "2025-01-15T10:00:00.000Z",
    "updatedAt": "2025-01-15T10:00:00.000Z",
    "requirements": ["..."],
    "results": ["..."],
    "pageTexts": ["..."]
  }
]

Error responses

Status	Reason
`401`	Missing or invalid authentication token

DELETE /api/tenders/:id

Permanently deletes a tender analysis record. Ownership is validated server-side — only the user whose userId matches tender.userId can delete it. Auth required: Yes

Path parameters

string

required

The UUID of the tender to delete.

curl example

curl -X DELETE https://tendercheckai.elecodes.online/api/tenders/<tender_id> \
  -H "Authorization: Bearer <token>"

Success response — `200 OK`

{
  "status": "success",
  "message": "Tender deleted"
}

Error responses

Status	Reason
`400`	Invalid or missing tender `id`
`401`	Missing or invalid authentication token
`403`	The authenticated user is not the owner of this tender (`tender.userId !== req.user.userId`)
`404`	No tender found with the given `id`

TenderAnalysis Response Schema

The following fields are returned by /analyze and each item in the GET / history array.

string

UUID that uniquely identifies this analysis. Used as the id path parameter in /validate-proposal and DELETE.

userId

string

UUID of the user who created the analysis.

tenderTitle

string

Title extracted from the tender document by the AI model.

documentUrl

string

Reserved for a future PDF storage URL. Currently always an empty string.

status

string

Processing state of the analysis. One of PENDING, PROCESSING, COMPLETED, or FAILED.

createdAt

string

ISO 8601 timestamp of when the analysis was created.

updatedAt

string

ISO 8601 timestamp of the last update (e.g. when validation results are written).

requirements

Requirement[]

Array of requirements extracted from the tender document by the AI. Populated after a successful /analyze call.

Show Requirement object fields

string

UUID for this specific requirement.

text

string

The raw requirement text as it appears (or was paraphrased) from the document.

normalizedText

string

Optional. Cleaned-up version of the requirement text used internally for processing.

type

string

Requirement classification. One of MANDATORY, OPTIONAL, or UNKNOWN.

source

object

Location of the requirement in the original document.

Show source fields

pageNumber

number

1-based page number where the requirement was found.

paragraph

number

Optional. Paragraph index within the page.

snippet

string

Short surrounding text for context.

keywords

string[]

Keywords extracted by the AI to assist with proposal matching.

confidence

number

AI confidence score (0.0 – 1.0) that this passage is indeed a requirement.

results

ValidationResult[]

Array of validation results produced by /validate-proposal. Empty after /analyze — results are only populated once a proposal has been validated against this tender.

Show ValidationResult object fields

requirementId

string

UUID of the Requirement this result corresponds to.

status

string

One of MET, NOT_MET, PARTIALLY_MET, or AMBIGUOUS.

reasoning

string

AI-generated explanation of why the status was assigned.

confidence

number

AI confidence score for this validation decision (0.0 – 1.0).

evidence

object

Optional. The passage in the proposal that supports (or contradicts) the requirement.

Show evidence fields

text

string

Extracted text from the proposal.

pageNumber

number

Page in the proposal where the evidence was found.

fileUrl

string

Optional. URL of the source file if applicable.

manualOverride

object

Optional. A human reviewer’s override of the AI decision.

Show manualOverride fields

isOverride

boolean

Whether this result has been manually overridden.

newStatus

string

The reviewer’s assigned status. One of MET, NOT_MET, PARTIALLY_MET, or AMBIGUOUS.

comment

string

Reviewer’s justification for the override.

updatedAt

string

ISO 8601 timestamp of when the override was applied.

pageTexts

string[]

Array of full page text strings extracted from the tender PDF, one entry per page. Used by the frontend to display source citations inline.

metadata

object

Optional processing metadata.

Show metadata fields

pageCount

number

Total number of pages in the uploaded document.

processingTimeMs

number

Total time in milliseconds taken by the AI analysis pipeline.

modelVersion

string

Identifier of the AI model version used for extraction.

The documentUrl field is always an empty string in the current release. The uploaded PDF is parsed in-memory and not persisted to storage — only the extracted analysis metadata, requirements, and validation results are saved to the database.

Overview

Endpoints

Tender API Endpoints: Analyze, Validate, History

POST /api/tenders/analyze

Request fields

curl example

Success response — `201 Created`

Error responses

POST /api/tenders/:id/validate-proposal

Path parameters

Request fields

curl example

Success response — `200 OK`

ValidationStatus values

Error responses

GET /api/tenders

curl example

Success response — `200 OK`

Error responses

DELETE /api/tenders/:id

Path parameters

curl example

Success response — `200 OK`

Error responses

TenderAnalysis Response Schema

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​POST /api/tenders/analyze

​Request fields

​curl example

​Success response — 201 Created

​Error responses

​POST /api/tenders/:id/validate-proposal

​Path parameters

​Request fields

​curl example

​Success response — 200 OK

​ValidationStatus values

​Error responses

​GET /api/tenders

​curl example

​Success response — 200 OK

​Error responses

​DELETE /api/tenders/:id

​Path parameters

​curl example

​Success response — 200 OK

​Error responses

​TenderAnalysis Response Schema

Build docs developers (and LLMs) love

POST /api/tenders/analyze

Request fields

curl example

Success response — `201 Created`

Error responses

POST /api/tenders/:id/validate-proposal

Path parameters

Request fields

curl example

Success response — `200 OK`

ValidationStatus values

Error responses

GET /api/tenders

curl example

Success response — `200 OK`

Error responses

DELETE /api/tenders/:id

Path parameters

curl example

Success response — `200 OK`

Error responses

TenderAnalysis Response Schema