Profiles and Case Assignees

Profiles

A profile is how First AML represents an individual or an entity across all of your cases. It is identified by a profileId.

The Public API has previously referred to an individual or entity by an individualId or an entityId. Those IDs come from an older model, which profiles replace, so use a profileId in new integrations. Read Profiles for the concept in full, including how legacy IDs and merged profiles are handled.

Every new query and mutation below accepts either a profileId or the individualId / entityId you already store, so you can adopt profiles without migrating your records first.

Looking up a profile

Each profile returns its status, its ongoing monitoring, every legacy ID that resolves to it (individualIds or entityIds), and the mergedProfileIds of any profiles merged into it. A merged profile’s profileId resolves to the profile it was merged into.

query {
  individualProfileDetails(input: { individualId: "20417" }) {
    ... on IndividualProfile {
      profileId
      preferredName { fullName }
      dateOfBirth
      status
      monitoring { status expiresOn }
      individualIds
      mergedProfileIds
    }
    ... on ValidationErrors { errors { message } }
  }
}

Searching profiles

  • searchIndividualProfiles finds individuals by name, email or phone.
  • searchEntityProfiles finds entities by entityName or identifier.

Results are paged. When hasNextPage is true, pass nextCursor to nextPageOfIndividualProfiles or nextPageOfEntityProfiles. Profiles that belong only to offices you can’t access, but which share their profiles in a limited form, are returned as an IndividualLimitedProfile or EntityLimitedProfile carrying just their ID and names.

Managing profiles

These mutations need the new profile-management scope:

Mutation What it does
enableIndividualProfileMonitoring / enableEntityProfileMonitoring Turns on ongoing monitoring, which raises alerts when new screening hits are found. Supply an expiresOn date or neverExpires: true. The profile must be active and screened.
disableIndividualProfileMonitoring / disableEntityProfileMonitoring Turns off ongoing monitoring.
deactivateIndividualProfile / deactivateEntityProfile Marks a profile as inactive, for example when you no longer act for the client. Ongoing monitoring is turned off.
activateIndividualProfile / activateEntityProfile Marks an inactive profile as active again. Monitoring stays off until you turn it back on.

New scope: profile-management

Select the profile-management scope when creating an API client under Settings > Integrations > API Credentials. It is also needed to set custom fields on a profile once custom fields are released. See Authentication for every scope.

Profile merged events

Two new event types, INDIVIDUAL_PROFILES_MERGED and ENTITY_PROFILES_MERGED, fire when a user merges duplicate profiles. The payload gives the surviving profileId, every profile merged into it, and every individualId or entityId that now resolves to it, so you can update your stored IDs. You don’t have to: any old ID still resolves to the surviving profile.

{
  "eventType": "IndividualProfilesMerged",
  "eventTimestamp": "2026-10-23T01:02:03Z",
  "organizationId": "3f2b8c1e9a4d4e7f8b6c5d4e3f2a1b0c",
  "profileId": "c7e5a3b1-9d2f-4c8e-a6b4-3f1e2d0c9b8a",
  "mergedProfileIds": [
    "6d1f4b2a-3c8e-4a7d-9b5f-2e1c0d9a8b7c"
  ],
  "individualIds": [
    "20417",
    "20533"
  ]
}

EntityProfilesMerged has the same shape, with entityIds in place of individualIds.

Existing individuals and entities

When you add an existing individual or entity to a case (existingIndividuals and existingRootEntity on createCase, or existingIndividuals on addExistingIndividualsToCase), their details are now taken from their profile, using the latest details held across all of your cases rather than only cases where that exact individualId or entityId appears. An individual whose profile is already on the case is reused rather than added twice, even if you supply a different ID for them.

See the profile examples for complete requests and responses.

Assigning users

Assign by email when creating a case

createCase now accepts assignedUserEmails on CreateCaseInput. It can be used on its own or alongside assignedUsers. Each email must belong to a user who can be assigned to the case.

Assign and unassign on an existing case

Two new mutations change who is assigned to an open case without replacing the current assignees. Both accept userIds, userEmails or both, need the case-management scope, and return the case with every user now assigned to it.

  • addCaseAssignees assigns more users. Users already assigned stay assigned.
  • removeCaseAssignees unassigns users. Users who aren’t assigned are ignored.
mutation {
  addCaseAssignees(input: {
    caseId: "48213"
    userEmails: ["tom.walker@example.com"]
  }) {
    ... on CaseInformation {
      caseId
      assignedUsers { id name }
    }
    ... on ValidationErrors { errors { message } }
  }
}

See the assigning users examples.

Coming soon: custom fields

The examples now include custom fields, marked Preview. Custom fields aren’t available in production yet, and the details may change before they are. When they arrive you’ll be able to:

  • list your organization’s custom field definitions
  • read custom field values on cases and profiles
  • set custom fields when creating a case, or later with setCustomFieldValue and clearCustomFieldValue
  • filter searchCases, searchIndividualProfiles and searchEntityProfiles by custom field value

See the custom field examples for a preview.


Getting Started
Authentication
Domain Concepts
API Features
Zapier
Embedded EIV
Help