chore: import upstream snapshot with attribution

apps/sim/tools/persona/approve_inquiry.ts

@@ -0,0 +1,61 @@
+import type { PersonaApproveInquiryParams, PersonaInquiryResponse } from '@/tools/persona/types'
+import {
+  asResource,
+  buildPersonaHeaders,
+  INQUIRY_OUTPUT_PROPERTIES,
+  mapInquiry,
+  PERSONA_API_BASE,
+  parsePersonaResponse,
+} from '@/tools/persona/utils'
+import type { ToolConfig } from '@/tools/types'
+
+export const personaApproveInquiryTool: ToolConfig<
+  PersonaApproveInquiryParams,
+  PersonaInquiryResponse
+> = {
+  id: 'persona_approve_inquiry',
+  name: 'Persona Approve Inquiry',
+  description:
+    'Approve an identity verification inquiry. Approving prevents further progress on the inquiry and triggers any associated workflows and webhooks.',
+  version: '1.0.0',
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Persona API key',
+    },
+    inquiryId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Inquiry ID to approve (starts with inq_)',
+    },
+  },
+
+  request: {
+    url: (params) =>
+      `${PERSONA_API_BASE}/inquiries/${encodeURIComponent(params.inquiryId.trim())}/approve`,
+    method: 'POST',
+    headers: (params) => buildPersonaHeaders(params.apiKey),
+  },
+
+  transformResponse: async (response) => {
+    const data = await parsePersonaResponse(response)
+    return {
+      success: true,
+      output: {
+        inquiry: mapInquiry(asResource(data.data)),
+      },
+    }
+  },
+
+  outputs: {
+    inquiry: {
+      type: 'object',
+      description: 'The approved inquiry',
+      properties: INQUIRY_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/persona/create_account.ts

@@ -0,0 +1,109 @@
+import type { PersonaAccountResponse, PersonaCreateAccountParams } from '@/tools/persona/types'
+import {
+  ACCOUNT_OUTPUT_PROPERTIES,
+  asResource,
+  buildPersonaHeaders,
+  mapAccount,
+  PERSONA_API_BASE,
+  parseJsonObjectParam,
+  parsePersonaResponse,
+  parseStringArrayParam,
+} from '@/tools/persona/utils'
+import type { ToolConfig } from '@/tools/types'
+
+export const personaCreateAccountTool: ToolConfig<
+  PersonaCreateAccountParams,
+  PersonaAccountResponse
+> = {
+  id: 'persona_create_account',
+  name: 'Persona Create Account',
+  description:
+    'Create an account that represents an individual in Persona. Accounts consolidate inquiries, verifications, and reports for the same person.',
+  version: '1.0.0',
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Persona API key',
+    },
+    accountTypeId: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        'Account type ID to create the account for (starts with acttp_); defaults to your organization default',
+    },
+    referenceId: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Reference ID that refers to an entity in your user model',
+    },
+    countryCode: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'ISO 3166-1 alpha-2 country code (e.g. US)',
+    },
+    fields: {
+      type: 'json',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        'JSON object of field name to field value pairs, as defined by the account type (e.g. {"name-first": "Jane"})',
+    },
+    tags: {
+      type: 'array',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'JSON array of tag names to associate with the account (e.g. ["vip"])',
+    },
+  },
+
+  request: {
+    url: `${PERSONA_API_BASE}/accounts`,
+    method: 'POST',
+    headers: (params) => buildPersonaHeaders(params.apiKey),
+    body: (params) => {
+      const attributes: Record<string, unknown> = {}
+      if (params.accountTypeId?.trim()) {
+        attributes['account-type-id'] = params.accountTypeId.trim()
+      }
+      if (params.referenceId?.trim()) {
+        attributes['reference-id'] = params.referenceId.trim()
+      }
+      if (params.countryCode?.trim()) {
+        attributes['country-code'] = params.countryCode.trim()
+      }
+      const fields = parseJsonObjectParam(params.fields, 'Fields')
+      if (fields) {
+        attributes.fields = fields
+      }
+      const tags = parseStringArrayParam(params.tags, 'Tags')
+      if (tags) {
+        attributes.tags = tags
+      }
+      return { data: { attributes } }
+    },
+  },
+
+  transformResponse: async (response) => {
+    const data = await parsePersonaResponse(response)
+    return {
+      success: true,
+      output: {
+        account: mapAccount(asResource(data.data)),
+      },
+    }
+  },
+
+  outputs: {
+    account: {
+      type: 'object',
+      description: 'The created account',
+      properties: ACCOUNT_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/persona/create_inquiry.ts

@@ -0,0 +1,131 @@
+import type { PersonaCreateInquiryParams, PersonaInquiryResponse } from '@/tools/persona/types'
+import {
+  asResource,
+  buildPersonaHeaders,
+  INQUIRY_OUTPUT_PROPERTIES,
+  mapInquiry,
+  PERSONA_API_BASE,
+  parseJsonObjectParam,
+  parsePersonaResponse,
+} from '@/tools/persona/utils'
+import type { ToolConfig } from '@/tools/types'
+
+export const personaCreateInquiryTool: ToolConfig<
+  PersonaCreateInquiryParams,
+  PersonaInquiryResponse
+> = {
+  id: 'persona_create_inquiry',
+  name: 'Persona Create Inquiry',
+  description:
+    'Create a new identity verification inquiry from an inquiry template. Returns the created inquiry, which can then be completed by the individual via a one-time link.',
+  version: '1.0.0',
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Persona API key',
+    },
+    inquiryTemplateId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description:
+        'Inquiry template ID (starts with itmpl_), inquiry template version ID (starts with itmplv_), or legacy template ID (starts with tmpl_)',
+    },
+    accountId: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Account ID (starts with act_) to associate with this inquiry',
+    },
+    referenceId: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        'Reference ID that refers to an entity in your user model. An account is auto-created for it if one does not exist.',
+    },
+    fields: {
+      type: 'json',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        'JSON object of field name to field value pairs to pre-fill, as defined by the inquiry template (e.g. {"name-first": "Jane"})',
+    },
+    note: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Free-form note to attach to the inquiry',
+    },
+    redirectUri: {
+      type: 'string',
+      required: false,
+      visibility: 'user-only',
+      description: 'URI to redirect the individual to after completing the inquiry flow',
+    },
+  },
+
+  request: {
+    url: `${PERSONA_API_BASE}/inquiries`,
+    method: 'POST',
+    headers: (params) => buildPersonaHeaders(params.apiKey),
+    body: (params) => {
+      const templateId = params.inquiryTemplateId?.trim()
+      if (!templateId) {
+        throw new Error('Inquiry template ID is required')
+      }
+
+      const attributes: Record<string, unknown> = {}
+      if (templateId.startsWith('itmplv_')) {
+        attributes['inquiry-template-version-id'] = templateId
+      } else if (templateId.startsWith('itmpl_')) {
+        attributes['inquiry-template-id'] = templateId
+      } else if (templateId.startsWith('tmpl_')) {
+        attributes['template-id'] = templateId
+      } else {
+        throw new Error('Inquiry template ID must start with itmpl_, itmplv_, or tmpl_')
+      }
+
+      if (params.accountId?.trim()) {
+        attributes['account-id'] = params.accountId.trim()
+      }
+      const fields = parseJsonObjectParam(params.fields, 'Fields')
+      if (fields) {
+        attributes.fields = fields
+      }
+      if (params.note?.trim()) {
+        attributes.note = params.note.trim()
+      }
+      if (params.redirectUri?.trim()) {
+        attributes['redirect-uri'] = params.redirectUri.trim()
+      }
+
+      const body: Record<string, unknown> = { data: { attributes } }
+      if (params.referenceId?.trim()) {
+        body.meta = { 'auto-create-account-reference-id': params.referenceId.trim() }
+      }
+      return body
+    },
+  },
+
+  transformResponse: async (response) => {
+    const data = await parsePersonaResponse(response)
+    return {
+      success: true,
+      output: {
+        inquiry: mapInquiry(asResource(data.data)),
+      },
+    }
+  },
+
+  outputs: {
+    inquiry: {
+      type: 'object',
+      description: 'The created inquiry',
+      properties: INQUIRY_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/persona/create_report.ts

@@ -0,0 +1,155 @@
+import type { PersonaCreateReportParams, PersonaReportResponse } from '@/tools/persona/types'
+import {
+  asResource,
+  buildPersonaHeaders,
+  mapReport,
+  PERSONA_API_BASE,
+  parsePersonaResponse,
+  REPORT_OUTPUT_PROPERTIES,
+} from '@/tools/persona/utils'
+import type { ToolConfig } from '@/tools/types'
+
+const SUPPORTED_REPORT_TYPES = ['watchlist', 'adverse-media', 'politically-exposed-person'] as const
+
+export const personaCreateReportTool: ToolConfig<PersonaCreateReportParams, PersonaReportResponse> =
+  {
+    id: 'persona_create_report',
+    name: 'Persona Create Report',
+    description:
+      'Run a screening report (watchlist, adverse media, or politically exposed person) against an individual by name or search term.',
+    version: '1.0.0',
+
+    params: {
+      apiKey: {
+        type: 'string',
+        required: true,
+        visibility: 'user-only',
+        description: 'Persona API key',
+      },
+      reportType: {
+        type: 'string',
+        required: true,
+        visibility: 'user-or-llm',
+        description:
+          'Type of report to run: watchlist, adverse-media, or politically-exposed-person',
+      },
+      reportTemplateId: {
+        type: 'string',
+        required: true,
+        visibility: 'user-or-llm',
+        description: 'Report template ID to run (starts with rptp_)',
+      },
+      term: {
+        type: 'string',
+        required: false,
+        visibility: 'user-or-llm',
+        description:
+          'Full-name search term (e.g. "Jane Q Doe"). Provide this or the separate name parts.',
+      },
+      nameFirst: {
+        type: 'string',
+        required: false,
+        visibility: 'user-or-llm',
+        description: 'First name of the individual to search',
+      },
+      nameMiddle: {
+        type: 'string',
+        required: false,
+        visibility: 'user-or-llm',
+        description: 'Middle name of the individual to search',
+      },
+      nameLast: {
+        type: 'string',
+        required: false,
+        visibility: 'user-or-llm',
+        description: 'Last name of the individual to search',
+      },
+      birthdate: {
+        type: 'string',
+        required: false,
+        visibility: 'user-or-llm',
+        description: 'Birthdate of the individual, formatted as YYYY-MM-DD',
+      },
+      countryCode: {
+        type: 'string',
+        required: false,
+        visibility: 'user-or-llm',
+        description: 'ISO 3166-1 alpha-2 country code (e.g. US)',
+      },
+      accountId: {
+        type: 'string',
+        required: false,
+        visibility: 'user-or-llm',
+        description: 'Account ID (starts with act_) to associate with this report',
+      },
+    },
+
+    request: {
+      url: `${PERSONA_API_BASE}/reports`,
+      method: 'POST',
+      headers: (params) => buildPersonaHeaders(params.apiKey),
+      body: (params) => {
+        const reportType = params.reportType?.trim()
+        if (
+          !SUPPORTED_REPORT_TYPES.includes(reportType as (typeof SUPPORTED_REPORT_TYPES)[number])
+        ) {
+          throw new Error(`Report type must be one of: ${SUPPORTED_REPORT_TYPES.join(', ')}`)
+        }
+
+        const reportTemplateId = params.reportTemplateId?.trim()
+        if (!reportTemplateId) {
+          throw new Error('Report template ID is required (starts with rptp_)')
+        }
+
+        const query: Record<string, unknown> = {}
+        if (params.term?.trim()) query.term = params.term.trim()
+        if (params.nameFirst?.trim()) query['name-first'] = params.nameFirst.trim()
+        if (params.nameMiddle?.trim()) query['name-middle'] = params.nameMiddle.trim()
+        if (params.nameLast?.trim()) query['name-last'] = params.nameLast.trim()
+        if (params.birthdate?.trim()) query.birthdate = params.birthdate.trim()
+        if (params.countryCode?.trim()) {
+          query[reportType === 'watchlist' ? 'country-code' : 'address-country-code'] =
+            params.countryCode.trim()
+        }
+
+        if (!query.term && !query['name-first'] && !query['name-middle'] && !query['name-last']) {
+          throw new Error(
+            'At least one of term, nameFirst, nameMiddle, or nameLast is required to run a report'
+          )
+        }
+
+        const attributes: Record<string, unknown> = {
+          'report-template-id': reportTemplateId,
+          query,
+        }
+        if (params.accountId?.trim()) {
+          attributes['account-id'] = params.accountId.trim()
+        }
+
+        return {
+          data: {
+            type: `report/${reportType}`,
+            attributes,
+          },
+        }
+      },
+    },
+
+    transformResponse: async (response) => {
+      const data = await parsePersonaResponse(response)
+      return {
+        success: true,
+        output: {
+          report: mapReport(asResource(data.data)),
+        },
+      }
+    },
+
+    outputs: {
+      report: {
+        type: 'object',
+        description: 'The created report. Reports run asynchronously; poll until status is ready.',
+        properties: REPORT_OUTPUT_PROPERTIES,
+      },
+    },
+  }

apps/sim/tools/persona/decline_inquiry.ts

@@ -0,0 +1,61 @@
+import type { PersonaDeclineInquiryParams, PersonaInquiryResponse } from '@/tools/persona/types'
+import {
+  asResource,
+  buildPersonaHeaders,
+  INQUIRY_OUTPUT_PROPERTIES,
+  mapInquiry,
+  PERSONA_API_BASE,
+  parsePersonaResponse,
+} from '@/tools/persona/utils'
+import type { ToolConfig } from '@/tools/types'
+
+export const personaDeclineInquiryTool: ToolConfig<
+  PersonaDeclineInquiryParams,
+  PersonaInquiryResponse
+> = {
+  id: 'persona_decline_inquiry',
+  name: 'Persona Decline Inquiry',
+  description:
+    'Decline an identity verification inquiry. Declining prevents further progress on the inquiry and triggers any associated workflows and webhooks.',
+  version: '1.0.0',
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Persona API key',
+    },
+    inquiryId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Inquiry ID to decline (starts with inq_)',
+    },
+  },
+
+  request: {
+    url: (params) =>
+      `${PERSONA_API_BASE}/inquiries/${encodeURIComponent(params.inquiryId.trim())}/decline`,
+    method: 'POST',
+    headers: (params) => buildPersonaHeaders(params.apiKey),
+  },
+
+  transformResponse: async (response) => {
+    const data = await parsePersonaResponse(response)
+    return {
+      success: true,
+      output: {
+        inquiry: mapInquiry(asResource(data.data)),
+      },
+    }
+  },
+
+  outputs: {
+    inquiry: {
+      type: 'object',
+      description: 'The declined inquiry',
+      properties: INQUIRY_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/persona/expire_inquiry.ts

@@ -0,0 +1,61 @@
+import type { PersonaExpireInquiryParams, PersonaInquiryResponse } from '@/tools/persona/types'
+import {
+  asResource,
+  buildPersonaHeaders,
+  INQUIRY_OUTPUT_PROPERTIES,
+  mapInquiry,
+  PERSONA_API_BASE,
+  parsePersonaResponse,
+} from '@/tools/persona/utils'
+import type { ToolConfig } from '@/tools/types'
+
+export const personaExpireInquiryTool: ToolConfig<
+  PersonaExpireInquiryParams,
+  PersonaInquiryResponse
+> = {
+  id: 'persona_expire_inquiry',
+  name: 'Persona Expire Inquiry',
+  description:
+    'Expire an in-progress inquiry, invalidating its sessions and one-time links so the individual can no longer continue it.',
+  version: '1.0.0',
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Persona API key',
+    },
+    inquiryId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Inquiry ID to expire (starts with inq_)',
+    },
+  },
+
+  request: {
+    url: (params) =>
+      `${PERSONA_API_BASE}/inquiries/${encodeURIComponent(params.inquiryId.trim())}/expire`,
+    method: 'POST',
+    headers: (params) => buildPersonaHeaders(params.apiKey),
+  },
+
+  transformResponse: async (response) => {
+    const data = await parsePersonaResponse(response)
+    return {
+      success: true,
+      output: {
+        inquiry: mapInquiry(asResource(data.data)),
+      },
+    }
+  },
+
+  outputs: {
+    inquiry: {
+      type: 'object',
+      description: 'The expired inquiry',
+      properties: INQUIRY_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/persona/generate_inquiry_link.ts

@@ -0,0 +1,101 @@
+import type {
+  PersonaGenerateInquiryLinkParams,
+  PersonaGenerateInquiryLinkResponse,
+} from '@/tools/persona/types'
+import {
+  asResource,
+  buildPersonaHeaders,
+  INQUIRY_OUTPUT_PROPERTIES,
+  mapInquiry,
+  PERSONA_API_BASE,
+  parsePersonaResponse,
+} from '@/tools/persona/utils'
+import type { ToolConfig } from '@/tools/types'
+
+export const personaGenerateInquiryLinkTool: ToolConfig<
+  PersonaGenerateInquiryLinkParams,
+  PersonaGenerateInquiryLinkResponse
+> = {
+  id: 'persona_generate_inquiry_link',
+  name: 'Persona Generate Inquiry Link',
+  description:
+    'Generate a one-time link for an inquiry that the individual can open to complete their identity verification.',
+  version: '1.0.0',
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Persona API key',
+    },
+    inquiryId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Inquiry ID to generate a one-time link for (starts with inq_)',
+    },
+    expiresInSeconds: {
+      type: 'number',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        'Number of seconds from now until the link expires (must be greater than 0; defaults to the inquiry template setting, typically 24 hours)',
+    },
+  },
+
+  request: {
+    url: (params) =>
+      `${PERSONA_API_BASE}/inquiries/${encodeURIComponent(params.inquiryId.trim())}/generate-one-time-link`,
+    method: 'POST',
+    headers: (params) => buildPersonaHeaders(params.apiKey),
+    body: (params) => {
+      if (params.expiresInSeconds === undefined || params.expiresInSeconds === null) {
+        return {}
+      }
+      const expiresInSeconds = Number(params.expiresInSeconds)
+      if (!Number.isInteger(expiresInSeconds) || expiresInSeconds <= 0) {
+        throw new Error('Link expiry must be a positive whole number of seconds')
+      }
+      return { meta: { 'expires-in-seconds': expiresInSeconds } }
+    },
+  },
+
+  transformResponse: async (response) => {
+    const data = await parsePersonaResponse(response)
+    const oneTimeLink = data.meta?.['one-time-link']
+    const oneTimeLinkShort = data.meta?.['one-time-link-short']
+    if (typeof oneTimeLink !== 'string' || oneTimeLink.length === 0) {
+      throw new Error(
+        'Persona did not return a one-time link; check the inquiry status and template settings'
+      )
+    }
+    return {
+      success: true,
+      output: {
+        inquiry: mapInquiry(asResource(data.data)),
+        oneTimeLink,
+        oneTimeLinkShort:
+          typeof oneTimeLinkShort === 'string' && oneTimeLinkShort.length > 0
+            ? oneTimeLinkShort
+            : oneTimeLink,
+      },
+    }
+  },
+
+  outputs: {
+    inquiry: {
+      type: 'object',
+      description: 'The inquiry the link was generated for',
+      properties: INQUIRY_OUTPUT_PROPERTIES,
+    },
+    oneTimeLink: {
+      type: 'string',
+      description: 'One-time link the individual can open to complete the inquiry',
+    },
+    oneTimeLinkShort: {
+      type: 'string',
+      description: 'Shortened version of the one-time link',
+    },
+  },
+}

apps/sim/tools/persona/get_account.ts

@@ -0,0 +1,57 @@
+import type { PersonaAccountResponse, PersonaGetAccountParams } from '@/tools/persona/types'
+import {
+  ACCOUNT_OUTPUT_PROPERTIES,
+  asResource,
+  buildPersonaHeaders,
+  mapAccount,
+  PERSONA_API_BASE,
+  parsePersonaResponse,
+} from '@/tools/persona/utils'
+import type { ToolConfig } from '@/tools/types'
+
+export const personaGetAccountTool: ToolConfig<PersonaGetAccountParams, PersonaAccountResponse> = {
+  id: 'persona_get_account',
+  name: 'Persona Get Account',
+  description:
+    'Retrieve a single account by ID, including its reference ID, fields, tags, and status.',
+  version: '1.0.0',
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Persona API key',
+    },
+    accountId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Account ID to retrieve (starts with act_)',
+    },
+  },
+
+  request: {
+    url: (params) => `${PERSONA_API_BASE}/accounts/${encodeURIComponent(params.accountId.trim())}`,
+    method: 'GET',
+    headers: (params) => buildPersonaHeaders(params.apiKey),
+  },
+
+  transformResponse: async (response) => {
+    const data = await parsePersonaResponse(response)
+    return {
+      success: true,
+      output: {
+        account: mapAccount(asResource(data.data)),
+      },
+    }
+  },
+
+  outputs: {
+    account: {
+      type: 'object',
+      description: 'The retrieved account',
+      properties: ACCOUNT_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/persona/get_case.ts

@@ -0,0 +1,57 @@
+import type { PersonaCaseResponse, PersonaGetCaseParams } from '@/tools/persona/types'
+import {
+  asResource,
+  buildPersonaHeaders,
+  CASE_OUTPUT_PROPERTIES,
+  mapCase,
+  PERSONA_API_BASE,
+  parsePersonaResponse,
+} from '@/tools/persona/utils'
+import type { ToolConfig } from '@/tools/types'
+
+export const personaGetCaseTool: ToolConfig<PersonaGetCaseParams, PersonaCaseResponse> = {
+  id: 'persona_get_case',
+  name: 'Persona Get Case',
+  description:
+    'Retrieve a single manual review case by ID, including its status, resolution, and assignee.',
+  version: '1.0.0',
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Persona API key',
+    },
+    caseId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Case ID to retrieve (starts with case_)',
+    },
+  },
+
+  request: {
+    url: (params) => `${PERSONA_API_BASE}/cases/${encodeURIComponent(params.caseId.trim())}`,
+    method: 'GET',
+    headers: (params) => buildPersonaHeaders(params.apiKey),
+  },
+
+  transformResponse: async (response) => {
+    const data = await parsePersonaResponse(response)
+    return {
+      success: true,
+      output: {
+        case: mapCase(asResource(data.data)),
+      },
+    }
+  },
+
+  outputs: {
+    case: {
+      type: 'object',
+      description: 'The retrieved case',
+      properties: CASE_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/persona/get_document.ts

@@ -0,0 +1,59 @@
+import type { PersonaDocumentResponse, PersonaGetDocumentParams } from '@/tools/persona/types'
+import {
+  asResource,
+  buildPersonaHeaders,
+  DOCUMENT_OUTPUT_PROPERTIES,
+  mapDocument,
+  PERSONA_API_BASE,
+  parsePersonaResponse,
+} from '@/tools/persona/utils'
+import type { ToolConfig } from '@/tools/types'
+
+export const personaGetDocumentTool: ToolConfig<PersonaGetDocumentParams, PersonaDocumentResponse> =
+  {
+    id: 'persona_get_document',
+    name: 'Persona Get Document',
+    description:
+      'Retrieve a single document by ID (government ID, generic document, and more), including its processing status and uploaded files.',
+    version: '1.0.0',
+
+    params: {
+      apiKey: {
+        type: 'string',
+        required: true,
+        visibility: 'user-only',
+        description: 'Persona API key',
+      },
+      documentId: {
+        type: 'string',
+        required: true,
+        visibility: 'user-or-llm',
+        description: 'Document ID to retrieve (starts with doc_)',
+      },
+    },
+
+    request: {
+      url: (params) =>
+        `${PERSONA_API_BASE}/documents/${encodeURIComponent(params.documentId.trim())}`,
+      method: 'GET',
+      headers: (params) => buildPersonaHeaders(params.apiKey),
+    },
+
+    transformResponse: async (response) => {
+      const data = await parsePersonaResponse(response)
+      return {
+        success: true,
+        output: {
+          document: mapDocument(asResource(data.data)),
+        },
+      }
+    },
+
+    outputs: {
+      document: {
+        type: 'object',
+        description: 'The retrieved document',
+        properties: DOCUMENT_OUTPUT_PROPERTIES,
+      },
+    },
+  }

apps/sim/tools/persona/get_inquiry.ts

@@ -0,0 +1,57 @@
+import type { PersonaGetInquiryParams, PersonaInquiryResponse } from '@/tools/persona/types'
+import {
+  asResource,
+  buildPersonaHeaders,
+  INQUIRY_OUTPUT_PROPERTIES,
+  mapInquiry,
+  PERSONA_API_BASE,
+  parsePersonaResponse,
+} from '@/tools/persona/utils'
+import type { ToolConfig } from '@/tools/types'
+
+export const personaGetInquiryTool: ToolConfig<PersonaGetInquiryParams, PersonaInquiryResponse> = {
+  id: 'persona_get_inquiry',
+  name: 'Persona Get Inquiry',
+  description:
+    'Retrieve a single identity verification inquiry by ID, including its status, collected fields, and decision timestamps.',
+  version: '1.0.0',
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Persona API key',
+    },
+    inquiryId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Inquiry ID to retrieve (starts with inq_)',
+    },
+  },
+
+  request: {
+    url: (params) => `${PERSONA_API_BASE}/inquiries/${encodeURIComponent(params.inquiryId.trim())}`,
+    method: 'GET',
+    headers: (params) => buildPersonaHeaders(params.apiKey),
+  },
+
+  transformResponse: async (response) => {
+    const data = await parsePersonaResponse(response)
+    return {
+      success: true,
+      output: {
+        inquiry: mapInquiry(asResource(data.data)),
+      },
+    }
+  },
+
+  outputs: {
+    inquiry: {
+      type: 'object',
+      description: 'The retrieved inquiry',
+      properties: INQUIRY_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/persona/get_report.ts

@@ -0,0 +1,57 @@
+import type { PersonaGetReportParams, PersonaReportResponse } from '@/tools/persona/types'
+import {
+  asResource,
+  buildPersonaHeaders,
+  mapReport,
+  PERSONA_API_BASE,
+  parsePersonaResponse,
+  REPORT_OUTPUT_PROPERTIES,
+} from '@/tools/persona/utils'
+import type { ToolConfig } from '@/tools/types'
+
+export const personaGetReportTool: ToolConfig<PersonaGetReportParams, PersonaReportResponse> = {
+  id: 'persona_get_report',
+  name: 'Persona Get Report',
+  description:
+    'Retrieve a single screening report by ID, including its status, match results, and full type-specific attributes.',
+  version: '1.0.0',
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Persona API key',
+    },
+    reportId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Report ID to retrieve (starts with rep_)',
+    },
+  },
+
+  request: {
+    url: (params) => `${PERSONA_API_BASE}/reports/${encodeURIComponent(params.reportId.trim())}`,
+    method: 'GET',
+    headers: (params) => buildPersonaHeaders(params.apiKey),
+  },
+
+  transformResponse: async (response) => {
+    const data = await parsePersonaResponse(response)
+    return {
+      success: true,
+      output: {
+        report: mapReport(asResource(data.data)),
+      },
+    }
+  },
+
+  outputs: {
+    report: {
+      type: 'object',
+      description: 'The retrieved report',
+      properties: REPORT_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/persona/get_verification.ts

@@ -0,0 +1,64 @@
+import type {
+  PersonaGetVerificationParams,
+  PersonaVerificationResponse,
+} from '@/tools/persona/types'
+import {
+  asResource,
+  buildPersonaHeaders,
+  mapVerification,
+  PERSONA_API_BASE,
+  parsePersonaResponse,
+  VERIFICATION_OUTPUT_PROPERTIES,
+} from '@/tools/persona/utils'
+import type { ToolConfig } from '@/tools/types'
+
+export const personaGetVerificationTool: ToolConfig<
+  PersonaGetVerificationParams,
+  PersonaVerificationResponse
+> = {
+  id: 'persona_get_verification',
+  name: 'Persona Get Verification',
+  description:
+    'Retrieve a single verification by ID (government ID, selfie, document, database, and more), including its status and the checks that ran.',
+  version: '1.0.0',
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Persona API key',
+    },
+    verificationId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Verification ID to retrieve (starts with ver_)',
+    },
+  },
+
+  request: {
+    url: (params) =>
+      `${PERSONA_API_BASE}/verifications/${encodeURIComponent(params.verificationId.trim())}`,
+    method: 'GET',
+    headers: (params) => buildPersonaHeaders(params.apiKey),
+  },
+
+  transformResponse: async (response) => {
+    const data = await parsePersonaResponse(response)
+    return {
+      success: true,
+      output: {
+        verification: mapVerification(asResource(data.data)),
+      },
+    }
+  },
+
+  outputs: {
+    verification: {
+      type: 'object',
+      description: 'The retrieved verification',
+      properties: VERIFICATION_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/persona/import_accounts.ts

@@ -0,0 +1,63 @@
+import type {
+  PersonaImportAccountsParams,
+  PersonaImportAccountsResponse,
+} from '@/tools/persona/types'
+import { IMPORTER_OUTPUT_PROPERTIES } from '@/tools/persona/utils'
+import type { ToolConfig } from '@/tools/types'
+
+export const personaImportAccountsTool: ToolConfig<
+  PersonaImportAccountsParams,
+  PersonaImportAccountsResponse
+> = {
+  id: 'persona_import_accounts',
+  name: 'Persona Import Accounts',
+  description:
+    'Bulk-import accounts into Persona from a CSV file. Returns an importer whose status can be polled until processing completes.',
+  version: '1.0.0',
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Persona API key',
+    },
+    file: {
+      type: 'file',
+      required: true,
+      visibility: 'user-only',
+      description: 'CSV file of accounts to import',
+    },
+  },
+
+  request: {
+    url: '/api/tools/persona/import-accounts',
+    method: 'POST',
+    headers: () => ({
+      'Content-Type': 'application/json',
+    }),
+    body: (params) => ({
+      apiKey: params.apiKey,
+      file: params.file,
+    }),
+  },
+
+  transformResponse: async (response) => {
+    const data = await response.json()
+    if (!data.success) {
+      throw new Error(data.error || 'Failed to import accounts into Persona')
+    }
+    return {
+      success: true,
+      output: data.output,
+    }
+  },
+
+  outputs: {
+    importer: {
+      type: 'object',
+      description: 'The created account importer',
+      properties: IMPORTER_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/persona/index.ts

@@ -0,0 +1,26 @@
+export { personaApproveInquiryTool } from '@/tools/persona/approve_inquiry'
+export { personaCreateAccountTool } from '@/tools/persona/create_account'
+export { personaCreateInquiryTool } from '@/tools/persona/create_inquiry'
+export { personaCreateReportTool } from '@/tools/persona/create_report'
+export { personaDeclineInquiryTool } from '@/tools/persona/decline_inquiry'
+export { personaExpireInquiryTool } from '@/tools/persona/expire_inquiry'
+export { personaGenerateInquiryLinkTool } from '@/tools/persona/generate_inquiry_link'
+export { personaGetAccountTool } from '@/tools/persona/get_account'
+export { personaGetCaseTool } from '@/tools/persona/get_case'
+export { personaGetDocumentTool } from '@/tools/persona/get_document'
+export { personaGetInquiryTool } from '@/tools/persona/get_inquiry'
+export { personaGetReportTool } from '@/tools/persona/get_report'
+export { personaGetVerificationTool } from '@/tools/persona/get_verification'
+export { personaImportAccountsTool } from '@/tools/persona/import_accounts'
+export { personaListAccountsTool } from '@/tools/persona/list_accounts'
+export { personaListCasesTool } from '@/tools/persona/list_cases'
+export { personaListInquiriesTool } from '@/tools/persona/list_inquiries'
+export { personaListInquiryTemplatesTool } from '@/tools/persona/list_inquiry_templates'
+export { personaListReportsTool } from '@/tools/persona/list_reports'
+export { personaMarkInquiryForReviewTool } from '@/tools/persona/mark_inquiry_for_review'
+export { personaPrintInquiryPdfTool } from '@/tools/persona/print_inquiry_pdf'
+export { personaRedactAccountTool } from '@/tools/persona/redact_account'
+export { personaRedactInquiryTool } from '@/tools/persona/redact_inquiry'
+export { personaResumeInquiryTool } from '@/tools/persona/resume_inquiry'
+export { personaUpdateAccountTool } from '@/tools/persona/update_account'
+export { personaUpdateInquiryTool } from '@/tools/persona/update_inquiry'

apps/sim/tools/persona/list_accounts.ts

@@ -0,0 +1,92 @@
+import type { PersonaListAccountsParams, PersonaListAccountsResponse } from '@/tools/persona/types'
+import {
+  ACCOUNT_OUTPUT_PROPERTIES,
+  asResourceList,
+  buildPersonaHeaders,
+  getNextCursor,
+  mapAccount,
+  PERSONA_API_BASE,
+  parsePersonaResponse,
+} from '@/tools/persona/utils'
+import type { ToolConfig } from '@/tools/types'
+
+export const personaListAccountsTool: ToolConfig<
+  PersonaListAccountsParams,
+  PersonaListAccountsResponse
+> = {
+  id: 'persona_list_accounts',
+  name: 'Persona List Accounts',
+  description:
+    'List accounts in your Persona organization, optionally filtered by reference ID. Results are cursor-paginated.',
+  version: '1.0.0',
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Persona API key',
+    },
+    referenceId: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Filter by reference ID',
+    },
+    pageSize: {
+      type: 'number',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Number of accounts to return per page (1-100, default 10)',
+    },
+    pageAfter: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Pagination cursor: return accounts after this account ID',
+    },
+  },
+
+  request: {
+    url: (params) => {
+      const searchParams = new URLSearchParams()
+      if (params.referenceId?.trim()) {
+        searchParams.set('filter[reference-id]', params.referenceId.trim())
+      }
+      if (params.pageSize) searchParams.set('page[size]', String(params.pageSize))
+      if (params.pageAfter?.trim()) searchParams.set('page[after]', params.pageAfter.trim())
+      const query = searchParams.toString()
+      return `${PERSONA_API_BASE}/accounts${query ? `?${query}` : ''}`
+    },
+    method: 'GET',
+    headers: (params) => buildPersonaHeaders(params.apiKey),
+  },
+
+  transformResponse: async (response) => {
+    const data = await parsePersonaResponse(response)
+    const accounts = asResourceList(data.data)
+    return {
+      success: true,
+      output: {
+        accounts: accounts.map(mapAccount),
+        nextCursor: getNextCursor(data.links),
+      },
+    }
+  },
+
+  outputs: {
+    accounts: {
+      type: 'array',
+      description: 'Accounts matching the filters',
+      items: {
+        type: 'object',
+        properties: ACCOUNT_OUTPUT_PROPERTIES,
+      },
+    },
+    nextCursor: {
+      type: 'string',
+      description: 'Cursor for the next page (pass as pageAfter), or null on the last page',
+      optional: true,
+    },
+  },
+}

apps/sim/tools/persona/list_cases.ts

@@ -0,0 +1,103 @@
+import type { PersonaListCasesParams, PersonaListCasesResponse } from '@/tools/persona/types'
+import {
+  asResourceList,
+  buildPersonaHeaders,
+  CASE_OUTPUT_PROPERTIES,
+  getNextCursor,
+  mapCase,
+  PERSONA_API_BASE,
+  parsePersonaResponse,
+} from '@/tools/persona/utils'
+import type { ToolConfig } from '@/tools/types'
+
+export const personaListCasesTool: ToolConfig<PersonaListCasesParams, PersonaListCasesResponse> = {
+  id: 'persona_list_cases',
+  name: 'Persona List Cases',
+  description:
+    'List manual review cases, optionally filtered by status, account ID, or reference ID. Results are cursor-paginated.',
+  version: '1.0.0',
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Persona API key',
+    },
+    status: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Filter by case status (e.g. Open, Resolved)',
+    },
+    accountId: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Filter by account ID (starts with act_)',
+    },
+    referenceId: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Filter by reference ID',
+    },
+    pageSize: {
+      type: 'number',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Number of cases to return per page (1-100, default 10)',
+    },
+    pageAfter: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Pagination cursor: return cases after this case ID',
+    },
+  },
+
+  request: {
+    url: (params) => {
+      const searchParams = new URLSearchParams()
+      if (params.status?.trim()) searchParams.set('filter[status]', params.status.trim())
+      if (params.accountId?.trim()) searchParams.set('filter[account-id]', params.accountId.trim())
+      if (params.referenceId?.trim()) {
+        searchParams.set('filter[reference-id]', params.referenceId.trim())
+      }
+      if (params.pageSize) searchParams.set('page[size]', String(params.pageSize))
+      if (params.pageAfter?.trim()) searchParams.set('page[after]', params.pageAfter.trim())
+      const query = searchParams.toString()
+      return `${PERSONA_API_BASE}/cases${query ? `?${query}` : ''}`
+    },
+    method: 'GET',
+    headers: (params) => buildPersonaHeaders(params.apiKey),
+  },
+
+  transformResponse: async (response) => {
+    const data = await parsePersonaResponse(response)
+    const cases = asResourceList(data.data)
+    return {
+      success: true,
+      output: {
+        cases: cases.map(mapCase),
+        nextCursor: getNextCursor(data.links),
+      },
+    }
+  },
+
+  outputs: {
+    cases: {
+      type: 'array',
+      description: 'Cases matching the filters',
+      items: {
+        type: 'object',
+        properties: CASE_OUTPUT_PROPERTIES,
+      },
+    },
+    nextCursor: {
+      type: 'string',
+      description: 'Cursor for the next page (pass as pageAfter), or null on the last page',
+      optional: true,
+    },
+  },
+}

apps/sim/tools/persona/list_inquiries.ts

@@ -0,0 +1,128 @@
+import type {
+  PersonaListInquiriesParams,
+  PersonaListInquiriesResponse,
+} from '@/tools/persona/types'
+import {
+  asResourceList,
+  buildPersonaHeaders,
+  getNextCursor,
+  INQUIRY_OUTPUT_PROPERTIES,
+  mapInquiry,
+  PERSONA_API_BASE,
+  parsePersonaResponse,
+} from '@/tools/persona/utils'
+import type { ToolConfig } from '@/tools/types'
+
+export const personaListInquiriesTool: ToolConfig<
+  PersonaListInquiriesParams,
+  PersonaListInquiriesResponse
+> = {
+  id: 'persona_list_inquiries',
+  name: 'Persona List Inquiries',
+  description:
+    'List identity verification inquiries, optionally filtered by status, account ID, reference ID, or creation date range. Results are cursor-paginated.',
+  version: '1.0.0',
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Persona API key',
+    },
+    status: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        'Filter by inquiry status (created, pending, completed, failed, expired, needs_review, approved, declined)',
+    },
+    accountId: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Filter by account ID (starts with act_); comma-separate multiple IDs',
+    },
+    referenceId: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Filter by reference ID',
+    },
+    createdAtStart: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Filter to inquiries created at or after this ISO 8601 timestamp',
+    },
+    createdAtEnd: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Filter to inquiries created at or before this ISO 8601 timestamp',
+    },
+    pageSize: {
+      type: 'number',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Number of inquiries to return per page (1-100, default 10)',
+    },
+    pageAfter: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Pagination cursor: return inquiries after this inquiry ID',
+    },
+  },
+
+  request: {
+    url: (params) => {
+      const searchParams = new URLSearchParams()
+      if (params.status?.trim()) searchParams.set('filter[status]', params.status.trim())
+      if (params.accountId?.trim()) searchParams.set('filter[account-id]', params.accountId.trim())
+      if (params.referenceId?.trim()) {
+        searchParams.set('filter[reference-id]', params.referenceId.trim())
+      }
+      if (params.createdAtStart?.trim()) {
+        searchParams.set('filter[created-at-start]', params.createdAtStart.trim())
+      }
+      if (params.createdAtEnd?.trim()) {
+        searchParams.set('filter[created-at-end]', params.createdAtEnd.trim())
+      }
+      if (params.pageSize) searchParams.set('page[size]', String(params.pageSize))
+      if (params.pageAfter?.trim()) searchParams.set('page[after]', params.pageAfter.trim())
+      const query = searchParams.toString()
+      return `${PERSONA_API_BASE}/inquiries${query ? `?${query}` : ''}`
+    },
+    method: 'GET',
+    headers: (params) => buildPersonaHeaders(params.apiKey),
+  },
+
+  transformResponse: async (response) => {
+    const data = await parsePersonaResponse(response)
+    const inquiries = asResourceList(data.data)
+    return {
+      success: true,
+      output: {
+        inquiries: inquiries.map(mapInquiry),
+        nextCursor: getNextCursor(data.links),
+      },
+    }
+  },
+
+  outputs: {
+    inquiries: {
+      type: 'array',
+      description: 'Inquiries matching the filters',
+      items: {
+        type: 'object',
+        properties: INQUIRY_OUTPUT_PROPERTIES,
+      },
+    },
+    nextCursor: {
+      type: 'string',
+      description: 'Cursor for the next page (pass as pageAfter), or null on the last page',
+      optional: true,
+    },
+  },
+}

apps/sim/tools/persona/list_inquiry_templates.ts

@@ -0,0 +1,86 @@
+import type {
+  PersonaListInquiryTemplatesParams,
+  PersonaListInquiryTemplatesResponse,
+} from '@/tools/persona/types'
+import {
+  asResourceList,
+  buildPersonaHeaders,
+  getNextCursor,
+  INQUIRY_TEMPLATE_OUTPUT_PROPERTIES,
+  mapInquiryTemplate,
+  PERSONA_API_BASE,
+  parsePersonaResponse,
+} from '@/tools/persona/utils'
+import type { ToolConfig } from '@/tools/types'
+
+export const personaListInquiryTemplatesTool: ToolConfig<
+  PersonaListInquiryTemplatesParams,
+  PersonaListInquiryTemplatesResponse
+> = {
+  id: 'persona_list_inquiry_templates',
+  name: 'Persona List Inquiry Templates',
+  description:
+    'List the inquiry templates in your Persona organization, to discover template IDs for creating inquiries. Results are cursor-paginated.',
+  version: '1.0.0',
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Persona API key',
+    },
+    pageSize: {
+      type: 'number',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Number of templates to return per page (1-100, default 10)',
+    },
+    pageAfter: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Pagination cursor: return templates after this template ID',
+    },
+  },
+
+  request: {
+    url: (params) => {
+      const searchParams = new URLSearchParams()
+      if (params.pageSize) searchParams.set('page[size]', String(params.pageSize))
+      if (params.pageAfter?.trim()) searchParams.set('page[after]', params.pageAfter.trim())
+      const query = searchParams.toString()
+      return `${PERSONA_API_BASE}/inquiry-templates${query ? `?${query}` : ''}`
+    },
+    method: 'GET',
+    headers: (params) => buildPersonaHeaders(params.apiKey),
+  },
+
+  transformResponse: async (response) => {
+    const data = await parsePersonaResponse(response)
+    const templates = asResourceList(data.data)
+    return {
+      success: true,
+      output: {
+        inquiryTemplates: templates.map(mapInquiryTemplate),
+        nextCursor: getNextCursor(data.links),
+      },
+    }
+  },
+
+  outputs: {
+    inquiryTemplates: {
+      type: 'array',
+      description: 'Inquiry templates in the organization',
+      items: {
+        type: 'object',
+        properties: INQUIRY_TEMPLATE_OUTPUT_PROPERTIES,
+      },
+    },
+    nextCursor: {
+      type: 'string',
+      description: 'Cursor for the next page (pass as pageAfter), or null on the last page',
+      optional: true,
+    },
+  },
+}

apps/sim/tools/persona/list_reports.ts

@@ -0,0 +1,99 @@
+import type { PersonaListReportsParams, PersonaListReportsResponse } from '@/tools/persona/types'
+import {
+  asResourceList,
+  buildPersonaHeaders,
+  getNextCursor,
+  mapReport,
+  PERSONA_API_BASE,
+  parsePersonaResponse,
+  REPORT_OUTPUT_PROPERTIES,
+} from '@/tools/persona/utils'
+import type { ToolConfig } from '@/tools/types'
+
+export const personaListReportsTool: ToolConfig<
+  PersonaListReportsParams,
+  PersonaListReportsResponse
+> = {
+  id: 'persona_list_reports',
+  name: 'Persona List Reports',
+  description:
+    'List screening reports, optionally filtered by account ID or reference ID. Results are cursor-paginated.',
+  version: '1.0.0',
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Persona API key',
+    },
+    accountId: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Filter by account ID (starts with act_)',
+    },
+    referenceId: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Filter by reference ID',
+    },
+    pageSize: {
+      type: 'number',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Number of reports to return per page (1-100, default 10)',
+    },
+    pageAfter: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Pagination cursor: return reports after this report ID',
+    },
+  },
+
+  request: {
+    url: (params) => {
+      const searchParams = new URLSearchParams()
+      if (params.accountId?.trim()) searchParams.set('filter[account-id]', params.accountId.trim())
+      if (params.referenceId?.trim()) {
+        searchParams.set('filter[reference-id]', params.referenceId.trim())
+      }
+      if (params.pageSize) searchParams.set('page[size]', String(params.pageSize))
+      if (params.pageAfter?.trim()) searchParams.set('page[after]', params.pageAfter.trim())
+      const query = searchParams.toString()
+      return `${PERSONA_API_BASE}/reports${query ? `?${query}` : ''}`
+    },
+    method: 'GET',
+    headers: (params) => buildPersonaHeaders(params.apiKey),
+  },
+
+  transformResponse: async (response) => {
+    const data = await parsePersonaResponse(response)
+    const reports = asResourceList(data.data)
+    return {
+      success: true,
+      output: {
+        reports: reports.map(mapReport),
+        nextCursor: getNextCursor(data.links),
+      },
+    }
+  },
+
+  outputs: {
+    reports: {
+      type: 'array',
+      description: 'Reports matching the filters',
+      items: {
+        type: 'object',
+        properties: REPORT_OUTPUT_PROPERTIES,
+      },
+    },
+    nextCursor: {
+      type: 'string',
+      description: 'Cursor for the next page (pass as pageAfter), or null on the last page',
+      optional: true,
+    },
+  },
+}

apps/sim/tools/persona/mark_inquiry_for_review.ts

@@ -0,0 +1,64 @@
+import type {
+  PersonaInquiryResponse,
+  PersonaMarkInquiryForReviewParams,
+} from '@/tools/persona/types'
+import {
+  asResource,
+  buildPersonaHeaders,
+  INQUIRY_OUTPUT_PROPERTIES,
+  mapInquiry,
+  PERSONA_API_BASE,
+  parsePersonaResponse,
+} from '@/tools/persona/utils'
+import type { ToolConfig } from '@/tools/types'
+
+export const personaMarkInquiryForReviewTool: ToolConfig<
+  PersonaMarkInquiryForReviewParams,
+  PersonaInquiryResponse
+> = {
+  id: 'persona_mark_inquiry_for_review',
+  name: 'Persona Mark Inquiry for Review',
+  description:
+    'Mark an identity verification inquiry for manual review, moving it to the needs_review status.',
+  version: '1.0.0',
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Persona API key',
+    },
+    inquiryId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Inquiry ID to mark for review (starts with inq_)',
+    },
+  },
+
+  request: {
+    url: (params) =>
+      `${PERSONA_API_BASE}/inquiries/${encodeURIComponent(params.inquiryId.trim())}/mark-for-review`,
+    method: 'POST',
+    headers: (params) => buildPersonaHeaders(params.apiKey),
+  },
+
+  transformResponse: async (response) => {
+    const data = await parsePersonaResponse(response)
+    return {
+      success: true,
+      output: {
+        inquiry: mapInquiry(asResource(data.data)),
+      },
+    }
+  },
+
+  outputs: {
+    inquiry: {
+      type: 'object',
+      description: 'The inquiry marked for review',
+      properties: INQUIRY_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/persona/print_inquiry_pdf.ts

@@ -0,0 +1,83 @@
+import type {
+  PersonaPrintInquiryPdfParams,
+  PersonaPrintInquiryPdfResponse,
+} from '@/tools/persona/types'
+import {
+  extractPersonaErrorMessage,
+  PERSONA_API_BASE,
+  PERSONA_API_VERSION,
+} from '@/tools/persona/utils'
+import type { ToolConfig } from '@/tools/types'
+
+export const personaPrintInquiryPdfTool: ToolConfig<
+  PersonaPrintInquiryPdfParams,
+  PersonaPrintInquiryPdfResponse
+> = {
+  id: 'persona_print_inquiry_pdf',
+  name: 'Persona Print Inquiry PDF',
+  description:
+    'Download a PDF summary of an inquiry, including its collected information and verification results.',
+  version: '1.0.0',
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Persona API key',
+    },
+    inquiryId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Inquiry ID to print (starts with inq_)',
+    },
+  },
+
+  request: {
+    url: (params) =>
+      `${PERSONA_API_BASE}/inquiries/${encodeURIComponent(params.inquiryId.trim())}/print`,
+    method: 'GET',
+    headers: (params) => ({
+      Authorization: `Bearer ${params.apiKey}`,
+      'Persona-Version': PERSONA_API_VERSION,
+      Accept: 'application/pdf',
+    }),
+  },
+
+  transformResponse: async (response, params) => {
+    if (!response.ok) {
+      const fallback = `Persona API error: ${response.status} ${response.statusText}`
+      const errorBody: unknown = await response
+        .text()
+        .then((text) => JSON.parse(text))
+        .catch(() => null)
+      throw new Error(extractPersonaErrorMessage(errorBody, fallback))
+    }
+    const arrayBuffer = await response.arrayBuffer()
+    const buffer = Buffer.from(arrayBuffer)
+    const inquiryId = params?.inquiryId?.trim() ?? 'inquiry'
+    return {
+      success: true,
+      output: {
+        file: {
+          name: `${inquiryId}.pdf`,
+          mimeType: 'application/pdf',
+          data: buffer.toString('base64'),
+          size: buffer.length,
+        },
+      },
+    }
+  },
+
+  outputs: {
+    file: {
+      type: 'file',
+      description: 'PDF summary of the inquiry, stored in execution files',
+      fileConfig: {
+        mimeType: 'application/pdf',
+        extension: 'pdf',
+      },
+    },
+  },
+}

apps/sim/tools/persona/redact_account.ts

@@ -0,0 +1,60 @@
+import type { PersonaAccountResponse, PersonaRedactAccountParams } from '@/tools/persona/types'
+import {
+  ACCOUNT_OUTPUT_PROPERTIES,
+  asResource,
+  buildPersonaHeaders,
+  mapAccount,
+  PERSONA_API_BASE,
+  parsePersonaResponse,
+} from '@/tools/persona/utils'
+import type { ToolConfig } from '@/tools/types'
+
+export const personaRedactAccountTool: ToolConfig<
+  PersonaRedactAccountParams,
+  PersonaAccountResponse
+> = {
+  id: 'persona_redact_account',
+  name: 'Persona Redact Account',
+  description:
+    'Permanently delete all personally identifiable information stored on an account, for example to honor a data deletion request. This cannot be undone.',
+  version: '1.0.0',
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Persona API key',
+    },
+    accountId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Account ID to redact (starts with act_)',
+    },
+  },
+
+  request: {
+    url: (params) => `${PERSONA_API_BASE}/accounts/${encodeURIComponent(params.accountId.trim())}`,
+    method: 'DELETE',
+    headers: (params) => buildPersonaHeaders(params.apiKey),
+  },
+
+  transformResponse: async (response) => {
+    const data = await parsePersonaResponse(response)
+    return {
+      success: true,
+      output: {
+        account: mapAccount(asResource(data.data)),
+      },
+    }
+  },
+
+  outputs: {
+    account: {
+      type: 'object',
+      description: 'The redacted account (PII fields are removed)',
+      properties: ACCOUNT_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/persona/redact_inquiry.ts

@@ -0,0 +1,60 @@
+import type { PersonaInquiryResponse, PersonaRedactInquiryParams } from '@/tools/persona/types'
+import {
+  asResource,
+  buildPersonaHeaders,
+  INQUIRY_OUTPUT_PROPERTIES,
+  mapInquiry,
+  PERSONA_API_BASE,
+  parsePersonaResponse,
+} from '@/tools/persona/utils'
+import type { ToolConfig } from '@/tools/types'
+
+export const personaRedactInquiryTool: ToolConfig<
+  PersonaRedactInquiryParams,
+  PersonaInquiryResponse
+> = {
+  id: 'persona_redact_inquiry',
+  name: 'Persona Redact Inquiry',
+  description:
+    'Permanently delete all personally identifiable information collected by an inquiry, for example to honor a data deletion request. This cannot be undone.',
+  version: '1.0.0',
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Persona API key',
+    },
+    inquiryId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Inquiry ID to redact (starts with inq_)',
+    },
+  },
+
+  request: {
+    url: (params) => `${PERSONA_API_BASE}/inquiries/${encodeURIComponent(params.inquiryId.trim())}`,
+    method: 'DELETE',
+    headers: (params) => buildPersonaHeaders(params.apiKey),
+  },
+
+  transformResponse: async (response) => {
+    const data = await parsePersonaResponse(response)
+    return {
+      success: true,
+      output: {
+        inquiry: mapInquiry(asResource(data.data)),
+      },
+    }
+  },
+
+  outputs: {
+    inquiry: {
+      type: 'object',
+      description: 'The redacted inquiry (PII fields are removed)',
+      properties: INQUIRY_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/persona/resume_inquiry.ts

@@ -0,0 +1,74 @@
+import type {
+  PersonaResumeInquiryParams,
+  PersonaResumeInquiryResponse,
+} from '@/tools/persona/types'
+import {
+  asResource,
+  buildPersonaHeaders,
+  INQUIRY_OUTPUT_PROPERTIES,
+  mapInquiry,
+  PERSONA_API_BASE,
+  parsePersonaResponse,
+} from '@/tools/persona/utils'
+import type { ToolConfig } from '@/tools/types'
+
+export const personaResumeInquiryTool: ToolConfig<
+  PersonaResumeInquiryParams,
+  PersonaResumeInquiryResponse
+> = {
+  id: 'persona_resume_inquiry',
+  name: 'Persona Resume Inquiry',
+  description:
+    'Resume a pending or expired inquiry, creating a new session so the individual can continue verification. Returns a session token.',
+  version: '1.0.0',
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Persona API key',
+    },
+    inquiryId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Inquiry ID to resume (starts with inq_)',
+    },
+  },
+
+  request: {
+    url: (params) =>
+      `${PERSONA_API_BASE}/inquiries/${encodeURIComponent(params.inquiryId.trim())}/resume`,
+    method: 'POST',
+    headers: (params) => buildPersonaHeaders(params.apiKey),
+  },
+
+  transformResponse: async (response) => {
+    const data = await parsePersonaResponse(response)
+    const sessionToken = data.meta?.['session-token']
+    if (typeof sessionToken !== 'string' || sessionToken.length === 0) {
+      throw new Error('Persona did not return a session token; check the inquiry status')
+    }
+    return {
+      success: true,
+      output: {
+        inquiry: mapInquiry(asResource(data.data)),
+        sessionToken,
+      },
+    }
+  },
+
+  outputs: {
+    inquiry: {
+      type: 'object',
+      description: 'The resumed inquiry',
+      properties: INQUIRY_OUTPUT_PROPERTIES,
+    },
+    sessionToken: {
+      type: 'string',
+      description:
+        'Session token for the new inquiry session, used to continue the flow in embedded SDKs',
+    },
+  },
+}

apps/sim/tools/persona/types.ts

@@ -0,0 +1,388 @@
+import type { ToolResponse } from '@/tools/types'
+
+interface PersonaBaseParams {
+  apiKey: string
+}
+
+/**
+ * Flattened representation of a Persona Inquiry resource.
+ */
+export interface PersonaInquiry {
+  id: string
+  status: string | null
+  referenceId: string | null
+  note: string | null
+  tags: string[]
+  fields: Record<string, unknown> | null
+  createdAt: string | null
+  startedAt: string | null
+  completedAt: string | null
+  failedAt: string | null
+  expiredAt: string | null
+  decisionedAt: string | null
+}
+
+/**
+ * Flattened representation of a Persona Account resource.
+ */
+export interface PersonaAccount {
+  id: string
+  referenceId: string | null
+  accountTypeName: string | null
+  accountStatus: string | null
+  tags: string[]
+  fields: Record<string, unknown> | null
+  createdAt: string | null
+  updatedAt: string | null
+}
+
+/**
+ * Flattened representation of a Persona Case resource.
+ */
+export interface PersonaCase {
+  id: string
+  status: string | null
+  name: string | null
+  resolution: string | null
+  assigneeId: string | null
+  tags: string[]
+  fields: Record<string, unknown> | null
+  createdAt: string | null
+  assignedAt: string | null
+  resolvedAt: string | null
+}
+
+/**
+ * Flattened representation of a Persona Report resource. The `attributes`
+ * payload varies by report type, so the full attributes are preserved.
+ */
+export interface PersonaReport {
+  id: string
+  type: string
+  status: string | null
+  hasMatch: boolean | null
+  tags: string[]
+  createdAt: string | null
+  completedAt: string | null
+  attributes: Record<string, unknown>
+}
+
+/**
+ * Flattened representation of a Persona Verification resource. The
+ * `attributes` payload varies by verification type, so the full attributes
+ * are preserved.
+ */
+export interface PersonaVerification {
+  id: string
+  type: string
+  status: string | null
+  checks: Array<Record<string, unknown>>
+  countryCode: string | null
+  createdAt: string | null
+  submittedAt: string | null
+  completedAt: string | null
+  attributes: Record<string, unknown>
+}
+
+/**
+ * Flattened representation of a Persona Document resource. The `attributes`
+ * payload varies by document type, so the full attributes are preserved.
+ */
+export interface PersonaDocument {
+  id: string
+  type: string
+  status: string | null
+  kind: string | null
+  files: Array<{ filename: string | null; url: string | null; byteSize: number | null }>
+  createdAt: string | null
+  processedAt: string | null
+  attributes: Record<string, unknown>
+}
+
+/**
+ * Flattened representation of a Persona Account Importer resource.
+ */
+export interface PersonaImporter {
+  id: string
+  status: string | null
+  successfulCount: number
+  errorCount: number
+  duplicateCount: number
+  createdAt: string | null
+  completedAt: string | null
+}
+
+/**
+ * Flattened representation of a Persona Inquiry Template resource.
+ */
+export interface PersonaInquiryTemplate {
+  id: string
+  name: string | null
+  status: string | null
+}
+
+export interface PersonaCreateInquiryParams extends PersonaBaseParams {
+  inquiryTemplateId: string
+  accountId?: string
+  referenceId?: string
+  fields?: Record<string, unknown> | string
+  note?: string
+  redirectUri?: string
+}
+
+export interface PersonaGetInquiryParams extends PersonaBaseParams {
+  inquiryId: string
+}
+
+export interface PersonaListInquiriesParams extends PersonaBaseParams {
+  status?: string
+  accountId?: string
+  referenceId?: string
+  createdAtStart?: string
+  createdAtEnd?: string
+  pageSize?: number
+  pageAfter?: string
+}
+
+export interface PersonaUpdateInquiryParams extends PersonaBaseParams {
+  inquiryId: string
+  note?: string
+  fields?: Record<string, unknown> | string
+  tags?: string[] | string
+  redirectUri?: string
+}
+
+export interface PersonaApproveInquiryParams extends PersonaBaseParams {
+  inquiryId: string
+}
+
+export interface PersonaMarkInquiryForReviewParams extends PersonaBaseParams {
+  inquiryId: string
+}
+
+export interface PersonaResumeInquiryParams extends PersonaBaseParams {
+  inquiryId: string
+}
+
+export interface PersonaExpireInquiryParams extends PersonaBaseParams {
+  inquiryId: string
+}
+
+export interface PersonaRedactInquiryParams extends PersonaBaseParams {
+  inquiryId: string
+}
+
+export interface PersonaDeclineInquiryParams extends PersonaBaseParams {
+  inquiryId: string
+}
+
+export interface PersonaGenerateInquiryLinkParams extends PersonaBaseParams {
+  inquiryId: string
+  expiresInSeconds?: number
+}
+
+export interface PersonaPrintInquiryPdfParams extends PersonaBaseParams {
+  inquiryId: string
+}
+
+export interface PersonaCreateAccountParams extends PersonaBaseParams {
+  accountTypeId?: string
+  referenceId?: string
+  countryCode?: string
+  fields?: Record<string, unknown> | string
+  tags?: string[] | string
+}
+
+export interface PersonaGetAccountParams extends PersonaBaseParams {
+  accountId: string
+}
+
+export interface PersonaUpdateAccountParams extends PersonaBaseParams {
+  accountId: string
+  referenceId?: string
+  countryCode?: string
+  fields?: Record<string, unknown> | string
+  tags?: string[] | string
+}
+
+export interface PersonaRedactAccountParams extends PersonaBaseParams {
+  accountId: string
+}
+
+export interface PersonaListAccountsParams extends PersonaBaseParams {
+  referenceId?: string
+  pageSize?: number
+  pageAfter?: string
+}
+
+export interface PersonaImportAccountsParams extends PersonaBaseParams {
+  file: Record<string, unknown>
+}
+
+export interface PersonaListCasesParams extends PersonaBaseParams {
+  status?: string
+  accountId?: string
+  referenceId?: string
+  pageSize?: number
+  pageAfter?: string
+}
+
+export interface PersonaGetCaseParams extends PersonaBaseParams {
+  caseId: string
+}
+
+export interface PersonaCreateReportParams extends PersonaBaseParams {
+  reportType: string
+  reportTemplateId: string
+  term?: string
+  nameFirst?: string
+  nameMiddle?: string
+  nameLast?: string
+  birthdate?: string
+  countryCode?: string
+  accountId?: string
+}
+
+export interface PersonaGetReportParams extends PersonaBaseParams {
+  reportId: string
+}
+
+export interface PersonaListReportsParams extends PersonaBaseParams {
+  accountId?: string
+  referenceId?: string
+  pageSize?: number
+  pageAfter?: string
+}
+
+export interface PersonaListInquiryTemplatesParams extends PersonaBaseParams {
+  pageSize?: number
+  pageAfter?: string
+}
+
+export interface PersonaGetVerificationParams extends PersonaBaseParams {
+  verificationId: string
+}
+
+export interface PersonaGetDocumentParams extends PersonaBaseParams {
+  documentId: string
+}
+
+export interface PersonaInquiryResponse extends ToolResponse {
+  output: {
+    inquiry: PersonaInquiry
+  }
+}
+
+export interface PersonaListInquiriesResponse extends ToolResponse {
+  output: {
+    inquiries: PersonaInquiry[]
+    nextCursor: string | null
+  }
+}
+
+export interface PersonaResumeInquiryResponse extends ToolResponse {
+  output: {
+    inquiry: PersonaInquiry
+    sessionToken: string
+  }
+}
+
+export interface PersonaGenerateInquiryLinkResponse extends ToolResponse {
+  output: {
+    inquiry: PersonaInquiry
+    oneTimeLink: string
+    oneTimeLinkShort: string
+  }
+}
+
+export interface PersonaPrintInquiryPdfResponse extends ToolResponse {
+  output: {
+    file: {
+      name: string
+      mimeType: string
+      data: string
+      size: number
+    }
+  }
+}
+
+export interface PersonaAccountResponse extends ToolResponse {
+  output: {
+    account: PersonaAccount
+  }
+}
+
+export interface PersonaListAccountsResponse extends ToolResponse {
+  output: {
+    accounts: PersonaAccount[]
+    nextCursor: string | null
+  }
+}
+
+export interface PersonaImportAccountsResponse extends ToolResponse {
+  output: {
+    importer: PersonaImporter
+  }
+}
+
+export interface PersonaCaseResponse extends ToolResponse {
+  output: {
+    case: PersonaCase
+  }
+}
+
+export interface PersonaListCasesResponse extends ToolResponse {
+  output: {
+    cases: PersonaCase[]
+    nextCursor: string | null
+  }
+}
+
+export interface PersonaReportResponse extends ToolResponse {
+  output: {
+    report: PersonaReport
+  }
+}
+
+export interface PersonaListReportsResponse extends ToolResponse {
+  output: {
+    reports: PersonaReport[]
+    nextCursor: string | null
+  }
+}
+
+export interface PersonaListInquiryTemplatesResponse extends ToolResponse {
+  output: {
+    inquiryTemplates: PersonaInquiryTemplate[]
+    nextCursor: string | null
+  }
+}
+
+export interface PersonaVerificationResponse extends ToolResponse {
+  output: {
+    verification: PersonaVerification
+  }
+}
+
+export interface PersonaDocumentResponse extends ToolResponse {
+  output: {
+    document: PersonaDocument
+  }
+}
+
+export type PersonaResponse =
+  | PersonaInquiryResponse
+  | PersonaListInquiriesResponse
+  | PersonaResumeInquiryResponse
+  | PersonaGenerateInquiryLinkResponse
+  | PersonaListReportsResponse
+  | PersonaListInquiryTemplatesResponse
+  | PersonaPrintInquiryPdfResponse
+  | PersonaAccountResponse
+  | PersonaListAccountsResponse
+  | PersonaImportAccountsResponse
+  | PersonaCaseResponse
+  | PersonaListCasesResponse
+  | PersonaReportResponse
+  | PersonaVerificationResponse
+  | PersonaDocumentResponse

apps/sim/tools/persona/update_account.ts

@@ -0,0 +1,110 @@
+import type { PersonaAccountResponse, PersonaUpdateAccountParams } from '@/tools/persona/types'
+import {
+  ACCOUNT_OUTPUT_PROPERTIES,
+  asResource,
+  buildPersonaHeaders,
+  mapAccount,
+  PERSONA_API_BASE,
+  parseJsonObjectParam,
+  parsePersonaResponse,
+  parseStringArrayParam,
+} from '@/tools/persona/utils'
+import type { ToolConfig } from '@/tools/types'
+
+export const personaUpdateAccountTool: ToolConfig<
+  PersonaUpdateAccountParams,
+  PersonaAccountResponse
+> = {
+  id: 'persona_update_account',
+  name: 'Persona Update Account',
+  description:
+    'Update an account’s reference ID, country code, fields, or tags. Only the provided values are changed.',
+  version: '1.0.0',
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Persona API key',
+    },
+    accountId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Account ID to update (starts with act_)',
+    },
+    referenceId: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Reference ID that refers to an entity in your user model',
+    },
+    countryCode: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'ISO 3166-1 alpha-2 country code (e.g. US)',
+    },
+    fields: {
+      type: 'json',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        'JSON object of field name to field value pairs to set, as defined by the account type (e.g. {"name-first": "Jane"})',
+    },
+    tags: {
+      type: 'array',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'JSON array of tag names to set on the account (e.g. ["vip"])',
+    },
+  },
+
+  request: {
+    url: (params) => `${PERSONA_API_BASE}/accounts/${encodeURIComponent(params.accountId.trim())}`,
+    method: 'PATCH',
+    headers: (params) => buildPersonaHeaders(params.apiKey),
+    body: (params) => {
+      const attributes: Record<string, unknown> = {}
+      if (params.referenceId?.trim()) {
+        attributes['reference-id'] = params.referenceId.trim()
+      }
+      if (params.countryCode?.trim()) {
+        attributes['country-code'] = params.countryCode.trim()
+      }
+      const fields = parseJsonObjectParam(params.fields, 'Fields')
+      if (fields) {
+        attributes.fields = fields
+      }
+      const tags = parseStringArrayParam(params.tags, 'Tags')
+      if (tags) {
+        attributes.tags = tags
+      }
+      if (Object.keys(attributes).length === 0) {
+        throw new Error(
+          'Provide at least one of referenceId, countryCode, fields, or tags to update'
+        )
+      }
+      return { data: { attributes } }
+    },
+  },
+
+  transformResponse: async (response) => {
+    const data = await parsePersonaResponse(response)
+    return {
+      success: true,
+      output: {
+        account: mapAccount(asResource(data.data)),
+      },
+    }
+  },
+
+  outputs: {
+    account: {
+      type: 'object',
+      description: 'The updated account',
+      properties: ACCOUNT_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/persona/update_inquiry.ts

@@ -0,0 +1,108 @@
+import type { PersonaInquiryResponse, PersonaUpdateInquiryParams } from '@/tools/persona/types'
+import {
+  asResource,
+  buildPersonaHeaders,
+  INQUIRY_OUTPUT_PROPERTIES,
+  mapInquiry,
+  PERSONA_API_BASE,
+  parseJsonObjectParam,
+  parsePersonaResponse,
+  parseStringArrayParam,
+} from '@/tools/persona/utils'
+import type { ToolConfig } from '@/tools/types'
+
+export const personaUpdateInquiryTool: ToolConfig<
+  PersonaUpdateInquiryParams,
+  PersonaInquiryResponse
+> = {
+  id: 'persona_update_inquiry',
+  name: 'Persona Update Inquiry',
+  description:
+    'Update an inquiry’s note, fields, tags, or redirect URI. Only the provided values are changed.',
+  version: '1.0.0',
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Persona API key',
+    },
+    inquiryId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Inquiry ID to update (starts with inq_)',
+    },
+    note: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Free-form note to set on the inquiry',
+    },
+    fields: {
+      type: 'json',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        'JSON object of field name to field value pairs to set, as defined by the inquiry template (e.g. {"name-first": "Jane"})',
+    },
+    tags: {
+      type: 'array',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'JSON array of tag names to set on the inquiry (e.g. ["vip"])',
+    },
+    redirectUri: {
+      type: 'string',
+      required: false,
+      visibility: 'user-only',
+      description: 'URI to redirect the individual to after completing the inquiry flow',
+    },
+  },
+
+  request: {
+    url: (params) => `${PERSONA_API_BASE}/inquiries/${encodeURIComponent(params.inquiryId.trim())}`,
+    method: 'PATCH',
+    headers: (params) => buildPersonaHeaders(params.apiKey),
+    body: (params) => {
+      const attributes: Record<string, unknown> = {}
+      if (params.note?.trim()) {
+        attributes.note = params.note.trim()
+      }
+      const fields = parseJsonObjectParam(params.fields, 'Fields')
+      if (fields) {
+        attributes.fields = fields
+      }
+      const tags = parseStringArrayParam(params.tags, 'Tags')
+      if (tags) {
+        attributes.tags = tags
+      }
+      if (params.redirectUri?.trim()) {
+        attributes['redirect-uri'] = params.redirectUri.trim()
+      }
+      if (Object.keys(attributes).length === 0) {
+        throw new Error('Provide at least one of note, fields, tags, or redirectUri to update')
+      }
+      return { data: { attributes } }
+    },
+  },
+
+  transformResponse: async (response) => {
+    const data = await parsePersonaResponse(response)
+    return {
+      success: true,
+      output: {
+        inquiry: mapInquiry(asResource(data.data)),
+      },
+    }
+  },
+
+  outputs: {
+    inquiry: {
+      type: 'object',
+      description: 'The updated inquiry',
+      properties: INQUIRY_OUTPUT_PROPERTIES,
+    },
+  },
+}

apps/sim/tools/persona/utils.ts

@@ -0,0 +1,523 @@
+import type {
+  PersonaAccount,
+  PersonaCase,
+  PersonaDocument,
+  PersonaImporter,
+  PersonaInquiry,
+  PersonaInquiryTemplate,
+  PersonaReport,
+  PersonaVerification,
+} from '@/tools/persona/types'
+import type { OutputProperty } from '@/tools/types'
+
+export const PERSONA_API_BASE = 'https://api.withpersona.com/api/v1'
+
+/**
+ * Persona API version pinned for this integration so responses keep a stable
+ * shape regardless of the organization's dashboard default.
+ */
+export const PERSONA_API_VERSION = '2025-12-08'
+
+/**
+ * Raw JSON:API resource object returned by the Persona API.
+ */
+export interface PersonaResourceData {
+  type?: string
+  id?: string
+  attributes?: Record<string, unknown>
+  relationships?: Record<string, unknown>
+}
+
+/**
+ * Top-level JSON:API envelope returned by the Persona API.
+ */
+export interface PersonaApiEnvelope {
+  data?: unknown
+  links?: unknown
+  meta?: Record<string, unknown>
+}
+
+/**
+ * Extracts a human-readable message from a Persona JSON:API error body.
+ */
+export function extractPersonaErrorMessage(body: unknown, fallback: string): string {
+  if (body !== null && typeof body === 'object') {
+    const errors = (body as Record<string, unknown>).errors
+    if (Array.isArray(errors) && errors.length > 0) {
+      const first = errors[0]
+      if (first !== null && typeof first === 'object') {
+        const title = (first as Record<string, unknown>).title
+        if (typeof title === 'string' && title.length > 0) {
+          return title
+        }
+      }
+    }
+  }
+  return fallback
+}
+
+/**
+ * Reads a Persona JSON response, throwing a descriptive error for non-2xx
+ * responses using the JSON:API error format.
+ */
+export async function parsePersonaResponse(response: Response): Promise<PersonaApiEnvelope> {
+  const body: unknown = await response.json().catch(() => null)
+  if (!response.ok) {
+    throw new Error(
+      extractPersonaErrorMessage(
+        body,
+        `Persona API error: ${response.status} ${response.statusText}`
+      )
+    )
+  }
+  return body !== null && typeof body === 'object' ? (body as PersonaApiEnvelope) : {}
+}
+
+/**
+ * Narrows an unknown JSON:API `data` value to a single resource object.
+ */
+export function asResource(value: unknown): PersonaResourceData {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as PersonaResourceData)
+    : {}
+}
+
+/**
+ * Narrows an unknown JSON:API `data` value to a list of resource objects.
+ */
+export function asResourceList(value: unknown): PersonaResourceData[] {
+  return Array.isArray(value) ? value.map(asResource) : []
+}
+
+/**
+ * Builds the standard headers for Persona API requests.
+ */
+export function buildPersonaHeaders(apiKey: string): Record<string, string> {
+  return {
+    Authorization: `Bearer ${apiKey}`,
+    'Persona-Version': PERSONA_API_VERSION,
+    'Content-Type': 'application/json',
+    Accept: 'application/json',
+  }
+}
+
+/**
+ * Parses a JSON object param that may arrive as an object or a JSON string.
+ * Throws a descriptive error when the value is not a JSON object.
+ */
+export function parseJsonObjectParam(
+  value: Record<string, unknown> | string | undefined,
+  label: string
+): Record<string, unknown> | undefined {
+  if (value === undefined || value === '') return undefined
+  let parsed: unknown = value
+  if (typeof value === 'string') {
+    try {
+      parsed = JSON.parse(value)
+    } catch {
+      throw new Error(`${label} must be a valid JSON object`)
+    }
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`${label} must be a JSON object of key-value pairs`)
+  }
+  return parsed as Record<string, unknown>
+}
+
+/**
+ * Parses a string array param that may arrive as an array or a JSON string.
+ * Throws a descriptive error when the value is not an array of strings.
+ */
+export function parseStringArrayParam(
+  value: string[] | string | undefined,
+  label: string
+): string[] | undefined {
+  if (value === undefined || value === '') return undefined
+  let parsed: unknown = value
+  if (typeof value === 'string') {
+    try {
+      parsed = JSON.parse(value)
+    } catch {
+      throw new Error(`${label} must be a valid JSON array of strings`)
+    }
+  }
+  if (!Array.isArray(parsed) || !parsed.every((item) => typeof item === 'string')) {
+    throw new Error(`${label} must be a JSON array of strings`)
+  }
+  return parsed
+}
+
+function getString(attrs: Record<string, unknown>, key: string): string | null {
+  const value = attrs[key]
+  return typeof value === 'string' ? value : null
+}
+
+function getBoolean(attrs: Record<string, unknown>, key: string): boolean | null {
+  const value = attrs[key]
+  return typeof value === 'boolean' ? value : null
+}
+
+function getNumber(attrs: Record<string, unknown>, key: string, fallback: number): number {
+  const value = attrs[key]
+  return typeof value === 'number' ? value : fallback
+}
+
+function getStringArray(attrs: Record<string, unknown>, key: string): string[] {
+  const value = attrs[key]
+  return Array.isArray(value)
+    ? value.filter((item): item is string => typeof item === 'string')
+    : []
+}
+
+function getObject(attrs: Record<string, unknown>, key: string): Record<string, unknown> | null {
+  const value = attrs[key]
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null
+}
+
+/**
+ * Extracts the `page[after]` cursor from a JSON:API `links.next` URL.
+ */
+export function getNextCursor(links: unknown): string | null {
+  if (links === null || typeof links !== 'object') return null
+  const next = (links as Record<string, unknown>).next
+  if (typeof next !== 'string' || next.length === 0) return null
+  const queryIndex = next.indexOf('?')
+  if (queryIndex === -1) return null
+  const searchParams = new URLSearchParams(next.slice(queryIndex + 1))
+  return searchParams.get('page[after]')
+}
+
+/**
+ * Maps a raw Persona Inquiry resource to its flattened representation.
+ */
+export function mapInquiry(data: PersonaResourceData): PersonaInquiry {
+  const attrs = data.attributes ?? {}
+  return {
+    id: data.id ?? '',
+    status: getString(attrs, 'status'),
+    referenceId: getString(attrs, 'reference-id'),
+    note: getString(attrs, 'note'),
+    tags: getStringArray(attrs, 'tags'),
+    fields: getObject(attrs, 'fields'),
+    createdAt: getString(attrs, 'created-at'),
+    startedAt: getString(attrs, 'started-at'),
+    completedAt: getString(attrs, 'completed-at'),
+    failedAt: getString(attrs, 'failed-at'),
+    expiredAt: getString(attrs, 'expired-at'),
+    decisionedAt: getString(attrs, 'decisioned-at'),
+  }
+}
+
+/**
+ * Maps a raw Persona Account resource to its flattened representation.
+ */
+export function mapAccount(data: PersonaResourceData): PersonaAccount {
+  const attrs = data.attributes ?? {}
+  return {
+    id: data.id ?? '',
+    referenceId: getString(attrs, 'reference-id'),
+    accountTypeName: getString(attrs, 'account-type-name'),
+    accountStatus: getString(attrs, 'account-status'),
+    tags: getStringArray(attrs, 'tags'),
+    fields: getObject(attrs, 'fields'),
+    createdAt: getString(attrs, 'created-at'),
+    updatedAt: getString(attrs, 'updated-at'),
+  }
+}
+
+/**
+ * Maps a raw Persona Case resource to its flattened representation.
+ */
+export function mapCase(data: PersonaResourceData): PersonaCase {
+  const attrs = data.attributes ?? {}
+  return {
+    id: data.id ?? '',
+    status: getString(attrs, 'status'),
+    name: getString(attrs, 'name'),
+    resolution: getString(attrs, 'resolution'),
+    assigneeId: getString(attrs, 'assignee-id'),
+    tags: getStringArray(attrs, 'tags'),
+    fields: getObject(attrs, 'fields'),
+    createdAt: getString(attrs, 'created-at'),
+    assignedAt: getString(attrs, 'assigned-at'),
+    resolvedAt: getString(attrs, 'resolved-at'),
+  }
+}
+
+/**
+ * Maps a raw Persona Report resource to its flattened representation.
+ */
+export function mapReport(data: PersonaResourceData): PersonaReport {
+  const attrs = data.attributes ?? {}
+  return {
+    id: data.id ?? '',
+    type: data.type ?? '',
+    status: getString(attrs, 'status'),
+    hasMatch: getBoolean(attrs, 'has-match'),
+    tags: getStringArray(attrs, 'tags'),
+    createdAt: getString(attrs, 'created-at'),
+    completedAt: getString(attrs, 'completed-at'),
+    attributes: attrs,
+  }
+}
+
+/**
+ * Maps a raw Persona Verification resource to its flattened representation.
+ */
+export function mapVerification(data: PersonaResourceData): PersonaVerification {
+  const attrs = data.attributes ?? {}
+  const checks = attrs.checks
+  return {
+    id: data.id ?? '',
+    type: data.type ?? '',
+    status: getString(attrs, 'status'),
+    checks: Array.isArray(checks)
+      ? checks.filter(
+          (check): check is Record<string, unknown> => check !== null && typeof check === 'object'
+        )
+      : [],
+    countryCode: getString(attrs, 'country-code'),
+    createdAt: getString(attrs, 'created-at'),
+    submittedAt: getString(attrs, 'submitted-at'),
+    completedAt: getString(attrs, 'completed-at'),
+    attributes: attrs,
+  }
+}
+
+/**
+ * Maps a raw Persona Document resource to its flattened representation.
+ */
+export function mapDocument(data: PersonaResourceData): PersonaDocument {
+  const attrs = data.attributes ?? {}
+  const files = attrs.files
+  return {
+    id: data.id ?? '',
+    type: data.type ?? '',
+    status: getString(attrs, 'status'),
+    kind: getString(attrs, 'kind'),
+    files: Array.isArray(files)
+      ? files
+          .filter(
+            (file): file is Record<string, unknown> => file !== null && typeof file === 'object'
+          )
+          .map((file) => ({
+            filename: typeof file.filename === 'string' ? file.filename : null,
+            url: typeof file.url === 'string' ? file.url : null,
+            byteSize: typeof file['byte-size'] === 'number' ? file['byte-size'] : null,
+          }))
+      : [],
+    createdAt: getString(attrs, 'created-at'),
+    processedAt: getString(attrs, 'processed-at'),
+    attributes: attrs,
+  }
+}
+
+/**
+ * Maps a raw Persona Inquiry Template resource to its flattened representation.
+ */
+export function mapInquiryTemplate(data: PersonaResourceData): PersonaInquiryTemplate {
+  const attrs = data.attributes ?? {}
+  return {
+    id: data.id ?? '',
+    name: getString(attrs, 'name'),
+    status: getString(attrs, 'status'),
+  }
+}
+
+/**
+ * Maps a raw Persona Account Importer resource to its flattened representation.
+ */
+export function mapImporter(data: PersonaResourceData): PersonaImporter {
+  const attrs = data.attributes ?? {}
+  return {
+    id: data.id ?? '',
+    status: getString(attrs, 'status'),
+    successfulCount: getNumber(attrs, 'successful-count', 0),
+    errorCount: getNumber(attrs, 'error-count', 0),
+    duplicateCount: getNumber(attrs, 'duplicate-count', 0),
+    createdAt: getString(attrs, 'created-at'),
+    completedAt: getString(attrs, 'completed-at'),
+  }
+}
+
+export const INQUIRY_OUTPUT_PROPERTIES: Record<string, OutputProperty> = {
+  id: { type: 'string', description: 'Inquiry ID (starts with inq_)' },
+  status: {
+    type: 'string',
+    description:
+      'Inquiry status (created, pending, completed, failed, expired, needs_review, approved, declined)',
+    nullable: true,
+  },
+  referenceId: {
+    type: 'string',
+    description: 'Reference ID linking the inquiry to an entity in your user model',
+    nullable: true,
+  },
+  note: { type: 'string', description: 'Free-form note on the inquiry', nullable: true },
+  tags: {
+    type: 'array',
+    description: 'Tags associated with the inquiry',
+    items: { type: 'string' },
+  },
+  fields: {
+    type: 'json',
+    description: 'Field name to field value pairs collected by the inquiry template',
+    nullable: true,
+  },
+  createdAt: { type: 'string', description: 'ISO 8601 creation timestamp', nullable: true },
+  startedAt: { type: 'string', description: 'ISO 8601 start timestamp', nullable: true },
+  completedAt: { type: 'string', description: 'ISO 8601 completion timestamp', nullable: true },
+  failedAt: { type: 'string', description: 'ISO 8601 failure timestamp', nullable: true },
+  expiredAt: { type: 'string', description: 'ISO 8601 expiration timestamp', nullable: true },
+  decisionedAt: { type: 'string', description: 'ISO 8601 decision timestamp', nullable: true },
+}
+
+export const ACCOUNT_OUTPUT_PROPERTIES: Record<string, OutputProperty> = {
+  id: { type: 'string', description: 'Account ID (starts with act_)' },
+  referenceId: {
+    type: 'string',
+    description: 'Reference ID linking the account to an entity in your user model',
+    nullable: true,
+  },
+  accountTypeName: { type: 'string', description: 'Name of the account type', nullable: true },
+  accountStatus: { type: 'string', description: 'Status set on the account', nullable: true },
+  tags: {
+    type: 'array',
+    description: 'Tags associated with the account',
+    items: { type: 'string' },
+  },
+  fields: {
+    type: 'json',
+    description: 'Field name to field value pairs defined by the account type',
+    nullable: true,
+  },
+  createdAt: { type: 'string', description: 'ISO 8601 creation timestamp', nullable: true },
+  updatedAt: { type: 'string', description: 'ISO 8601 last update timestamp', nullable: true },
+}
+
+export const CASE_OUTPUT_PROPERTIES: Record<string, OutputProperty> = {
+  id: { type: 'string', description: 'Case ID (starts with case_)' },
+  status: { type: 'string', description: 'Case status', nullable: true },
+  name: { type: 'string', description: 'Case name', nullable: true },
+  resolution: { type: 'string', description: 'Case resolution', nullable: true },
+  assigneeId: { type: 'string', description: 'ID of the assigned reviewer', nullable: true },
+  tags: { type: 'array', description: 'Tags associated with the case', items: { type: 'string' } },
+  fields: {
+    type: 'json',
+    description: 'Field name to field value pairs defined by the case template',
+    nullable: true,
+  },
+  createdAt: { type: 'string', description: 'ISO 8601 creation timestamp', nullable: true },
+  assignedAt: { type: 'string', description: 'ISO 8601 assignment timestamp', nullable: true },
+  resolvedAt: { type: 'string', description: 'ISO 8601 resolution timestamp', nullable: true },
+}
+
+export const REPORT_OUTPUT_PROPERTIES: Record<string, OutputProperty> = {
+  id: { type: 'string', description: 'Report ID (starts with rep_)' },
+  type: { type: 'string', description: 'Report type (e.g. report/watchlist)' },
+  status: {
+    type: 'string',
+    description: 'Report status (pending, ready, errored)',
+    nullable: true,
+  },
+  hasMatch: {
+    type: 'boolean',
+    description: 'Whether the report found at least one match',
+    nullable: true,
+    optional: true,
+  },
+  tags: {
+    type: 'array',
+    description: 'Tags associated with the report',
+    items: { type: 'string' },
+  },
+  createdAt: { type: 'string', description: 'ISO 8601 creation timestamp', nullable: true },
+  completedAt: { type: 'string', description: 'ISO 8601 completion timestamp', nullable: true },
+  attributes: {
+    type: 'json',
+    description: 'Full report attributes, which vary by report type',
+  },
+}
+
+export const VERIFICATION_OUTPUT_PROPERTIES: Record<string, OutputProperty> = {
+  id: { type: 'string', description: 'Verification ID (starts with ver_)' },
+  type: { type: 'string', description: 'Verification type (e.g. verification/government-id)' },
+  status: {
+    type: 'string',
+    description:
+      'Verification status (initiated, submitted, passed, failed, requires_retry, canceled)',
+    nullable: true,
+  },
+  checks: {
+    type: 'array',
+    description: 'Individual checks run as part of the verification',
+    items: { type: 'object' },
+  },
+  countryCode: { type: 'string', description: 'ISO 3166-1 alpha-2 country code', nullable: true },
+  createdAt: { type: 'string', description: 'ISO 8601 creation timestamp', nullable: true },
+  submittedAt: { type: 'string', description: 'ISO 8601 submission timestamp', nullable: true },
+  completedAt: { type: 'string', description: 'ISO 8601 completion timestamp', nullable: true },
+  attributes: {
+    type: 'json',
+    description: 'Full verification attributes, which vary by verification type',
+  },
+}
+
+export const DOCUMENT_OUTPUT_PROPERTIES: Record<string, OutputProperty> = {
+  id: { type: 'string', description: 'Document ID (starts with doc_)' },
+  type: { type: 'string', description: 'Document type (e.g. document/government-id)' },
+  status: {
+    type: 'string',
+    description: 'Document status (initiated, submitted, processed, errored)',
+    nullable: true,
+  },
+  kind: { type: 'string', description: 'Kind of document collected', nullable: true },
+  files: {
+    type: 'array',
+    description: 'Files uploaded to the document, with Persona-hosted download URLs',
+    items: {
+      type: 'object',
+      properties: {
+        filename: { type: 'string', description: 'Original file name', nullable: true },
+        url: {
+          type: 'string',
+          description: 'Persona-hosted file URL (requires API key to download)',
+          nullable: true,
+        },
+        byteSize: { type: 'number', description: 'File size in bytes', nullable: true },
+      },
+    },
+  },
+  createdAt: { type: 'string', description: 'ISO 8601 creation timestamp', nullable: true },
+  processedAt: { type: 'string', description: 'ISO 8601 processing timestamp', nullable: true },
+  attributes: {
+    type: 'json',
+    description: 'Full document attributes, which vary by document type',
+  },
+}
+
+export const INQUIRY_TEMPLATE_OUTPUT_PROPERTIES: Record<string, OutputProperty> = {
+  id: { type: 'string', description: 'Inquiry template ID (starts with itmpl_)' },
+  name: { type: 'string', description: 'Name of the inquiry template', nullable: true },
+  status: {
+    type: 'string',
+    description: 'Inquiry template status (active, inactive)',
+    nullable: true,
+  },
+}
+
+export const IMPORTER_OUTPUT_PROPERTIES: Record<string, OutputProperty> = {
+  id: { type: 'string', description: 'Importer ID (starts with mprt_)' },
+  status: {
+    type: 'string',
+    description: 'Importer status (pending, ready, errored)',
+    nullable: true,
+  },
+  successfulCount: { type: 'number', description: 'Number of rows imported successfully' },
+  errorCount: { type: 'number', description: 'Number of rows that failed to import' },
+  duplicateCount: { type: 'number', description: 'Number of duplicate rows skipped' },
+  createdAt: { type: 'string', description: 'ISO 8601 creation timestamp', nullable: true },
+  completedAt: { type: 'string', description: 'ISO 8601 completion timestamp', nullable: true },
+}