Uploading Attachments

Attachments are managed through dedicated endpoints and are intentionally separated from general candidate updates to prevent accidental data loss and to make file operations explicit.

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

What are attachments?

Attachments represent files linked to a candidate, such as:

• Curriculum vitae (CV)

• Certificates or diplomas

• Portfolios

• Supporting documents or images

Attachments are stored externally and linked to a candidate record. They are treated as append-only resources unless explicitly removed.

Attachment fields

Attachments are grouped into two distinct fields:

• curriculumVitae
  Files that represent the candidate’s CV.

• otherAttachments
  Any other supporting documents.

Each field has its own limits and must be managed explicitly.

Attachment lifecycle overview

Attachments can be:

• Added to an existing candidate

• Removed from a candidate

Attachments are not updated in place. To change a file, you must remove the existing attachment and upload a new one.

All attachment mutations are handled asynchronously by the Mutation Engine.

Adding attachments to a candidate

Use POST /candidates/{id}/attachments to upload and link attachments to an existing candidate.

POST /candidates/{id}/attachments

Characteristics:

• The candidate must already exist

• Existing attachments are preserved

• New attachments are appended

• An attachment payload can contain no more than 5 files per attachment field.

• At least one attachment field must be provided:

  • curriculumVitae

  • otherAttachments

This endpoint is ideal for:

• Uploading documents after initial candidate creation

• Adding missing files

• Incrementally enriching candidate records

Attachment payload formats

Each attachment can be provided in one of two ways.

Attachment via URL

Use this when the file is already publicly accessible.

• The API fetches and stores the file

• The URL must be reachable at request time

• Supports file size of up to 25MB

Attachment via base64 data

Use this when uploading files directly.

• Include base64-encoded data

• The value must include the full data URI prefix

• Support file size of up to 5MB

Both formats are validated against the same schema and limits.

Limits and constraints

• Maximum of 5 attachments per field

• Filenames must be provided

• Attachments are immutable once stored

• Payloads are validated before the mutation is queued

• Not all mime types are accepted

Removing attachments

Use DELETE /candidates/{id}/attachments to remove one or more attachments from a candidate.

DELETE /candidates/{id}/attachments

Characteristics:

• Attachments are removed by attachment ID

• At least one attachment must be specified

• Removal is permanent and cannot be undone

Inline attachments during candidate creation

Attachments can also be provided inline when creating a candidate via POST /candidates.

This allows you to:

• Create a fully populated candidate in a single request

• Avoid follow-up attachment uploads for initial submissions

Mutation Engine responses

All attachment operations 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

Attachment endpoints support sandbox mode via:

• The x-api-sandbox: true header, or

• The /sandbox endpoint prefix

This allows you to safely test upload and removal flows without affecting production data.