# Get a single record

Fetches one record by ID or URL. Supports `json`, `json-ld`, and `markdown`.

This page focuses on response structure and integration notes; full schemas and demos live in the companion folder. Example files are sanitized.

## Request example



```python [Python + requests]
import requests

url = 'https://open.cli.im/api/v2/rpc/record/getRecord'
data = {
    'record_id': 10001,
    'format': 'json'
}
headers = {
    'Authorization': 'Bearer <your API Key>',
    'Content-Type': 'application/json'
}
response = requests.post(url, json=data, headers=headers)
print(response.text)
```

```bash [curl]
curl -X POST 'https://open.cli.im/api/v2/rpc/record/getRecord' \
  -H 'Authorization: Bearer <your API Key>' \
  -H 'Content-Type: application/json' \
  -d '{"record_id": 10001, "format": "json"}'
```



## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `record_id` | integer | No | Record ID. Provide either this or `record_url`; at least one is required |
| `record_url` | string | No | Short record URL, typically the full access URL starting with the record code `r`. Provide either this or `record_id`; at least one is required |
| `format` | string | No | Output format, default `json`. Values: `json`, `json-ld`, `markdown` |

## Output format overview

| `format` | `data.content_type` | `data.data` type | Typical use |
| --- | --- | --- | --- |
| `json` | `application/json; charset=utf-8` | object | Programmatic parsing, field-level processing, data sync |
| `json-ld` | `application/ld+json; charset=utf-8` | object | Semantic data exchange, Schema.org style integration |
| `markdown` | `text/markdown; charset=utf-8` | string | Reading, archive export, summarization |

The code blocks below show the response skeleton for each format.



```json [format=json]
{
  "code": 0,
  "message": "ok",
  "data": {
    "format": "json",
    "content_type": "application/json; charset=utf-8",
    "data": {
      "record_id": 10001,
      "record_number": "REC-001",
      "record_code": "record_demo_code_001",
      "record_url": "https://example.com/records/record-demo-001",
      "submit_at": 1773056539,
      "submit_at_iso": "2026-03-09 19:42:19(UTC+08:00)",
      "submit_method": "扫一扫填写",
      "recorder": { "auth_id": 20001, "user_id": 30001, "name": "张**" },
      "project": { "id": 40001, "name": "示例园区", "number": "P001" },
      "qrcode": { "id": 50001, "name": "示例点位A", "type": 0, "type_text": "普通二维码", "template_id": 50010, "qrcode_url": "https://example.com/qrcodes/qrcode-demo-001", "number": "", "category_id": 50020 },
      "org": { "id": 60001, "name": "示例企业", "code": "org_demo_code", "logo_url": "https://example.com/assets/logo-demo.png" },
      "record_template": { "id": 70001, "name": "设备巡检示例", "type": 0, "type_text": "普通表单", "number": "TPL-001" },
      "audit": { "enabled": true, "current_stage_id": 80001, "current_stage_title": "组长审批", "status": 0, "status_text": "待审核", "auditor_name": "李**" },
      "process_status": { "enabled": true, "text": "处理中", "color": "#155EB7" },
      "state_changes": [],
      "trusted_notary": { "tx_hash": "a1b2c3d4...", "evidence_url": "https://example.com/notary/...", "notarized_at": 1775539953, "notarized_at_iso": "2026-04-07 13:32:33(UTC+08:00)" },
      "tpl_groups": [ { "...": "See example files and schema for full field structure" } ]
    }
  }
}
```

```json [format=json-ld]
{
  "code": 0,
  "message": "ok",
  "data": {
    "format": "json-ld",
    "content_type": "application/ld+json; charset=utf-8",
    "data": {
      "@context": "https://schema.org",
      "@type": "CreativeWork",
      "identifier": "record-demo-001",
      "name": "设备巡检示例-REC-001",
      "url": "https://example.com/records/record-demo-001",
      "mainEntity": { "@type": "ItemList", "name": "组件数据" }
    }
  }
}
```

```json [format=markdown]
{
  "code": 0,
  "message": "ok",
  "data": {
    "format": "markdown",
    "content_type": "text/markdown; charset=utf-8",
    "data": "---\ntitle: 设备巡检示例-REC-001\nrecord_id: 10001\n...\n---\n\n# 设备巡检示例-REC-001\n\n## 基本信息\n\n**记录编号：** REC-001"
  }
}
```



## Response structure overview

**response.schema.json (full API response schema)**
<<< ./record-get-record/schema/response.schema.json


| Path | Type | Description |
| --- | --- | --- |
| `code` | integer | Platform status code; `0` means success |
| `message` | string | Status message |
| `data` | object | Unified business wrapper |
| `data.format` | string | Actual return format, corresponds to the `format` in the request |
| `data.content_type` | string | MIME type of the business payload |
| `data.data` | object \| string | Business payload; actual type depends on `data.format` |

Wrapper example:

```json
{
  "format": "json",
  "content_type": "application/json; charset=utf-8",
  "data": { "...": "..." }
}
```

## `format=json` details

When `format=json`, `data.data` is a structured record object. Full payload schema and examples are in the collapsible sections below.

**content-json.schema.json (payload schema)**
<<< ./record-get-record/schema/content-json.schema.json


:::: details Full examples

<<< ./record-get-record/examples/json/success-normal.response.json [Normal record]
<<< ./record-get-record/examples/json/success-child-qrcode-edit.response.json [Subcode edit record]

::::

### Record detail object

| Field | Type | Description |
| --- | --- | --- |
| `record_id` | integer | Record ID |
| `record_number` | string | Record number |
| `record_code` | string | Record code, unique identifier in the platform |
| `record_url` | string | Record access URL |
| `submit_at` | integer | Submission Unix timestamp in seconds |
| `submit_at_iso` | string | Formatted submission time with timezone |
| `submit_method` | string | Submission method |
| `recorder` | object | Submitter info |
| `project` | object | Project (partition) info |
| `qrcode` | object | QR code info |
| `org` | object | Organization info |
| `record_template` | object | Form template info |
| `audit` | object | Approval info |
| `process_status` | object | Processing status info |
| `state_changes` | array | Triggered state change list |
| `trusted_notary` | object \| null | Latest blockchain trusted notarization summary; returns `null` when no notarization data exists |
| `tpl_groups` | array | Groups and field content in the record |

### Key nested objects

| Object | Key fields | Description |
| --- | --- | --- |
| `recorder` | `auth_id`, `user_id`, `name` | Submitter info |
| `project` | `id`, `name`, `number` | Project info |
| `qrcode` | `id`, `name`, `type`, `qrcode_url` | QR code info |
| `org` | `id`, `name`, `code`, `logo_url` | Organization info |
| `record_template` | `id`, `name`, `type`, `number` | Form template info |
| `audit` | `enabled`, `current_stage_id`, `status` | Approval info |
| `process_status` | `enabled`, `text`, `color` | Processing status |
| `state_changes[]` | `state`, `from_state_option`, `to_state_option` | State change details |
| `trusted_notary` | `tx_hash`, `evidence_url`, `notarized_at`, `notarized_at_iso` | Latest blockchain trusted notarization summary |

### `trusted_notary`

Returns `null` when no notarization data exists.

When notarization data is available, returns the latest notarization summary:

```json
{
  "tx_hash": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "evidence_url": "https://example.com/notary/2026/0407/13/evidence-demo-001.md",
  "notarized_at": 1775539953,
  "notarized_at_iso": "2026-04-07 13:32:33(UTC+08:00)"
}
```

| Field | Type | Description |
| --- | --- | --- |
| `tx_hash` | string | On-chain notarization hash |
| `evidence_url` | string | URL of the source file for the latest notarization |
| `notarized_at` | integer | Latest notarization Unix timestamp in seconds |
| `notarized_at_iso` | string | Formatted latest notarization time with timezone |

### `tpl_groups[]`

| Field | Type | Description |
| --- | --- | --- |
| `group_id` | integer | Group ID |
| `group_title` | string | Group title; empty string means no title |
| `show_group_title` | boolean | Whether to show the group title |
| `is_page_break_group` | boolean | Whether this is a page-break marker group. `fields` is usually an empty array for such groups |
| `fields` | array | List of fields in the group |

### `tpl_groups[].fields[]`

| Field | Type | Description |
| --- | --- | --- |
| `field_id` | integer | Field ID |
| `field_title` | string | Field title |
| `field_desc` | string | Field description or hint text |
| `field_type` | string | Field type identifier; determines the structure of `field_value` |
| `field_short_name` | string | Field short name |
| `group_id` | integer | Parent group ID |
| `field_value` | mixed | Field value; format varies by `field_type` |
| `options` | object | Display options: `is_result`, `is_highlight`, `is_hidden`, `is_masked` |

### `field_type` and `field_value`

For a full overview of field names, categories, and naming conventions, see: [Form component types overview](https://cli.im/open-api/en/openapi/v2/api/record/components-field-types.md).

When integrating with `record/getRecord`, read `field_type` first, then parse `field_value` accordingly. This section only covers what value structure each field type returns; the complete mapping is defined in `content-json.schema.json` (see the collapsible section above).

| Category | `field_type` | `field_value` shape |
| --- | --- | --- |
| Plain text | `name`, `tel`, `recorder`, `identity`, `job_number`, `text`, `textarea`, `date`, `time`, `customer_name`, `customer_mobile`, `customer_number`, `carnumber` | string |
| Single choice | `sex`, `radio` | object with `option_text`, `option_id` |
| Number | `number` | object with `value`, `unit`, `unit_enabled` |
| Multi choice | `checkbox` | object with `values[]` |
| Checklist | `checklist` | array of items with `item_id`, `item_title`, `value` |
| Matrix | `matrix` | object with `columns[]` |
| Dynamic matrix | `dynamic_matrix` | object with `rows[]` |
| Location | `address` | object with `address`, `lat`, `lng` |
| Address | `owner_address` | object with `province`, `city`, `district`, `street`, `detail`, `full_address` |
| Cascaded select | `chained_selects` | object with `values[]` |
| Image / signature | `image`, `signature` | array of media objects |
| Audio | `audio` | array of items with `url`, `size`, `duration`, etc. |
| Video | `video` | array of items with `url`, `size`, `duration` |
| File | `file` | array of items with `url`, `size`, `file_name` |
| Description | `description` | object with `description_html` |
| OCR | `ocr_*` | object with `items[]` and `image` |
| Subcode edit diff | `sub_qrcode_edit_diff` | array of items with `before_value`, `after_value` |

## `format=json-ld`

When `format=json-ld`, `data.data` returns a Schema.org-style semantic object. Suitable for knowledge graphs, semantic search, or systems that need to preserve contextual semantics.

Companion files:

**content-jsonld.schema.json (payload schema)**
<<< ./record-get-record/schema/content-jsonld.schema.json


:::: details Full examples

<<< ./record-get-record/examples/jsonld/success-normal.response.json [Normal record]
<<< ./record-get-record/examples/jsonld/success-child-qrcode-edit.response.json [Subcode edit record]

::::

## `format=markdown`

When `format=markdown`, `data.data` returns a full Markdown text, suitable for display, archive export, or LLM-based reading tasks.

Companion files:

**content-markdown.schema.json (payload schema)**
<<< ./record-get-record/schema/content-markdown.schema.json


:::: details Full examples

<<< ./record-get-record/examples/markdown/success-normal.response.json [Normal record]
<<< ./record-get-record/examples/markdown/success-child-qrcode-edit.response.json [Subcode edit record]

::::

## Other conventions

### Null values

| Case | Rule |
| --- | --- |
| Field not filled | `field_value` may return `null` |
| Related entity does not exist | Structure remains unchanged, but nested field values may be `null` |
| String field with no content | Usually returns empty string `""` |
| Array field with no content | Usually returns empty array `[]` |

### Masking

| Case | Description |
| --- | --- |
| Live API response | Whether data is masked depends on the org's authorization and output configuration |
| Doc example files | All example files linked in this document are sanitized, for structure reference and integration testing only |
| `tpl_groups[].fields[].options.is_masked` | Indicates whether the masking toggle is enabled for the field; does not guarantee the current response value is masked |

### AI image audit fields

The following image objects may contain an optional `ai_audit_result` object:

- `field_value[]` items of `image` / `signature`
- `value.images[]` in checklists
- `image` in OCR
- `media_items[]` in subcode edit diff

| Field | Type | Description |
| --- | --- | --- |
| `ai_audit_result.audit_status` | integer | `0` default, `1` pass, `2` fail, `3` error, `4` pending |
| `ai_audit_result.audit_status_text` | string | Chinese label for `audit_status` |
| `ai_audit_result.reason` | string | Reason text returned by AI |

## Error response

On failure, a non-success status is typically returned. The response body may contain the following fields:

```json
{
  "code": 400,
  "error_code": 100300,
  "message": "System error",
  "message_detail": ""
}
```

| Field | Type | Description |
| --- | --- | --- |
| `code` | integer | HTTP status code or platform error status |
| `error_code` | integer | Business error code |
| `message` | string | Error summary |
| `message_detail` | string | Detailed error message; may be empty string |

For error code definitions, see: [Error codes and rate limits](https://cli.im/open-api/en/openapi/v2/error-codes.md).
