Isto Intents

Use this when the user wants to be told over time about a used car or a home that is not on offer today, in a given country — e.g. "let me know until March about an estate car in Portugal under 15 000 €, not diesel". The wish goes to an independent listing portal that serves that country and has asked to receive wishes this way (Isto Intents registry, istointents.org). It returns that portal's own consentUrl: the USER must open it, enter their own e-mail there and confirm — nothing is watched before that, and the contact stays with that portal. Never ask the user for their e-mail and never open or fill in the link for them. If several portals fit, the answer is outcome "choose_holder" with their names: ask the user which one, then call again with holder. If none serves the country yet, the answer is outcome "no_holder": tell the user plainly. Send the country only, never a city or address. hiddenLimit is optional and only if the user said it: it is passed once to the portal, sealed there, never stored here or shown to sellers. Matches come from the chosen portal's own aggregation of its national market and may be incomplete.

{
  "type": "object",
  "properties": {
    "statement": {
      "type": "string",
      "minLength": 2,
      "maxLength": 500,
      "description": "What it MUST be, in the user's own words and language, e.g. \"estate car under 15000 €, not diesel\"."
    },
    "country": {
      "type": "string",
      "pattern": "^[A-Za-z]{2}$",
      "description": "Country where the user wants to buy, ISO 3166-1 alpha-2 (e.g. PT, SK, CZ). Country only."
    },
    "category": {
      "type": "string",
      "enum": [
        "vehicle",
        "property"
      ],
      "description": "vehicle = cars and other road vehicles; property = homes, flats and land."
    },
    "niceToHave": {
      "type": "string",
      "maxLength": 500,
      "description": "Wishes that are not required (never filters), e.g. \"tow bar, automatic\"."
    },
    "buyBy": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Date (YYYY-MM-DD) by which the user wants to buy; watching stops after it."
    },
    "hiddenLimit": {
      "type": "object",
      "description": "Optional private maximum price, only if the user stated it.",
      "properties": {
        "amount": {
          "type": "integer",
          "minimum": 1,
          "maximum": 1000000000
        },
        "currency": {
          "type": "string",
          "pattern": "^[A-Za-z]{3}$",
          "description": "ISO 4217, e.g. EUR, CZK, PLN"
        }
      },
      "required": [
        "amount",
        "currency"
      ],
      "additionalProperties": false
    },
    "holder": {
      "type": "string",
      "maxLength": 253,
      "description": "Only after a \"choose_holder\" answer: the host of the portal the user chose."
    }
  },
  "required": [
    "statement",
    "country",
    "category"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "outcome": {
      "type": "string",
      "enum": [
        "forwarded",
        "choose_holder",
        "no_holder"
      ]
    },
    "intentCode": {
      "type": "string",
      "description": "Keep it in the conversation; use it with intent_get_intent, intent_list_matches and intent_withdraw_intent."
    },
    "status": {
      "type": "string"
    },
    "consentUrl": {
      "type": "string",
      "description": "The portal's page where the USER confirms with their own e-mail. Show it unchanged."
    },
    "consentExpiresAt": {
      "type": "string"
    },
    "holder": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string"
        },
        "operator": {
          "type": "string"
        },
        "title": {
          "type": "string"
        }
      },
      "required": [
        "host",
        "operator"
      ]
    },
    "holders": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "host": {
            "type": "string"
          },
          "operator": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "languages": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "host",
          "operator"
        ]
      }
    },
    "understood": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "notUnderstood": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "hiddenLimit": {
      "type": "string",
      "enum": [
        "none",
        "passed",
        "currency_not_accepted",
        "not_supported"
      ],
      "description": "What happened to the hidden limit. If not passed, tell the user."
    },
    "served": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "country": {
            "type": "string"
          },
          "category": {
            "type": "string"
          }
        }
      },
      "description": "With no_holder: where portals can be reached today."
    }
  },
  "required": [
    "outcome"
  ]
}

Returns the state of an intent published with intent_publish_intent, as the portal that holds it reports it, and which portal that is. Matches come from the chosen portal's own aggregation of its national market and may be incomplete.

{
  "type": "object",
  "properties": {
    "intentCode": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{32}$",
      "description": "The intentCode returned by intent_publish_intent."
    }
  },
  "required": [
    "intentCode"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "found": {
      "type": "boolean"
    },
    "status": {
      "type": "string"
    },
    "holder": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string"
        },
        "operator": {
          "type": "string"
        },
        "title": {
          "type": "string"
        }
      },
      "required": [
        "host",
        "operator"
      ]
    }
  },
  "required": [
    "found"
  ]
}

Returns the listings the portal found for the intent, unchanged — show every url as given. Works once the user has confirmed on the portal's page. Matches come from the chosen portal's own aggregation of its national market and may be incomplete.

{
  "type": "object",
  "properties": {
    "intentCode": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{32}$",
      "description": "The intentCode returned by intent_publish_intent."
    },
    "since": {
      "type": "string",
      "description": "Optional ISO time; only matches delivered after it."
    }
  },
  "required": [
    "intentCode"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "found": {
      "type": "boolean"
    },
    "status": {
      "type": "string"
    },
    "matches": {
      "type": "array"
    },
    "holder": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string"
        },
        "operator": {
          "type": "string"
        },
        "title": {
          "type": "string"
        }
      },
      "required": [
        "host",
        "operator"
      ]
    }
  },
  "required": [
    "found"
  ]
}

Stops the intent at the portal immediately; nothing more is sent to the user. Cannot be undone — publishing again needs a new confirmation.

{
  "type": "object",
  "properties": {
    "intentCode": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{32}$",
      "description": "The intentCode returned by intent_publish_intent."
    }
  },
  "required": [
    "intentCode"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "found": {
      "type": "boolean"
    },
    "status": {
      "type": "string"
    },
    "holder": {
      "type": "object",
      "properties": {
        "host": {
          "type": "string"
        },
        "operator": {
          "type": "string"
        },
        "title": {
          "type": "string"
        }
      },
      "required": [
        "host",
        "operator"
      ]
    }
  },
  "required": [
    "found"
  ]
}