Request a credential evaluation

This guide covers the full flow: you upload a candidate’s academic documents, request a quote, approve it, and download the finished evaluation report. Webhooks tell you when each step happens, so you don’t need to poll.

Before you begin

You need:

An Internal app API key (sk-...). See Authentication. The flow uses the files:write, quotes:write, quotes:approve, orders:read, documents:read, and webhooks:manage scopes.
Net-terms invoicing on your account if you want to approve quotes through the API. Contact support to turn it on. Without it, you can still create quotes through the API and approve them in the Customer Portal.
An HTTPS endpoint that can receive webhooks.

Choose an evaluation type

Set evaluation_type on the quote to one of these values:

`evaluation_type`	What you get
`diploma_evaluation`	The U.S. equivalency of each degree or diploma
`course_by_course_evaluation`	Every course listed with U.S. semester credits and grades, plus a GPA
`work_experience_evaluation`	An equivalency based on professional experience, for candidates whose work history substitutes for education

Most employment and H-1B cases need a diploma_evaluation. Licensing boards, universities, and credit transfers usually need a course_by_course_evaluation. If you’re not sure, add a question in notes and our team will confirm before pricing the quote.

curl https://api.fortiseval.com/v1/webhook-endpoints \
  -H "Authorization: Bearer sk-your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/fortis",
    "events": ["quote.*", "order.*", "file.*"]
  }'

The response contains the endpoint’s signing secret (whsec_...). Store it somewhere safe. You need it to verify signatures.

Upload the candidate's documents

Upload each diploma, transcript, or mark sheet with the files API:

curl https://api.fortiseval.com/v1/files \
  -H "Authorization: Bearer sk-your-secret-key" \
  -F "file=@/path/to/bachelor-diploma.pdf"

{
  "message": "File uploaded successfully.",
  "data": {
    "id": "upload_3kR9vQ...",
    "status": "ready",
    "source": "direct_upload",
    "file_name": "bachelor-diploma.pdf",
    "mime_type": "application/pdf",
    "size": 482113
  }
}

Keep each id. If your documents are already hosted somewhere, skip this step and pass their URLs in document_urls when you create the quote.

Send the diploma and the transcript or mark sheets for every degree. A missing transcript is the most common reason a quote is delayed.

Create the quote

curl https://api.fortiseval.com/v1/quotes \
  -H "Authorization: Bearer sk-your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{
    "quote_type": "academic_evaluation",
    "evaluation_type": "course_by_course_evaluation",
    "turnaround": "standard",
    "document_ids": ["upload_3kR9vQ...", "upload_8pLm2X..."],
    "candidate": {
      "first_name": "Priya",
      "last_name": "Raman",
      "visa_type": "h1b"
    },
    "reference": "CASE-1042",
    "cc_emails": ["paralegal@example.com"]
  }'

The API responds with 201 and the new quote in status requested:

{
  "message": "Quote request created successfully.",
  "data": {
    "id": "quot_Wd81nZ...",
    "status": "requested",
    "quote_type": "academic_evaluation",
    "requested_turnaround": "standard",
    "total_cents": 0,
    "items": [],
    "documents": [
      { "id": "doc_Yt4sPa...", "file_name": "bachelor-diploma.pdf", "document_role": "source" },
      { "id": "doc_Jq2mRb...", "file_name": "transcript.pdf", "document_role": "source" }
    ],
    "requested_at": "2026-09-24T14:02:11+00:00"
  }
}

Evaluation fields:

Field	Required	Description
`quote_type`	Yes	`academic_evaluation`
`evaluation_type`	Yes	See Choose an evaluation type
`document_ids` / `document_urls`	Yes, at least one	Up to 50 documents in total
`turnaround`	No	`standard`, `expedited`, `next_day`, or `same_day` (rush)
`desired_equivalency`	No	The equivalency you need, such as `U.S. Bachelor of Science in Computer Science`
`translation_preference`	No	`client_provided` if you include translations, or `translation_service` for us to translate foreign-language documents
`candidate.first_name`, `middle_name`, `last_name`	No	The person being evaluated, as their name should appear on the report
`candidate.pronoun_type`	No	`masculine`, `feminine`, or `neutral`. Controls pronouns in the report
`candidate.visa_type`	No	The visa or petition the evaluation supports, such as `h1b`, `o1a`, `eb2_niw`, `eb3`, or `other`
`reference`	No	Your own case or matter ID
`notes`	No	Instructions for our team, up to 10,000 characters
`cc_emails`	No	Up to 10 addresses to copy on updates
`team`	No	A team token on your account

The API reference has the full list of visa_type values.

Wait for quote.ready

Our team reviews the documents and prices the quote. When it’s ready, the quote moves to awaiting_payment and your endpoint receives quote.ready:

{
  "id": "evt_01K5ZQ4T...",
  "type": "quote.ready",
  "api_version": "v1",
  "created": "2026-09-24T15:40:02+00:00",
  "data": {
    "object": {
      "id": "quot_Wd81nZ...",
      "status": "awaiting_payment",
      "quote_type": "academic_evaluation",
      "turnaround_label": "Standard",
      "total_cents": 18500,
      "total": "185.00",
      "items": [
        {
          "service_name": "Course-by-Course Evaluation",
          "quantity": 1,
          "price": 18500,
          "subtotal": 18500,
          "currency": "usd"
        }
      ],
      "expires_at": "2026-10-24T15:40:02+00:00"
    }
  }
}

Check total_cents and items before you approve. If the quote is cancelled, you receive quote.cancelled.

Approve the quote

curl -X POST https://api.fortiseval.com/v1/quotes/quot_Wd81nZ.../approve \
  -H "Authorization: Bearer sk-your-secret-key"

Approval creates the order and adds it to your open invoice. The response (201) is the new order:

{
  "message": "Quote approved successfully.",
  "data": {
    "id": "ord_Ka93Lx...",
    "status": "created",
    "quote_id": "quot_Wd81nZ...",
    "total": 18500,
    "currency": "usd"
  }
}

You also receive quote.approved and order.created. If approval fails, the API returns 422 with an error_code. See Approving quotes for the full list.

Track the order

The order sends an event each time its status changes:

Event	Order `status`	What it means
`order.created`	`created`	The order is queued
`order.in_progress`	`in_progress`	An evaluator is working on it
`order.ready_for_review`	`awaiting_review`	Deliverables are ready for your review
`order.completed`	`completed`	The final report is ready to download
`order.cancelled`	`cancelled`	The order was cancelled
`order.refunded`	`refunded`	The order was refunded

Use PUT /v1/orders/{id} to attach your own custom_reference or custom_metadata to the order at any point.

Download the report

Order events don’t include documents, so fetch the order when you receive order.completed:

curl https://api.fortiseval.com/v1/orders/ord_Ka93Lx... \
  -H "Authorization: Bearer sk-your-secret-key"

The order’s documents include the files you uploaded (document_role: "source") and the deliverables. Evaluation reports have document_role set to evaluation or course_evaluation. Request a download URL for each one:

curl https://api.fortiseval.com/v1/documents/doc_Rm7cVd.../download \
  -H "Authorization: Bearer sk-your-secret-key"

{
  "url": "https://...signed-download-url...",
  "file_name": "CBC-Raman-Course-by-Course-Evaluation.pdf",
  "mime_type": "application/pdf",
  "expires_at": "2026-09-30T18:12:44+00:00"
}

The URL expires after one hour. Download the file right away and store your own copy.

Put it together

This Express handler verifies each event, then approves quotes under a budget and downloads reports when orders complete. It uses the verifyFortisSignature function from the webhooks guide.

Node.js

import express from "express";

const app = express();
const API = "https://api.fortiseval.com/v1";
const headers = { Authorization: `Bearer ${process.env.FORTIS_API_KEY}` };
const AUTO_APPROVE_LIMIT_CENTS = 30000;

app.post(
  "/webhooks/fortis",
  express.raw({ type: "application/json" }), // keep the raw body for the signature
  async (req, res) => {
    const payload = req.body.toString("utf8");

    if (!verifyFortisSignature(payload, req.get("X-Fortis-Signature"), process.env.FORTIS_WHSEC)) {
      return res.sendStatus(400);
    }

    res.sendStatus(200); // acknowledge fast, then do the work

    const event = JSON.parse(payload);
    const object = event.data.object;

    if (event.type === "quote.ready" && object.total_cents <= AUTO_APPROVE_LIMIT_CENTS) {
      await fetch(`${API}/quotes/${object.id}/approve`, { method: "POST", headers });
    }

    if (event.type === "order.completed") {
      const order = await fetch(`${API}/orders/${object.id}`, { headers }).then((r) => r.json());
      const reports = order.documents.filter((d) =>
        ["evaluation", "course_evaluation"].includes(d.document_role),
      );

      for (const report of reports) {
        const { url, file_name } = await fetch(`${API}/documents/${report.id}/download`, { headers })
          .then((r) => r.json());
        await saveToCaseFile(object.custom_reference, file_name, url); // your code
      }
    }
  },
);

Deliveries can arrive out of order or more than once. Deduplicate on the X-Fortis-Delivery header. When you need the current state, fetch the resource from the API.

Without webhooks

If you can’t receive webhooks, poll instead:

GET /v1/quotes/{id} until status is awaiting_payment.
GET /v1/orders/{id} until status is completed.

Poll no more than once a minute. Evaluations take hours to days, depending on the turnaround you choose.

Getting Started

Guides

Before you begin

Choose an evaluation type

Put it together

Without webhooks

​Before you begin

​Choose an evaluation type

​Put it together

​Without webhooks

Before you begin

Choose an evaluation type

Put it together

Without webhooks