Skip to main content

​
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\":\"[email protected]\",\"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": "[email protected]",
  "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.