> ## Documentation Index
> Fetch the complete documentation index at: https://developers.harvey.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Intake

> Submit legal requests into Harvey from your own systems and track them

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.

> [!NOTE]
>
> Rate limits are applied per workspace, per minute: **30** for submitting a request and **60** for reading one.

```bash theme={null}
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](mailto: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:

```bash theme={null}
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"
```

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

```bash theme={null}
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.

```bash theme={null}
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.

```json theme={null}
{
  "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.


## Related topics

- [Create Request](https://developers.harvey.ai/api-reference/intake/create-request.md)
- [Get Request](https://developers.harvey.ai/api-reference/intake/get-request.md)
- [Audit Logs](https://developers.harvey.ai/guides/audit_logs.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.