# OrgOrg API v1 — Documents — instructions for AI agents

This document describes the Documents endpoints of the OrgOrg v1 REST API. Fetch it from https://orgorg.com/docs/api/v1/documents/agents.md. The full API is documented at https://orgorg.com/docs/api/v1/agents.md.

## Basics

- Base URL: `https://orgorg.com`. All endpoint paths below are relative to it.
- Every request requires an `Authorization: Bearer <token>` header.
- `GET` endpoints take parameters in the URL query string. `POST` endpoints take a JSON body with a `Content-Type: application/json` header.
- All responses are JSON. A non-2xx status means the request failed; the body describes the problem.
- Endpoints are stable, but new response fields may be added without notice — ignore fields you do not recognize.

## Getting a token

Tokens are created by a signed-in user at https://orgorg.com/docs/credentials and inherit that user's permissions in their organization. If you do not have a token, ask your user to create one there. Verify a token works with:

```sh
curl "https://orgorg.com/api/v1/auth/test" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN"
```

A valid token returns `{ "ok": true, ... }`.

## Documents

The forms your org sends out for signature. List templates, send one to an email address, and import each signed form with its receipt and file. Human-readable docs: https://orgorg.com/docs/api/v1/documents

### List document templates

`GET /api/v1/documents/templates/list`

The forms your org sends out for signature, newest first. Requires documents:read (or :write).

Parameters: none.

Example request:

```sh
curl -X GET "https://orgorg.com/api/v1/documents/templates/list" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN"
```

Response shape:

```ts
{
  data: {
    id: string;
    name: string;
    fileName: string;
    sizeBytes: number;
    sha256: string;
    createdAt: number;
  }[]
}
```

### List signature requests

`GET /api/v1/documents/requests/list`

Every template sent to an email address that the owner of the token can open, newest first, with its state and, once signed, its receipt: the requests they sent, and the ones shared with them. Pass status=Signed and since=<ms> to import the forms signed after your last run. Requires documents:read (or :write).

Parameters:

- `status` (`Pending` | `Waiting` | `Signed` | `Declined` | `Expired` | `Cancelled`, optional) — Only requests in this state.
- `since` (number, optional) — Only requests updated at or after this time (milliseconds since the epoch).

Example request:

```sh
curl -X GET "https://orgorg.com/api/v1/documents/requests/list?status=Signed" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN"
```

Response shape:

```ts
{
  data: {
    id: string;
    templateId: string;
    templateName: string;
    fileName: string;
    signingUrl: string;
    recipientEmail: string;
    recipientName: string | null;
    message: string | null;
    status: 'Pending' | 'Waiting' | 'Signed' | 'Declined' | 'Expired' | 'Cancelled';
    packetId: string | null;
    signerOrder: number | null;
    signerCount: number | null;
    contactId: string | null;
    expiresAt: number | null;
    openedAt: number | null;
    remindedAt: number | null;
    decline: { reason: string | null; declinedAt: number } | null;
    signature: {
      legalName: string;
      consentText: string;
      consentVersion: number;
      documentSha256: string;
      signedAt: number;
      ipAddress: string | null;
      userAgent: string | null;
      fieldValues: { fieldId: string; kind: string; label: string; value: string; drawn: boolean }[];
    } | null;
    signedDocumentUrl: string | null;
    createdAt: number;
    updatedAt: number;
  }[]
}
```

### Get a signature request

`GET /api/v1/documents/requests/get`

One request that the owner of the token can open, with its receipt and a URL for the exact file that was signed. The URL is short-lived: download it right away. A request that is not shared with the owner reads as not found. Requires documents:read (or :write).

Parameters:

- `id` (string, required) — Request id (from /api/v1/documents/requests/list).

Example request:

```sh
curl -X GET "https://orgorg.com/api/v1/documents/requests/get?id=REQUEST_ID" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN"
```

Response shape:

```ts
{
  data: {
    id: string;
    templateId: string;
    templateName: string;
    fileName: string;
    signingUrl: string;
    documentUrl: string | null;
    recipientEmail: string;
    recipientName: string | null;
    message: string | null;
    status: 'Pending' | 'Waiting' | 'Signed' | 'Declined' | 'Expired' | 'Cancelled';
    packetId: string | null;
    signerOrder: number | null;
    signerCount: number | null;
    contactId: string | null;
    expiresAt: number | null;
    openedAt: number | null;
    remindedAt: number | null;
    decline: { reason: string | null; declinedAt: number } | null;
    signature: {
      legalName: string;
      consentText: string;
      consentVersion: number;
      documentSha256: string;
      signedAt: number;
      ipAddress: string | null;
      userAgent: string | null;
      fieldValues: { fieldId: string; kind: string; label: string; value: string; drawn: boolean }[];
    } | null;
    signedDocumentUrl: string | null;
    createdAt: number;
    updatedAt: number;
  }
}
```

### Send a template for signing

`POST /api/v1/documents/requests/send`

Email a template to an address with a link to read and sign it. The recipient needs no account. Requires documents:write.

Parameters:

- `templateId` (string, required) — Template id (from /api/v1/documents/templates/list).
- `email` (string, optional) — The address that receives the signing link. Required unless signers is given.
- `signers` (object, optional) — A JSON array of signers in signing order, each { email, name?, contactId? }, at most 6. Two or more make a packet: each signer gets the link when the one before has signed, and signs on top of their signature. The response names the first request and the packetId.
- `name` (string, optional) — The recipient name, used in the email and prefilled on the signing page.
- `message` (string, optional) — A note that appears in the email and on the signing page.
- `expiresInDays` (number, optional) — Whole days until the link stops working, 1 to 365. Defaults to 2 (48 hours). Pass null for a link that never expires.
- `contactId` (string, optional) — The CRM contact this goes to. The send, the signature, and a decline write activities on it. Without it, a contact with the same email is matched.

Example request:

```sh
curl -X POST "https://orgorg.com/api/v1/documents/requests/send" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "TEMPLATE_ID",
    "email": "signer@example.com",
    "name": "Alex Example"
  }'
```

Response shape:

```ts
{
  data: {
    id: string;
    signingUrl: string;
    status: 'Pending';
    packetId: string | null;
    signerCount: number | null;
  };
  created: true;
}
```