Alloy Investigations API
Investigations are reviewable items that contain Alerts for suspicious activities for Alloy's Ongoing Monitoring solution.
OpenAPI Specification
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: {}