Arva Platform

Create a new case

To open and evaluate a new case, you must first create the customer in the Arva platform. This is done by sending a POST request to the following endpoint:

https://platform.arva.ai/api/v0/customer/create

You need to provide the Agent ID and the registered name of the business. If the agent is configured for the United States, you also need to provide the state of registration of the business.

curl -X POST 'https://platform.arva.ai/api/v0/customer/create' \
-H 'Authorization: Bearer <YOUR_API_KEY>' \
-H 'Content-Type: application/json' \
-d '{
  "agentId": "<YOUR_AGENT_ID>",
  "registeredName": "<REGISTERED_NAME>",
  "state": "<STATE>", # optional only required for US agents
}'

npm i @arva-ai/sdk

import { Arva } from '@arva-ai/sdk'

const client = new Arva(
  '<YOUR_API_KEY>'
)

const customer = await client.customers.create({
  agentId: '<YOUR_AGENT_ID>',
  registeredName: '<REGISTERED_NAME>',
  state: '<STATE>' // only required for US agents
})

const customerId = customer.id

import requests

response = requests.post(
    'https://platform.arva.ai/api/v0/customer/create',
    headers={'Authorization': 'Bearer <YOUR_API_KEY>'},
    # state is only required for US agents
    json={'agentId': '<YOUR_AGENT_ID>', 'registeredName': '<REGISTERED_NAME>', 'state': '<STATE>'}
)
    
customer = response.json()
customerId = customer['id']

pip install arva-sdk

from arva import Arva

client = Arva(
    api_key='<YOUR_API_KEY>'
)

customer = client.customer.create(
  agent_id='<YOUR_AGENT_ID>',
  registered_name='<REGISTERED_NAME>',
  state='<STATE>' # only required for US agents
)

customerId = customer['id']

If the request is successful, the response from the API will be an object with the following schema:

{
  id: string // customer ID
}

Create a case and run it

You can optionally provide the initial data for the case when creating it at the same endpoint by providing the user-provided information, websites and file uploads in the request. The fields you provide here will depend on which checks you have enabled for the agent.

curl -X POST "https://platform.arva.ai/api/v0/customer/create" \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: multipart/form-data" \
-F "agentId=<AGENT_ID>" \
-F "registeredName=<REGISTERED_NAME>" \
-F "state=<STATE>" # optional, only required for US agents \
-F "userInfoPatch={
  "dba": <string>, # optional
  "fkas": <string[]>, # optional
  "natureOfBusiness": <string>, # optional
  "operatingAddress": <string>, # optional
  "tin": <string>, # optional
  "entities": Entity[] # optional, see schemas below
}' \
-F "websites=<ARRAY_OF_USER_WEBSITE_URLS>" \
-F "file=@<FILE_1_PATH>" \
-F "file=@<FILE_2_PATH>"

npm i @arva-ai/sdk

import { Arva } from '@arva-ai/sdk'

const client = new Arva(
  '<YOUR_API_KEY>'
)

const customer = await client.customers.createAndRun({
  agentId: '<YOUR_AGENT_ID>',
  registeredName: '<REGISTERED_NAME>',
  state: '<STATE>', // only required for US agents
  userInfoPatch: {
    'dba': <string>, // optional,
    'fkas': <string[]>, // optional,
    'natureOfBusiness': <string>, // optional,
    'operatingAddress': <string>, // optional,
    'tin': <string>, // optional,
    'entities': <Entity[]> // optional, see schemas below
  },
  websites: <string[]>,
  files: <File[]>,
  // optional, pass this to run only a subset of the enabled checks, e.g. ['INCORPORATION']
  // This will skip the overall verdict and RFI but will return the results for those checks
  checks: <CheckType[]> 
})

const customerId = customer.id

import json
import requests
import os
from requests_toolbelt import MultipartEncoder

user_info_patch = {
  # The fields you provide here will depend on which checks you have enabled for the agent
  'dba': <string> | None,
  'fkas': <string[]> | None,
  'natureOfBusiness': <string> | None,
  'operatingAddress': <string> | None,
  'tin': <string> | None,
  'entities': Entity[] | None # see schemas below
}

websites = <string[]>

file_paths = <string[]>

files = [open(fp, 'rb') for fp in file_paths]
file_tuples = [('file', (os.path.basename(f.name), f, 'application/pdf')) for f in files]

# Optional, pass this to run only a subset of the enabled checks, e.g. ['INCORPORATION']
# This will skip the overall verdict and RFI but will return the results for those checks
checks = ['INCORPORATION']

mp_encoder = MultipartEncoder(
  fields=[
    ('agentId', '<YOUR_AGENT_ID>'),
    ('registeredName', '<REGISTERED_NAME>'),
    ('state', '<STATE>'), # only required for US agents
    ('user_info_patch', json.dumps(user_info_patch)),
    ('websites', json.dumps(websites)),
    ('checks', json.dumps(checks))
  ] + file_tuples
)

response = requests.post(
  'https://platform.arva.ai/api/v0/customer/create',
  headers={
    'Authorization': 'Bearer ' + apiKey,
    'Content-Type': mp_encoder.content_type
  },
  data=mp_encoder,
)

pip install arva-sdk

from arva import Arva

client = Arva(
  api_key='<YOUR_API_KEY>'
)

customer = client.customer.createAndRun(
  agent_id='<YOUR_AGENT_ID>',
  registered_name='<REGISTERED_NAME>',
  state='<STATE>', # only required for US agents
  user_info_patch={
    'dba': <string>, # optional
    'fkas': <string[]>, # optional
    'natureOfBusiness': <string>, # optional
    'operatingAddress': <string>, # optional
    'tin': <string>, # optional
    'entities': Entity[] # optional, see schemas below
  },
  websites=[<string>],
  files=[<File>],
  # optional, pass this to run only a subset of the enabled checks, e.g. ['INCORPORATION']
  # This will skip the overall verdict and RFI but will return the results for those checks
  checks=[<CheckType>],
)

customerId = customer['id']

If the request is successful, the response from the API will be an object with the following schema:

{
  id: string // customer ID
  name: string
  state: string | undefined
  createdAt: Date
  verdict: 'ACCEPT' | 'REJECT' | 'REQUEST_INFORMATION' | 'PENDING'
  riskLevel: 'HIGH' | 'MEDIUM' | 'LOW' | undefined
  periodicReviewYears: number | undefined // undefined unless the verdict is ACCEPT
  rfi: string | undefined // undefined unless the verdict is REQUEST_INFORMATION
  requiresManualReview: boolean
  checks: {
    type: string
    verdict: 'ACCEPT' | 'REJECT' | 'REQUEST_INFORMATION' | 'PENDING'
    riskLevel: 'HIGH' | 'MEDIUM' | 'LOW' | undefined // undefined unless the verdict is ACCEPT
    reason: string
    periodicReviewYears: number | undefined // undefined unless the verdict is ACCEPT
    requiresManualReview: boolean
    proofs: Proof[]
    // Some checks return additional details e.g. registry results
    details: Record<string, unknown> | undefined
  }[]
  entities: EntityWithScreeningResults[]
}

Where:

type Proof = {
  id: string
  type: 'DOCUMENT' | 'WEBSITE'
  inferredType: string
  name: string
  url: string
}

type IndividualEntity = {
  type: 'individual'
  metadata: {
    firstName: string
    middleNames: string | undefined
    lastName: string
    dateOfBirth: {
      day: number | undefined
      month: number | undefined
      year: number
    } | undefined
    address: string | undefined
    country: string | undefined
  }
}

type CorporateOrTrustEntity = {
  type: 'corporate' | 'trust'
  metadata: {
    name: string
    registrationJurisdiction: string | undefined
    registrationNumber: string | undefined
    address: string | undefined
  }
  relationships: Relationship[]
}

type Entity = IndividualEntity | CorporateOrTrustEntity

type Relationship = {
  type: 'director' | 'officer' | 'psc'
  positions: string[]
} | {
  type: 'owner'
  ownershipPercentage: number
  entityId?: string // ID of the owned entity, if not the customer entity
} | {
  type: 'additional'
  reason: string
}


type EntityWithScreeningResults = Entity & {
  screeningHits: ScreeningResult[]
}

type ScreeningResult = {
  type: 'adverse_media' | 'sanctions_screening' | 'peps_screening' | 'other_screening'
  verdict: 'LOW' | 'MEDIUM' | 'HIGH' | 'REJECT' | 'DISCOUNTED' | 'REVIEW'
  reason: string
  source: string // e.g. 'webSearch', 'complyAdvantage'
  fromMonitoring: boolean
  externalIds: {
    // varies by provider
  }
  matchingName: string
  // Additional fields vary by type and provider
  names: string[] | undefined
  url: string | undefined
  date: string | undefined
  lists: {
    name: string
    identifier: string
    url: string
    countryCodes: string[]
    dateAdded: string
  }[] | undefined
  groupId: string | undefined // Adverse media hits that share the same groupId are likely to be the same event
}

Next, see how you can add data to the case.