> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fortiseval.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Request a credential evaluation
> Order a diploma, course-by-course, or work experience evaluation through the API and track it with webhooks
export const EvaluationLifecycleDiagram = () => ;
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](/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](mailto:support@fortiseval.com) to turn it on.
Without it, you can still create quotes through the API and approve them in
the [Customer Portal](https://portal.fortiseval.com).
* 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.
Register your endpoint once and reuse it for every order. Subscribe to the
quote, order, and file events:
```bash theme={null}
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](/guides/webhooks#verifying-signatures).
Upload each diploma, transcript, or mark sheet with the [files API](/guides/files):
```bash theme={null}
curl https://api.fortiseval.com/v1/files \
-H "Authorization: Bearer sk-your-secret-key" \
-F "file=@/path/to/bachelor-diploma.pdf"
```
```json theme={null}
{
"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.
```bash theme={null}
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`:
```json theme={null}
{
"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](#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](/api-reference) has the full list of `visa_type` values.
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`:
```json theme={null}
{
"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`.
```bash theme={null}
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:
```json theme={null}
{
"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](/guides/quotes#approving-quotes) for the full list.
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.
Order events don't include documents, so fetch the order when you receive
`order.completed`:
```bash theme={null}
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:
```bash theme={null}
curl https://api.fortiseval.com/v1/documents/doc_Rm7cVd.../download \
-H "Authorization: Bearer sk-your-secret-key"
```
```json theme={null}
{
"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](/guides/webhooks#verifying-signatures).
```javascript Node.js theme={null}
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.