{
  "name": "Household Pet web-to-app handoff",
  "version": 1,
  "market": "au",
  "canonicalBase": "https://au.household.pet",
  "documentation": "https://au.household.pet/add-reminder/",
  "summary": "Household Pet's mobile app can be handed a pet or a reminder from the web. The details travel inside the link itself as flat query parameters — there is no API, no account, no request to a server, and nothing is stored anywhere along the way.",
  "safety": "These links are inert. Building one writes nothing and reveals nothing: the values sit in the URL and go no further until a person opens it on their phone, and the app then shows what it read and waits for a tap before it creates anything. A link built with a wrong value costs that person one tap on \"No thanks\", so aim for correct values rather than defensive omissions — a reminder handed over with a missing date is worse than one handed over with a date the person can see and correct.",
  "workflows": [
    {
      "when": "The person is at a computer.",
      "give": "a prefilled form link",
      "urlTemplate": "https://au.household.pet/add-reminder/?rt={title}&rk={kind}&rd={dueDate}&rtm={dueTime}&rn={notes}&rp={petName}",
      "then": "They open it, the form is already filled in and a QR code is already drawn, and they scan it with their phone. This is the usual case: the page exists because a phone keyboard is the slowest place to type any of this."
    },
    {
      "when": "The person is reading on the phone that has the app.",
      "give": "the handoff link itself",
      "urlTemplate": "https://au.household.pet/import/?v=1&t=addreminder&rt={title}&rk={kind}&rd={dueDate}&rtm={dueTime}&rn={notes}&rp={petName}",
      "then": "Tapping it opens the app straight onto the confirmation screen, with no QR code in between. On a phone without the app it falls through to a web page with the install links, which is why this is the wrong link to send to a computer."
    },
    {
      "when": "You are driving a real browser.",
      "give": "nothing — fill the form",
      "urlTemplate": "https://au.household.pet/add-reminder/",
      "then": "Every control carries a data-hhp-field attribute naming the key it maps to, and the kind selector is a native <select> whose option values are the wire values below. When the form is complete the panel marked data-hhp-state=\"ready\" holds the finished link, readable from the element with id \"handoff-url\" — read it back rather than rebuilding it."
    }
  ],
  "rules": [
    "One reminder per link. For a course of four puppy vaccinations, build four links and list them; there is no repeating parameter, and packing several into one URL makes the QR code too dense for a phone camera to read off a screen.",
    "Dates are absolute. Resolve \"next Tuesday\" or \"in six weeks\" yourself, in the person's own timezone, and send the calendar date. There is no relative syntax, and a value that is not a real day is dropped and reported on the page rather than guessed at.",
    "Times are local wall clock on the phone that receives them, not UTC. If the person said 9am, send 09:00.",
    "Unknown parameters are ignored, so a key this contract does not list is not an error — it simply does not arrive. Never invent a key expecting it to be understood.",
    "Values are capped at the lengths below and are truncated, not rejected, if longer. Keep a title to a few words and put the detail in the notes.",
    "Set src to a short identifier for whatever built the link. It is attribution only, it is never shown to the person, and it is the only way to tell later how much of this is worth supporting."
  ],
  "tools": {
    "addreminder": {
      "summary": "Adds one reminder to a pet that already exists in the app. The website cannot know the pet's id, so the app asks which pet when the link is opened — rp only pre-selects that choice and never creates a pet.",
      "formUrl": "https://au.household.pet/add-reminder/",
      "handoffUrl": "https://au.household.pet/import/",
      "required": [
        "rt",
        "rd"
      ],
      "fields": [
        {
          "key": "rt",
          "label": "Title",
          "type": "text",
          "maxLength": 60,
          "required": true,
          "example": "Annual vaccination"
        },
        {
          "key": "rk",
          "label": "Kind",
          "type": "enum",
          "required": false,
          "default": "vaccination",
          "values": [
            {
              "value": "vaccination",
              "label": "Vaccination"
            },
            {
              "value": "medication",
              "label": "Medication"
            },
            {
              "value": "vetVisit",
              "label": "Vet visit"
            },
            {
              "value": "weight",
              "label": "Weigh-in"
            },
            {
              "value": "parasite",
              "label": "Parasite"
            },
            {
              "value": "grooming",
              "label": "Grooming"
            },
            {
              "value": "behaviour",
              "label": "Note"
            },
            {
              "value": "symptom",
              "label": "Symptom"
            }
          ],
          "note": "Send the value, not the label. Two are not guessable from the label: the value for \"Vet visit\" is vetVisit, and the value behind the label \"Note\" is behaviour, spelled that way in both markets because it is a field name rather than a word on screen."
        },
        {
          "key": "rd",
          "label": "Due date",
          "type": "date",
          "format": "YYYY-MM-DD",
          "required": true,
          "example": "2026-11-03",
          "note": "Absolute, never relative. May be in the future (the normal case) or the past (which writes an already-overdue reminder)."
        },
        {
          "key": "rtm",
          "label": "Due time",
          "type": "time",
          "format": "HH:mm",
          "required": false,
          "default": "09:00",
          "example": "09:00",
          "note": "Local time on the person's phone. Ignored without rd."
        },
        {
          "key": "rn",
          "label": "Notes",
          "type": "text",
          "maxLength": 100,
          "required": false,
          "example": "Second C3 booster — book with the usual clinic"
        },
        {
          "key": "rp",
          "label": "Pet name",
          "type": "text",
          "maxLength": 40,
          "required": false,
          "example": "Bowie",
          "note": "A hint used to pre-select the pet in the app's picker, matched on name without regard to case. A name that matches nothing is harmless — the person picks."
        }
      ]
    },
    "addpet": {
      "summary": "Creates a pet. Field-for-field with the app's own add-pet screen, minus the photo, which is far too large to travel in a link.",
      "formUrl": "https://au.household.pet/add-pet/",
      "handoffUrl": "https://au.household.pet/import/",
      "required": [
        "n",
        "sp",
        "sx"
      ],
      "fields": [
        {
          "key": "n",
          "label": "Name",
          "type": "text",
          "maxLength": 40,
          "required": true
        },
        {
          "key": "fn",
          "label": "Full name",
          "type": "text",
          "maxLength": 60,
          "required": false,
          "note": "A formal or registered name, where the short name is what they are called."
        },
        {
          "key": "sp",
          "label": "Species",
          "type": "enum",
          "required": true,
          "values": [
            {
              "value": "dog",
              "label": "Dog"
            },
            {
              "value": "cat",
              "label": "Cat"
            },
            {
              "value": "rabbit",
              "label": "Rabbit"
            },
            {
              "value": "bird",
              "label": "Bird"
            },
            {
              "value": "ferret",
              "label": "Ferret"
            },
            {
              "value": "reptile",
              "label": "Reptile"
            },
            {
              "value": "cow",
              "label": "Cow"
            },
            {
              "value": "horse",
              "label": "Horse"
            },
            {
              "value": "other",
              "label": "Other"
            }
          ]
        },
        {
          "key": "br",
          "label": "Breed",
          "type": "text",
          "maxLength": 40,
          "required": false
        },
        {
          "key": "sx",
          "label": "Sex",
          "type": "enum",
          "required": true,
          "values": [
            {
              "value": "m",
              "label": "Male"
            },
            {
              "value": "f",
              "label": "Female"
            },
            {
              "value": "u",
              "label": "Unknown"
            }
          ]
        },
        {
          "key": "dx",
          "label": "Desexed",
          "type": "boolean",
          "format": "1 or 0",
          "required": false,
          "note": "Omit it when unknown. An absent dx means \"not answered\", which is not the same as 0 and must not be sent as one — 0 asserts something about an animal."
        },
        {
          "key": "dob",
          "label": "Date of birth",
          "type": "date",
          "format": "YYYY-MM-DD",
          "required": false,
          "note": "Must be in the past."
        },
        {
          "key": "mc",
          "label": "Microchip or livestock identifier",
          "type": "text",
          "maxLength": 30,
          "required": false,
          "note": "Held in the same field for every species; only the label on screen changes (cattle carry an NLIS device or an official ear tag rather than a microchip)."
        },
        {
          "key": "co",
          "label": "Colour and markings",
          "type": "text",
          "maxLength": 60,
          "required": false
        },
        {
          "key": "fl",
          "label": "Lifestyle and clinical flags",
          "type": "enum-list",
          "format": "comma-separated, or the single word \"none\"",
          "required": false,
          "values": [
            {
              "value": "outdoorAccess",
              "label": "Has outdoor access",
              "hint": "Goes outside or roams — affects parasite and injury risk"
            },
            {
              "value": "animalContact",
              "label": "Contact with other animals",
              "hint": "Multi-pet home, dog parks, boarding or daycare"
            },
            {
              "value": "pregnantOrNursing",
              "label": "Pregnant or nursing",
              "hint": "Raises the urgency of many symptoms (e.g. straining, collapse, fever)"
            }
          ],
          "note": "Three-way, and the middle case is easy to miss. Omit fl when you were not asked about these at all; send \"none\" when they were asked about and none apply, which clears any left over from a previous import; send the keys that do apply. Pregnant or nursing is dropped for a male or desexed pet."
        }
      ]
    }
  },
  "common": {
    "v": {
      "label": "Seed version",
      "required": "on the handoff link, omitted on the form link",
      "value": "1"
    },
    "t": {
      "label": "Tool key",
      "required": "on the handoff link, omitted on the form link",
      "values": [
        "addreminder",
        "addpet",
        "sitter",
        "vax",
        "parasite",
        "age",
        "rego"
      ]
    },
    "src": {
      "label": "Attribution",
      "required": false,
      "maxLength": 16,
      "note": "A short identifier for whatever built the link."
    },
    "maxUrlLength": 512
  }
}