# REST API (beta) ### Setup 1. Go to **Settings > Integrations** in the ScribeWare desktop app 2. Under the **REST API** section, click **Generate API Key** 3. Copy and save your API key securely — you will need it for all API requests 4. Optionally, enter a **Webhook URL** (must be HTTPS) to receive notifications when reports created via the API are published ### Authentication All API requests must include your API key in the `X-API-KEY` header: ``` X-API-KEY: your-api-key-here ``` You can verify your API key is working by calling the auth endpoint: ```bash curl https://us-central1-scribeware5.cloudfunctions.net/rest/auth \ -H "X-API-KEY: your-api-key-here" ``` Response: ```json {"result": "ok"} ``` ### Endpoints #### Create a Report **POST** `/reports/new` Creates a new inspection report in your ScribeWare company account. **Request Body:** | Field | Type | Required | Description | | ----------------- | ------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `clientNames` | string or string\[] | Yes | Client name(s). Multiple names are joined with commas. | | `clientEmails` | string or string\[] | No | Client email(s). | | `clientPhones` | string or string\[] | No | Client phone number(s). | | `inspectionDate` | string | Yes | Inspection date in ISO format (e.g., `"2025-06-15"`). | | `address` | string | No | Property address. | | `invoiceItems` | string or string\[] | No | Invoice line items in `"Description: $Price"` format. | | `yearBuilt` | string | No | Year the property was built. | | `squareFeet` | string | No | Square footage of the property. | | `notes` | string | No | Inspector notes. | | `inspectorEmails` | string or string\[] | No | Email(s) of inspectors to assign. Must match existing ScribeWare user emails. | | `restId` | string | No | Your external ID for the report. If provided and a report with this `restId` already exists, it will be updated instead of creating a new one. | | `fromRestService` | string | No | Name of the originating service. Defaults to `"REST API"`. Shown in ScribeWare as the source of the report. | | `agentName` | string | No | Real estate agent name. | | `agentEmail` | string | No | Real estate agent email. | | `agentPhone` | string | No | Real estate agent phone. | **Example:** ```bash curl -X POST https://us-central1-scribeware5.cloudfunctions.net/rest/reports/new \ -H "X-API-KEY: your-api-key-here" \ -H "Content-Type: application/json" \ -d '{ "clientNames": ["John Doe", "Jane Doe"], "clientEmails": ["john@example.com", "jane@example.com"], "clientPhones": ["555-1234"], "inspectionDate": "2025-06-15", "address": "123 Main St, Anytown, USA 12345", "invoiceItems": ["Home Inspection: $500.00", "Radon Test: $150.00"], "yearBuilt": "2000", "squareFeet": "2500", "notes": "Access code: 1234", "agentName": "Bob Agent", "agentEmail": "bob@realty.com", "restId": "your-system-id-123" }' ``` **Response:** ```json { "result": "ok", "id": "rpt_abc123" } ``` The report will appear in ScribeWare with a "New from REST API" status badge. Inspectors can then apply a template and complete the inspection as usual. #### List Reports **GET** `/reports` Returns a list of your company's reports, ordered by inspection date (newest first). **Query Parameters:** | Parameter | Type | Default | Description | | --------- | ------ | ------- | ------------------------------------ | | `limit` | number | 20 | Maximum number of reports to return. | **Example:** ```bash curl https://us-central1-scribeware5.cloudfunctions.net/rest/reports?limit=10 \ -H "X-API-KEY: your-api-key-here" ``` **Response:** ```json [ { "id": "rpt_abc123", "address": "123 Main St, Anytown, USA 12345", "clientName": "John Doe, Jane Doe", "clientEmail": "john@example.com, jane@example.com", "clientPhone": "555-1234", "agentName": "Bob Agent", "agentEmail": "bob@realty.com", "agentPhone": "", "inspectorName": "Inspector Smith", "inspectorEmail": "smith@inspect.com", "inspectorNotes": "Access code: 1234", "inspectionDate": "2025-06-15T00:00:00.000Z", "fromRestService": "REST API", "restId": "your-system-id-123", "publishedUrl": "" } ] ``` #### Get a Single Report **GET** `/reports/:reportId` Returns details for a specific report. **Example:** ```bash curl https://us-central1-scribeware5.cloudfunctions.net/rest/reports/rpt_abc123 \ -H "X-API-KEY: your-api-key-here" ``` The response format is the same as a single item in the list reports response. ### Webhook Notifications When a report that was created via the REST API is published, ScribeWare can send a webhook notification to your server. #### Setup 1. In **Settings > Integrations > REST API**, enter your webhook URL (must be HTTPS) 2. Click **Save** #### How It Works 1. An inspector publishes a report that was originally created via the REST API 2. ScribeWare shows a confirmation dialog asking if the inspector wants to notify the REST API integration 3. If confirmed, ScribeWare sends a POST request to your webhook URL with the full report data **Important:** The webhook only fires for reports that were created via the REST API (identified by the `fromRestService` field). Reports created directly in ScribeWare will not trigger the webhook. If no webhook URL is configured, reports created via the REST API will be published using the normal email flow — no webhook notification will be sent. #### Webhook Payload The POST body sent to your webhook URL contains the report data: ```json { "id": "rpt_abc123", "address": "123 Main St, Anytown, USA 12345", "clientName": "John Doe, Jane Doe", "clientEmail": "john@example.com, jane@example.com", "clientPhone": "555-1234", "agentName": "Bob Agent", "agentEmail": "bob@realty.com", "agentPhone": "", "inspectorName": "Inspector Smith", "inspectorEmail": "smith@inspect.com", "inspectorNotes": "Access code: 1234", "inspectionDate": "2025-06-15T00:00:00.000Z", "fromRestService": "REST API", "restId": "your-system-id-123", "publishedUrl": "https://reports.getscribeware.com/abc123" } ``` #### Error Handling If the POST to your webhook URL fails (network error, non-2xx response, etc.), the error is displayed to the inspector in the ScribeWare app. They can retry the publish or skip the webhook notification. ### Managing Your API Key * **Generate**: Settings > Integrations > REST API > Generate API Key * **Copy**: Click the copy icon next to the API key to copy it to your clipboard * **Revoke**: Click "Revoke REST API Integration" to delete the API key and webhook URL. This will disable all REST API access. Existing reports created via the API will remain but will no longer trigger webhook notifications on publish. ### Error Responses API errors are returned as JSON with an HTTP status code: | Status | Meaning | | ------ | ---------------------------------------- | | 400 | Bad request — missing or invalid API key | | 404 | Report not found | | 500 | Internal server error | ```json { "error": "Api key not found!" } ``` ### Rate Limits There are currently no explicit rate limits on the REST API. Please be reasonable with your request volume. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.scribeware.com/into-the-weeds/integrations/rest-api-beta.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.