openapi: 3.0.3 info: title: Dimmi Public API version: 1.0.0 description: >- External, organization-scoped API for Dimmi cases and documents. Authenticate with `Authorization: Bearer dk_live_.`. paths: /admin/api-keys: get: operationId: admin_api_keys_list summary: List API keys for the calling organisation tags: - admin security: - JWTAuth: [] responses: '200': content: application/json: schema: type: array items: $ref: '#/components/schemas/ApiKey' description: '' post: operationId: admin_api_keys_create summary: Create an API key (returns secret exactly once) tags: - admin security: - JWTAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/ApiKeyCreateResponse' description: '' /admin/api-keys/{key_id}/revoke: post: operationId: admin_api_keys_revoke_create summary: Revoke an API key parameters: - in: path name: key_id schema: type: string format: uuid required: true tags: - admin security: - JWTAuth: [] responses: '200': description: No response body /admin/webhooks: get: operationId: admin_webhooks_list summary: List webhooks for the calling organisation tags: - admin security: - JWTAuth: [] responses: '200': content: application/json: schema: type: array items: $ref: '#/components/schemas/Webhook' description: '' post: operationId: admin_webhooks_create summary: Create a webhook (returns secret once) tags: - admin security: - JWTAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/WebhookSecret' description: '' /admin/webhooks/{webhook_id}: get: operationId: admin_webhooks_retrieve summary: Retrieve a webhook parameters: - in: path name: webhook_id schema: type: string format: uuid required: true tags: - admin security: - JWTAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/Webhook' description: '' patch: operationId: admin_webhooks_partial_update summary: Update a webhook parameters: - in: path name: webhook_id schema: type: string format: uuid required: true tags: - admin security: - JWTAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/Webhook' description: '' delete: operationId: admin_webhooks_destroy summary: Delete a webhook parameters: - in: path name: webhook_id schema: type: string format: uuid required: true tags: - admin security: - JWTAuth: [] responses: '204': description: No response body /admin/webhooks/{webhook_id}/deliveries: get: operationId: admin_webhooks_deliveries_list summary: List recent delivery attempts for a webhook parameters: - in: path name: webhook_id schema: type: string format: uuid required: true tags: - admin security: - JWTAuth: [] responses: '200': content: application/json: schema: type: array items: $ref: '#/components/schemas/WebhookDelivery' description: '' /assignments: get: operationId: assignments_list description: >- Common base for /api/v1/* views: API-key auth, throttle, JSON-only error envelope. summary: List cross-border assignments parameters: - in: query name: cursor schema: type: string - in: query name: host_country schema: type: string - in: query name: journey_kind schema: type: string - in: query name: page_size schema: type: integer - in: query name: person_id schema: type: string tags: - assignments security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedPublicAssignmentList' description: '' /assignments/{assignment_id}: get: operationId: assignments_retrieve description: >- Common base for /api/v1/* views: API-key auth, throttle, JSON-only error envelope. summary: Retrieve an assignment parameters: - in: path name: assignment_id schema: type: string required: true tags: - assignments security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/PublicAssignment' description: '' /cases: get: operationId: cases_list description: >- Common base for /api/v1/* views: API-key auth, throttle, JSON-only error envelope. summary: List cases in the organization parameters: - in: query name: case_kind schema: type: string description: extension | family - in: query name: category schema: type: string description: immigration | social_security | relocation - in: query name: certificate_type schema: type: string description: a1 | s1 - in: query name: cursor schema: type: string description: Pagination cursor. - in: query name: external_reference schema: type: string description: Filter by your own ID for the case. - in: query name: jurisdiction schema: type: string - in: query name: lifecycle_stage schema: type: string - in: query name: needs_attention schema: type: string - in: query name: ongoing schema: type: string - in: query name: page_size schema: type: integer description: Page size (max 100). - in: query name: person_id schema: type: string - in: query name: search schema: type: string - in: query name: status schema: type: string description: >- Filter by status. One of: biometrics, draft, in_progress, permit_acquired, permit_expired, permit_expires_soon, processing, ready_to_submit, submitted - in: query name: updated_since schema: type: string description: ISO-8601 timestamp; only cases updated since. tags: - cases security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedPublicCaseList' description: '' post: operationId: cases_create description: >- Common base for /api/v1/* views: API-key auth, throttle, JSON-only error envelope. summary: >- Create a case (typed JSON for client parity, or multipart contract upload) tags: - cases security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/PublicCase' description: '' /cases/{case_id}: get: operationId: cases_retrieve description: >- Common base for /api/v1/* views: API-key auth, throttle, JSON-only error envelope. summary: Retrieve a single case parameters: - in: path name: case_id schema: type: string required: true tags: - cases security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/PublicCase' description: '' /cases/{case_id}/complete: post: operationId: cases_complete_create description: >- POST /api/v1/cases/{id}/complete — finish start-case wizard / Policy approvals. summary: Complete the start-case wizard for a draft case parameters: - in: path name: case_id schema: type: string required: true tags: - cases security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/PublicCase' description: '' /cases/{case_id}/documents: get: operationId: cases_documents_list description: >- Common base for /api/v1/* views: API-key auth, throttle, JSON-only error envelope. summary: List documents for a case parameters: - in: path name: case_id schema: type: string required: true - name: cursor required: false in: query description: The pagination cursor value. schema: type: string - name: page_size required: false in: query description: Number of results to return per page. schema: type: integer tags: - cases security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedPublicDocumentList' description: '' post: operationId: cases_documents_create description: >- Common base for /api/v1/* views: API-key auth, throttle, JSON-only error envelope. summary: Upload a document to a case parameters: - in: path name: case_id schema: type: string required: true tags: - cases security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/PublicDocument' description: '' /certificates: get: operationId: certificates_list description: >- Common base for /api/v1/* views: API-key auth, throttle, JSON-only error envelope. summary: List certificates (employee records and social-security cases) parameters: - in: query name: cursor schema: type: string - in: query name: ongoing schema: type: string - in: query name: page_size schema: type: integer - in: query name: person_id schema: type: string - in: query name: source schema: type: string description: employee_record or case - in: query name: type schema: type: string description: a1 or s1 tags: - certificates security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedPublicCertificateList' description: '' /certificates/{certificate_id}: get: operationId: certificates_retrieve description: >- Common base for /api/v1/* views: API-key auth, throttle, JSON-only error envelope. summary: Retrieve a certificate parameters: - in: path name: certificate_id schema: type: string required: true tags: - certificates security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/PublicCertificate' description: '' /company-certification-cases: post: operationId: company_certification_cases_create description: >- Common base for /api/v1/* views: API-key auth, throttle, JSON-only error envelope. summary: Create a company certification case tags: - company-certification-cases security: - ApiKeyAuth: [] responses: '200': description: No response body /documents/{document_id}: get: operationId: documents_retrieve description: >- Common base for /api/v1/* views: API-key auth, throttle, JSON-only error envelope. summary: Retrieve document metadata + signed download URL parameters: - in: path name: document_id schema: type: string required: true tags: - documents security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/PublicDocument' description: '' /documents/{document_id}/content: get: operationId: documents_content_retrieve description: >- Issues a fresh presigned URL via 302 so partner integrations can download files. summary: Redirect (302) to a fresh presigned download URL parameters: - in: path name: document_id schema: type: string required: true tags: - documents security: - ApiKeyAuth: [] responses: '200': description: No response body /people: get: operationId: people_list description: >- Common base for /api/v1/* views: API-key auth, throttle, JSON-only error envelope. summary: List people (employees) in the organisation parameters: - in: query name: cursor schema: type: string - in: query name: page_size schema: type: integer - in: query name: search schema: type: string tags: - people security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedPublicPersonList' description: '' /people/{person_id}: get: operationId: people_retrieve description: >- Common base for /api/v1/* views: API-key auth, throttle, JSON-only error envelope. summary: Retrieve a person parameters: - in: path name: person_id schema: type: string required: true tags: - people security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/PublicPerson' description: '' /permits: get: operationId: permits_list description: >- Common base for /api/v1/* views: API-key auth, throttle, JSON-only error envelope. summary: List issued permits parameters: - in: query name: cursor schema: type: string - in: query name: jurisdiction schema: type: string - in: query name: page_size schema: type: integer - in: query name: person_id schema: type: string - in: query name: search schema: type: string - in: query name: status schema: type: string - in: query name: valid_until_after schema: type: string - in: query name: valid_until_before schema: type: string tags: - permits security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedPublicPermitResourceList' description: '' /permits/{permit_id}: get: operationId: permits_retrieve description: >- Common base for /api/v1/* views: API-key auth, throttle, JSON-only error envelope. summary: Retrieve a permit parameters: - in: path name: permit_id schema: type: string required: true tags: - permits security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/PublicPermitResource' description: '' /schemes: get: operationId: schemes_retrieve description: >- Common base for /api/v1/* views: API-key auth, throttle, JSON-only error envelope. summary: List supported schemes (DK) tags: - schemes security: - ApiKeyAuth: [] responses: '200': description: No response body /short-term-cases: post: operationId: short_term_cases_create description: >- Common base for /api/v1/* views: API-key auth, throttle, JSON-only error envelope. summary: Create short-term visitor cases (one per member) tags: - short-term-cases security: - ApiKeyAuth: [] responses: '200': description: No response body /webhooks: get: operationId: webhooks_list description: >- Common base for /api/v1/* views: API-key auth, throttle, JSON-only error envelope. summary: List webhooks for the calling API key org tags: - webhooks security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: type: array items: $ref: '#/components/schemas/Webhook' description: '' post: operationId: webhooks_create description: >- Common base for /api/v1/* views: API-key auth, throttle, JSON-only error envelope. summary: Create a webhook (returns secret once) tags: - webhooks security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/WebhookSecret' description: '' /webhooks/{webhook_id}: get: operationId: webhooks_retrieve description: >- Common base for /api/v1/* views: API-key auth, throttle, JSON-only error envelope. summary: Retrieve a webhook parameters: - in: path name: webhook_id schema: type: string required: true tags: - webhooks security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/Webhook' description: '' patch: operationId: webhooks_partial_update description: >- Common base for /api/v1/* views: API-key auth, throttle, JSON-only error envelope. summary: Update a webhook parameters: - in: path name: webhook_id schema: type: string required: true tags: - webhooks security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/Webhook' description: '' delete: operationId: webhooks_destroy description: >- Common base for /api/v1/* views: API-key auth, throttle, JSON-only error envelope. summary: Delete a webhook parameters: - in: path name: webhook_id schema: type: string required: true tags: - webhooks security: - ApiKeyAuth: [] responses: '204': description: No response body components: schemas: ApiKey: type: object description: Read shape for listing keys; secret is never returned here. properties: id: type: string readOnly: true name: type: string description: Human label, e.g. "Workday integration". maxLength: 128 environment: $ref: '#/components/schemas/EnvironmentEnum' display_key: type: string readOnly: true scopes: type: array items: $ref: '#/components/schemas/ScopesEnum' rate_limit_per_min: type: integer maximum: 2147483647 minimum: -2147483648 last_used_at: type: string format: date-time nullable: true expires_at: type: string format: date-time nullable: true revoked_at: type: string format: date-time nullable: true created_at: type: string format: date-time readOnly: true required: - created_at - display_key - id - name - scopes ApiKeyCreateResponse: type: object description: Returned exactly once on POST; includes the plaintext secret. properties: id: type: string name: type: string environment: type: string display_key: type: string secret: type: string full_token: type: string description: 'The complete `Authorization: Bearer ...` token, shown once.' scopes: type: array items: type: string rate_limit_per_min: type: integer expires_at: type: string format: date-time nullable: true created_at: type: string format: date-time required: - created_at - display_key - environment - expires_at - full_token - id - name - rate_limit_per_min - scopes - secret EnvironmentEnum: enum: - live - test type: string description: |- * `live` - Live * `test` - Test EventsEnum: enum: - case.created - case.status_changed - case.document_uploaded - case.linked - permit.granted - permit.expiring - permit.expired - certificate.granted - assignment.created - monitoring.employee_at_risk - monitoring.crisis_alert type: string description: |- * `case.created` - case.created * `case.status_changed` - case.status_changed * `case.document_uploaded` - case.document_uploaded * `case.linked` - case.linked * `permit.granted` - permit.granted * `permit.expiring` - permit.expiring * `permit.expired` - permit.expired * `certificate.granted` - certificate.granted * `assignment.created` - assignment.created * `monitoring.employee_at_risk` - monitoring.employee_at_risk * `monitoring.crisis_alert` - monitoring.crisis_alert PaginatedPublicAssignmentList: type: object required: - results properties: next: type: string nullable: true format: uri example: http://api.example.org/accounts/?cursor=cD00ODY%3D" previous: type: string nullable: true format: uri example: http://api.example.org/accounts/?cursor=cj0xJnA9NDg3 results: type: array items: $ref: '#/components/schemas/PublicAssignment' PaginatedPublicCaseList: type: object required: - results properties: next: type: string nullable: true format: uri example: http://api.example.org/accounts/?cursor=cD00ODY%3D" previous: type: string nullable: true format: uri example: http://api.example.org/accounts/?cursor=cj0xJnA9NDg3 results: type: array items: $ref: '#/components/schemas/PublicCase' PaginatedPublicCertificateList: type: object required: - results properties: next: type: string nullable: true format: uri example: http://api.example.org/accounts/?cursor=cD00ODY%3D" previous: type: string nullable: true format: uri example: http://api.example.org/accounts/?cursor=cj0xJnA9NDg3 results: type: array items: $ref: '#/components/schemas/PublicCertificate' PaginatedPublicDocumentList: type: object required: - results properties: next: type: string nullable: true format: uri example: http://api.example.org/accounts/?cursor=cD00ODY%3D" previous: type: string nullable: true format: uri example: http://api.example.org/accounts/?cursor=cj0xJnA9NDg3 results: type: array items: $ref: '#/components/schemas/PublicDocument' PaginatedPublicPermitResourceList: type: object required: - results properties: next: type: string nullable: true format: uri example: http://api.example.org/accounts/?cursor=cD00ODY%3D" previous: type: string nullable: true format: uri example: http://api.example.org/accounts/?cursor=cj0xJnA9NDg3 results: type: array items: $ref: '#/components/schemas/PublicPermitResource' PaginatedPublicPersonList: type: object required: - results properties: next: type: string nullable: true format: uri example: http://api.example.org/accounts/?cursor=cD00ODY%3D" previous: type: string nullable: true format: uri example: http://api.example.org/accounts/?cursor=cj0xJnA9NDg3 results: type: array items: $ref: '#/components/schemas/PublicPerson' PublicAssignment: type: object properties: id: type: string readOnly: true object: type: string readOnly: true journey_kind: type: string home_country: type: string host_country: type: string start_date: type: string format: date nullable: true end_date: type: string format: date nullable: true applicant_email: type: string format: email person_id: type: string nullable: true readOnly: true case_ids: type: array items: {} readOnly: true created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true required: - applicant_email - case_ids - created_at - end_date - home_country - host_country - id - journey_kind - object - person_id - start_date - updated_at PublicCase: type: object description: Read-only Case representation for /api/v1/cases. properties: id: type: string readOnly: true object: type: string readOnly: true status: type: string readOnly: true type: type: string readOnly: true jurisdiction: type: string readOnly: true scheme_key: type: string nullable: true readOnly: true display_number: type: string nullable: true readOnly: true applicant: type: object additionalProperties: {} readOnly: true person_id: type: string nullable: true readOnly: true company: type: object additionalProperties: {} nullable: true readOnly: true permit: type: object additionalProperties: {} readOnly: true employment: type: object additionalProperties: {} readOnly: true assignment_id: type: string nullable: true readOnly: true is_extension: type: boolean readOnly: true parent_case_id: type: string nullable: true readOnly: true linked_cases: type: array items: {} readOnly: true assignment: type: object additionalProperties: {} nullable: true readOnly: true has_documents: type: boolean nullable: true readOnly: true external_reference: type: string readOnly: true created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true required: - applicant - assignment - assignment_id - company - created_at - display_number - employment - external_reference - has_documents - id - is_extension - jurisdiction - linked_cases - object - parent_case_id - permit - person_id - scheme_key - status - type - updated_at PublicCertificate: type: object properties: id: type: string readOnly: true object: type: string readOnly: true source: type: string readOnly: true type: type: string readOnly: true status: type: string nullable: true readOnly: true person_id: type: string nullable: true readOnly: true case_id: type: string nullable: true readOnly: true valid_from: type: string readOnly: true valid_until: type: string readOnly: true jurisdiction: type: string readOnly: true has_document: type: boolean readOnly: true required: - case_id - has_document - id - jurisdiction - object - person_id - source - status - type - valid_from - valid_until PublicDocument: type: object properties: id: type: string readOnly: true object: type: string readOnly: true case_id: type: string readOnly: true type: type: string readOnly: true file_name: type: string readOnly: true mime_type: type: string readOnly: true size_bytes: type: string readOnly: true uploaded_at: type: string format: date-time readOnly: true download_url: type: string readOnly: true download_url_expires_at: type: string readOnly: true required: - case_id - download_url - download_url_expires_at - file_name - id - mime_type - object - size_bytes - type - uploaded_at PublicPermitResource: type: object properties: id: type: string readOnly: true object: type: string readOnly: true status: type: string readOnly: true case_id: type: string readOnly: true person_id: type: string nullable: true readOnly: true applicant: type: object additionalProperties: {} readOnly: true jurisdiction: type: string readOnly: true scheme_key: type: string nullable: true readOnly: true type: type: string readOnly: true valid_from: type: string readOnly: true valid_until: type: string readOnly: true has_document: type: boolean readOnly: true updated_at: type: string format: date-time readOnly: true required: - applicant - case_id - has_document - id - jurisdiction - object - person_id - scheme_key - status - type - updated_at - valid_from - valid_until PublicPerson: type: object properties: id: type: string readOnly: true object: type: string readOnly: true email: type: string readOnly: true full_name: type: string nullable: true readOnly: true job_title: type: string department: type: string nationality: type: string nullable: true readOnly: true permit: type: object additionalProperties: {} nullable: true readOnly: true active_certificates: type: array items: {} readOnly: true in_progress_cases: type: array items: {} readOnly: true created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true required: - active_certificates - created_at - email - full_name - id - in_progress_cases - nationality - object - permit - updated_at ScopesEnum: enum: - cases:read - cases:write - documents:read - documents:write - people:read - permits:read - certificates:read - webhooks:read - webhooks:write type: string description: |- * `cases:read` - cases:read * `cases:write` - cases:write * `documents:read` - documents:read * `documents:write` - documents:write * `people:read` - people:read * `permits:read` - permits:read * `certificates:read` - certificates:read * `webhooks:read` - webhooks:read * `webhooks:write` - webhooks:write StatusEnum: enum: - pending - delivered - failed type: string description: |- * `pending` - Pending * `delivered` - Delivered * `failed` - Failed Webhook: type: object description: >- Public Webhook representation. ``secret`` is exposed only on creation (separate path). properties: id: type: string readOnly: true url: type: string format: uri events: type: array items: $ref: '#/components/schemas/EventsEnum' description: type: string active: type: boolean created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true required: - created_at - events - id - updated_at - url WebhookDelivery: type: object properties: id: type: string readOnly: true webhook_id: type: string readOnly: true event_id: type: string format: uuid readOnly: true event_type: type: string maxLength: 64 status: $ref: '#/components/schemas/StatusEnum' attempts: type: integer maximum: 2147483647 minimum: -2147483648 response_code: type: integer maximum: 2147483647 minimum: -2147483648 nullable: true response_body_excerpt: type: string error_message: type: string next_retry_at: type: string format: date-time nullable: true delivered_at: type: string format: date-time nullable: true created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true required: - created_at - event_id - event_type - id - updated_at - webhook_id WebhookSecret: type: object description: Returned exactly once on creation; includes the signing secret. properties: id: type: string readOnly: true url: type: string format: uri maxLength: 1024 events: {} description: type: string maxLength: 255 active: type: boolean secret: type: string readOnly: true created_at: type: string format: date-time readOnly: true required: - created_at - id - secret - url securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: dk__. description: >- Provide your API key as `Authorization: Bearer dk_live_.`. JWTAuth: type: http scheme: bearer bearerFormat: JWT description: JWT issued by the Dimmi case-manager login flow.