METUS API Hub
Warranty
Warranty

POST

Register a warranty (structured error objects)

POST
https://api.metahvac.com
/warranties/v2.0/register

Submits a new warranty registration. Identical request and pipeline to v1.0/register; the only difference is the response shape. Where v1.0 returns errors as flat strings, v2.0 returns errors as an array of { code, message } objects so callers can branch on a machine-readable code instead of parsing the message. Success responses serialize errors as an empty array. The 409 reason discriminator that the v1 design briefly carried is gone — its values (CONFLICT, HIERARCHY_BLOCKED) are now per-error code values.

Register a warranty (structured error objects) › Headers

Authorization
​string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Register a warranty (structured error objects) › Request Body

type
​string · enum · required

Who is registering the warranty. Drives which contractor field is required: Homeowner → contractor.name; Contractor → contractor.salesforceId.

Enum values:
Homeowner
Contractor
installDate
​string · date-time · required

Installation date as an RFC3339 timestamp.

​object · required
​object · required

Required field depends on type. When type=Contractor, salesforceId is required (name is ignored). When type=Homeowner, name is required (salesforceId is ignored).

​object[] · minItems: 1 · required

At least one unit is required.

registrationComments
​string

Optional comments for the registration.

source
​string

Optional originating system or channel identifier; forwarded to Salesforce.

​object

Optional warranty term overrides (years).

propertyType
​string

Optional property type classification.

Register a warranty (structured error objects) › Responses

Registration accepted by the upstream registration service, OR the upstream responded but rejected the submission at the application layer (e.g. Tavant returned a non-Success status such as "Already registered under MP00…123"). On acceptance: success is true and errors is an empty array. On application-layer rejection: success is false and errors carries a single object with code REGISTRATION_REJECTED and the upstream message. In both cases data carries the generated warrantyNumber and per-unit details. Transport-level failures surface as 502 with no data block.

status
​integer
success
​boolean

True when the registration was accepted by the upstream registration service.

message
​string
​object
​object[]

Empty on a clean success. On an application-layer rejection it carries a single REGISTRATION_REJECTED object.

version
​string