Quickstart

This guide walks you through the core Rekord API workflow: defining a model, creating a decisioning context, ingesting evidence, and reading the resolved record.

Prerequisites

• A Rekord workspace with a valid API token that has write permissions.

• curl or any HTTP client

All examples use $REKORD_API_TOKEN and $REKORD_BASE_URL as environment variables. Replace these with your actual values.

Step 1: Create a model

Define an "Applicant" model with three fields:

curl -X POST "$REKORD_BASE_URL/models" \
  -H "Authorization: Bearer $REKORD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Applicant",
    "description": "Mortgage applicant profile",
    "fields": [
      {
        "name": "firstName",
        "type": "text",
        "description": "Applicant legal first name",
        "required": true
      },
      {
        "name": "lastName",
        "type": "text",
        "description": "Applicant legal last name",
        "required": true
      },
      {
        "name": "annualIncome",
        "type": "currency",
        "description": "Gross annual income",
        "resolutionPolicy": "highest_confidence"
      }
    ]
  }'

The response includes the server-assigned modelId and a status of draft:

{
  "modelId": "01957c3a-1234-7000-8000-000000000001",
  "name": "Applicant",
  "status": "draft",
  "fields": [
    {
      "fieldId": "01957c3a-1234-7000-8000-000000000010",
      "name": "firstName",
      "type": "text",
      "required": true
    },
    {
      "fieldId": "01957c3a-1234-7000-8000-000000000011",
      "name": "lastName",
      "type": "text",
      "required": true
    },
    {
      "fieldId": "01957c3a-1234-7000-8000-000000000012",
      "name": "annualIncome",
      "type": "currency",
      "resolutionPolicy": "highest_confidence"
    }
  ],
  "createdAt": "2026-02-20T10:00:00Z"
}

Step 2: Activate the model

A model in draft status cannot accept records. Transition it to active when you're happy it is complete:

curl -X PUT "$REKORD_BASE_URL/models/01957c3a-1234-7000-8000-000000000001/status/active" \
  -H "Authorization: Bearer $REKORD_API_TOKEN"

{
  "modelId": "01957c3a-1234-7000-8000-000000000001",
  "name": "Applicant",
  "status": "active"
}

Step 3: Create a decisioning context

Open a context to scope your decision:

curl -X POST "$REKORD_BASE_URL/contexts" \
  -H "Authorization: Bearer $REKORD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sarah Jones — Mortgage Application",
    "type": "mortgage_application",
    "metadata": {
      "applicationRef": "APP-2026-00142"
    }
  }'

{
  "contextId": "01957c3a-5678-7000-8000-000000000001",
  "name": "Sarah Jones — Mortgage Application",
  "type": "mortgage_application",
  "status": "active",
  "freshness": "resolved",
  "tags": {
    "applicationRef": "APP-2026-00142"
  },
  "createdAt": "2026-02-20T10:01:00Z"
}

The context starts with freshness: resolved because there is no evidence to process yet.

Step 4: Ingest a contribution

Submit evidence from a document extraction. The contribution includes per-field confidence scores:

curl -X POST "$REKORD_BASE_URL/contributions" \
  -H "Authorization: Bearer $REKORD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payslip-extraction-001" \
  -d '{
    "contextId": "01957c3a-5678-7000-8000-000000000001",
    "modelId": "01957c3a-1234-7000-8000-000000000001",
    "sourceId": "doc-extract-payslip-2026-01",
    "sourceType": "document_extraction",
    "data": {
      "firstName": "Sarah",
      "lastName": "Jones",
      "annualIncome": 54200
    },
    "fieldConfidences": {
      "firstName": 0.95,
      "lastName": 0.95,
      "annualIncome": 0.85
    }
  }'

{
  "contributionId": "01957c3a-9abc-7000-8000-000000000001",
  "contextId": "01957c3a-5678-7000-8000-000000000001",
  "modelId": "01957c3a-1234-7000-8000-000000000001",
  "sourceId": "doc-extract-payslip-2026-01",
  "sourceType": "document_extraction",
  "data": {
    "firstName": "Sarah",
    "lastName": "Jones",
    "annualIncome": 54200
  },
  "fieldConfidences": {
    "firstName": 0.95,
    "lastName": 0.95,
    "annualIncome": 0.85
  },
  "createdAt": "2026-02-20T10:02:00Z"
}

The context is now stale — the platform will process this contribution and resolve it into a record.

Step 5: Read the resolved record

After the platform resolves the contribution (typically within seconds), read the record:

curl "$REKORD_BASE_URL/records?filter[contextId][eq]=01957c3a-5678-7000-8000-000000000001" \
  -H "Authorization: Bearer $REKORD_API_TOKEN"

{
  "data": [
    {
      "recordId": "01957c3a-def0-7000-8000-000000000001",
      "modelId": "01957c3a-1234-7000-8000-000000000001",
      "contextId": "01957c3a-5678-7000-8000-000000000001",
      "freshness": "resolved",
      "sha256": "a1b2c3d4...",
      "data": {
        "firstName": "Sarah",
        "lastName": "Jones",
        "annualIncome": 54200
      },
      "createdAt": "2026-02-20T10:02:05Z",
      "updatedAt": "2026-02-20T10:02:05Z"
    }
  ]
}

Check the freshness field before relying on the data. If it is stale or computing, the record has not yet converged on the latest evidence.

Step 6: Update the record directly

You can also update a record directly through the API. This creates a contribution internally at maximum confidence:

curl -X PATCH "$REKORD_BASE_URL/records/01957c3a-def0-7000-8000-000000000001" \
  -H "Authorization: Bearer $REKORD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "annualIncome": 55000
    }
  }'

The record is returned immediately with freshness: stale. Once the platform re-resolves, the annualIncome field will reflect the new value — and because direct API writes carry maximum confidence, the new value takes precedence over lower-confidence contributions.

Next steps

• Learn about Querying & Filtering — filter, sort, expand, and select fields across any list endpoint

• Explore the full API Reference — detailed endpoint documentation for Models, Records, Contributions, Contexts, Rules, and more

• Read Building Integrations — production best practices for ingesting data, handling corrections, batch operations, and observing convergence