Didit Cases API
The Cases API from Didit — 24 operation(s) for cases.
OpenAPI Specification
openapi: 3.0.0
info:
version: 3.0.0
title: Didit Verification Billing Cases API
description: Identity verification API. Authenticate with x-api-key header.
servers:
- url: https://verification.didit.me
tags:
- name: Cases
paths:
/v3/organization/{organization_id}/application/{application_id}/cases/:
get:
summary: List cases
description: List cases for the application, newest first. Supports filtering, search, and sorting; see query parameters. Paginated with `limit`/`offset`.
operationId: list_cases
tags:
- Cases
parameters:
- name: organization_id
in: path
required: true
schema:
type: string
format: uuid
description: Organization UUID.
- name: application_id
in: path
required: true
schema:
type: string
format: uuid
description: Application UUID.
- name: limit
in: query
schema:
type: integer
default: 50
minimum: 1
description: Page size. Defaults to 50.
- name: offset
in: query
schema:
type: integer
default: 0
minimum: 0
description: Zero-based offset of the first record.
- name: status__in
in: query
schema:
type: string
description: Comma-separated statuses to include, e.g. OPEN,AWAITING_USER.
- name: priority
in: query
schema:
type: string
description: Comma-separated priorities to include.
- name: source__in
in: query
schema:
type: string
description: Comma-separated sources to include.
- name: blueprint
in: query
schema:
type: string
format: uuid
description: Filter to cases on this blueprint.
- name: assigned_to
in: query
schema:
type: string
format: uuid
description: Filter to cases assigned to this user.
- name: unassigned
in: query
schema:
type: boolean
description: true for unassigned cases, false for assigned cases.
- name: tag
in: query
schema:
type: string
description: Filter to cases carrying this exact tag.
- name: search
in: query
schema:
type: string
description: Matches title, case_number, tag, subject name/UUID/external ID, linked session UUID, or linked transaction UUID.
- name: date_from
in: query
schema:
type: string
format: date
description: Created-at lower bound (inclusive).
- name: date_to
in: query
schema:
type: string
format: date
description: Created-at upper bound (inclusive).
- name: due_before
in: query
schema:
type: string
format: date-time
description: due_at upper bound.
- name: overdue
in: query
schema:
type: boolean
description: true to return only overdue open/awaiting-user cases.
- name: ordering
in: query
schema:
type: string
enum:
- created_at
- -created_at
- due_at
- -due_at
default: -created_at
description: Sort order. due_at sorts nulls last.
x-codeSamples:
- lang: curl
label: curl
source: "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/?status__in=OPEN,AWAITING_USER&ordering=-due_at' \\\n -H 'x-api-key: YOUR_API_KEY'"
- lang: python
label: Python
source: "import os\n\nimport requests\n\nresp = requests.get(\n 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/',\n headers={'x-api-key': os.environ['DIDIT_API_KEY']},\n params={'status__in': 'OPEN,AWAITING_USER', 'ordering': '-due_at'},\n timeout=10,\n)\nresp.raise_for_status()\nfor case in resp.json()['results']:\n print(case['case_number'], case['title'], case['priority'], case['due_at'])"
responses:
'200':
description: Paginated case list.
content:
application/json:
schema:
type: object
properties:
count:
type: integer
description: Number of matching rows. Exact up to 100, capped at 100 beyond that for performance. Rely on `next` being null to detect the last page.
next:
type: string
nullable: true
description: Absolute URL of the next page, or null.
previous:
type: string
nullable: true
description: Absolute URL of the previous page, or null.
results:
type: array
items:
$ref: '#/components/schemas/CaseListItem'
post:
summary: Create case
description: Create a case anchored to exactly one subject (a user or a business), directly or by deriving the subject from an attached session/transaction link. Source is always `MANUAL` for API-created cases.
operationId: create_case
tags:
- Cases
parameters:
- name: organization_id
in: path
required: true
schema:
type: string
format: uuid
description: Organization UUID.
- name: application_id
in: path
required: true
schema:
type: string
format: uuid
description: Application UUID.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- title
properties:
title:
type: string
maxLength: 255
blueprint:
type: string
format: uuid
nullable: true
description: CaseBlueprint UUID. Omit for no blueprint.
priority:
type: string
enum:
- LOW
- MEDIUM
- HIGH
default: MEDIUM
due_at:
type: string
format: date-time
nullable: true
tags:
type: array
items:
type: string
subject:
type: object
description: Required unless links is provided; the case's exactly-one subject.
properties:
type:
type: string
enum:
- user
- business
uuid:
type: string
format: uuid
links:
type: array
description: 'Sessions/business sessions/transactions to attach on creation, e.g. [{"entity_type": "transaction", "entity_uuid": "..."}]. When subject is omitted, the subject is derived from the first link''s owner.'
items:
type: object
assigned_to:
type: string
format: uuid
nullable: true
description: User UUID to assign immediately.
x-codeSamples:
- lang: curl
label: curl
source: "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"title\": \"Manual - Jane Doe\", \"blueprint\": \"b1de0000-0000-4000-8000-000000000002\", \"priority\": \"HIGH\", \"subject\": {\"type\": \"user\", \"uuid\": \"5b9a0000-0000-4000-8000-00000000f00d\"}, \"tags\": [\"review\"]}'"
- lang: python
label: Python
source: "import os\n\nimport requests\n\nresp = requests.post(\n 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/',\n headers={'x-api-key': os.environ['DIDIT_API_KEY']},\n json={\n 'title': 'Manual - Jane Doe',\n 'blueprint': 'b1de0000-0000-4000-8000-000000000002',\n 'priority': 'HIGH',\n 'subject': {'type': 'user', 'uuid': '5b9a0000-0000-4000-8000-00000000f00d'},\n },\n timeout=10,\n)\nresp.raise_for_status()\ncase = resp.json()\nprint(case['case_number'], case['uuid'])"
responses:
'201':
description: Case created.
content:
application/json:
schema:
$ref: '#/components/schemas/CaseDetail'
'400':
description: Neither subject nor links provided, or the subject/blueprint/assignee was not found.
content:
application/json:
schema:
type: object
/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/:
get:
summary: Get case
description: Retrieve a case with its subject, blueprint, notes, events, links, and checklist.
operationId: get_case
tags:
- Cases
parameters:
- name: organization_id
in: path
required: true
schema:
type: string
format: uuid
description: Organization UUID.
- name: application_id
in: path
required: true
schema:
type: string
format: uuid
description: Application UUID.
- name: case_uuid
in: path
required: true
schema:
type: string
format: uuid
example: c1a5e000-0000-4000-8000-000000000001
description: Case UUID.
x-codeSamples:
- lang: curl
label: curl
source: "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/' \\\n -H 'x-api-key: YOUR_API_KEY'"
responses:
'200':
description: Case detail.
content:
application/json:
schema:
$ref: '#/components/schemas/CaseDetail'
'404':
description: Case (or nested resource) not found in this application.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
patch:
summary: Update case
description: Update the case's title, priority, due date, or tags. Logs PRIORITY_CHANGED/DUE_DATE_CHANGED/TAG_ADDED/TAG_REMOVED events as applicable.
operationId: update_case
tags:
- Cases
parameters:
- name: organization_id
in: path
required: true
schema:
type: string
format: uuid
description: Organization UUID.
- name: application_id
in: path
required: true
schema:
type: string
format: uuid
description: Application UUID.
- name: case_uuid
in: path
required: true
schema:
type: string
format: uuid
example: c1a5e000-0000-4000-8000-000000000001
description: Case UUID.
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
title:
type: string
maxLength: 255
priority:
type: string
enum:
- LOW
- MEDIUM
- HIGH
due_at:
type: string
format: date-time
nullable: true
tags:
type: array
items:
type: string
x-codeSamples:
- lang: curl
label: curl
source: "curl -X PATCH 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"priority\": \"HIGH\", \"due_at\": \"2026-08-01T00:00:00Z\"}'"
responses:
'200':
description: Updated case.
content:
application/json:
schema:
$ref: '#/components/schemas/CaseDetail'
delete:
summary: Delete case
description: Soft-delete a case. There is no undelete endpoint; the row is retained internally for audit purposes only.
operationId: delete_case
tags:
- Cases
parameters:
- name: organization_id
in: path
required: true
schema:
type: string
format: uuid
description: Organization UUID.
- name: application_id
in: path
required: true
schema:
type: string
format: uuid
description: Application UUID.
- name: case_uuid
in: path
required: true
schema:
type: string
format: uuid
example: c1a5e000-0000-4000-8000-000000000001
description: Case UUID.
x-codeSamples:
- lang: curl
label: curl
source: "curl -X DELETE 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/' \\\n -H 'x-api-key: YOUR_API_KEY'"
responses:
'204':
description: Case deleted.
/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/assign/:
post:
summary: Assign or unassign case
description: 'Assign the case to a user, or unassign it by sending assignee_user_id: null. assignee_email/assignee_name auto-provision a User row when the assignee does not exist yet.'
operationId: assign_case
tags:
- Cases
parameters:
- name: organization_id
in: path
required: true
schema:
type: string
format: uuid
description: Organization UUID.
- name: application_id
in: path
required: true
schema:
type: string
format: uuid
description: Application UUID.
- name: case_uuid
in: path
required: true
schema:
type: string
format: uuid
example: c1a5e000-0000-4000-8000-000000000001
description: Case UUID.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- assignee_user_id
properties:
assignee_user_id:
type: string
format: uuid
nullable: true
description: null to unassign.
assignee_email:
type: string
format: email
nullable: true
assignee_name:
type: string
nullable: true
x-codeSamples:
- lang: curl
label: curl
source: "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/assign/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"assignee_user_id\": \"9a000000-0000-4000-8000-0000000000aa\"}'"
responses:
'200':
description: Case assigned/unassigned.
content:
application/json:
schema:
$ref: '#/components/schemas/CaseDetail'
/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/resolve/:
post:
summary: Resolve case
description: Resolve the case as false_positive or valid_threat. Blocked with 400 if the blueprint's checklist is not optional and items remain incomplete, or if the blueprint requires a resolution note and none is given. When the case's blueprint has a four_eyes_checker_blueprint configured, the resolution is staged (case.pending_resolution) and the case moves to the checker blueprint instead of resolving immediately; a different user must call approve or reject-approval.
operationId: resolve_case
tags:
- Cases
parameters:
- name: organization_id
in: path
required: true
schema:
type: string
format: uuid
description: Organization UUID.
- name: application_id
in: path
required: true
schema:
type: string
format: uuid
description: Application UUID.
- name: case_uuid
in: path
required: true
schema:
type: string
format: uuid
example: c1a5e000-0000-4000-8000-000000000001
description: Case UUID.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- resolution
properties:
resolution:
type: string
enum:
- FALSE_POSITIVE
- VALID_THREAT
note:
type: string
nullable: true
description: Required when the blueprint sets require_resolution_note.
x-codeSamples:
- lang: curl
label: curl
source: "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/resolve/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"resolution\": \"FALSE_POSITIVE\", \"note\": \"Confirmed legitimate activity after reviewing documents.\"}'"
- lang: python
label: Python
source: "import os\n\nimport requests\n\nresp = requests.post(\n 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/resolve/',\n headers={'x-api-key': os.environ['DIDIT_API_KEY']},\n json={'resolution': 'FALSE_POSITIVE', 'note': 'Confirmed legitimate activity.'},\n timeout=10,\n)\nresp.raise_for_status()\ncase = resp.json()\nprint(case['status'], case['resolution'], case.get('pending_resolution'))"
responses:
'200':
description: Resolved, or staged for 4-eyes approval.
content:
application/json:
schema:
$ref: '#/components/schemas/CaseDetail'
'400':
description: Incomplete checklist items, or a resolution note is required.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/reopen/:
post:
summary: Reopen case
description: Move an awaiting-user or resolved case back to open, clearing resolution, resolution_notes, resolved_at, and resolved_by_email.
operationId: reopen_case
tags:
- Cases
parameters:
- name: organization_id
in: path
required: true
schema:
type: string
format: uuid
description: Organization UUID.
- name: application_id
in: path
required: true
schema:
type: string
format: uuid
description: Application UUID.
- name: case_uuid
in: path
required: true
schema:
type: string
format: uuid
example: c1a5e000-0000-4000-8000-000000000001
description: Case UUID.
x-codeSamples:
- lang: curl
label: curl
source: "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/reopen/' \\\n -H 'x-api-key: YOUR_API_KEY'"
responses:
'200':
description: Reopen case.
content:
application/json:
schema:
$ref: '#/components/schemas/CaseDetail'
/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/request-info/:
post:
summary: Request info (awaiting user)
description: Move an open case to awaiting_user while more information is collected from the verified user. Fails with 400 if a resolution is currently pending 4-eyes approval.
operationId: request_case_info
tags:
- Cases
parameters:
- name: organization_id
in: path
required: true
schema:
type: string
format: uuid
description: Organization UUID.
- name: application_id
in: path
required: true
schema:
type: string
format: uuid
description: Application UUID.
- name: case_uuid
in: path
required: true
schema:
type: string
format: uuid
example: c1a5e000-0000-4000-8000-000000000001
description: Case UUID.
x-codeSamples:
- lang: curl
label: curl
source: "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/request-info/' \\\n -H 'x-api-key: YOUR_API_KEY'"
responses:
'200':
description: Request info (awaiting user).
content:
application/json:
schema:
$ref: '#/components/schemas/CaseDetail'
/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/escalate/:
post:
summary: Escalate case
description: Move the case to its blueprint's configured escalation_blueprint. Requires the current blueprint to have escalation_enabled and an escalation_blueprint set, otherwise 400.
operationId: escalate_case
tags:
- Cases
parameters:
- name: organization_id
in: path
required: true
schema:
type: string
format: uuid
description: Organization UUID.
- name: application_id
in: path
required: true
schema:
type: string
format: uuid
description: Application UUID.
- name: case_uuid
in: path
required: true
schema:
type: string
format: uuid
example: c1a5e000-0000-4000-8000-000000000001
description: Case UUID.
x-codeSamples:
- lang: curl
label: curl
source: "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/escalate/' \\\n -H 'x-api-key: YOUR_API_KEY'"
responses:
'200':
description: Escalate case.
content:
application/json:
schema:
$ref: '#/components/schemas/CaseDetail'
/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/transfer/:
post:
summary: Transfer case
description: Move the case to a different, active blueprint of the same application. Requires the current blueprint to have transfer_enabled, otherwise 400.
operationId: transfer_case
tags:
- Cases
parameters:
- name: organization_id
in: path
required: true
schema:
type: string
format: uuid
description: Organization UUID.
- name: application_id
in: path
required: true
schema:
type: string
format: uuid
description: Application UUID.
- name: case_uuid
in: path
required: true
schema:
type: string
format: uuid
example: c1a5e000-0000-4000-8000-000000000001
description: Case UUID.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- target_blueprint
properties:
target_blueprint:
type: string
format: uuid
x-codeSamples:
- lang: curl
label: curl
source: "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/transfer/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"target_blueprint\": \"b1de0000-0000-4000-8000-000000000002\"}'"
responses:
'200':
description: Case transferred.
content:
application/json:
schema:
$ref: '#/components/schemas/CaseDetail'
/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/approve/:
post:
summary: Approve staged resolution (4-eyes)
description: Apply a resolution staged by resolve on a maker blueprint. The caller must be a different user than the one who submitted it, otherwise 403.
operationId: approve_case_resolution
tags:
- Cases
parameters:
- name: organization_id
in: path
required: true
schema:
type: string
format: uuid
description: Organization UUID.
- name: application_id
in: path
required: true
schema:
type: string
format: uuid
description: Application UUID.
- name: case_uuid
in: path
required: true
schema:
type: string
format: uuid
example: c1a5e000-0000-4000-8000-000000000001
description: Case UUID.
x-codeSamples:
- lang: curl
label: curl
source: "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/approve/' \\\n -H 'x-api-key: YOUR_API_KEY'"
responses:
'200':
description: Resolution applied.
content:
application/json:
schema:
$ref: '#/components/schemas/CaseDetail'
'403':
description: The caller is the same user who submitted the resolution (or the case has no recorded maker); a different officer must approve it.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
'409':
description: Case has no resolution pending approval.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/reject-approval/:
post:
summary: Reject staged resolution (4-eyes)
description: Reject a resolution staged by resolve and return the case to its maker blueprint. The caller must be a different user than the one who submitted it, otherwise 403.
operationId: reject_case_resolution
tags:
- Cases
parameters:
- name: organization_id
in: path
required: true
schema:
type: string
format: uuid
description: Organization UUID.
- name: application_id
in: path
required: true
schema:
type: string
format: uuid
description: Application UUID.
- name: case_uuid
in: path
required: true
schema:
type: string
format: uuid
example: c1a5e000-0000-4000-8000-000000000001
description: Case UUID.
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
notes:
type: string
nullable: true
x-codeSamples:
- lang: curl
label: curl
source: "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/reject-approval/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"notes\": \"Needs a clearer rationale before this can be approved.\"}'"
responses:
'200':
description: Resolution rejected, case returned to the maker blueprint.
content:
application/json:
schema:
$ref: '#/components/schemas/CaseDetail'
'403':
description: The caller is the same user who submitted the resolution (or the case has no recorded maker); a different officer must reject it.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
'409':
description: Case has no resolution pending approval.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/entity-actions/:
post:
summary: Apply entity action
description: 'Act on the case''s subject without leaving the case: set_status changes the user/business status, add_tags applies applicant tags, add_note posts an internal case note, and add_to_blocklist adds the subject''s latest document and face to the blocklist. Logs an ENTITY_ACTION event.'
operationId: apply_case_entity_action
tags:
- Cases
parameters:
- name: organization_id
in: path
required: true
schema:
type: string
format: uuid
description: Organization UUID.
- name: application_id
in: path
required: true
schema:
type: string
format: uuid
description: Application UUID.
- name: case_uuid
in: path
required: true
schema:
type: string
format: uuid
example: c1a5e000-0000-4000-8000-000000000001
description: Case UUID.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- action
properties:
action:
type: string
enum:
- set_status
- add_tags
- add_note
- add_to_blocklist
status:
type: string
nullable: true
description: Required for set_status; a valid VendorUser/VendorBusiness status.
tags:
type: array
items:
type: string
description: Required for add_tags.
note:
type: string
nullable: true
description: Required for add_note.
x-codeSa
# --- truncated at 32 KB (87 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/didit/refs/heads/main/openapi/didit-cases-api-openapi.yml