# Integration guide

This guide walks you, or an AI agent working for you, through a complete phone collection with the Hearsay API:

1. Sign in, or create an account, and choose your organization.
2. Create a case.
3. Create an extraction code and send it to the custodian.
4. Read and tag the messages collected from the custodian's phone.
5. Export the collected phone data (Android and iOS).

The topics below describe the steps and the rules. The exact request fields, response shapes and status codes are in the endpoint reference on this site, which is the source of truth for field names and types.

> info
> **Using an AI agent?** Give it this guide and the OpenAPI definition of this API. Tell it to treat the definition as the source of truth for field names and types, and to follow the "Safety rules for AI agents" topic.

## How a collection flows

```mermaid
flowchart TD
  A[Sign in and choose the organization] --> B[Create a case]
  B --> C[Create an extraction code]
  C --> D[Custodian enters the code in the Hearsay desktop app and uploads the phone data]
  D --> E[Poll the data status until the phone source is completed]
  E --> F[Optional: read and tag messages]
  F --> G[Start an export]
  G --> H[Poll the export until it is completed]
  H --> I[Download the file]
```

Your integration cannot collect phone data itself. It creates the code, delivers it, and waits for the custodian to upload.

## End-to-end checklist

1. Log in (or register). Store the access and refresh tokens securely.
2. Read `userProfile.userOrganizations` and pick the organization. Send its id as the `organization` header from now on.
3. `POST /case` creates the case. Save the case id from `data.case.id`.
4. `POST /case/{caseId}/extraction` with the custodian, `requestedSources` (`ios`, `android` or both) and `sendEmail: true`. Save the code from `data.code`.
5. Poll `GET /case/{caseId}/data-status-v2` until the phone source is completed and has items. Note its `sourceId`: that is the device id.
6. Optional: list the conversations and messages, create case tags, and tag the relevant messages in bulk.
7. `POST /case/{caseId}/export` with `source: conversation`, a `type`, `sortBy` and `device` (plus `tags` if you tagged). Save the export id from `data.id`.
8. Poll `GET /case/{caseId}/export?exportId=…` until `status` is `completed`, or stop on `failed`.
9. Get a signed URL for the export's `file.id` and download the file.

## Fields to leave alone

Some request and response models contain fields you will not need, such as payment fields and billing summaries. Leave those alone unless Hearsay tells you otherwise.


## Example
The calls of a full collection, in order:

```
POST /auth/login
POST /case
POST /case/{caseId}/extraction
GET  /case/{caseId}/data-status-v2          # poll
GET  /conversation/search                   # optional
POST /conversation/entries/tags/{caseId}/bulk   # optional
POST /case/{caseId}/export
GET  /case/{caseId}/export?exportId=...     # poll
GET  /common/file/{fileId}/signed-url
```