Skip to main content

​
API Integration Guide

Use this handbook to align your custom integration API implementation with Avoca’s integration patterns. Each section outlines the baseline contract, validation rules, and operational playbooks we need before moving into certification.

​
1. API Foundations

  • HTTPS everywhere – Publish sandbox and production base URLs (for example, https://sandbox.example.com/rest/forms/v1 and https://api.example.com/rest/forms/v1). Lock both to TLS 1.2+ and document any mutual-auth requirements.
  • Header-based credentials – Avoca sends a single authorization header per environment (e.g., Authorization: Basic {token}). Specify how secrets are rotated, distribution procedures, and any IP allow-listing so we can automate credential refresh.
  • Two-step payload workflow – Every transactional endpoint follows the same handshake: 
    GET {base}/payload           # returns { "data": { "payloadId": "<uuid>" } }
POST {base}/payload/{payloadId}/submit
    • Document request/response schemas for POST calls, including required metadata inside the JSON body.
    • Capture timeout expectations (default 10 s) and retry limits (Avoca retries once after 500 ms unless flagged non-retryable).
    • Define validation error semantics: HTTP status codes, response envelope, and field-level error structure.
  • Idempotency rules – State whether resubmitting the same payloadId is rejected, overwritten, or treated as a no-op. If duplicates are detected, identify the error code and guidance so Avoca can distinguish retryable vs terminal failures.
  • Response formats – Prefer JSON bodies. If an endpoint must return plain text or mixed content, provide a schema (for example, text/csv, text/plain with delimiter notes) so Avoca can parse it safely. List any exceptions explicitly.

​
2. Customer & Identity Workflows

  • Lookup by ID – The response should include the full customer profile: primary and secondary addresses, scheduled appointments, equipment metadata, and free-form notes. Document which arrays may be empty and how null values appear.
  • Customer creation – Accept a constrained payload: customer name (≤30 characters), uppercase abbreviated address fields, customerType (RES/COM), campaign code, primary/secondary phone numbers, optional email. Specify formatting (e.g., phone digits only) and validation error messages. Include how you echo back or reference the new customer ID in the success payload.
  • Propagation timing – Clarify how long new customers take to surface in lookup endpoints. Note any throttling, duplicate-customer blocks, or rate limits so Avoca can pace retries appropriately.

​
3. Booking & Job Management

  • Call-type catalogue – Publish the enumerated call-type codes (SC, CC, E, P, etc.) with human-readable descriptions, and note whether additions are backward-compatible or require coordination.
  • Job creation payload – Require: customerId, formatted callerPhone, campaignCode, callType, scheduledDate (YYYYMMDD), scheduledStartTime/scheduledEndTime (HHMM), and default salesPersonId. Identify optional fields and how validation errors surface when time windows overlap or fall outside operating hours.
  • Customer linkage – If jobs must reference an existing customer, document failure envelopes for missing or invalid IDs and the remediation path (e.g., retry after lookup, create customer first).

​
4. Equipment & Parts

  • Equipment submission – Accept: customer number, sequential equipment number, itemCode, serialNumber, install flag (Y/N), numeric ageYears, optional ladderSize/equipmentLocation, problem notes, and problem codes. Document accepted enumerations and numeric formats.
  • Part submission – Link to equipment sequence numbers and require partCode, quantity, and unitPrice. Provide the canonical part-code dictionary (code, description, default price) and the escalation path to request new codes.
  • Order dependencies – Clarify workflow ordering (equipment before parts before job) and whether endpoints enforce uniqueness, allow updates, or support partial replacements.

​
5. Availability & Scheduling

  • Timeframe endpoint – Supply a high-level availability feed (e.g., array of dates or windows) that explains how to interpret empty results and standardized error responses.
  • Granular slot lookup – If supported, define a GET endpoint that accepts query parameters such as callType, date (YYYYMMDD), equipmentAge, and installedByUs. Return structured slots (start, end, capacity, technicianType) and document parameter validation rules with sample queries.

​
6. Operational Expectations

  • Retries & SLAs – Outline service-level targets, max retry guidance, and the contact route for automated timeout alerts. Avoca emails both teams after two failures—share the distribution group that should receive escalations.
  • Credential & data hygiene – Document rotation cadence for sandbox and production secrets, how sandbox data is refreshed, and any blackout periods that affect testing or deployments.
  • Security & compliance – List supported TLS versions, mutual-auth or certificate pinning requirements, logging/monitoring expectations, and any auditing or transcript retention policies that apply to payload contents.

​
7. Next Steps

Review these guidelines with your engineering team, confirm sample payloads, and align on incident escalation contacts. Once the contract is finalized, Avoca will schedule certification testing that validates handshake behavior, error handling, and end-to-end workflows.