RErecruitwithatlas
Placements

Get placement details

Changed on

Use this endpoint to retrieve the full details of a single placement by its ID, including all linked fees and their splits.

This is the endpoint to use when you already know which placement you want — for example, after finding it via the List placements endpoint. It returns everything Atlas knows about the placement in one response.

What you need to provide: Just the placement's ID in the URL path (e.g. /api/v1/placements/abc-123). Placement IDs are UUIDs returned by the List placements endpoint.

What you get back:

  • Placement core fields — type, start date, salary information
  • approvalStatus — pending (approval required, not yet given), approved (approval required and given), or null (the placement does not need approval)
  • owner — the top-level placement owner (id, name, email), mapped from the candidate owner. This is the primary recruiter attribution field for counting placements per recruiter and for "my placements" filtering
  • Candidate context — candidate name, current role, current company
  • Nested owners — candidate.owner (the candidate-record owner) and project.owner (the job owner) are retained as secondary context; project.owner is job/client context, not the placement-count attribution
  • Fees — every fee linked to this placement, each one including its amount in both the fee currency and the agency default currency, status, and timestamps for paid/invoiced events
  • Splits — for each fee, the breakdown of how it is split between fee earners (consultants), including their share, name, and email. Fee earners are finance/commission attribution only — not placement-count attribution
get/api/v1/placements/{id}

Request

Path parameters

idstring uuid required

Placement ID

Example:550e8400-e29b-41d4-a716-446655440000

Response

Placement details with fees and splits

status'ok' required

Example response

{
  "data": {
    "type": "permanent",
    "salary": {
      "value": "15000",
      "currency": "GBP"
    },
    "bonus": "5000",
    "commissionRate": "20",
    "approvalStatus": "pending",
    "owner": {
      "name": "Jane Smith",
      "email": "jane@agency.com"
    },
    "candidate": {
      "name": "John Doe",
      "role": "Senior Software Engineer",
      "company": "Acme Corp",
      "owner": {
        "name": "Jane Smith"
      }
    },
    "project": {
      "owner": {
        "name": "Jane Smith"
      }
    },
    "client": {
      "company": {
        "name": "Acme Corp"
      },
      "companyContact": {
        "name": "Bob Client"
      }
    },
    "fees": [
      {
        "feeType": {
          "name": "Placement Fee"
        },
        "feeDate": "2025-06-15",
        "amount": {
          "value": "15000",
          "currency": "GBP"
        },
        "amountInAgencyCurrency": {
          "value": "15000",
          "currency": "GBP"
        },
        "projectFeeStatus": "earned",
        "createdBy": {
          "name": "Jane Smith"
        },
        "splits": [
          {
            "feeEarner": {
              "name": "Jane Smith",
              "email": "jane@agency.com"
            },
            "feeType": {
              "name": "Placement Fee"
            },
            "share": "60.00"
          }
        ]
      }
    ]
  }
}

Changes

  • 158ee454751cRevision changes
    • warning

      added the new undefined enum value to the / response property for the response status

    • warning

      added the new undefined enum value to the /// response property for the response status

    • warning

      added the new undefined enum value to the / response property for the response status

  • b7e1215476a1Revision changes
    • info

      added the required property / to the response with the status