RErecruitwithatlas
Contracts

Get contract details

Changed on

Use this endpoint to retrieve the full details of a single contract by its ID.

A contract represents an ongoing engagement where a contractor works for a client company on a project — the agency invoices the client (the payor side) and pays the contractor or their umbrella/limited company (the payee side). Contracts progress through statuses: draft, scheduled, active, ended, terminated, and cancelled.

Each contract carries its rates (charge/pay rates with a single base rate), contacts (people linked to the contract such as line managers or timesheet approvers), attributions (how the contract's revenue is credited to agency users, each with an optional earner role), and allowances (billable expenses such as travel or accommodation).

All monetary amounts are returned as decimal strings to preserve precision, denominated in the agency base currency unless a currency field says otherwise. durationDays, revenue, and grossMarginPercent are derived from the stored schedule and base rate.

Contract placement financials: This endpoint is the source of the fields a contract engagement needs that GET /api/v1/placements does not carry: the engagement end date is endDate, and the bill/charge rate and pay rate are chargeRate and payRate on the entry in rates[] where isBase is true (exactly one rate per contract is the base rate). unit on that rate says what the amounts are per (hourly, daily, weekly, monthly, project).

What you need to provide:

  • The contract's ID in the URL path

What you get back: The contract record with its rates, contacts, attributions, and allowances. clientCompany, project, contractor and owner are always present, including when the referenced record has itself been deleted in Atlas — you will still receive its id and name so you can reconcile against your own copy.

get/api/v1/contracts/{id}

Request

Path parameters

idstring uuid required

Contract ID

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

Response

Contract details

status'ok' required

Example response

{
  "data": {
    "status": "active",
    "owner": {
      "email": "jordan@agency.com",
      "name": "Jordan Smith"
    },
    "createdBy": {
      "email": "jordan@agency.com",
      "name": "Jordan Smith"
    },
    "approvedBy": {
      "email": "jordan@agency.com",
      "name": "Jordan Smith"
    },
    "clientCompany": {
      "name": "Bullhorn Inc"
    },
    "companyLocation": {
      "name": "London HQ"
    },
    "project": {
      "jobRole": "Software Developer"
    },
    "contractor": {
      "firstName": "Eveling",
      "lastName": "Garcia",
      "email": "eveling@example.com"
    },
    "contractTypes": [
      {
        "name": "Employer of Record"
      }
    ],
    "assignment": "ABC Phase 1",
    "purchaseOrderNumber": "PO-2026-0042",
    "startDate": "2026-04-01",
    "endDate": "2026-06-30",
    "daysPerWeek": 5,
    "hoursPerDay": 8,
    "fixedDays": [
      "Monday",
      "Tuesday",
      "Wednesday"
    ],
    "durationDays": 90,
    "extendedBy": {
      "email": "jordan@agency.com",
      "name": "Jordan Smith"
    },
    "payor": "project_company",
    "payorCompany": {
      "name": "Bullhorn Inc"
    },
    "payorInvoiceFrequency": "monthly",
    "payee": "contractor_company",
    "payeeCompany": {
      "name": "Bullhorn Inc"
    },
    "payeeContractorCompany": {
      "entityName": "Garcia Consulting Ltd",
      "registrationNumber": "12345678"
    },
    "payeePayInvoiceFrequency": "monthly",
    "terminationActionedBy": {
      "email": "jordan@agency.com",
      "name": "Jordan Smith"
    },
    "terminationReason": {
      "name": "Employer of Record"
    },
    "weeklyRevenue": "4000.00",
    "weeklyGp": "800.00",
    "monthlyRevenue": "17333.33",
    "monthlyGp": "3466.67",
    "revenue": "52000.00",
    "grossMarginPercent": "20.00",
    "rates": [
      {
        "rateType": {
          "name": "Employer of Record"
        },
        "unit": "daily",
        "chargeRate": "800.00",
        "chargeCurrency": "GBP",
        "payRate": "640.00",
        "payCurrency": "GBP",
        "baseCurrency": "GBP",
        "baseChargeRate": "800.00",
        "basePayRate": "640.00",
        "marginPercent": "20.00"
      }
    ],
    "contacts": [
      {
        "person": {
          "firstName": "Eveling",
          "lastName": "Garcia",
          "email": "eveling@example.com"
        },
        "role": {
          "name": "Employer of Record"
        }
      }
    ],
    "attributions": [
      {
        "feeEarner": {
          "name": "Jane Smith",
          "email": "jane@agency.com"
        },
        "feeType": {
          "name": "Recruiter"
        },
        "share": "100.00"
      }
    ],
    "allowances": [
      {
        "allowanceType": "travel",
        "amount": "50.00",
        "currency": "GBP",
        "unit": "per_day",
        "capAmount": "500.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

    • 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

  • cd4bc8bbd95eRevision changes
    • info

      added the optional property to the response with the status