Register First Position

Overview

Registering a position in Dark Matter runs from document preparation and upload through extraction, review, registration, and verification. The Ingest API submits documents; the Registry API finalizes the position.

Prerequisites

• API key with ingest:write, registry:read, registry:write scopes
• Position documents (e.g., operating agreement, subscription agreement) in PDF or supported format
• Basic understanding of the Position Object schema

Step 1: Prepare documents

Gather the source documents that define the position: operating agreement, side letter, subscription agreement, or equivalent. Ensure documents are complete, legible, and in a supported format (PDF preferred). Organize by position if you have multiple.

Step 2: Upload via ingest API

Call POST /ingest (or the document upload endpoint) with your files. Use multipart form data or a presigned URL flow as documented. The API returns a job ID; poll for completion or use webhooks. Extraction produces structured data aligned with the Position Object schema.

curl -X POST "https://api.dmtr.ai/v1/ingest" \
-H "Authorization: Bearer $API_KEY" \
-F "file=@operating-agreement.pdf" \
-F "document_type=operating_agreement"

Step 3: Review extracted data

Retrieve the extraction result and review the mapped fields: entity details, economic rights, transfer restrictions, compliance requirements. Correct any mis-extractions via the API or dashboard. Validate that required fields are populated before proceeding to registration.

Step 4: Register position

Submit the reviewed data to the Registry via POST /positions or the registration endpoint. Include all required canonical fields and any conditional fields. Use an idempotency key for safe retries. The API returns the registered Position Object with entity_id and status.

{
  "entity_id": "meg-2026-047",
  "status": "active",
  "asset": {
    "vehicle_class": "spv_llc",
    "issuer": {
      "name": "Acme Growth Fund III"
    },
    "terms_hash": "sha256:a1b2c3d4..."
  },
  "created_at": "2026-03-13T10:30:00Z"
}

Step 5: Verify in registry

Query GET /positions/{entity_id} or GET /registry/entities/{id} to confirm the position is in the registry. Check status, asset details, and transfer restrictions. The position is now available for search, transfer workflows, and downstream integrations.

Error handling

Handle extraction failures (e.g., unsupported document type, parse errors) by reviewing error details and resubmitting with corrected documents. Registration may fail for validation errors; fix field-level issues and retry. Use idempotency keys to avoid duplicate registrations on retry.