SIMDATA

Random records API

Sample synthetic records conforming to the specified record schema.

CLI equivalent: simhealth sample {recordType} --count 1 --seed 1842 (--format json|ndjson|avro, extra --constraint key=value).

The project ID must match the project permanently bound to the Bearer API key. The unscoped path GET /v1/random/{recordType} is retained as a legacy compatibility route for existing clients; use the project-scoped path for new integrations.

Request parameters

ParameterTypeDefaultDescription
recordTypepath stringrequiredRecord definition name, such as person or encounter.
countquery integer1Number of records. Up to 10,000 for JSON and 10,000,000 for Avro.
seedquery integerrandom64-bit unsigned seed for deterministic sampling.
fieldsquery stringallComma-separated fields to include.

Headers and content negotiation

  • Authorization: Bearer <SIMHEALTH_API_KEY> is required. A signed-in Firebase ID token or an API key is enough. Omitting x-customer-id does not return 400.
  • x-customer-id is an optional credit-ledger override. When omitted, the call is metered as anonymous. An sk_live_... value in this header is ignored for the ledger. Any other value must be 1–128 ASCII letters, digits, _, or -, must not be anonymous, and must not start with cs_. An invalid value is HTTP 400 {"error":"invalid customer id","message":"invalid customer id"}.
  • Accept: application/json returns buffered JSON (the default), up to 10,000 records.
  • Accept: application/avro-binary or application/avro returns a streaming Avro OCF, up to the caller's record quota (default ceiling 10,000,000).
  • Accept: application/x-ndjson returns newline-delimited JSON.

The API does not guarantee a throughput rate or a client rate limit. The figures above are count caps.

Example response

{
  "recordType": "person",
  "count": 1,
  "seed": 1842,
  "records": [
    {
      "person_id": "P-981742",
      "first_name": "Maria",
      "last_name": "Santos",
      "gender": "female",
      "birth_date": "1984-06-12",
      "mrn": "MRN-004928"
    }
  ]
}

View Markdown source