---
updatedAt: 2026-04-24T07:17:22.000Z
agentTools:
  projectIndex: https://apidocs.pearch.ai/llms.txt
---

# Index jobs

Accepts a JSON array of job objects, each with `job_id` and `job_description` fields, and adds them to a custom index. Each account can have a single custom index only. 
This endpoint is used in conjunction with `/v1/find_matching_jobs` endpoint. 
1. First you need to upsert jobs with [/v1/upsert_jobs](/reference/post_v1-upsert-jobs)
2. Then you can use [/v1/find_matching_jobs](/reference/post_v1-find-matching-jobs) to find jobs relevant to a profile.        

**Cost: 1 credit per job**

_Check out official [Python client](https://github.com/Pearch-ai/pearch-client)_


<Cards columns={2}>
  <Card title="PRICING" href="https://pearch.ai/pricing" icon="fa-money-bill" target="_blank">
    CHECK HOW OUR CREDIT SYSTEM WORKS
  </Card>

  <Card title="KNOWLEDGE BASE" href="https://pearch.ai/articles" icon="fa-book" target="_blank">
    Insights and Research from PEARCH AI team
  </Card>
</Cards>

<BookDemoButton label="Book a demo" sublabel="15 minutes • Calendly" size="lg" fullWidth={false} align="center" />

# OpenAPI definition

```json
{
  "openapi": "3.0.4",
  "info": {
    "title": "Pearch.AI API",
    "description": "Pearch.AI API. You need to pass API key as 'Authorization: Bearer <API_KEY>' header.",
    "version": "2.0"
  },
  "x-readme": {
    "explorer-enabled": true,
    "samples-languages": [
      "shell"
    ],
    "proxy-enabled": false
  },
  "servers": [
    {
      "url": "https://api.pearch.ai/",
      "description": "Main server"
    }
  ],
  "paths": {
    "/v1/upsert_jobs": {
      "post": {
        "operationId": "post_v1-upsert-jobs",
        "summary": "Index jobs",
        "tags": [
          "Jobs"
        ],
        "description": "Accepts a JSON array of job objects, each with `job_id` and `job_description` fields, and adds them to a custom index. Each account can have a single custom index only. \nThis endpoint is used in conjunction with `/v1/find_matching_jobs` endpoint. \n1. First you need to upsert jobs with [/v1/upsert_jobs](/reference/post_v1-upsert-jobs)\n2. Then you can use [/v1/find_matching_jobs](/reference/post_v1-find-matching-jobs) to find jobs relevant to a profile.        \n\n**Cost: 1 credit per job**\n\n_Check out official [Python client](https://github.com/Pearch-ai/pearch-client)_\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "jobs": {
                    "type": "array",
                    "description": "List of job objects to be upserted. **Cost: 1 credit per job**",
                    "items": {
                      "type": "object",
                      "properties": {
                        "job_id": {
                          "type": "string",
                          "description": "Unique identifier for the job. This is used to match jobs in consecutive calls to /v1/upsert_jobs.",
                          "example": "job-1234"
                        },
                        "job_description": {
                          "type": "string",
                          "description": "Free form description of the job. This can be full JD or a shorter description.",
                          "example": "Machine Learning Engineer for an AI startup with leadership skills"
                        }
                      },
                      "required": [
                        "job_id",
                        "job_description"
                      ]
                    }
                  },
                  "replace": {
                    "type": "boolean",
                    "description": "* If `\"replace\"` is true, all existing jobs will be replaced with the provided list. This means for example that if a job with existing `job_id` \"job-1234\" already exists, but it is not provided in the request, then it will be removed from the index. \n* If `\"replace\"` is false or omitted, jobs are upserted (added or updated only).\n",
                    "example": false
                  }
                },
                "required": [
                  "jobs"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Jobs accepted and processed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "uuid": {
                      "type": "string",
                      "description": "Unique identifier for the query.",
                      "example": "ec191bf9-99ff-4989-8383-c97c71fafb6d"
                    },
                    "status": {
                      "type": "string",
                      "example": "success"
                    },
                    "processed_count": {
                      "type": "integer",
                      "example": 10
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid job data"
          },
          "401": {
            "description": "Invalid API key"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ]
}
```