> ## Documentation Index
> Fetch the complete documentation index at: https://docs.collective.work/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Job

> Create a new job posting



## OpenAPI

````yaml POST /job
openapi: 3.0.1
info:
  title: Collective Work Job API
  description: API for managing job postings on the Collective Work platform
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.collective.work/{environment}/v1
    description: Collective Work API server
    variables:
      environment:
        default: sandbox
        description: API environment
        enum:
          - sandbox
          - production
security:
  - bearerAuth: []
paths:
  /job:
    post:
      description: Create a new job posting
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewJobInput'
      responses:
        '201':
          description: Job successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '400':
          description: >-
            Invalid input data, or the organization reached its monthly job
            limit, with the message `JOBS_QUOTA_EXCEEDED`. Contact
            support@collective.work to raise the limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: >-
            Missing or invalid API key, or organization without production API
            access. Use Authorization: Bearer <organization API key>.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
components:
  schemas:
    NewJobInput:
      type: object
      required:
        - description
      properties:
        accountEmail:
          type: string
          format: email
          description: >-
            Email of the account on Collective under which this job will be
            posted. If not specified, the first account found will be picked.

            **This field can only be set at creation.**
        internalJobId:
          type: string
          description: >-
            Your unique identifier for the job. This field can only be set at
            creation. Use it as the id when retrieving, updating, or closing the
            job. If omitted, responses return internalJobId as null. See [Job
            identifiers](/docs/jobs#understanding-the-job-identifiers).
          example: open-ai-fullstack-engineer-123
        contractType:
          type: string
          enum:
            - FREELANCE
            - PERMANENT_CONTRACT
          default: FREELANCE
          description: |-
            The contract type for the job

            Values should be one of `FREELANCE` or `PERMANENT_CONTRACT`.
          example: FREELANCE
        companyLogoUrl:
          type: string
          format: uri
          description: URL of the company logo
          example: https://openai.com/logo.png
        companyName:
          type: string
          description: >-
            Name of the company


            If not specified, we will default to the recruiter's account default
            company
          example: OpenAI.com
        title:
          type: string
          description: >-
            Job title


            If not specified, we will try to infer it


            Note: In sandbox, we add the `[Sandbox]` prefix to the job title to
            prevent mistakes
          example: Senior Fullstack Developer
        description:
          type: string
          description: >-
            Job description


            It can be plain text or HTML (we sanitise it to keep only basic
            tags)
          example: >-
            I am searching for a talented developer to join our team! The stack
            includes javascript, react, and nodejs.
        profileWanted:
          type: string
          description: >-
            Description of the ideal candidate profile - ⚠️ If you want your
            offer to perform and be multi posted well, we highly recommend
            filling this field.


            It can be plain text or HTML (we sanitise it to keep only basic
            tags)
          example: >-
            We are looking for a senior engineer with 5+ years of experience in
            distributed systems and a strong background in cloud infrastructure.
        isSalaryAccordingToProfile:
          type: boolean
          description: >-
            Whether the salary is open to negotiation and based on the candidate
            profile - ⚠️ We don't recommend setting this to `true` as jobs
            without salary perform way worse.


            When set to `true`, the salary/budget will be displayed as
            "According to profile" on the job posting, overriding any `budget`
            value specified.
        budget:
          type: string
          description: >-
            Salary for the position - ⚠️ If you want your offer to perform and
            be multi posted well, we highly recommend filling this field.


            If not specified, we will try to infer it or default to empty.


            Note: there is no need to set this field when
            `isSalaryAccordingToProfile` is `true`.
          example: 1250€/day or 80-100K€/year
        startingDate:
          type: string
          enum:
            - ASAP
            - IN_2_TO_4_WEEKS
            - IN_4_TO_8_WEEKS
            - IN_8_WEEKS_OR_MORE
          description: >-
            Start date for the position


            If not specified, we will try to infer it or default to
            `IN_2_TO_4_WEEKS`
          example: IN_2_TO_4_WEEKS
        expirationDate:
          type: string
          format: date
          description: >-
            Max date until which users can apply to the job


            Date should be in **"YYYY-MM-DD"** format.


            If not specified, we will try to infer it or default to "In 2 weeks
            from now".
          example: '2026-11-29'
        notifyByEmailForEveryApplication:
          type: boolean
          description: >-
            Controls whether the recruiter who posted the job will be notified
            by email for every application. Defaults to false.
          default: false
        requirePhoneNumber:
          type: boolean
          description: Whether phone number is required for application
          default: false
        requireResume:
          type: boolean
          description: >-
            Whether resume is required for application (deprecated - resume is
            always required now)
          default: true
          deprecated: true
        questions:
          type: array
          items:
            type: string
          maxItems: 4
          description: >-
            Questions asked to applicants. **This field can only be set at
            creation.**
          example:
            - What is your favorite programming language?
            - How much experience do you have in this industry?
        skills:
          type: array
          items:
            type: string
          description: >-
            Required skills for the position


            We will match it also with our skills database to improve the job
            visibility, which may result in skills being added or tweaked.
          example:
            - javascript
            - react
            - node.js
        workPreferences:
          type: string
          description: >-
            Work arrangement preferences (remote, hybrid, on-site)


            Values should be one of `ON_SITE` (no remote allowed at all),
            `HYBRID` (some remote allowed, but still ne to come onsite), or
            `REMOTE` (no need to come to the office).


            If not specified, we will try to infer it.
          example: ON_SITE
        location:
          type: string
          description: >-
            Job location. We **only accept a city** (no region, or country, and
            we don't accept multiple cities - create 2 different jobs for that).


            If not specified, we will try to infer it.


            This field is a string but will be automatically remapped to an
            exact location in the google maps API.
          example: San Francisco, CA
        language:
          type: string
          enum:
            - en
            - fr
          description: |-
            Language of the job posting

            Values should be one of `en` (English) or `fr` (French).

            If not specified, the language will be automatically detected.
          example: fr
    JobResponse:
      allOf:
        - $ref: '#/components/schemas/JobSummary'
        - type: object
          required:
            - description
            - profileWanted
            - questions
            - requirePhoneNumber
            - notifyByEmailForEveryApplication
          properties:
            description:
              type: string
              description: Job description (text or sanitized HTML)
              example: <p>We are looking for a full stack developer.</p>
              nullable: true
            profileWanted:
              type: string
              description: >-
                Description of the ideal candidate profile (text or sanitized
                HTML)
              example: <p>5 years of experience with TypeScript.</p>
              nullable: true
            questions:
              description: Questions for applicants, in display order
              example:
                - Why are you interested in this job?
              type: array
              items:
                type: string
            requirePhoneNumber:
              type: boolean
              description: Whether phone number is required for application
              example: false
            notifyByEmailForEveryApplication:
              type: boolean
              description: >-
                Whether the recruiter who posted the job is notified by email
                for every application
              example: false
    Error400:
      type: object
      required:
        - message
        - error
        - statusCode
      properties:
        message:
          type: array
          items:
            type: string
        statusCode:
          type: integer
          example: 400
        error:
          type: string
          example: Bad Request
    Error401:
      type: object
      required:
        - message
        - error
        - statusCode
      properties:
        message:
          type: string
          example: 'Invalid authorization header: Please provide a valid API key'
        statusCode:
          type: integer
          example: 401
        error:
          type: string
          example: Unauthorized
    Error500:
      type: object
      required:
        - message
        - error
        - statusCode
      properties:
        message:
          type: array
          items:
            type: string
          example:
            - Internal server error
        statusCode:
          type: integer
          example: 500
        error:
          type: string
          example: Internal Server Error
    JobSummary:
      type: object
      properties:
        jobId:
          type: string
          description: Unique identifier of the job posting generated by Collective.
          example: cm71yqftr00000ck0bpz3hpg1
        internalJobId:
          type: string
          description: Your job identifier, provided at creation, or null when not set.
          example: CLIENT-123
          nullable: true
        jobUrl:
          type: string
          description: >-
            Public URL of the job on Collective, in the form
            `https://www.collective.work/jobs/<language>/<slug>`.
          example: https://www.collective.work/jobs/en/full-stack-developer-paris-8rnv
          format: uri
        accountEmail:
          type: string
          description: Email of the recruiter who owns the job posting
          example: recruiter@example.com
          format: email
        status:
          type: string
          description: >-
            OPEN, PAUSED, or CLOSED. The list endpoint defaults to OPEN; use its
            status parameter to select other statuses. Expiration does not
            change the status; check isExpired.
          enum:
            - OPEN
            - CLOSED
            - PAUSED
          example: OPEN
        isExpired:
          type: boolean
          description: >-
            Whether the expiration date is set and has passed. Expiry does not
            change the status.
          example: false
        expirationDate:
          type: string
          description: Expiration date of the job posting
          example: '2026-11-30T22:00:00.000Z'
          format: date-time
          nullable: true
        closedAt:
          type: string
          description: Date the job was closed, or null if it has not been closed.
          example: null
          format: date-time
          nullable: true
        createdAt:
          format: date-time
          type: string
          description: Date the job was created
          example: '2026-10-22T09:30:00.000Z'
        title:
          type: string
          description: Job title
          example: Full Stack Developer
        companyName:
          type: string
          description: Name of the company
          example: Collective
          nullable: true
        companyLogoUrl:
          type: string
          description: URL of the company logo
          example: https://assets.collective.work/logos/collective.png
          nullable: true
        budget:
          type: string
          description: Daily rate or salary range for the position, or null when not set.
          example: 600-750€/day
          nullable: true
        isSalaryAccordingToProfile:
          type: boolean
          description: Whether the salary is determined based on the candidate profile
          example: false
        contractType:
          type: string
          description: The contract type for the job
          enum:
            - FREELANCE
            - PERMANENT_CONTRACT
          example: FREELANCE
        location:
          type: string
          description: Job location, as its full English name
          example: Paris, France
          nullable: true
        workPreferences:
          type: array
          description: >-
            Work arrangements accepted for the job. Responses return an array;
            creation and update accept a single string.
          example:
            - REMOTE
            - HYBRID
          items:
            type: string
            enum:
              - REMOTE
              - HYBRID
              - ON_SITE
        skills:
          description: Required skills for the position
          example:
            - TypeScript
            - React
          type: array
          items:
            type: string
        language:
          type: string
          description: >-
            Language of the job posting, such as en, fr, or es, or null when not
            set.
          example: en
          nullable: true
      required:
        - jobId
        - internalJobId
        - jobUrl
        - accountEmail
        - status
        - isExpired
        - expirationDate
        - closedAt
        - createdAt
        - title
        - companyName
        - companyLogoUrl
        - budget
        - isSalaryAccordingToProfile
        - contractType
        - location
        - workPreferences
        - skills
        - language
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Your organization API key, available in [Organisation
        settings](https://app.collective.work/recruiter/organization/api).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.