Intake

Harvey’s Intake APIs let your systems raise legal requests in Harvey and follow them to completion, routed exactly as requests raised in the product are. Submit a request with the documents it concerns, store the id you get back, then read the request for its status, assignee, and attachments.

Rate limits are applied per workspace, per minute: 30 for submitting a request and 60 for reading one.

POST /api/v1/intake/requests
GET  /api/v1/intake/requests/{request_id}

Overview

A request is submitted once and worked asynchronously inside Harvey by a reviewer or by Harvey’s routing agent. Submitting returns immediately with a request_id; everything after that is read through the request.

Key Capabilities

Raise Requests From Your Own Systems: Push work into Harvey from a ticketing system, intranet form, or service desk, with the documents it concerns attached
Safe to Retry: Every submission is keyed on an idempotency key of your choosing, so a retried call never raises the same request twice
Track to Completion: Read status, assignee, due date, and attachments as they change in Harvey

Before You Start

The Intake API must be enabled for your workspace. Until it is, every endpoint returns 404 rather than an authorization error. Contact your Account Manager or reach out to us at support@harvey.ai to request it. Your token needs the Intake permissions, set in the API Tokens section of your workspace settings. Intake must also be configured for your workspace, with somewhere for incoming requests to land. A workspace with the API enabled but no Intake configuration returns 404 on submission, with the message Intake is not configured for this workspace. API tokens act as your workspace’s service user rather than as the person who created the token, so reads return the requests that service user may see — judged exactly as the Intake product judges them.

The Request Cycle

Submit the request, store its request_id, then read it when you need its progress:

curl -X POST "https://api.harvey.ai/api/v1/intake/requests" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -F "idempotency_key=ticket-48213" \
  -F "title=Review the Northwind master services agreement" \
  -F "description=Counterparty sent back redlines on termination and liability." \
  -F "files=@northwind-msa.pdf"

{
  "request_id": "6b5d8f02-4c1a-4f8e-9a77-2d0c3e5b1a94",
  "status": "RECEIVED",
  "harvey_url": "https://app.harvey.ai/intake/requests/6b5d8f02-4c1a-4f8e-9a77-2d0c3e5b1a94"
}

curl "https://api.harvey.ai/api/v1/intake/requests/6b5d8f02-4c1a-4f8e-9a77-2d0c3e5b1a94" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

Store the request_id it returns — it is the only handle you get on the request, and how you read it back.

Use Cases

Use Case 1: Raise Requests From a Ticketing System

Challenge: Legal work arrives as tickets, emails, and intranet form submissions, and someone has to retype each one into Harvey before it can be worked. Solution: Submit the request from the system that received it, carrying your own ticket reference as the idempotency key.

POST /api/v1/intake/requests

Send up to 50 files, and up to 100 MB per file for most types. If any file’s type or size is not accepted, the entire request is refused and nothing is created, so a request never silently loses a document.

Use Case 2: Retry Without Duplicating Work

Challenge: A network timeout leaves your integration unsure whether Harvey took the request, and retrying risks two identical requests landing in the queue. Solution: Pass a stable idempotency_key — your own ticket id works well. The first call returns 201; a retry carrying the same key returns 200 and names the original request without creating a second one. Both responses have the same body, so your integration can treat them identically. If an earlier submission under that key is in a state Harvey cannot return, the call returns 409; retrying the same key will not resolve it, so submit under a new key.

Use Case 3: Report Progress Back to Your Own System

Challenge: Requesters work in the ticketing system, not in Harvey, and keep asking where their request stands. Solution: Read the request and mirror what it reports — status, assignee, due_at, and completed_at — onto the ticket.

{
  "request_id": "6b5d8f02-4c1a-4f8e-9a77-2d0c3e5b1a94",
  "status": "IN_PROGRESS",
  "title": "Review the Northwind master services agreement",
  "due_at": "2026-10-16",
  "completed_at": null,
  "assignee": { "type": "USER", "name": "Dana Whitfield" },
  "attachments": [
    { "file_id": "66fead63-460e-4426-a179-39c70b224a99", "name": "northwind-msa.pdf" }
  ]
}

assignee.type is AGENT while Harvey’s routing agent holds the request and USER once a person does. To hand the request to someone instead, link them to harvey_url. This endpoint reads any request your token’s user can see, whatever submitted it — requests raised in Harvey directly or arriving by email, not only those this API created.

Best Practices

Poll on Terminal Status

Read status and stop when it is DONE or CANCELLED. Do not treat a 200 as meaning the request has finished — an open request returns 200 as well. A 429 carries a Retry-After header giving the seconds to wait. Honor it rather than retrying immediately.

Switch on Validation Codes

A submission rejected on its fields returns 422 with a details array naming every field at fault. Switch on details[].code rather than matching message text, which is localized and may change.

Write Self-Contained Requests

Avoid: “See attached”
Use: “Review the attached MSA against our standard positions. Flag any deviation on termination, liability, or indemnity that needs partner sign-off.”

Titles can be up to 255 characters and descriptions up to 10,000.

Error Handling

The Intake APIs use standard HTTP status codes. A request your workspace cannot reach returns 404 rather than 403 — one 404 covers a request that does not exist, one belonging to another workspace, one you lack access to, and a workspace without the Intake API enabled. A token that lacks the Intake permission returns 401, not 403. The 403 is narrower: Intake accepted the call but refused the request while routing it, because your token’s service user is not a member of your workspace’s Intake space.

Status Code	Description	Example Error Message
200	Success – Request read, or submission replayed	N/A
201	Created – Request submitted	N/A
400	Bad Request – A document was rejected, or too many files	`{ "error": "Upload failed. File northwind-msa.pdf exceeds maximum size of 100MB." }`
401	Unauthorized – Invalid token, or one lacking the Intake permission	`{ "error": "User does not have permission to create Intake requests" }`
403	Forbidden – Intake refused the request while routing it	`{ "error": "User does not have permission to create Intake requests" }`
404	Not Found – Request not reachable, or Intake not configured	`{ "error": "Request not found." }`
409	Conflict – An earlier submission under this key cannot be returned	`{ "error": "The original request is no longer available." }`
422	Unprocessable Content – A form field is missing, empty, or too long	`{ "error": "Invalid request", "details": [ ... ] }`
429	Too Many Requests – Rate limit exceeded	`{ "error": "Too many requests. Retry after 30 seconds." }`
500	Internal Server Error	N/A

Submissions rejected on their form fields return one of these codes per field in details:

Code	Cause
`missing`	A required field — `idempotency_key` or `title` — was not sent
`string_too_short`	`idempotency_key` or `title` was sent empty
`string_too_long`	`title` is over 255 characters, or `description` over 10,000
`value_error`	`idempotency_key` was whitespace only

Need help getting started? Contact your Harvey Customer Success Manager for more information.

Getting Started

Endpoint Overview

MCP (Beta)

Overview

Key Capabilities

Before You Start

The Request Cycle

Use Cases

Use Case 1: Raise Requests From a Ticketing System

Use Case 2: Retry Without Duplicating Work

Use Case 3: Report Progress Back to Your Own System

Best Practices

Poll on Terminal Status

Switch on Validation Codes

Write Self-Contained Requests

Error Handling

​Overview

​Key Capabilities

​Before You Start

​The Request Cycle

​Use Cases

​Use Case 1: Raise Requests From a Ticketing System

​Use Case 2: Retry Without Duplicating Work

​Use Case 3: Report Progress Back to Your Own System

​Best Practices

​Poll on Terminal Status

​Switch on Validation Codes

​Write Self-Contained Requests

​Error Handling

Overview

Key Capabilities

Before You Start

The Request Cycle

Use Cases

Use Case 1: Raise Requests From a Ticketing System

Use Case 2: Retry Without Duplicating Work

Use Case 3: Report Progress Back to Your Own System

Best Practices

Poll on Terminal Status

Switch on Validation Codes

Write Self-Contained Requests

Error Handling