RErecruitwithatlas
Projects

Create a project

Changed on

Use this endpoint to create a new project (job, job lead, or talent pool) in your Atlas account.

Project types:

  • job — an active recruitment assignment for a confirmed role at a client company. Maps to project state active.
  • job_lead — a potential opportunity that is not yet confirmed. Maps to project state lead. Optionally link to an existing opportunity via opportunityId.
  • talent_pool — a pipeline of candidates not tied to a specific role. Maps to project state talent_pool. Does not require a companyId.

Required fields:

  • projectType, jobRole, ownerEmail (and companyId for job and job_lead).

Validation rules:

  • ownerEmail must resolve to an existing user within the agency.
  • companyId, when provided, must belong to the same agency.
  • opportunityId, when provided, must belong to the same agency.
  • memberEmails entries that don't match a user in the agency are silently skipped — only matching emails are added as members.
  • companyContactIds must be CompanyContact junction IDs (the person↔company link, retrievable from companyContact.id on GET /api/v1/people/{id}) belonging to the project's companyId — not person IDs.
  • customAttributes[].customAttributeId must reference a project-scoped custom attribute in the agency.

The owner is automatically added as a project member with the lead role; additional memberEmails are added as regular members.

post/api/v1/projects

Request

Request body

projectType'job' | 'job_lead' | 'talent_pool' required

Type of project: job, job_lead, talent_pool

jobRolestring required

Job title or role name

companyIdstring uuid nullable

Company this project belongs to. Required for job and job_lead

ownerEmailstring email required

Email of the project owner. Must be an existing, active user in the agency

jobDescriptionstring nullable

Plain text job description

jobNumberstring nullable

Job reference number. Must be non-empty when supplied; omit to auto-generate.

contractType'full_time' | 'part_time' | 'contract' | 'non_exec' | 'null' nullable

Contract type

workMode'office' | 'hybrid' | 'remote' | 'null' nullable

Work mode

seniority'partner' | 'board' | 'founder' | 'cxo' | 'vp' | 'director' | 'manager' | 'senior' | 'middle' | 'junior' | 'training' | 'unpaid' | 'null' nullable

Seniority level

funcstring nullable

Job function (e.g. Engineering, Sales). Empty strings are rejected — omit or send null to clear.

sourceUrlstring nullable

URL where this project was sourced from

skillsstring[] nullable

List of required skills. Duplicate entries are silently dropped.

hireTargetinteger

Number of positions to fill

visaSupportboolean nullable

Whether visa sponsorship is offered

publicboolean

Whether the project is publicly visible

feeTermsstring nullable

Fee terms description

notesstring nullable

Internal notes

startedAtstring nullable

Planned or actual start date (YYYY-MM-DD). Must be no earlier than one calendar month ago. Stored as UTC midnight of that calendar day.

memberEmailsstring[]

Emails of team members to add. Must be existing users in the agency. Duplicate entries are silently dropped.

companyContactIdsstring[]

CompanyContact IDs to associate with the project — these are the person↔company link IDs, NOT person IDs. Retrieve a value from the companyContact.id field on GET /api/v1/people/{id}. Each must belong to the project's companyId; passing a person ID (or an ID from another company) returns 404. Duplicate entries are silently dropped.

opportunityIdstring uuid nullable

Opportunity to link this project to. Only allowed for job_lead

Example request

{
  "projectType": "job",
  "jobRole": "Senior Software Engineer",
  "ownerEmail": "owner@agency.com",
  "jobNumber": "ENG-2026-042",
  "seniority": "senior",
  "func": "Engineering",
  "sourceUrl": "https://example.com/jobs/senior-engineer",
  "skills": [
    "TypeScript",
    "React"
  ],
  "hireTarget": 1,
  "salary": {
    "value": "120000-150000",
    "currency": "USD"
  },
  "expectedFee": {
    "value": "25000.00",
    "currency": "USD"
  },
  "feeTerms": "20% of annual salary",
  "startedAt": "2026-04-01",
  "location": {
    "name": "London, UK",
    "locality": "London",
    "region": "England",
    "metro": "new york, new york",
    "country": "United Kingdom",
    "streetAddress": "123 Baker Street",
    "addressLine2": "Suite 200",
    "postalCode": "NW1 6XE",
    "raw": "123 Baker Street, London NW1 6XE, United Kingdom",
    "latitude": 51.523767,
    "longitude": -0.158519
  }
}

Response

Project created

status'ok' required

Changes

  • 158ee454751cRevision changes
    • info

      added the new undefined enum value to the request property

    • info

      added the new undefined enum value to the request property

    • info

      added the new undefined enum value to the request property

  • cd4bc8bbd95eRevision changes
    • info

      added the optional property to the response with the status