openapi: 3.1.0
info:
  title: LinkedIn Job Posting API
  description: >-
    LinkedIn's Job Posting API enables authorized third parties such as clients,
    ATS systems, and Job Distributors to post jobs directly to LinkedIn on behalf
    of customers.

    This API supports two job categories:

    - **Basic Jobs**: Free job posts gathered by LinkedIn from external sources
    - **Promoted Jobs**: Paid job postings with enhanced visibility

    The use of these APIs is restricted to developers approved by LinkedIn.
    Please reach out to your LinkedIn Relationship Manager or Business Development
    contact for access.

    For more information, refer to the
    [Job Posting Overview](https://docs.microsoft.com/en-us/linkedin/talent/job-postings/job-posting-overview).
  version: 1.0.0
  contact:
    name: LinkedIn Talent Solutions
    url: https://business.linkedin.com/talent-solutions

servers:
- url: https://api.linkedin.com
  description: LinkedIn Production API Server

tags:
- name: Apply Connect Jobs
  description: APIs for creating and managing Apply Connect enabled job postings
- name: Job Lifecycle Management
  description: APIs for managing the lifecycle of job postings
- name: Customer Integrations
  description: APIs for managing customer ATS integrations for premium job posting

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 Bearer Token authentication

    OAuth2Auth:
      type: oauth2
      description: OAuth 2.0 authentication
      flows:
        clientCredentials:
          tokenUrl: https://www.linkedin.com/oauth/v2/accessToken
          scopes:
            w_organization_social: Write organization social content

  schemas:
    SimpleJobPostingRequest:
      type: object
      description: Request body for creating or updating job postings
      required:
      - elements
      properties:
        elements:
          type: array
          items:
            $ref: '#/components/schemas/JobPostingElement'

    JobPostingElement:
      type: object
      description: Individual job posting element
      required:
      - externalJobPostingId
      - title
      - description
      - integrationContext
      - listingType
      - location
      properties:
        externalJobPostingId:
          type: string
          description: External identifier for the job posting
          example: "JOB-2024-001"
        title:
          type: string
          description: Job title
          example: "Software Developer in Test"
        description:
          type: string
          description: Full job description
          example: "We are looking for a talented Software Developer in Test to join our engineering team..."
        integrationContext:
          type: string
          description: Organization URN for the job posting
          example: "urn:li:organization:12345678"
        jobPostingOperationType:
          type: string
          description: Operation type for the job posting
          enum:
          - CREATE
          - UPDATE
          - CLOSE
          example: "CREATE"
        listingType:
          type: string
          description: Type of job listing
          enum:
          - BASIC
          - PREMIUM
          example: "BASIC"
        listedAt:
          type: integer
          format: int64
          description: Timestamp when the job was listed
          example: 1702693664000
        location:
          type: string
          description: Job location
          example: "San Francisco, CA"
        companyApplyUrl:
          type: string
          format: uri
          description: URL for company's application page
          example: "https://company.com/careers/apply"
        onsiteApplyConfiguration:
          $ref: '#/components/schemas/OnsiteApplyConfiguration'

    OnsiteApplyConfiguration:
      type: object
      description: Configuration for onsite application collection
      properties:
        jobApplicationWebhookUrl:
          type: string
          format: uri
          description: Webhook URL for receiving job applications
          example: "https://ats.company.com/webhooks/linkedin-applications"
        questions:
          $ref: '#/components/schemas/ApplicationQuestions'

    ApplicationQuestions:
      type: object
      description: Questions configuration for job applications
      properties:
        resumeQuestions:
          $ref: '#/components/schemas/ResumeQuestions'
        coverLetterQuestions:
          $ref: '#/components/schemas/CoverLetterQuestions'
        voluntarySelfIdentificationQuestions:
          type: object
          description: Voluntary self-identification questions
        educationQuestions:
          $ref: '#/components/schemas/EducationQuestions'
        workQuestions:
          $ref: '#/components/schemas/WorkQuestions'
        additionalQuestions:
          $ref: '#/components/schemas/AdditionalQuestions'

    ResumeQuestions:
      type: object
      properties:
        resumeQuestionRequirement:
          type: string
          enum:
          - REQUIRED
          - OPTIONAL
          - NOT_AVAILABLE
          example: "REQUIRED"

    CoverLetterQuestions:
      type: object
      properties:
        coverLetterQuestionRequirement:
          type: string
          enum:
          - REQUIRED
          - OPTIONAL
          - NOT_AVAILABLE
          example: "OPTIONAL"

    EducationQuestions:
      type: object
      properties:
        educationExperienceQuestionSet:
          type: object

    WorkQuestions:
      type: object
      properties:
        workExperienceQuestionSet:
          type: object

    AdditionalQuestions:
      type: object
      properties:
        customQuestionSets:
          type: array
          items:
            $ref: '#/components/schemas/CustomQuestionSet'

    CustomQuestionSet:
      type: object
      properties:
        questionSetId:
          type: string
          example: "custom-questions-001"
        questions:
          type: array
          items:
            $ref: '#/components/schemas/CustomQuestion'

    CustomQuestion:
      type: object
      properties:
        required:
          type: boolean
          example: true
        partnerQuestionIdentifier:
          type: string
          example: "question-001"
        questionText:
          type: string
          example: "Are you authorized to work in the United States?"
        questionDetails:
          $ref: '#/components/schemas/QuestionDetails'

    QuestionDetails:
      type: object
      properties:
        multipleChoiceQuestionDetails:
          $ref: '#/components/schemas/MultipleChoiceQuestionDetails'

    MultipleChoiceQuestionDetails:
      type: object
      properties:
        choices:
          type: array
          items:
            $ref: '#/components/schemas/QuestionChoice'
        selectMultiple:
          type: boolean
          example: false
        preferredFormComponent:
          type: string
          enum:
          - RADIO_BUTTONS
          - DROPDOWN
          - CHECKBOXES
          example: "RADIO_BUTTONS"

    QuestionChoice:
      type: object
      properties:
        symbolicName:
          type: string
          example: "yes"
        displayValue:
          type: string
          example: "Yes"

    JobPostingResponse:
      type: object
      description: Response from job posting creation
      properties:
        elements:
          type: array
          items:
            $ref: '#/components/schemas/JobPostingResult'

    JobPostingResult:
      type: object
      properties:
        status:
          type: string
          example: "ACCEPTED"
        taskUrn:
          type: string
          description: URN of the task to track posting status
          example: "urn:li:simpleJobPostingTask:12345678"

    JobPostingTaskResponse:
      type: object
      description: Response for job posting task status
      properties:
        results:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/JobPostingTaskResult'

    JobPostingTaskResult:
      type: object
      properties:
        status:
          type: string
          enum:
          - PENDING
          - SUCCEEDED
          - FAILED
          example: "SUCCEEDED"
        jobPostingUrn:
          type: string
          description: URN of the created job posting
          example: "urn:li:jobPosting:2722131308"
        errorMessage:
          type: string
          description: Error message if task failed

          example: example_value
    AtsIntegrationUpdateRequest:
      type: object
      description: Request body for updating ATS integrations
      properties:
        entities:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/AtsIntegrationPatch'

    AtsIntegrationPatch:
      type: object
      properties:
        patch:
          type: object
          properties:
            $set:
              type: object
              properties:
                integrationName:
                  type: string
                  example: "Customer Name - LinkedIn LTS Premium Job Posting Integration"

    AtsIntegrationResponse:
      type: object
      description: Response for ATS integration details
      properties:
        results:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/AtsIntegrationDetail'

    AtsIntegrationDetail:
      type: object
      properties:
        integrationContext:
          type: string
          example: "urn:li:contract:12345"
        integrationType:
          type: string
          example: "PREMIUM_JOB_POSTING"
        integrationName:
          type: string
          example: "Customer Name - LinkedIn LTS Premium Job Posting Integration"
        status:
          type: string
          example: "ENABLED"

    ErrorResponse:
      type: object
      properties:
        status:
          type: integer
          example: 400
        message:
          type: string
          example: "Invalid request parameters"
        serviceErrorCode:
          type: integer
          example: 100

  examples:
    SimpleJobPostingRequestExample:
      summary: Example Apply Connect job posting request
      value:
        elements:
        - externalJobPostingId: "JOB-2024-001"
          title: "Software Developer in Test"
          description: "We are looking for a talented Software Developer in Test to join our engineering team. You will be responsible for designing and implementing automated tests."
          integrationContext: "urn:li:organization:12345678"
          jobPostingOperationType: "CREATE"
          listingType: "BASIC"
          listedAt: 1702693664000
          location: "San Francisco, CA"
          companyApplyUrl: "https://company.com/careers/apply"
          onsiteApplyConfiguration:
            jobApplicationWebhookUrl: "https://ats.company.com/webhooks/linkedin"
            questions:
              resumeQuestions:
                resumeQuestionRequirement: "REQUIRED"
              coverLetterQuestions:
                coverLetterQuestionRequirement: "OPTIONAL"

    CloseJobPostingRequestExample:
      summary: Example request to close a job posting
      value:
        elements:
        - externalJobPostingId: "JOB-2024-001"
          title: "Software Developer in Test"
          description: "Position has been filled."
          integrationContext: "urn:li:organization:12345678"
          jobPostingOperationType: "CLOSE"
          listingType: "BASIC"
          listedAt: 1702693664000
          location: "San Francisco, CA"

    JobPostingResponseExample:
      summary: Example job posting response
      value:
        elements:
        - status: "ACCEPTED"
          taskUrn: "urn:li:simpleJobPostingTask:12345678"

    JobPostingTaskResponseExample:
      summary: Example job posting task status response
      value:
        results:
          "urn:li:simpleJobPostingTask:12345678":
            status: "SUCCEEDED"
            jobPostingUrn: "urn:li:jobPosting:2722131308"

    AtsIntegrationUpdateRequestExample:
      summary: Example ATS integration update request
      value:
        entities:
          "integrationContext=urn:li:contract:12345&integrationType=PREMIUM_JOB_POSTING&tenantType=JOBS&dataProvider=ATS":
            patch:
              $set:
                integrationName: "Customer Name - LinkedIn LTS Premium Job Posting Integration"

    AtsIntegrationResponseExample:
      summary: Example ATS integration response
      value:
        results:
          "integrationContext=urn:li:contract:12345&integrationType=PREMIUM_JOB_POSTING&tenantType=JOBS&dataProvider=ATS":
            integrationContext: "urn:li:contract:12345"
            integrationType: "PREMIUM_JOB_POSTING"
            integrationName: "Customer Name - LinkedIn LTS Premium Job Posting Integration"
            status: "ENABLED"

    ErrorResponseExample:
      summary: Example error response
      value:
        status: 400
        message: "Invalid request parameters"
        serviceErrorCode: 100

  parameters:
    RestliMethodHeader:
      name: x-restli-method
      in: header
      required: true
      description: Rest.li method for batch operations
      schema:
        type: string
      example: "batch_create"

    TaskIdsQuery:
      name: ids
      in: query
      required: true
      description: Task URN(s) to check status
      schema:
        type: string
      example: "urn:li:simpleJobPostingTask:12345678"

    IntegrationContextQuery:
      name: ids[0].integrationContext
      in: query
      required: true
      description: Integration context URN
      schema:
        type: string
      example: "urn:li:contract:12345"

    IntegrationTypeQuery:
      name: ids[0].integrationType
      in: query
      required: true
      description: Type of integration
      schema:
        type: string
      example: "PREMIUM_JOB_POSTING"

    TenantTypeQuery:
      name: ids[0].tenantType
      in: query
      required: true
      description: Tenant type for the integration
      schema:
        type: string
      example: "JOBS"

    DataProviderQuery:
      name: ids[0].dataProvider
      in: query
      required: true
      description: Data provider identifier
      schema:
        type: string
      example: "ATS"

security:
- OAuth2Auth: []

paths:
  /v2/simpleJobPostings:
    post:
      operationId: createOrUpdateJobPosting
      tags:
      - Apply Connect Jobs
      summary: LinkedIn Create or Update Apply Connect Job Posting
      description: >-
        Creates a new Apply Connect enabled job posting or updates/closes an existing one.
        Use the `jobPostingOperationType` field to specify the operation:

        - `CREATE`: Create a new job posting
        - `UPDATE`: Update an existing job posting
        - `CLOSE`: Close an existing job posting

        For more information, refer to the
        [Apply Connect Jobs Lifecycle documentation](https://docs.microsoft.com/en-us/linkedin/talent/job-postings/api/sync-jobs-onsite-apply#apply-connect-jobs-lifecycle).
      x-microcks-operation:
        dispatcher: FALLBACK
        dispatcherRules: |
          {
            "dispatcher": "FALLBACK",
            "dispatcherRules": ""
          }
        delay: 100
      parameters:
      - $ref: '#/components/parameters/RestliMethodHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimpleJobPostingRequest'
            examples:
              CreateJobPosting:
                $ref: '#/components/examples/SimpleJobPostingRequestExample'
              CloseJobPosting:
                $ref: '#/components/examples/CloseJobPostingRequestExample'
      responses:
        '200':
          description: Job posting request accepted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobPostingResponse'
              examples:
                SuccessResponse:
                  $ref: '#/components/examples/JobPostingResponseExample'
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/ErrorResponseExample'
        '401':
          description: Unauthorized - invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v2/simpleJobPostingTasks:
    get:
      operationId: getJobPostingTaskStatus
      tags:
      - Job Lifecycle Management
      summary: LinkedIn Check Job Posting Task Status
      description: >-
        Retrieves the status of a job posting task to track whether the job has been
        successfully created, updated, or closed.

        After successful completion, the response includes the `jobPostingUrn` which
        can be used to view the job at: `https://www.linkedin.com/jobs/view/{jobPostingId}`

        For more information, refer to the
        [Check Job Task Status documentation](https://docs.microsoft.com/en-us/linkedin/talent/job-postings/api/check-job-taskstatus).
      x-microcks-operation:
        dispatcher: FALLBACK
        dispatcherRules: |
          {
            "dispatcher": "FALLBACK",
            "dispatcherRules": ""
          }
        delay: 100
      parameters:
      - $ref: '#/components/parameters/TaskIdsQuery'
      responses:
        '200':
          description: Successfully retrieved task status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobPostingTaskResponse'
              examples:
                SuccessResponse:
                  $ref: '#/components/examples/JobPostingTaskResponseExample'
        '400':
          description: Bad request - invalid task URN
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Task not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v2/atsIntegrations:
    post:
      operationId: updateCustomerIntegrations
      tags:
      - Customer Integrations
      summary: LinkedIn Update Customer ATS Integrations
      description: >-
        Updates customer ATS integrations for premium job posting capabilities.
        Partners use this endpoint to configure the integration name and other
        settings for their customers.
      x-microcks-operation:
        dispatcher: FALLBACK
        dispatcherRules: |
          {
            "dispatcher": "FALLBACK",
            "dispatcherRules": ""
          }
        delay: 100
      parameters:
      - $ref: '#/components/parameters/IntegrationContextQuery'
      - $ref: '#/components/parameters/IntegrationTypeQuery'
      - $ref: '#/components/parameters/TenantTypeQuery'
      - $ref: '#/components/parameters/DataProviderQuery'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AtsIntegrationUpdateRequest'
            examples:
              UpdateIntegration:
                $ref: '#/components/examples/AtsIntegrationUpdateRequestExample'
      responses:
        '200':
          description: Successfully updated the integration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtsIntegrationResponse'
              examples:
                SuccessResponse:
                  $ref: '#/components/examples/AtsIntegrationResponseExample'
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    get:
      operationId: getCustomerIntegrations
      tags:
      - Customer Integrations
      summary: LinkedIn Get Customer ATS Integration Details
      description: >-
        Retrieves the details of a customer's ATS integration for premium job posting.
        Use this endpoint to verify integration configuration and status.
      x-microcks-operation:
        dispatcher: FALLBACK
        dispatcherRules: |
          {
            "dispatcher": "FALLBACK",
            "dispatcherRules": ""
          }
        delay: 100
      parameters:
      - $ref: '#/components/parameters/IntegrationContextQuery'
      - $ref: '#/components/parameters/IntegrationTypeQuery'
      - $ref: '#/components/parameters/TenantTypeQuery'
      - $ref: '#/components/parameters/DataProviderQuery'
      responses:
        '200':
          description: Successfully retrieved integration details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtsIntegrationResponse'
              examples:
                SuccessResponse:
                  $ref: '#/components/examples/AtsIntegrationResponseExample'
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Integration not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'