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.

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.

string

UUID of the user who created the analysis.

string

Title extracted from the tender document by the AI model.

string

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

string

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

string

ISO 8601 timestamp of when the analysis was created.

string

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

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.

string

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

string

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

string

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

object

Location of the requirement in the original document.

Show source fields

number

1-based page number where the requirement was found.

number

Optional. Paragraph index within the page.

string

Short surrounding text for context.

string[]

Keywords extracted by the AI to assist with proposal matching.

number

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

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

string

UUID of the Requirement this result corresponds to.

string

One of MET, NOT_MET, PARTIALLY_MET, or AMBIGUOUS.

string

AI-generated explanation of why the status was assigned.

number

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

object

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

Show evidence fields

string

Extracted text from the proposal.

number

Page in the proposal where the evidence was found.

string

Optional. URL of the source file if applicable.

object

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

Show manualOverride fields

boolean

Whether this result has been manually overridden.

string

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

string

Reviewer’s justification for the override.

string

ISO 8601 timestamp of when the override was applied.

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.

object

Optional processing metadata.

Show metadata fields

number

Total number of pages in the uploaded document.

number

Total time in milliseconds taken by the AI analysis pipeline.

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.

​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

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