RErecruitwithatlas
Files

Attach files to entities

Changed on

Assigns one or more previously uploaded files (created via POST /api/v1/files) to one or more records. This is the second step of a two-step workflow: upload the binary first, then attach the returned file ID to a person, company, or project.

Each attachment group links every file in fileIds to every entity in entities (cartesian product), applying the same optional type and name overrides. A group with 3 files and 2 entities produces 6 results.

One link per entity type: a file holds a single link per entity type, so a group may contain at most one entity of each type (up to 3 entities: one person, one company, one project), and a file ID may appear in only one group. Requests that assign a file to two different entities of the same type return 422.

Skip vs replace: a combination whose link already points at the requested entity is returned as skipped; a link to a different entity of the same type is replaced; links of other entity types are untouched (partial assignment). When every combination in a group is skipped, the type and name overrides of that group are not applied.

CV processing: attaching a file with effective type resume to a person triggers CV enrichment of that person. brandedResume, passport, rightToWork, insurance, incorporation, and other are never parsed. Skipped combinations trigger no processing.

Only files uploaded via the API (source = api) can be attached. Files and entities belonging to a different agency return 404. entityType: "opportunity" is not supported in v1 and returns 422.

post/api/v1/files/attach

Request

Request body

Example request

{
  "attachments": [
    {
      "fileIds": [
        "550e8400-e29b-41d4-a716-446655440000"
      ],
      "entities": [
        {
          "entityType": "person",
          "entityId": "a1b2c3d4-e29b-41d4-a716-446655440000"
        }
      ],
      "type": "resume",
      "name": "John_Doe_Resume_2026.pdf"
    }
  ]
}

Response

Outcome for every file × entity combination

status'ok' required

Example response

{
  "data": {
    "results": [
      {
        "fileId": "550e8400-e29b-41d4-a716-446655440000",
        "entityType": "person",
        "entityId": "a1b2c3d4-e29b-41d4-a716-446655440000",
        "status": "attached",
        "reason": "File is already attached to this entity",
        "type": "resume",
        "name": "John_Doe_Resume_2026.pdf"
      }
    ]
  }
}

Changes