# Notary Connect

> Scheduling-platform integrations for signing services and title companies.

## OpenAPI specs
- [Notary Connect APIs](https://developers.snapdocs.com/content/notary-connect/specs/notary-connect-api.json)
(Specs are schemas, not prose — fetch the JSON directly rather than pasting it here.)

## Shared platform guides
Authentication, environments, webhooks, and testing are shared across every Snapdocs product — see [Getting Started](https://developers.snapdocs.com/platform/llms.txt).

## Guides

### Welcome to Notary Connect API

# Welcome to Notary Connect API

Welcome to the **Notary Connect API** — Snapdocs' integration solution for title and settlement companies to programmatically manage signing orders. With these APIs you can create and update orders, upload documents for the notary, track notary assignments, add comments, and download completed scanback documents.

The Notary Connect APIs use a simple token-based authentication model and support both JSON and XML response formats.

# Getting your API key

Notary Connect API keys are provisioned by Snapdocs and tied to your company or a specific client (title office branch) within your company. To obtain an API key:

1. **Contact your Snapdocs Customer Success Manager** and request a Notary Connect API key.
2. Your CS contact will generate the key and securely share the token with you.
3. Store the token securely — it grants full API access to orders under your company or client.

> 🚧 **Keep your API token secure**
>
> Your API token provides direct access to create and manage orders. Do not share it in client-side code, public repositories, or unencrypted channels. If you believe your token has been compromised, contact your Snapdocs Customer Success Manager immediately to have it revoked and reissued.

# API key types

There are two types of API keys, which affect the scope of data you can access:

| Key Type        | Scope                                                                                           | Notes                                                                                                              |
| :-------------- | :---------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------- |
| **Company Key** | Access to all orders, clients, and products across the entire company.                          | Can update order status (complete, cancel, etc.). Can specify `client_id` when creating orders. Can list comments. |
| **Client Key**  | Access limited to orders, products, and team members for a single client (title office branch). | Must provide `team_member_id` when creating orders. Cannot update order status. Cannot list comments.              |

Your CS contact will let you know which type of key you've been issued.

# Environments

Use our Demo Environment as any customer starting your integration. Once the integration is complete, you can then switch to Production Environment.

| ENV        | URL                             |
| ---------- | :------------------------------ |
| Demo       | <https://app.cs-demo0.snpd.io/> |
| Production | <https://app.snapdocs.com/>     |

# Base URL

All Notary Connect API requests should be made to:

```text Demo
https://app.cs-demo0.snpd.io/mobile_notary_api/v1/
```

# Authentication

Every API request must include your API token in the `X-AUTH-TOKEN` HTTP header.

```shell cURL Example
curl -X GET "https://app.cs-demo0.snpd.io/mobile_notary_api/v1/clients" \
  -H "X-AUTH-TOKEN: your_api_token_here" \
  -H "Content-Type: application/json"
```
```python Python Example
import requests

BASE_URL = "https://app.cs-demo0.snpd.io/mobile_notary_api/v1"
API_TOKEN = "your_api_token_here"

headers = {
    "X-AUTH-TOKEN": API_TOKEN,
    "Content-Type": "application/json"
}

response = requests.get(f"{BASE_URL}/clients", headers=headers)
print(response.json())
```
```javascript JavaScript Example
const BASE_URL = "https://app.cs-demo0.snpd.io/mobile_notary_api/v1";
const API_TOKEN = "your_api_token_here";

const response = await fetch(`${BASE_URL}/clients`, {
  method: "GET",
  headers: {
    "X-AUTH-TOKEN": API_TOKEN,
    "Content-Type": "application/json"
  }
});

const data = await response.json();
console.log(data);
```

If the token is missing, invalid, or has been revoked, the API returns a `401 Unauthorized` response with an empty body.

# Response format

The API supports both **JSON** (default) and **XML** response formats. The format is determined by the configuration of your API key at provisioning time — not by request headers. Your CS contact can configure this when creating your key.

| Format | Content-Type       | Notes                                                                                          |
| :----- | :----------------- | :--------------------------------------------------------------------------------------------- |
| `json` | `application/json` | Default format. Recommended for most integrations.                                             |
| `xml`  | `application/xml`  | For systems that require XML. Request bodies can be sent as XML with a root `<order>` element. |

# Available endpoints

The Notary Connect API provides the following endpoints:

| Endpoint                                      | Method | Description                                                                                        |
| :-------------------------------------------- | :----- | :------------------------------------------------------------------------------------------------- |
| [List clients](https://developers.snapdocs.com/notary-connect/reference/notary-connect-api/operations/ListClients)               | `GET`  | Retrieve clients with their products and team members. Use the returned IDs when creating orders.  |
| [List products](https://developers.snapdocs.com/notary-connect/reference/notary-connect-api/operations/ListProducts)             | `GET`  | Retrieve available signing products with detailed configuration (scanbacks, RON, witnesses, etc.). |
| [Create order](https://developers.snapdocs.com/notary-connect/reference/notary-connect-api/operations/CreateOrder)               | `POST` | Create a new signing order with signer details, signing location, and product selection.           |
| [Get order](https://developers.snapdocs.com/notary-connect/reference/notary-connect-api/operations/GetOrder)                     | `GET`  | Retrieve full order details including status, notary assignment, and attachments.                  |
| [Update order](https://developers.snapdocs.com/notary-connect/reference/notary-connect-api/operations/UpdateOrder)               | `PUT`  | Update order fields such as appointment date, signer info, or signing location.                    |
| [Update order status](https://developers.snapdocs.com/notary-connect/reference/notary-connect-api/operations/UpdateOrderStatus)  | `PUT`  | Complete, cancel, hold, or reactivate an order. **Company keys only.**                             |
| [Upload attachment](https://developers.snapdocs.com/notary-connect/reference/notary-connect-api/operations/UploadAttachment)     | `POST` | Upload a document to an order (multipart or base64).                                               |
| [Download attachment](https://developers.snapdocs.com/notary-connect/reference/notary-connect-api/operations/DownloadAttachment) | `GET`  | Download a document attachment (redirects to a temporary download URL).                            |
| [List comments](https://developers.snapdocs.com/notary-connect/reference/notary-connect-api/operations/ListComments)             | `GET`  | Retrieve all non-internal comments on an order. **Company keys only.**                             |
| [Create comment](https://developers.snapdocs.com/notary-connect/reference/notary-connect-api/operations/CreateComment)           | `POST` | Add a comment to an order with visibility controls.                                                |

# Next steps

Follow the Integration Workflow guides to learn the recommended order of API calls:

1. [Discover your configuration](https://developers.snapdocs.com/notary-connect/guides/guides/discover-your-configuration) — Retrieve clients, products, and team member IDs.
2. [Create orders](https://developers.snapdocs.com/notary-connect/guides/guides/create-orders) — Create signing orders with signer details.
3. [Upload documents](https://developers.snapdocs.com/notary-connect/guides/guides/upload-documents) — Upload closing documents for the notary.
4. [Monitor orders](https://developers.snapdocs.com/notary-connect/guides/guides/monitor-orders) — Track notary assignment and signing progress.
5. [Download & manage](https://developers.snapdocs.com/notary-connect/guides/guides/download-and-manage) — Download scanbacks, update status, and add comments.

Also review the [Errors guide](https://developers.snapdocs.com/notary-connect/guides/guides/errors) for error handling details, and explore the [API reference](https://developers.snapdocs.com/notary-connect/reference/notary-connect-api/operations/ListClients) for full endpoint documentation.

---
### Discover your configuration

# Discover your configuration

Before creating orders, you need to gather the IDs for your clients, products, and team members. These values are used as parameters when creating and managing orders. Call these endpoints once and cache the results — they change infrequently.

# List clients (with Products and Team members)

The [List clients](https://developers.snapdocs.com/notary-connect/reference/notary-connect-api/operations/ListClients) endpoint returns everything you need in a single call: client branches, their signing products, and team member (escrow officer) details.

```shell List Clients
curl -X GET "https://app.cs-demo0.snpd.io/mobile_notary_api/v1/clients" \
  -H "X-AUTH-TOKEN: your_api_token_here" \
  -H "Content-Type: application/json"
```

```json Response
{
  "clients": [
    {
      "id": 100,
      "company_name": "Acme Title - Downtown Branch",
      "products": [
        { "id": 50, "product_name": "Standard Loan Signing" },
        { "id": 51, "product_name": "Reverse Mortgage Signing" }
      ],
      "team_members": [
        { "id": 200, "full_name": "Sarah Johnson", "email": "sarah@acmetitle.com" },
        { "id": 201, "full_name": "Mike Williams", "email": "mike@acmetitle.com" }
      ]
    }
  ]
}
```

**What to store from this response:**

| Value               | Use For                                                                                           |
| :------------------ | :------------------------------------------------------------------------------------------------ |
| `client.id`         | The `client_id` parameter when creating orders (company keys only).                               |
| `product.id`        | The `product_id` parameter when creating orders. Determines signing type and notary requirements. |
| `team_member.id`    | The `team_member_id` parameter when creating orders. Identifies the escrow officer responsible.   |
| `team_member.email` | Can be used as `owner_email` as an alternative to `team_member_id`.                               |

# List products

For more detailed product configuration — including scanback requirements, attorney/witness requirements, and RON signing settings — use the [List products](https://developers.snapdocs.com/notary-connect/reference/notary-connect-api/operations/ListProducts) endpoint:

```shell List Products
curl -X GET "https://app.cs-demo0.snpd.io/mobile_notary_api/v1/products?page=1&per_page=50" \
  -H "X-AUTH-TOKEN: your_api_token_here"
```

# Next step

Once you have your client, product, and team member IDs, proceed to [Create orders](https://developers.snapdocs.com/notary-connect/guides/guides/create-orders).

---
### Create orders

# Create orders

With your client, product, and team member IDs from [Discover your configuration](https://developers.snapdocs.com/notary-connect/guides/guides/discover-your-configuration), you're ready to create signing orders. This page covers the standard order creation flow, co-signer support, and adding observers.

# Create a regular order

Use the [Create Order](https://developers.snapdocs.com/notary-connect/reference/notary-connect-api/operations/CreateOrder) endpoint with the signer's information, signing appointment details, and the IDs you collected.

```shell Create Order
curl -X POST "https://app.cs-demo0.snpd.io/mobile_notary_api/v1/orders" \
  -H "X-AUTH-TOKEN: your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 50,
    "team_member_id": 200,
    "escrow_number": "ESC-2024-001234",
    "appointment_date": "2024-06-15",
    "appointment_time": "2:00 PM",
    "first_name": "Jane",
    "last_name": "Smith",
    "mobile_phone": "555-123-4567",
    "signer_email": "jane.smith@example.com",
    "signing_street_address": "123 Main St",
    "signing_city": "San Francisco",
    "signing_state": "CA",
    "signing_zip": "94105",
    "lender": "First National Bank",
    "external_source": "MyTPS",
    "external_reference": "TPS-ORD-98765"
  }'
```

The response returns the full order object with the Snapdocs `id`. **Store this order ID** — you'll need it for all subsequent API calls.

> 📘 **Tip: Use `external_source` and `external_reference`**
>
> Set these to your system's name and internal order ID to correlate Snapdocs orders with your own records. These fields can only be set at creation time.

### Field Formatting Specifics

For `appointment_date` the following format should be used: `d/m/yyyy` (20/1/2026 for January 20, 2026).

For `appointment_time`, we will assume that it is in the timezone of the address of the order. The format is: `h:mm p` (9:00 am). Time should be between '5:30 am' and '11:45 pm' and should be rounded to 15min intervals. We will also accept one of the following values: `'morning'`, `'evening'`, `'afternoon'`, `'t_b_d'`, `'asap'`.

For `signing_state` and `property_state` use 2-letter uppercase state codes `CA, IL`, ... We attempt to find a team member matching `owner_email` to set as the order owner. If no email addresses match, the order owner will remain empty. `total_notary_fee` will only be shown to Company API keys.

For any phone number, the correct format is `(xxx) xxx-xxxx`.

# Orders with co-signers

Include co-signer fields when there is a second signer:

```json Order with Co-Signer
{
  "product_id": 50,
  "team_member_id": 200,
  "escrow_number": "ESC-2024-001234",
  "first_name": "Jane",
  "last_name": "Smith",
  "mobile_phone": "555-123-4567",
  "co_signer_first_name": "John",
  "co_signer_last_name": "Smith",
  "co_signer_mobile_phone": "555-987-6543",
  "co_signer_email": "john.smith@example.com",
  "signing_street_address": "123 Main St",
  "signing_city": "San Francisco",
  "signing_state": "CA",
  "signing_zip": "94105"
}
```

# Adding participants

Include a comma-separated list of observer emails in the `participants` field. Participants receive notifications about order status changes:

```json Order with Observers
{
  "product_id": 50,
  "team_member_id": 200,
  "escrow_number": "ESC-2024-001234",
  "last_name": "Smith",
  "participants": "manager@titleco.com,lender.contact@bank.com"
}
```

# Next step

After creating an order, proceed to [Upload documents](https://developers.snapdocs.com/notary-connect/guides/guides/upload-documents).

---
### Upload documents

# Upload documents

After creating an order, upload your closing documents so they're available for the notary. The [Upload attachment](https://developers.snapdocs.com/notary-connect/reference/notary-connect-api/operations/UploadAttachment) endpoint supports two upload methods: multipart file upload and base64-encoded upload.

You can upload as many documents as needed — each upload is a separate API call. If the company allows sending docs to notaries and a notary is already assigned, documents may be automatically queued for delivery.

# Method A: Multipart file upload

The simplest approach — send the file directly as a multipart form field:

```shell Multipart Upload
curl -X POST "https://app.cs-demo0.snpd.io/mobile_notary_api/v1/orders/12345/attachments" \
  -H "X-AUTH-TOKEN: your_api_token_here" \
  -F "file=@/path/to/closing_docs.pdf"
```

# Method B: Base64-encoded upload

For systems where multipart isn't convenient, send a JSON body with the file's name and base64-encoded content:

```shell Base64 Upload
curl -X POST "https://app.cs-demo0.snpd.io/mobile_notary_api/v1/orders/12345/attachments" \
  -H "X-AUTH-TOKEN: your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "file": {
      "name": "closing_docs.pdf",
      "base64": "JVBERi0xLjQKJeLjz9MK..."
    }
  }'
```

# Upload response

Both methods return the new attachment ID on success (HTTP 201):

```json Upload Response (201)
{
  "attachment": {
    "id": 8003
  }
}
```

# Common upload errors

| Error                                | Cause                                                                     |
| :----------------------------------- | :------------------------------------------------------------------------ |
| `The 'base64' attribute is required` | Using base64 method but `file.base64` is missing or empty.                |
| `The 'name' attribute is required`   | Using base64 method but `file.name` is missing or empty.                  |
| `Order has no Team Member assigned`  | Client API key — the order needs a team member assigned before uploading. |

# Next step

With documents uploaded, proceed to [Monitor orders and receive callbacks](https://developers.snapdocs.com/notary-connect/guides/guides/monitor-orders) to track notary assignment and signing progress.

---
### Monitor orders and receive callbacks

# Monitor orders and receive callbacks

Once an order is created and documents are uploaded, you'll want to track its progress — notary assignment, appointment confirmation, document delivery, and signing completion. Use the [Get order](https://developers.snapdocs.com/notary-connect/reference/notary-connect-api/operations/GetOrder) endpoint to poll for updates.

# Checking order status

```shell Get Order
curl -X GET "https://app.cs-demo0.snpd.io/mobile_notary_api/v1/orders/12345" \
  -H "X-AUTH-TOKEN: your_api_token_here"
```

# Key fields to monitor

| Field                             | What It Tells You                                            | Example Values                                                                                                                    |
| :-------------------------------- | :----------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------- |
| `status`                          | The current signing lifecycle stage.                         | `open`, `completed`, `canceled`, `on_hold`,  `did_not_sign`                                                                       |
| `notary`                          | The assigned notary. `null` until one is found and assigned. | Object with `id`, `first_name`, `last_name`, `phone`, `email`                                                                     |
| `appointment_confirmation_status` | Whether the signer confirmed the appointment.                | `confirmed`, `unconfirmed`, `change_requested`                                                                                    |
| `attachment_status`               | Document delivery status to the notary.                      | `null`, `sent_by_client`, `emailed_to_notary`, `direct_links`, `notary_picked_up_docs`, `overnighted`, `at_closing`, `downloaded` |
| `attachments`                     | All documents. Check `uploaded_by_notary` to find scanbacks. | Array of attachment objects                                                                                                       |

# Order status lifecycle

Orders move through these statuses as the signing progresses:

| Status         | Description                                                                              |
| :------------- | :--------------------------------------------------------------------------------------- |
| `open`         | This is an order that is currently being worked.                                         |
| `completed`    | This is for an order where a signing has been successfully completed.                    |
| `canceled`     | This order is canceled. It will no longer be worked and you will not be charged for it.  |
| `on_hold`      | This order is not being worked, but it may return to an `open` status at some point.     |
| `did_not_sign` | This is when a notary started work on an order, but for some reason it did not work out. |

The order field `attachment_status` can have the following values:

| Value                   | Description                                                |
| :---------------------- | :--------------------------------------------------------- |
| `null`                  | Docs have not been sent.                                   |
| `sent_by_client`        | Docs sent through API or by client.                        |
| `emailed_to_notary`     | Docs emailed by scheduler.                                 |
| `direct_links`          | Docs emailed by scheduler.                                 |
| `notary_picked_up_docs` | Docs not emailed.                                          |
| `overnighted`           | Docs not emailed.                                          |
| `at_closing`            | Docs not emailed.                                          |
| `downloaded`            | Docs were emailed and notary has downloaded *all* of them. |

# Order callbacks

When setting up your integration, we will ask for an API Callback endpoint.

In certain life-cycle events, we will call this endpoint with the following
details.

```json
 {
        "event": "notary_assigned", 
        "order": {
            "id": 123,
            "status": "open",
            "client_id": 1,
            "product_id": 2,
            "team_member_id": 3,
            "escrow_number": "11223344",
            "appointment_date": "2025-11-06",
            "appointment_time": "8:45 pm",
            "first_name": "Bo",
            "last_name": "Gettman",
            "mobile_phone": "(123) 456-7890",
            "home_phone": null,
            "work_phone": null,
            "appointment_confirmation_status": "unconfirmed",
            "attachment_status": null,
            "signer_email": "bo@signer.com",
            "signing_street_address": "100 Montgomery St",
            "signing_location_details": null,
            "signing_city": "San Francisco",
            "signing_state": "CA",
            "signing_zip": "94104",
            "property_street_address": null,
            "property_city": null,
            "property_state": null,
            "property_zip": null,
            "co_signer_first_name": null,
            "co_signer_last_name": null,
            "co_signer_home_phone": null,
            "co_signer_mobile_phone": null,
            "co_signer_work_phone": null,
            "co_signer_email": null,
            "external_source": null,
            "external_reference": null,
            "notary": {
                "id": 4,
                "first_name": "Natalie",
                "last_name": "Notary",
                "company_name": null,
                "payment_street_address": "100 Montgomery St",
                "payment_city": "San Francisco",
                "payment_state": "CA",
                "payment_zip": "94104",
                "phone": "(123) 456-7890",
                "email": "natalie@notary.com"
       			},
            "owner_email": "john.doe@snapdocs.com",
            "attachments": [
                {
                    "id": 19021,
                    "name": "FedEx Gettman 11223344 Priority Overnight.pdf",
                    "url": "/mobile_notary_api/v1/orders/3022143/attachments/19021",
                    "last_downloaded_at": null,
                    "created_at": "2024-11-27T19:29:09.994-08:00",
                    "uploaded_by_notary": false
                },
                {
                    "id": 19022,
                    "name": "response.pdf",
                    "url": "/mobile_notary_api/v1/orders/3022143/attachments/19022",
                    "last_downloaded_at": "2024-11-27T19:40:20.914-08:00",
                    "created_at": "2024-11-27T19:32:36.826-08:00",
                    "uploaded_by_notary": false
                },
                {
                    "id": 19023,
                    "name": "response2.pdf",
                    "url": "/mobile_notary_api/v1/orders/3022143/attachments/19023",
                    "last_downloaded_at": "2024-11-27T19:38:25.164-08:00",
                    "created_at": "2024-11-27T19:38:14.052-08:00",
                    "uploaded_by_notary": false
                }
            ],
            "special_instructions": "Signer must sign with black ink",
            "total_notary_fee": 30.0,
            "participants": ["email1@example.com", "email2@example.com"],
            "language_requirement": "English"
    		}
  }
```

At the moment, we call the endpoint when one of the following events happen:

* `notary_assigned`
* `notary_removed`
* `documents_status_changed`
* `status_changed` - refers to the order's signing status
* `automator_stopped` - only sent for company API keys
* `notary_fee_changed` - only sent for company API keys, and only sent if notary has already been assigned
* `scanback_added`
* `appointment_confirmed`
* `appointment_change_requested`
* `order_comment_added` - includes comments recorded on status changes and appointment change requests

The `order` JSON or XML reflects the change. You will receive JSON or XML depending on what you initially specified for your API key. (We send JSON by default.)

All callbacks are signed using HMAC-SHA1 using your API key. [This gem](https://github.com/mgomes/api_auth) does a good job of explaining how this can be used.

### Comments on status changes and appointment changes

An `order_comment_added` callback is sent alongside the status callback for these events, so the free text a notary, signer, or scheduler typed is delivered with the update:

| Trigger                                        | Status callback                | Comment callback      |
| ---------------------------------------------- | ------------------------------ | --------------------- |
| Order marked **Did Not Sign**                  | `status_changed`               | `order_comment_added` |
| Order marked **Completed**                     | `status_changed`               | `order_comment_added` |
| Appointment change requested by the **notary** | `appointment_change_requested` | `order_comment_added` |
| Appointment change requested by the **signer** | `appointment_change_requested` | `order_comment_added` |

Orders marked **Canceled** or **On Hold** do not send a comment callback.

The comment callback is sent shortly after its status callback, but delivery order is not guaranteed. Your integration should not assume the status callback always arrives first.

The comment `text` is sent exactly as recorded, with no added prefix. Examples:

```
Notary order was marked as "Did not sign" | Reason: Documents had errors | Comments: Wrong loan number
Signing complete | The scheduler, Jane Doe, marked the notary order as "Signing complete" | Comments: All docs signed
The notary, Jane Doe, has requested an appointment change. Comments: Signer asked to move to Friday
The consumer, John Smith, requested an appointment change. Additional comments: Work conflict
```

On Did Not Sign, the comment text does not name the person who marked the order. Use the `role` field (`"Notary"` or `"Scheduler"`) to identify them. The other three events name the actor in the text itself.

The payload is the standard `order_comment_added` shape, with the comment in a top-level `comment`
object next to `event` and `order`:

```json
{
  "event": "order_comment_added",
  "order": { "...": "..." },
  "comment": {
    "order_id": 123456,
    "commenter": "Jane Doe",
    "role": "Notary",
    "text": "Notary order was marked as \"Did not sign\" | Reason: Documents had errors",
    "created_at": "2026-08-07T12:00:00Z",
    "shared_with_client": true,
    "shared_with_consumer": false,
    "shared_with_lender": false,
    "shared_with_notary": true,
    "shared_with_settlement_agent": false
  }
}
```

# Next step

When orders reach `complete` status, proceed to [Download & manage](https://developers.snapdocs.com/notary-connect/guides/guides/download-and-manage) to retrieve scanbacks and manage order lifecycle.

---
### Download and manage

# Download and manage

This final step covers downloading completed scanback documents, updating order status, adding comments, and modifying order details. These actions round out the full order lifecycle.

# Download scanback documents

After a signing is complete, the notary uploads scanback documents. Identify these in the order response by checking `uploaded_by_notary: true` on attachment objects.

## Identify scanbacks

```python Identify Scanbacks
# From the Get Order response, filter for notary-uploaded files:
for att in order["attachments"]:
    if att["uploaded_by_notary"]:
        print(f"Scanback: {att['name']} - {att['url']}")
```

## Download a file

The [Download attachment](https://developers.snapdocs.com/notary-connect/reference/notary-connect-api/operations/DownloadAttachment) endpoint returns a `302` redirect to a temporary, pre-signed download URL:

```shell Download Scanback
curl -L -X GET "https://app.cs-demo0.snpd.io/mobile_notary_api/v1/orders/12345/attachments/8002" \
  -H "X-AUTH-TOKEN: your_api_token_here" \
  -o scanback_page1.pdf
```

***

# Update order status (company keys only)

Use the [Update order status](https://developers.snapdocs.com/notary-connect/reference/notary-connect-api/operations/UpdateOrderStatus) endpoint to programmatically complete, cancel, hold, or reactivate orders:

```shell Complete
# Complete an order
curl -X PUT "https://app.cs-demo0.snpd.io/mobile_notary_api/v1/orders/12345/update_status" \
  -H "X-AUTH-TOKEN: your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{"status": "complete"}'
```
```shell Cancel
# Cancel an order
curl -X PUT "https://app.snapdocs.com/mobile_notary_api/v1/orders/12345/update_status" \
  -H "X-AUTH-TOKEN: your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{"status": "cancel"}'
```
```shell Reactivate
# Reactivate a canceled or on-hold order
curl -X PUT "https://app.snapdocs.com/mobile_notary_api/v1/orders/12345/update_status" \
  -H "X-AUTH-TOKEN: your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{"status": "reactivate"}'
```

| Status         | Action                                                                            |
| :------------- | :-------------------------------------------------------------------------------- |
| `complete`     | Mark the signing as successfully completed.                                       |
| `cancel`       | Cancel the order.                                                                 |
| `on_hold`      | Place the order on hold. Can be reactivated later.                                |
| `did_not_sign` | Signer did not complete the signing, but trip and travel fees may be appropriate. |
| `reactivate`   | Reactivate a canceled or on-hold order.                                           |

***

# Add comments

Use the [Create comment](https://developers.snapdocs.com/notary-connect/reference/notary-connect-api/operations/CreateComment) endpoint to communicate with the scheduling team, notary, and other parties. Specify `commenter_email` (a registered team member) and control visibility with `shared_with_*` flags:

```shell Create Comment
curl -X POST "https://app.cs-demo0.snpd.io/mobile_notary_api/v1/orders/12345/comments" \
  -H "X-AUTH-TOKEN: your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": {
      "text": "Borrower confirmed 3 PM signing. Please bring two forms of ID.",
      "commenter_email": "sarah@acmetitle.com",
      "send_email_notification": true,
      "shared_with_client": true,
      "shared_with_notary": true,
      "shared_with_consumer": true
    }
  }'
```

To retrieve all shared comments (**company keys only**), use the [List comments](https://developers.snapdocs.com/notary-connect/reference/notary-connect-api/operations/ListComments) endpoint:

```shell List Comments
curl -X GET "https://app.cs-demo0.snpd.io/mobile_notary_api/v1/orders/12345/comments" \
  -H "X-AUTH-TOKEN: your_api_token_here"
```

***

# Update order details

Use the [Update order](https://developers.snapdocs.com/notary-connect/reference/notary-connect-api/operations/UpdateOrder) endpoint to modify order fields. Only include fields you want to change:

```shell Update Order
curl -X PUT "https://app.cs-demo0.snpd.io/mobile_notary_api/v1/orders/12345" \
  -H "X-AUTH-TOKEN: your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "appointment_date": "2024-06-16",
    "appointment_time": "10:00 AM",
    "special_instructions": "Gate code is #4567."
  }'
```

> ⚠️ **Note:** If you include `participants` in an update, it **replaces** the entire observer list. Omit it to leave observers unchanged. The `external_source` and `external_reference` fields cannot be modified after creation.

<br />

---
### Errors

# Errors

The Notary Connect APIs use conventional HTTP response codes to indicate the success or failure of an API request. In general:

* Codes in the **2xx** range indicate success.
* Codes in the **4xx** range indicate an error based on the information provided (e.g., missing required fields, invalid token, resource not found).
* Codes in the **5xx** range indicate an error on Snapdocs' servers (these are rare).

# HTTP status codes

| HTTP Code | Meaning               | When You'll See It                                                                                       |
| :-------- | :-------------------- | :------------------------------------------------------------------------------------------------------- |
| 200       | OK                    | Successful GET request                                                                                   |
| 201       | Created               | Successful POST request — a new order, attachment, comment                                               |
| 202       | Accepted              | Successful PUT request — an order was updated.                                                           |
| 302       | Found (Redirect)      | Attachment download — redirects to a temporary download URL.                                             |
| 400       | Bad Request           | The request body is missing required fields or contains invalid data.                                    |
| 401       | Unauthorized          | The `X-AUTH-TOKEN` header is missing, the token is invalid, or the token has been revoked.               |
| 404       | Not Found             | The requested order, attachment, or resource does not exist or is not accessible with your API key.      |
| 422       | Unprocessable Entity  | The request was understood but contains semantic errors (e.g., invalid commenter email for comments).    |
| 500       | Internal Server Error | An unexpected error occurred on Snapdocs' servers. If persistent, contact your Customer Success Manager. |

# Error response format

When an error occurs, the API returns a JSON object with error details. There are two response formats depending on the endpoint:

## Standard error format (Orders, Attachments, Status, Products)

Most endpoints return errors in a `meta.errors` array:

```json 400 Bad Request
{
  "meta": {
    "errors": [
      "Team Member is required",
      "Last name can't be blank"
    ]
  }
}
```

## Comment error format

The Comments endpoint returns errors in a top-level `errors` array:

```json 422 Unprocessable Entity
{
  "errors": [
    "commenter_email is required"
  ]
}
```

# Getting help

If you encounter persistent errors or unexpected behavior:

* **Check your API key type.** Some endpoints are restricted to company keys only (status updates, listing comments).
* **Verify reference IDs.** Use the [List clients](https://developers.snapdocs.com/notary-connect/reference/notary-connect-api/operations/ListClients) endpoint to confirm that your `product_id`, `team_member_id`, and `client_id` values are valid.
* **Contact your Snapdocs Customer Success Manager** for assistance with account-specific issues or to request a new API key.

<br />

---