# Verify record certificate

Performs verification on credential-type records: set a specific status (`action_type=set_certificate_status`) or advance to the next status (`action_type=set_next_certificate_status`). When `action_type` is `set_certificate_status`, `to_certificate_status` is required. This is a write operation; the API key must have write permission.

## Request example



```python [Python + requests]
import requests

url = 'https://open.cli.im/api/v2/rpc/certificates/verify'
data = {
    'certificate_code': 'https://example.com/certificates/verify_demo_001',
    'action_type': 'set_certificate_status',
    'to_certificate_status': '已核销',
    'from_certificate_status': '待核销',
    'tpl_id': 122507,
    'code_id': 6763267
}
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/certificates/verify' \
  -H 'Authorization: Bearer <your API Key>' \
  -H 'Content-Type: application/json' \
  -d '{"certificate_code":"https://example.com/certificates/verify_demo_001","action_type":"set_certificate_status","to_certificate_status":"已核销","from_certificate_status":"待核销","tpl_id":122507,"code_id":6763267}'
```



## Response example

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "record_number": "R202603240001",
    "record_id": 123456789,
    "org_id": 94910252,
    "submit_at": 1773302553,
    "certificate_status": "已核销"
  }
}
```

## Error response example

```json
{
  "code": 400,
  "message": "Invalid target certificate status: 重复核销",
  "data": {},
  "error_code": 100326,
  "message_detail": "重复核销"
}
```

## Request fields

`certificate_code` string *required*

Certificate coding or full access URL identifying the credential record to verify.

---

`action_type` string *required*

Operation type:

- `set_certificate_status`: set to a specific status (`to_certificate_status` is required)
- `set_next_certificate_status`: advance to the next status

---

`to_certificate_status` string **conditionally required**

Target status name or ID; required when `action_type` is `set_certificate_status`. The request fails if the target does not exist, is unreachable, or no change is needed.

---

`from_certificate_status` string **optional**

Current status option name or ID. When provided, verification is only allowed from that source state—useful for constraining transitions in multi-step flows.

---

`tpl_id` integer **optional**

Restrict verification to records under a given form template. When set, the credential’s form must match.

---

`code_id` integer **optional**

Restrict verification to records under a given QR code. When set, the credential’s QR code must match.

---

## Response fields

`code` integer

Status code. `0` means success; business errors often return `400`; auth or permission issues may return `401` / `403`.

---

`message` string

Status message. `ok` on success; otherwise an error description.

---

`data` object

Result object after successful verification.

### `data` object

```json
{
  "record_number": "R202603240001",
  "record_id": 123456789,
  "org_id": 94910252,
  "submit_at": 1773302553,
  "certificate_status": "已核销"
}
```

| Field | Type | Description |
| --- | --- | --- |
| `record_number` | string | Record number |
| `record_id` | integer | Record ID |
| `org_id` | integer | Organization ID |
| `submit_at` | integer | Submission time (Unix seconds) |
| `certificate_status` | string | Certificate status text after verification |

---

`error_code` integer

Business error code when a business error occurs; use with the error-code reference.

---

`message_detail` string

Optional extra error detail; may be empty or omitted depending on the case.

---

## Error codes

Common errors:

| error_code | message | Description |
| --- | --- | --- |
| `100301` | `Invalid request parameters` | Missing or invalid parameters, or `to_certificate_status` omitted when `action_type=set_certificate_status` |
| `100319` | `Certificate verification failed` | Generic verification failure when no finer code applies |
| `100320` | `Invalid certificate code` | Invalid code or record not found |
| `100321` | `Certificate verification is not enabled` | Form or credential does not have verification enabled |
| `100322` | `Certificate record is not approved for verification` | Record not approved yet |
| `100323` | `Certificate does not match the requested scope` | Credential does not match `tpl_id` / `code_id` scope |
| `100324` | `Certificate cannot be verified in current status` | Current status disallows verification or flow is finished |
| `100325` | `Invalid verification action` | Unsupported action or form configuration |
| `100326` | `Invalid target certificate status` | Target invalid, no next status, or no change needed |
| `100327` | `Invalid verification authorization code` | Invalid or expired authorization code |
| `100328` | `No permission to verify this certificate` | Caller lacks permission |
| `100329` | `Identity information required before verification` | Identity must be completed before verification |

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