Quickstart

In this tutorial you’ll send Tickmarks a one-sentence lease and get back its start date, its duration, and an end date it never mentions, which Tickmarks works out for you. It takes about five minutes. You need an account and curl. A new account comes with €0.05 of free credit, which is 10 reads, so this tutorial costs nothing.

1. Create an API key

Sign up for a Tickmarks account. Every new account gets €0.05 of free credit (10 reads). Then open API keys in the panel and select Create key. Name it something like quickstart and leave the scopes on their default, which allows everything. Copy the key before you close the dialog: it starts with tmk_, and the panel won’t show it again.

Put the key and the API base URL in your shell, so the commands below can use them:

export TICKMARKS_API=https://api.tickmarks.nl   # your API base URL
export TICKMARKS_KEY=tmk_live_4fJ2kq9XbT8mWc1R    # the key you copied

2. Send a document and a schema

A request carries the document text and a schema that says what to look for. This schema asks for a start date, an end date and a duration, and adds one rule, the relation term: the end date is the start date plus the duration. Each field has a description that tells the model what to look for. That rule is what lets Tickmarks fill in the end date.

curl -X POST "$TICKMARKS_API/v1/extractions" \
  -H "Authorization: Bearer $TICKMARKS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document": "The lease starts on 1 March 2027 and runs for 12 months.",
    "language": "en",
    "schema": {
      "hydra_schema": "1.0",
      "name": "lease",
      "defaults": { "locales": ["en-GB"] },
      "fields": [
        { "name": "startDate", "type": "date", "description": "The calendar date on which the lease begins." },
        { "name": "endDate", "type": "date", "description": "The calendar date on which the lease ends. If it is not stated, the term relation can derive it from the start date and duration." },
        { "name": "duration", "type": "duration", "basis": "calendar", "description": "The duration of the lease: how long it runs, expressed as a number of months, years or days." }
      ],
      "relations": [
        { "id": "term", "expr": "endDate == startDate + duration" }
      ]
    }
  }'

3. Read the result

Tickmarks answers 200 OK with an extraction object. Here it is with most of the detail cut:

{
  "object": "extraction",
  "response": {
    "data": {
      "startDate": "2027-03-01",
      "endDate": "2028-03-01",
      "duration": "P12M"
    },
    "fields": {
      "endDate": {
        "status": "resolved",
        "source": "derived",
        "value": "2028-03-01",
        "confidence": { "posterior": 0.8827, "other": 1.0, "kind": "model_relative" },
        "derived_by": ["d0"]
      }
    }
  },
  "usage": { "input_tokens": 17, "reads": 1, "window_tokens": 4096 }
}

data holds the answers, ready to use. Notice endDate: the document never mentions it, and source: "derived" tells you Tickmarks computed it with the term relation rather than reading it. If you want to see how, derived_by points at a derivation that lists the inputs it used. usage says what the call consumed: here 17 document tokens and 1 read. A read is one pass over up to 4,096 tokens of schema plus document, so this call used 1 of your 10 free reads.

If you’d rather call Tickmarks from an AI assistant than from curl, see Use Tickmarks from an AI assistant.

If it fails

A typo in the schema is the most likely problem. If you write "type": "datum" instead of "date", you get 400 with a details entry that points at the bad value and lists the valid ones:

{
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed.",
    "details": [
      {
        "code": "invalid_value",
        "values": ["string", "int", "decimal", "bool", "date", "datetime", "duration", "money", "enum"],
        "path": ["schema", "fields", 2, "type"],
        "message": "Invalid option: expected one of \"string\"|\"int\"|…"
      }
    ]
  }
}

A 401 unauthorized means the key is missing or wrong; check that $TICKMARKS_KEY is set in the shell you’re running curl from. Errors covers every other case.

To extract more fields and add rules of your own, read the Schema overview. For every operator a rule can use, see Expressions and operators.