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.

How a collection flows

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.