Interactions

Learn how to create, update, list, and delete interactions associated with candidates.

Interactions represent contact moments or events—such as phone calls, emails, or meetings—and are modeled as first-class records linked to a candidate.

This article focuses exclusively on interaction management. Creating and updating candidates is covered in separate articles.

What are interactions?

Interactions capture when and how contact occurred with a candidate. Typical examples include:

• Intake calls
• Emails
• Advice or orientation meetings
• Event registrations

Interactions are always scoped to a single candidate and are stored as separate records linked to that candidate.

Interaction lifecycle overview

Interactions can be:

• Listed for an existing candidate
• Created (inline during candidate creation, or separately afterward)
• Updated
• Deleted

All interaction write operations are handled asynchronously by the Mutation Engine.

Read the Mutation Engine guide for the asynchronous write model.

Listing interactions

Use GET /candidates/{id}/interactions to retrieve all interactions linked to a candidate.

GET /candidates/{id}/interactions

Characteristics:

• Returns all interaction records for the candidate (up to 100 records)
• Results are scoped to the authenticated region
• Supports sandbox mode

This endpoint is typically used for:

• Candidate timelines
• CRM-style overviews
• Auditing or reporting

Creating interactions

Creating interactions for an existing candidate

Use POST /candidates/{id}/interactions to create one or more interactions for an existing candidate.

POST /candidates/{id}/interactions

Characteristics:

• Up to 10 interactions per request
• Each interaction must include:
  • type
  • performedAt
• Validation happens before the mutation is queued
• Ownership is enforced during mutation execution

This endpoint is ideal when:

• Logging follow-up actions
• Adding interactions after candidate creation
• Syncing interactions from external systems

Inline interaction creation (during candidate creation)

Interactions can also be created inline when creating a candidate via POST /candidates.

This allows you to:

• Create a candidate and initial interactions atomically
• Avoid follow-up API calls for first contact moments

Inline interaction creation is only supported during candidate creation. It is not supported when updating a candidate.

Read the candidate-submission guide for inline interactions.

Interaction payload basics

Each interaction payload follows the same schema, whether created inline or via the interaction endpoint.

Common fields include:

• type
  One or more predefined interaction types.
• performedAt
  Date or date-time when the interaction took place.
• summary (optional)
  Short description of the interaction.
• notes (optional)
  Additional details.
• duration (optional)
  Duration in seconds.

Allowed values and exact validation rules are defined by the /schema endpoint and enforced at runtime.

Read the schema guide for the authoritative interaction definition.

Updating interactions

Use PATCH /candidates/{id}/interactions/{interactionId} to update an existing interaction.

PATCH /candidates/{id}/interactions/{interactionId}

Characteristics:

• At least one field must be provided
• Only included fields are updated
• Patch semantics apply
• Validation happens before the mutation is queued

This endpoint is typically used to:

• Correct dates or summaries
• Add notes after the fact
• Adjust interaction metadata

Deleting interactions

Use DELETE /candidates/{id}/interactions/{interactionId} to remove an interaction.

DELETE /candidates/{id}/interactions/{interactionId}

Deleting an interaction permanently removes the interaction record from the candidate’s history.

Mutation Engine responses

All interaction mutations return a 202 Accepted response.

What a 202 response means

A successful submission returns a 202 Accepted response, indicating that:

• The request was validated successfully
• The mutation was accepted and queued
• Processing will happen asynchronously

{
    "statusCode": 202,
    "message": "The mutation request has been accepted for processing.",
    "data": {
        "status": "accepted",
        "idempotencyKey": "a_unique_key_generated_for_this_request_12345",
        "message": "The mutation request has been accepted for processing."
    },
    "meta": {
        "sandboxEnabled": false
    }
}

Important implications

• A 202 response is not confirmation that the candidate exists yet
• Treat the response as an acknowledgement, not a result
• Use idempotencyKey to safely retry requests
• Use callbackUrl to receive completion or failure notifications

Design your integration to be event-driven, not synchronous

Test interaction flows in the sandbox

All interaction endpoints support sandbox mode via:

• The x-api-sandbox: true header, or
• The /sandbox endpoint prefix

This allows you to test interaction flows without affecting production data.