openapi: 3.0.0 info: title: Alloy Identity Bank Accounts Investigations API version: 1.0.0 description: The Alloy Identity API provides endpoints for creating and managing person and business entities, running evaluations through configurable risk workflows, managing journey applications, submitting events for ongoing monitoring, handling document verification, and managing investigations and case alerts. Authentication is via Basic HTTP credentials or OAuth 2.0 Client Credentials. contact: name: Alloy Support url: https://help.alloy.com/hc/en-us license: name: Proprietary servers: - url: https://sandbox.alloy.co/v1 description: Sandbox environment - url: https://alloy.co/v1 description: Production environment security: - basic: [] - oauth2: [] tags: - name: Investigations description: Investigations are reviewable items that contain Alerts for suspicious activities for Alloy's Ongoing Monitoring solution. paths: /investigations/{investigation_token}: parameters: - in: path name: investigation_token schema: type: string required: true description: Token associated with the Investigation example: INV-EAx2xoAsqF1ibKTQzkXV get: tags: - Investigations summary: Get an Investigation description: Returns the details of an individual Investigation. responses: '200': description: Successfully retrieved Investigation Details content: application/json: schema: type: object properties: investigation_token: type: string example: INV-EAx2xoAsqF1ibKTQzkXV closed_at: type: string format: date-time example: '2024-12-05T20:05:43.643Z' created_at: type: string format: date-time example: '2024-11-26T16:00:14.677Z' name: type: string nullable: true type: type: string example: Fraud state: type: string example: case_review source: type: string example: alert outcome: type: string example: Dismissed updated_at: type: string format: date-time example: '2024-12-05T20:05:43.643Z' archived_at: type: string format: date-time example: '2024-12-05T20:05:43.643Z' _embedded: type: object properties: assigned_agent: type: object properties: first_name: type: string example: Mike last_name: type: string example: Alloy email: type: string example: safeandseamless@alloy.com token: type: string example: AG-L83m6iTwcXdNg3CHndS4 entities: type: object properties: P-KaKZxdSGnbxXfKXnXdyp: type: object properties: type: type: string example: person entity_token: type: string example: P-KaKZxdSGnbxXfKXnXdyp entity_name: type: string example: Trycia Turner meta: type: string nullable: true external_ingestion_identifier: type: string nullable: true recent_action: type: string nullable: true external_entity_identifier: type: string example: mjj09291-111824-3 risk_score: type: number nullable: true events: type: array items: type: object properties: event: type: string example: closed agent: type: object properties: first_name: type: string example: Mike last_name: type: string example: Alloy email: type: string example: safeandseamless@alloy.com token: type: string example: AG-L83m6iTwcXdNg3CHndS4 assigned_agent: type: object properties: first_name: type: string nullable: true last_name: type: string nullable: true email: type: string nullable: true token: type: string nullable: true note: type: string nullable: true meta: type: object nullable: true evidences: type: object properties: journey_alerts: type: array items: type: object properties: journey_application_token: type: string example: JA-PA0M5o6nyYCGhVyhXYWH journey_token: type: string example: J-O9aI8AWpkv895oavftOH tags: type: array items: type: object properties: tag_color: type: string example: FB923C tag_name: type: string example: Phone Reputation Fail is_outcome_reason: type: boolean example: true added_by: type: object properties: email: type: string example: agent@email.com first_name: type: string example: Mike last_name: type: string example: Alloy token: type: string example: AG-L83m6iTwcXdNg3CHndS4 documents: type: array items: $ref: '#/paths/~1documents~1%7Bdocument_token%7D/put/responses/200/content/application~1json/schema/items' notes: type: array items: type: object properties: created_at: type: string example: '2025-01-01T13:00:59.000Z' created_by: type: object properties: first_name: type: string example: Mike last_name: type: string example: Alloy email: type: string example: agent@email.com token: type: string example: AG-f5NJW4vCmoxwxkn4BpOV entity_name: type: string example: Nick Armstrong entity_token: type: string example: P-KaKZxdSGnbxXfKXnXdyp text: type: string example: My note is_investigation_level_note: type: boolean example: true reviews: type: array items: type: object properties: new_investigation_state: type: string example: alert_review_closed note: type: string nullable: true outcome: type: string example: Dismissed previous_investigation_state: type: string example: alert_review reason: type: string example: Verified by human reviewed_at: type: string format: date-time example: '2024-12-05T20:05:43.643Z' reviewed_by: type: object properties: first_name: type: string example: Mike last_name: type: string example: Alloy email: type: string example: safeandseamless@alloy.com token: type: string example: AG-L83m6iTwcXdNg3CHndS4 '401': description: Authentication Failure content: application/json: schema: allOf: - $ref: '#/paths/~1investigations~1types/get/responses/401/content/application~1json/schema' '404': description: Investigation Not Found content: application/json: schema: allOf: - $ref: '#/paths/~1investigations~1%7Binvestigation_token%7D~1alerts~1%7Bjourney_application_token%7D~1review/put/responses/404/content/application~1json/schema' '409': description: Resource Conflict content: application/json: schema: allOf: - type: object properties: status_code: type: string example: 409 error: type: object properties: minor_code: type: number example: 4091 type: type: string message: type: string details: type: object properties: document_token: type: string entity_token: type: string error_token: type: string timestamp: type: number example: 1725386185011 evaluation_token: type: string example: null entity_token: type: string example: null application_token: type: string application_version_id: type: string example: null '500': description: Unhandled Service Error content: application/json: schema: allOf: - type: object properties: status_code: type: string example: 500 error: type: object properties: minor_code: type: number example: 5000 type: type: string message: type: string error_token: type: string example: 31e6e353-e62b-4fe2-be16-ea37ea9a992c timestamp: type: number example: 1725386185011 evaluation_token: type: string example: null entity_token: type: string example: null application_token: type: string application_version_id: type: string example: null '503': description: Temporarily Offline for Maintenance content: application/json: schema: allOf: - type: object properties: status_code: type: string example: 503 error: type: object properties: minor_code: type: number example: 5031 type: type: string message: type: string example: Oops our database server is unreachable. The engineers have been notified. details: type: object properties: journey_token: type: string error_token: type: string timestamp: type: number example: 1725386185011 evaluation_token: type: string example: null entity_token: type: string example: null application_token: type: string application_version_id: type: string example: null /investigations: get: tags: - Investigations summary: Get list of Investigations description: Retrieves a filterable paginated list of investigations parameters: - in: query name: q schema: type: object description: Object to hold the investigations filters properties: statuses: type: string description: Listed by [Get Investigation filters](https://developer.alloy.com/public/reference/get_investigations-filters). E.g. `["alert_review"]`. types: type: string description: Listed by [Get Investigation filters](https://developer.alloy.com/public/reference/get_investigations-filters). E.g. `["Fraud"]`. assignedAgents: type: string description: Listed by [Get Investigation filters](https://developer.alloy.com/public/reference/get_investigations-filters). E.g. `["AG-L83m6iTwcXdNg3CHndS4"]` entityTokens: type: string description: E.g. `["P-KaKZxdSGnbxXfKXnXdyp"]` investigationTokens: type: string description: E.g. `["INV-EAx2xoAsqF1ibKTQzkXV"]` externalEntityIds: type: string description: E.g. `["external_entity_id"]` deviceIds: type: string description: E.g. `["device_vendor_identifier"]` programNames: type: string description: E.g. `["program_name"]` includeClosed: type: boolean archived: type: boolean description: E.g. `false` createdAtFrom: type: number description: E.g. `1737742979` createdAtTo: type: number description: E.g. `1737742979` updatedAtFrom: type: number description: E.g. `1737742979` updatedAtTo: type: number description: E.g. `1737742979` - in: query name: pageNum schema: type: number description: Which page number to return. Default is 1 default: 1 - in: query name: numRowsPerPage schema: type: number description: Limits results per page. Up to 100. default: 20 - in: query name: sortColumn schema: type: string enum: - updated_at - created_at - total_alerts - risk_score default: created_at - in: query name: sortOrder schema: type: string enum: - DESC - ASC default: DESC responses: '200': description: Success content: application/json: schema: type: object properties: _embedded: type: object properties: pagination: type: object properties: total_investigations: type: number example: 95 total_pages: type: number example: 4 page: type: number example: 1 per_page: type: number example: 20 sorting: type: object properties: column: type: string example: update_at order: type: string example: DESC error: type: object example: null investigations: type: array items: type: object properties: investigation_token: type: string example: INV-EAx2xoAsqF1ibKTQzkXV name: type: string example: Nick Armstrong's investigation total_alerts: type: number example: 2 type: type: string example: Fraud state: type: string example: alert_review source: type: string example: alert outcome: type: string example: Dismissed created_at: type: string format: date-time example: '2024-11-26T16:00:14.677Z' updated_at: type: string format: date-time example: '2024-11-26T16:00:14.677Z' closed_at: type: string format: date-time example: null archived_at: type: string format: date-time example: null _embedded: type: object properties: entities: type: object properties: P-KaKZxdSGnbxXfKXnXdyp: type: object properties: entity_name: type: string example: Nick Armstrong entity_type: type: string example: person entity_token: type: string example: P-KaKZxdSGnbxXfKXnXdyp risk_score: type: number example: 0.7 assigned_agent: type: object properties: first_name: type: string example: Mike last_name: type: string example: Alloy email: type: string example: agent@email.com token: type: string example: AG-L83m6iTwcXdNg3CHndS4 device_ids: type: array items: type: string example: device_vendor_identifier program_names: type: array items: type: string example: Program name alert_assignees: type: array items: type: string example: Agent name '401': description: Authentication Failure content: application/json: schema: allOf: - $ref: '#/paths/~1investigations~1types/get/responses/401/content/application~1json/schema' post: tags: - Investigations summary: Create an Investigation description: Manually creates a new Investigation requestBody: content: application/json: schema: type: object properties: investigation_state: type: string example: alert_review description: Listed by [Get Investigation filters](https://developer.alloy.com/public/reference/get_investigations-filters). investigation_type: type: string example: Fraud description: Listed by [Get Investigation types](https://developer.alloy.com/public/reference/get_investigations-types). entity_tokens: type: array items: type: string example: P-1GoQALm40nPQSp7UVTJS journey_alerts: type: array items: type: object properties: agent_token: type: string example: AG-L83m6iTwcXdNg3CHndS4 journey_alert_token: type: string example: JA-mhjlfS6nZe1G6HuvAKVq outcome: type: string example: Dismissed reason: type: string example: Passed manual checks note: type: string example: My note required: - agent_token - journey_alert_token investigation_assignee_token: type: string example: AG-L83m6iTwcXdNg3CHndS4 description: Listed by [Get list of assignable agents](https://developer.alloy.com/public/reference/get_investigations-assignable-agents). Assigns the new Investigation to an agent. should_aggregate_alerts: description: Setup if the automatic Alerts can be attached to the new Investigation later. type: boolean default: true investigation_name: type: string example: Investigation Nick Armstrong note: type: string example: My note tags: type: array minItems: 0 items: type: object properties: tag_name: type: string example: Suspicious Activity is_outcome_reason: type: boolean example: false description: If the tag has outcomes attached required: - tag_name - is_outcome_reason required: - investigation_type - investigation_state - journey_alerts - entity_tokens responses: '201': x-summary: OK description: Investigation content: application/json: schema: type: object $ref: '#/paths/~1investigations~1%7Binvestigation_token%7D/get/responses/200/content/application~1json/schema' '400': description: Missing required fields content: application/json: schema: type: object properties: status_code: type: string error: type: object timestamp: type: string evaluation_token: type: string entity_token: type: string application_token: type: string application_version_id: type: string example: status_code: 400 error: minor_code: 4002 type: Request Body Validation Failure message: Your request body contained invalid field(s) details: message: '"required_field" is required' path: required_field type: any.required context: key: required_field error_token: u82hfowjwl timestamp: 1652205025227 evaluation_token: null entity_token: null application_token: null application_version_id: null components: securitySchemes: basic: type: http description: HTTP basic authorization using a workflow token and secret scheme: basic oauth2: type: oauth2 description: OAuth2 using a workflow token and secret to generate a bearer token flows: clientCredentials: tokenUrl: /oauth/bearer scopes: {}