Didit Regulatory Reports API

openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification Billing Regulatory Reports API
  description: Identity verification API. Authenticate with x-api-key header.
servers:
- url: https://verification.didit.me
tags:
- name: Regulatory Reports
paths:
  /v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/regulatory-reports/:
    get:
      summary: List reports for case
      description: List FIU reports generated for the case.
      operationId: list_case_regulatory_reports
      tags:
      - Regulatory Reports
      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.
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
          minimum: 1
        description: Page size.
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
          minimum: 0
        description: Zero-based offset.
      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/regulatory-reports/' \\\n  -H 'x-api-key: YOUR_API_KEY'"
      responses:
        '200':
          description: Paginated reports for the case.
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: Number of matching rows, capped at 100 for performance.
                  next:
                    type: string
                    nullable: true
                  previous:
                    type: string
                    nullable: true
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/RegulatoryReportDetail'
    post:
      summary: Create report from case
      description: 'Create a draft FIU report for the case: DRAFT status, auto-populated from the optional template plus the case''s subject, linked transactions, and narrative. Validate then finalize to produce the goAML XML and PDF.'
      operationId: create_case_regulatory_report
      tags:
      - Regulatory Reports
      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:
                report_type:
                  type: string
                  enum:
                  - SAR
                  - STR
                  - CTR
                  - TTR
                  - UTR
                  - IFT
                  - CBR
                  - TFR
                  description: Required unless a template is given; the template's report_type is used otherwise.
                jurisdiction:
                  type: string
                  minLength: 2
                  maxLength: 2
                  description: Required unless a template is given.
                template:
                  type: string
                  format: uuid
                  nullable: true
                  description: Report template UUID; its field_config seeds the draft before case-derived data is merged in.
                transactions:
                  type: array
                  items:
                    type: string
                    format: uuid
                  nullable: true
                  description: Transactions to attach; defaults to the case's linked transactions.
                rentity_id:
                  type: string
                  nullable: true
                rentity_branch:
                  type: string
                  nullable: true
                submission_code:
                  type: string
                  enum:
                  - E
                  - M
                  default: E
                entity_reference:
                  type: string
                  nullable: true
                fiu_ref_number:
                  type: string
                  nullable: true
                currency_code_local:
                  type: string
                  minLength: 3
                  maxLength: 3
                  nullable: true
                submission_date:
                  type: string
                  format: date-time
                  nullable: true
                reporting_person:
                  type: object
                location:
                  type: object
                reason:
                  type: string
                  nullable: true
                action:
                  type: string
                  nullable: true
                activity:
                  type: string
                  nullable: true
                narrative:
                  type: object
                  properties:
                    who:
                      type: string
                    what:
                      type: string
                    when:
                      type: string
                    where:
                      type: string
                    why:
                      type: string
                    how:
                      type: string
                report_indicators:
                  type: array
                  items:
                    type: string
                included_fields:
                  type: array
                  items:
                    type: string
      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/regulatory-reports/' \\\n  -H 'x-api-key: YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"template\": \"7ec00000-0000-4000-8000-000000000006\"}'"
      responses:
        '201':
          description: Draft report created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegulatoryReportDetail'
        '400':
          description: The referenced template was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
  /v3/organization/{organization_id}/application/{application_id}/regulatory-reports/:
    get:
      summary: List reports
      description: Application-wide FIU report list, optionally filtered by status, report_type, or case.
      operationId: list_regulatory_reports
      tags:
      - Regulatory Reports
      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.
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
          minimum: 0
        description: Zero-based offset.
      - name: status
        in: query
        schema:
          type: string
          enum:
          - DRAFT
          - VALIDATED
          - FINALIZED
        description: Filter by status.
      - name: report_type
        in: query
        schema:
          type: string
          enum:
          - SAR
          - STR
          - CTR
          - TTR
          - UTR
          - IFT
          - CBR
          - TFR
        description: Filter by report type.
      - name: case
        in: query
        schema:
          type: string
          format: uuid
        description: Filter to reports on this case.
      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/regulatory-reports/' \\\n  -H 'x-api-key: YOUR_API_KEY'"
      responses:
        '200':
          description: Paginated reports across the application.
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: Number of matching rows, capped at 100 for performance.
                  next:
                    type: string
                    nullable: true
                  previous:
                    type: string
                    nullable: true
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/RegulatoryReportDetail'
    post:
      summary: Create standalone report
      description: 'Create a draft FIU report from the standalone Reports page: both case and template are required (unlike the case-scoped create, which can omit template).'
      operationId: create_standalone_regulatory_report
      tags:
      - Regulatory Reports
      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:
              - case
              - template
              properties:
                case:
                  type: string
                  format: uuid
                template:
                  type: string
                  format: uuid
                report_type:
                  type: string
                  enum:
                  - SAR
                  - STR
                  - CTR
                  - TTR
                  - UTR
                  - IFT
                  - CBR
                  - TFR
                  description: Required unless a template is given; the template's report_type is used otherwise.
                jurisdiction:
                  type: string
                  minLength: 2
                  maxLength: 2
                  description: Required unless a template is given.
                transactions:
                  type: array
                  items:
                    type: string
                    format: uuid
                  nullable: true
                  description: Transactions to attach; defaults to the case's linked transactions.
                rentity_id:
                  type: string
                  nullable: true
                rentity_branch:
                  type: string
                  nullable: true
                submission_code:
                  type: string
                  enum:
                  - E
                  - M
                  default: E
                entity_reference:
                  type: string
                  nullable: true
                fiu_ref_number:
                  type: string
                  nullable: true
                currency_code_local:
                  type: string
                  minLength: 3
                  maxLength: 3
                  nullable: true
                submission_date:
                  type: string
                  format: date-time
                  nullable: true
                reporting_person:
                  type: object
                location:
                  type: object
                reason:
                  type: string
                  nullable: true
                action:
                  type: string
                  nullable: true
                activity:
                  type: string
                  nullable: true
                narrative:
                  type: object
                  properties:
                    who:
                      type: string
                    what:
                      type: string
                    when:
                      type: string
                    where:
                      type: string
                    why:
                      type: string
                    how:
                      type: string
                report_indicators:
                  type: array
                  items:
                    type: string
                included_fields:
                  type: array
                  items:
                    type: string
      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/regulatory-reports/' \\\n  -H 'x-api-key: YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"case\": \"c1a5e000-0000-4000-8000-000000000001\", \"template\": \"7ec00000-0000-4000-8000-000000000006\"}'"
      responses:
        '201':
          description: Draft report created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegulatoryReportDetail'
        '400':
          description: The referenced template was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
  /v3/organization/{organization_id}/application/{application_id}/regulatory-reports/{report_uuid}/:
    get:
      summary: Get report
      description: Retrieve a regulatory report.
      operationId: get_regulatory_report
      tags:
      - Regulatory Reports
      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: report_uuid
        in: path
        required: true
        schema:
          type: string
          format: uuid
          example: 5ec00000-0000-4000-8000-000000000007
        description: Report 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/regulatory-reports/5ec00000-0000-4000-8000-000000000007/' \\\n  -H 'x-api-key: YOUR_API_KEY'"
      responses:
        '200':
          description: Report detail.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegulatoryReportDetail'
    patch:
      summary: Update report
      description: Edit a draft or validated report's fields. Finalized reports cannot be edited (409).
      operationId: update_regulatory_report
      tags:
      - Regulatory Reports
      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: report_uuid
        in: path
        required: true
        schema:
          type: string
          format: uuid
          example: 5ec00000-0000-4000-8000-000000000007
        description: Report UUID.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                jurisdiction:
                  type: string
                  minLength: 2
                  maxLength: 2
                rentity_id:
                  type: string
                  nullable: true
                rentity_branch:
                  type: string
                  nullable: true
                submission_code:
                  type: string
                  enum:
                  - E
                  - M
                  default: E
                entity_reference:
                  type: string
                  nullable: true
                fiu_ref_number:
                  type: string
                  nullable: true
                currency_code_local:
                  type: string
                  minLength: 3
                  maxLength: 3
                  nullable: true
                submission_date:
                  type: string
                  format: date-time
                  nullable: true
                reporting_person:
                  type: object
                location:
                  type: object
                reason:
                  type: string
                  nullable: true
                action:
                  type: string
                  nullable: true
                activity:
                  type: string
                  nullable: true
                narrative:
                  type: object
                  properties:
                    who:
                      type: string
                    what:
                      type: string
                    when:
                      type: string
                    where:
                      type: string
                    why:
                      type: string
                    how:
                      type: string
                report_indicators:
                  type: array
                  items:
                    type: string
                included_fields:
                  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/regulatory-reports/5ec00000-0000-4000-8000-000000000007/' \\\n  -H 'x-api-key: YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"rentity_id\": \"FIU-US-00123\", \"currency_code_local\": \"USD\"}'"
      responses:
        '200':
          description: Updated report.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegulatoryReportDetail'
        '409':
          description: Report is already finalized.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
    delete:
      summary: Delete report
      description: Soft-delete a draft or validated report. Finalized reports cannot be deleted (409).
      operationId: delete_regulatory_report
      tags:
      - Regulatory Reports
      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: report_uuid
        in: path
        required: true
        schema:
          type: string
          format: uuid
          example: 5ec00000-0000-4000-8000-000000000007
        description: Report 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/regulatory-reports/5ec00000-0000-4000-8000-000000000007/' \\\n  -H 'x-api-key: YOUR_API_KEY'"
      responses:
        '204':
          description: Report deleted.
        '409':
          description: Report is already finalized.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
  /v3/organization/{organization_id}/application/{application_id}/regulatory-reports/{report_uuid}/validate/:
    post:
      summary: Validate report
      description: 'Check the report against the obligatory goAML header fields (reporting entity ID, submission code, local currency, action taken, submission date), plus at least one attached transaction and a 2-letter jurisdiction, without generating any files. Also stores the result on the report: validation_errors and validated_at are updated, and a non-finalized report''s status moves to VALIDATED (no errors) or back to DRAFT (errors).'
      operationId: validate_regulatory_report
      tags:
      - Regulatory Reports
      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: report_uuid
        in: path
        required: true
        schema:
          type: string
          format: uuid
          example: 5ec00000-0000-4000-8000-000000000007
        description: Report 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/regulatory-reports/5ec00000-0000-4000-8000-000000000007/validate/' \\\n  -H 'x-api-key: YOUR_API_KEY'"
      responses:
        '200':
          description: Validation result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - DRAFT
                    - VALIDATED
                    - FINALIZED
                  is_valid:
                    type: boolean
                  errors:
                    type: array
                    description: Empty when valid.
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        message:
                          type: string
  /v3/organization/{organization_id}/application/{application_id}/regulatory-reports/{report_uuid}/finalize/:
    post:
      summary: Finalize report
      description: Re-validate, then render the goAML XML and PDF and upload both to S3. On SAR/STR/TFR reports, this also moves the case's transaction alerts from Pending SAR to SAR filed.
      operationId: finalize_regulatory_report
      tags:
      - Regulatory Reports
      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: report_uuid
        in: path
        required: true
        schema:
          type: string
          format: uuid
          example: 5ec00000-0000-4000-8000-000000000007
        description: Report 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/regulatory-reports/5ec00000-0000-4000-8000-000000000007/finalize/' \\\n  -H 'x-api-key: YOUR_API_KEY'"
      - 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/regulatory-reports/5ec00000-0000-4000-8000-000000000007/finalize/',\n    headers={'x-api-key': os.environ['DIDIT_API_KEY']},\n    timeout=30,\n)\nif resp.status_code == 400:\n    print('Validation failed:', resp.json()['errors'])\nelse:\n    resp.raise_for_status()\n    report = resp.json()\n    print(report['status'], report['report_number'])"
      responses:
        '200':
          description: Report finalized; xml_s3_key and pdf_s3_key are set.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegulatoryReportDetail'
        '400':
          description: Report failed validation.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        message:
                          type: string
        '409':
          description: Report is not in a finalizable state.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
  /v3/organization/{organization_id}/application/{application_id}/regulatory-reports/{report_uuid}/download-url/:
    get:
      summary: Get report download URL
      description: Mint a presigned URL for a finalized report's goAML XML or PDF.
      operationId: get_regulatory_report_download_url
      tags:
      - Regulatory Reports
      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: report_uuid
        in: path
        required: true
        schema:
          type: string
          format: uuid
          example: 5ec00000-0000-4000-8000-000000000007
        description: Report UUID.
      - name: file
        in: query
        schema:
          type: string
          enum:
          - pdf
          - xml
          default: pdf
        description: Which file to download.
      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/regulatory-reports/5ec00000-0000-4000-8000-000000000007/download-url/?file=xml' \\\n  -H 'x-api-key: YOUR_API_KEY'"
      responses:
        '200':
          description: Presigned download URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  download_url:
                    type: string
                    format: uri
                  file:
                    type: string
                    enum:
                    - pdf
                    - xml
        '409':
          description: Report is not finalized yet.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                  status:
                    type: string
components:
  schemas:
    RegulatoryReportDetail:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        case_uuid:
          type: string
          format: uuid
        case_number:
          type: string
          nullable: true
        report_type:
          type: string
          enum:
          - SAR
          - STR
          - CTR
          - TTR
          - UTR
          - IFT
          - CBR
          - TFR
        report_type_display:
          type: string
        report_code:
          type: string
          description: goAML report code derived from report_type, e.g. STR, CTR, BCR.
        report_number:
          type: string
          nullable: true
        status:
          type: string
          enum:
          - DRAFT
          - VALIDATED
          - FINALIZED
        status_display:
          type: string
        jurisdiction:
          type: string
          minLength: 2
          maxLength: 2
        rentity_id:
          type: string
          nullable: true
          description: Reporting entity ID issued by the FIU.
        rentity_branch:
          type: string
          nullable: true
        submission_code:
          type: string
          enum:
          - E
          - M
        entity_reference:
          type: string
          nullable: true
        fiu_ref_number:
          type: string
          nullable: true
        currency_code_local:
          type: string
          minLength: 3
          maxLength: 3
          nullable: true
        submission_date:
          type: string
          format: date-time
          nullable: true
        reporting_person:
          type: object
        location:
          type: object
        reason:
          type: string
          nullable: true
        action:
          type: string
          nullable: true
        activity:
          type: string
          nullable: true
        narrative:
          type: object
          description: Five Ws narrative sections.
          properties:
            who:
              type: string
            what:
              type: string
            when:
              type: string
            where:
              type: string
            why:
              type: string
            how:
              type: string
        report_indicators:
          type: array
          items:
            type: string
        included_fields:
          type: array
          items:
            type: string
        transactions:
          type: array
          items:
            type: string
            format: uuid
        validation_errors:
          type: array
          description: Result of the most recent validation; each entry is a {field, message} object.
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
        validated_at:
          type: string
          format: date-time
          nullable: true
        finalized_at:
          type: string
          format: date-time
          nullable: true
        created_by_email:
          type: string
          nullable: true
        created_by_name:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
    TransactionTokenAuth:
      type: apiKey
     

# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/didit/refs/heads/main/openapi/didit-regulatory-reports-api-openapi.yml