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.

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

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.

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

Sandbox support

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.