Best Practices for updating target languages using the API

Overview

The PhishingBox API can be used both to retrieve target information for use in external systems and to update selected target fields in PhishingBox.

This makes the API useful for organizations that need to integrate PhishingBox with HR systems, identity platforms, reporting applications, data warehouses, automation platforms, or other internal applications.

A common example is maintaining most target information through Microsoft Entra ID synchronization while maintaining the target's preferred language from another authoritative system.

For information about configuring API access, see the API article.

Click from the following to jump to the desired section:

• Retrieve Target Information
• Retrieve Specific Targets
• Retrieve Targets by Group
• Update Target Information
• Use Stable Identifiers
• Scheduled and Incremental Synchronization
• Validation and Reconciliation

Retrieve Target Information

The primary endpoint for exporting target information from PhishingBox is:

GET /api/v2/target/all

This endpoint returns targets associated with the account and includes pagination information and the target's group memberships.

Target information returned by this endpoint includes fields such as:

• Target UUID
• Email address
• First, middle, and last name
• Company and title
• Department
• Manager
• Language
• Timezone
• Integration ID
• Employee ID
• Active status
• Date hired
• Optional fields
• Group memberships

This endpoint is appropriate when an external system needs a current inventory of PhishingBox targets or when an integration needs to build an initial mapping between external users and PhishingBox target UUIDs.

Pagination

The endpoint supports limit and offset. The limit on any single request is 100 records. 

Integrations should continue requesting pages 100 records at a time, until all records have been retrieved.

Do not assume that a single request represents the complete target population.

Available Filters

The target list can also be filtered using:

• date_created_start
• date_created_end
• last_failed_start
• last_failed_end
• failed
• active

The date-created filters can be useful when an external process needs to retrieve targets created during a particular period.

Retrieve Specific Targets

When the integration already knows the PhishingBox UUID of a target, use:

GET /api/v2/target/get

The id parameter accepts target UUIDs. The API documentation allows multiple target UUIDs to be provided as a comma-separated value.

This endpoint returns the current target profile, including language, directory/integration identifiers, status, and group membership.

This is useful when another application does not need the entire target population and instead needs to refresh information for a known set of users.

For example, an external application that has stored the PhishingBox target UUID can retrieve the latest PhishingBox record before deciding whether an update is required.

External System
      |
      | Stored PhishingBox UUID
      v
GET /api/v2/target/get
      |
      v
Current PhishingBox Target
      |
      | Compare fields
      v
Update only if required

Retrieve Targets by Group

Integrations that operate on individual PhishingBox groups can use:

GET /api/v2/group/targets

The request requires the group's UUID and supports limit, offset, and an active filter.

In addition to the target information, the response includes information about the group such as:

• Group UUID
• Group name
• Integration type
• Automatic synchronization status
• Smart synchronization status
• Integration ID

This endpoint is useful when another system needs to reproduce or evaluate PhishingBox group membership rather than exporting every target in the account.

Update Target Information

Existing targets can be updated through:

PATCH /api/v2/target/update

For example, if an HR application is authoritative for preferred language, it can update the PhishingBox language field while Microsoft Entra ID continues managing other target attributes.

{
  "id": "<target_uuid>",
  "fields": {
    "email": "user@example.com",
    "language": "fr_CA"
  }
}

An automated integration should send only the fields it intends to manage. Avoid resubmitting unrelated target attributes unless the external system is intended to become authoritative for those fields.

Use Stable Identifiers

The PhishingBox target UUID should be retained by external integrations after the target has been identified.

Email address is useful for initial matching, but it should not be treated as the only permanent integration key because a user's email address may change.

The target responses also include integration_id and employee_id, which may be useful when correlating PhishingBox records with external identity systems.

A typical integration mapping can contain:

External User ID
PhishingBox Target UUID
Current Email
Last Synchronized Language
Last Successful Synchronization

Scheduled and Incremental Synchronization

Organizations do not normally need to retrieve and update every target each time a synchronization process runs.

A recommended process is:

1. Perform an initial retrieval using GET /api/v2/target/all.
2. Store the PhishingBox target UUID alongside the external user identifier.
3. Retrieve changes from the authoritative source system.
4. Use GET /api/v2/target/get when the current PhishingBox value needs to be verified.
5. Compare the authoritative value with the current value.
6. Use PATCH /api/v2/target/update only when a change is required.

This reduces unnecessary API requests and prevents unchanged target records from being repeatedly written.

Validation and Reconciliation

Automated synchronization should include periodic reconciliation even when normal changes are processed in real time.

A reconciliation job can retrieve targets using GET /api/v2/target/all and compare important fields against the authoritative source.

For a language integration, compare at least:

• External user identifier
• PhishingBox target UUID
• Email address
• Expected language
• Current PhishingBox language
• Active status

This allows missed events, unsuccessful updates, changed identifiers, and synchronization drift to be detected without requiring another manual Excel import.