> ## Documentation Index
> Fetch the complete documentation index at: https://docs.avoca.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Payload Handshake Template

> Canonical Avoca payload contract for custom integration form-based submissions

# Payload Handshake Integration Guide

This playbook defines the shared payload pattern Avoca expects when exchanging short-lived submission tokens with your services. Every workflow uses the same handshake, response envelope, and metadata wrapper so Avoca can plug into new resources without custom engineering.

***

## 1. Handshake Overview

### 1.1 Request a Payload Token

```http theme={null}
GET /rest/forms/v1/<resource>/payload
Authorization: Basic <token>
Accept: application/json
```

Successful responses mint a short-lived `payloadId`:

```json theme={null}
{
  "data": {
    "payloadId": "44ef31b6-8d63-4a07-9363-b961792aac1e",
    "expiresAt": "2024-11-20T18:25:43.511Z"
  }
}
```

### 1.2 Submit the Resource Payload

```http theme={null}
POST /rest/forms/v1/<resource>/payload/{payloadId}/submit
Authorization: Basic <token>
Content-Type: application/json
```

Request body:

```json theme={null}
{
  "payload": {
    /* resource-specific body */
  },
  "metadata": {
    "source": "avoca",
    "summary": "optional human-readable call summary",
    "callId": "external-call-id"
  }
}
```

### 1.3 Standard Success Envelope

```json theme={null}
{
  "data": {
    "message": "Submitted successfully",
    "reference": "optional client-side tracking number"
  }
}
```

***

## 2. Shared Error Envelope

All endpoints return a consistent error shape. Flag retryable errors explicitly so Avoca can apply automated retry logic.

```json theme={null}
{
  "error": {
    "code": "E_DUPLICATE",
    "message": "Customer already exists",
    "details": {
      "existingCustomerId": "0237077"
    },
    "retryable": false
  }
}
```

***

## 3. Customer & Identity Payloads

### 3.1 Lookup by Phone or Address

```http theme={null}
POST /rest/forms/v1/customer-lookup/payload/{payloadId}/submit
Authorization: Basic <token>
Content-Type: application/json
```

```json theme={null}
{
  "phone": "3125550199",
  "address": "3936 W 116TH ST"
}
```

Lookup responses may be stringified JSON (as shown) or structured objects—document whichever format you use and keep it consistent across environments.

```json theme={null}
{
  "data": {
    "message": "{\"customers\":[{\"customerId\":\"0237077\",\"name\":\"LUKE ASIMAKOPOULOS\",\"email\":\"LUKE@EXAMPLE.COM\",\"membership\":\"none\",\"customerType\":\"residential\",\"addresses\":[{\"street\":\"3936 W 116TH ST\",\"city\":\"ALSIP\",\"state\":\"IL\",\"zip\":\"60803-5803\",\"primaryPhone\":\"3125550199\",\"secondaryPhone\":\"\",\"scheduledAppointments\":[],\"equipment\":[{\"itemCode\":\"13ACX030\",\"serialNumber\":\"S1910E14219\",\"installedByUs\":\"Y\",\"ageYears\":\"15\",\"location\":\"GROUND\",\"ladderSize\":\"NO\",\"equipmentType\":\"AIR CONDITIONER\",\"warranty\":[]}]}],\"notes\":[]}]}"
  }
}
```

### 3.2 Create Customer

```http theme={null}
POST /rest/forms/v1/customer-create/payload/{payloadId}/submit
Authorization: Basic <token>
Content-Type: application/json
```

```json theme={null}
{
  "customerName": "JANE DOE",
  "streetAddress": "123 MAIN ST APT 2",
  "city": "CHICAGO",
  "state": "IL",
  "zipCode": "60601",
  "primaryPhone": "7735552121",
  "secondaryPhone": "8475550099",
  "email": "jane@example.com",
  "campaignCode": "OBCAVOCA",
  "customerType": "RES"
}
```

```json theme={null}
{
  "data": {
    "message": "{\"status\":\"created\",\"customerId\":\"0459981\"}"
  }
}
```

***

## 4. Job Booking Payloads

### 4.1 Call-Type Catalogue

Publish the active call types so Avoca can sync and validate options.

```json theme={null}
{
  "callTypes": [
    { "code": "SC", "description": "HVAC Service Call" },
    { "code": "CC", "description": "HVAC Maintenance Call" },
    { "code": "E", "description": "Sales Estimate" },
    { "code": "P", "description": "Plumbing Service" }
  ]
}
```

### 4.2 Create Job Submission

```http theme={null}
POST /rest/forms/v1/job-create/payload/{payloadId}/submit
Authorization: Basic <token>
Content-Type: application/json
```

```json theme={null}
{
  "customerId": "0459981",
  "callerPhone": "7735552121",
  "campaignCode": "OBCAVOCA",
  "callType": "SC",
  "scheduledDate": "20241118",
  "scheduledStartTime": "0800",
  "scheduledEndTime": "1200",
  "salesPersonId": "0"
}
```

```json theme={null}
{
  "data": {
    "message": "{\"status\":\"scheduled\",\"jobNumber\":\"JOB-889033\"}"
  }
}
```

***

## 5. Equipment & Parts Payloads

### 5.1 Equipment Submission

```http theme={null}
POST /rest/forms/v1/job-equipment/payload/{payloadId}/submit
Authorization: Basic <token>
Content-Type: application/json
```

```json theme={null}
{
  "customerId": "0459981",
  "sequenceNumber": "1",
  "itemCode": "ML180UH070P36A",
  "serialNumber": "S5912H40924",
  "installedByUs": "Y",
  "ageYears": "13",
  "problemCodes": "NA",
  "problemNotes": "Annual furnace maintenance, no issues reported.",
  "ladderSize": "NO",
  "equipmentLocation": "BASEMENT"
}
```

### 5.2 Parts Submission

```http theme={null}
POST /rest/forms/v1/job-part/payload/{payloadId}/submit
Authorization: Basic <token>
Content-Type: application/json
```

```json theme={null}
{
  "customerId": "0459981",
  "sequenceNumber": "1",
  "partCode": "C/C",
  "quantity": "1",
  "unitPrice": "139.95"
}
```

### 5.3 Part Catalogue Snapshot

```json theme={null}
{
  "parts": [
    { "code": "S/C", "description": "Service Call", "price": "85.00" },
    { "code": "C/C", "description": "HVAC Clean & Check", "price": "139.95" },
    { "code": "CMP-1", "description": "Care Program - 1 System", "price": "24.99" }
  ]
}
```

***

## 6. Availability Payloads

### 6.1 Timeframe Submission

```http theme={null}
POST /rest/forms/v1/job-availability/payload/{payloadId}/submit
Authorization: Basic <token>
Content-Type: application/json
```

```json theme={null}
{
  "timeframes": "next-available"
}
```

```json theme={null}
{
  "data": {
    "message": "[{\"callType\":\"SC\",\"dates\":[\"20241118\",\"20241119\",\"20241120\"]}]"
  }
}
```

### 6.2 Detailed Slot Lookup (Direct API)

```http theme={null}
GET /api/available-appointments?callType=SC&date=20241118&installedByUs=Y&equipmentAge=10
Authorization: Bearer <api-key>
Accept: application/json
```

```json theme={null}
{
  "callType": "SC",
  "date": "2024-11-18",
  "slots": [
    { "start": "2024-11-18T13:00:00Z", "end": "2024-11-18T17:00:00Z", "capacity": 2, "technicianType": "HVAC" },
    { "start": "2024-11-18T17:00:00Z", "end": "2024-11-18T21:00:00Z", "capacity": 1, "technicianType": "HVAC" }
  ]
}
```

***

## 7. Operational Expectations

* **Timeouts & retries**: Document expected response times, retry windows, and whether errors are retryable. Avoca defaults to a 10 s timeout and retries once after 500 ms.
* **Propagation**: Note how long new customers or jobs take to appear in lookup endpoints; Avoca currently waits 10 s before re-querying.
* **Alerts**: Provide escalation contacts (emails or webhooks) for repeated timeouts; Avoca sends one alert after the second failure.
* **Security**: Define TLS versions, credential rotation cadence, and any additional signing or encryption requirements beyond HTTPS.
* **Versioning**: Describe how you will introduce new fields or endpoints (additive JSON properties, versioned paths) so Avoca can adopt changes without breaking.

Use this template when publishing payload-based workflows to partners. Adjust field names or optional properties to match your systems, but keep the handshake pattern and envelope consistent so Avoca can integrate with minimal customization.