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

GET /rest/forms/v1/<resource>/payload
Authorization: Basic <token>
Accept: application/json

Successful responses mint a short-lived payloadId:

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

1.2 Submit the Resource Payload

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

Request body:

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

1.3 Standard Success Envelope

{
  "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.

{
  "error": {
    "code": "E_DUPLICATE",
    "message": "Customer already exists",
    "details": {
      "existingCustomerId": "0237077"
    },
    "retryable": false
  }
}

3. Customer & Identity Payloads

3.1 Lookup by Phone or Address

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

{
  "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.

{
  "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

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

{
  "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"
}

{
  "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.

{
  "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

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

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

{
  "data": {
    "message": "{\"status\":\"scheduled\",\"jobNumber\":\"JOB-889033\"}"
  }
}

5. Equipment & Parts Payloads

5.1 Equipment Submission

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

{
  "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

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

{
  "customerId": "0459981",
  "sequenceNumber": "1",
  "partCode": "C/C",
  "quantity": "1",
  "unitPrice": "139.95"
}

5.3 Part Catalogue Snapshot

{
  "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

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

{
  "timeframes": "next-available"
}

{
  "data": {
    "message": "[{\"callType\":\"SC\",\"dates\":[\"20241118\",\"20241119\",\"20241120\"]}]"
  }
}

6.2 Detailed Slot Lookup (Direct API)

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

{
  "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.

Overview

Technical Overview

API Specifications

Operations

Integration Templates

Payload Handshake Template

Payload Handshake Integration Guide

1. Handshake Overview

1.1 Request a Payload Token

1.2 Submit the Resource Payload

1.3 Standard Success Envelope

2. Shared Error Envelope

3. Customer & Identity Payloads

3.1 Lookup by Phone or Address

3.2 Create Customer

4. Job Booking Payloads

4.1 Call-Type Catalogue

4.2 Create Job Submission

5. Equipment & Parts Payloads

5.1 Equipment Submission

5.2 Parts Submission

5.3 Part Catalogue Snapshot

6. Availability Payloads

6.1 Timeframe Submission

6.2 Detailed Slot Lookup (Direct API)

7. Operational Expectations

​Payload Handshake Integration Guide

​1. Handshake Overview

​1.1 Request a Payload Token

​1.2 Submit the Resource Payload

​1.3 Standard Success Envelope

​2. Shared Error Envelope

​3. Customer & Identity Payloads

​3.1 Lookup by Phone or Address

​3.2 Create Customer

​4. Job Booking Payloads

​4.1 Call-Type Catalogue

​4.2 Create Job Submission

​5. Equipment & Parts Payloads

​5.1 Equipment Submission

​5.2 Parts Submission

​5.3 Part Catalogue Snapshot

​6. Availability Payloads

​6.1 Timeframe Submission

​6.2 Detailed Slot Lookup (Direct API)

​7. Operational Expectations

Payload Handshake Integration Guide

1. Handshake Overview

1.1 Request a Payload Token

1.2 Submit the Resource Payload

1.3 Standard Success Envelope

2. Shared Error Envelope

3. Customer & Identity Payloads

3.1 Lookup by Phone or Address

3.2 Create Customer

4. Job Booking Payloads

4.1 Call-Type Catalogue

4.2 Create Job Submission

5. Equipment & Parts Payloads

5.1 Equipment Submission

5.2 Parts Submission

5.3 Part Catalogue Snapshot

6. Availability Payloads

6.1 Timeframe Submission

6.2 Detailed Slot Lookup (Direct API)

7. Operational Expectations