Tutorial: Add a New Position to an Inquiry

This tutorial guides you through the workflow for adding a new position (hire) to an existing inquiry using the public API layer in People Cloud.

This public endpoint is internally routed to the original authenticated People Cloud logic, ensuring that email notifications, validations, and business rules behave exactly like the internal platform.

---

Step 1: Make a POST Request for New Position

Send a POST request to the following public API endpoint:

POST /api/public/inquiry/{orderId}/position/new

---

Authorization

This endpoint requires authentication. Use the Bearer token from the authenticated user session.

Request Headers

Authorization: Bearer <your_token_here>
Accept: application/json
Content-Type: application/json

---

Request Body Structure

Below is a breakdown of the fields required to create a new position:

• stage: Must be "searching" for a newly created position.
• title: Name of the job role.
• type: "external" or "internal".
• experience_level: General competency level (e.g., "Intermediate").
• order_need_reqs: Array of skill requirements, each containing:
• name: Skill name (e.g., "programming").
• importance: Importance (1–5).
• language_reqs: Languages required for the role.
• is_remote_work: "yes", "no", or "partly".
• location: Job location text (optional).
• allocation: Allocation percentage (string).
• budget: Budget per month (string).
• files: Array of uploaded file references (optional).
• is_video_required: Boolean. 0 for no and 1 for yes.
• job_start: Start date of the contract (ISO format).
• job_end: End date of the contract (ISO format).

---

Example

JSON

{
  "stage": "searching",
  "title": "Cloud Engineer",
  "type": "external",
  "experience_level": "Intermediate",
  "order_need_reqs": [
    { "name": "programming", "importance": 3 }
  ],
  "language_reqs": "English",
  "is_remote_work": "no",
  "location": "Remote",
  "allocation": "10",
  "budget": "5000",
  "cv_deadline": "",
  "files": [],
  "is_video_required": 0,
  "job_start": "2025-11-01 16:30:00",
  "job_end": "2025-11-30 16:00:00"
}

---

Step 2: Add New Position

Once you're ready, the draft new position can be published using this endpoint.

cURL

curl -X POST http://127.0.0.1:8000/api/public/inquiry/1/position/new   -H "Authorization: Bearer $TOKEN"   -H "Accept: application/json"   -H "Content-Type: application/json"   -d '{
    "stage": "searching",
    "title": "Cloud Engineer",
    "type": "external",
    "experience_level": "Intermediate",
    "order_need_reqs": [
      {
        "name": "programming",
        "importance": 3
      }
    ],
    "language_reqs": "English",
    "is_remote_work": "no",
    "location": "Remote", 
    "allocation": "10",
    "budget": "5000",
    "cv_deadline": "",
    "files": [],
    "is_video_required": 1,
    "job_start": "2025-11-01 16:30:00",
    "job_end": "2025-11-30 16:00:00"
  }'

---

Step 3: Evaluate response

If everything goes well, you should get an HTTP response with an JSON message ({ "message": "New position successfully added" }) in the response body.

Status	Meaning	Description
200	OK	Position added successfully
401	Unauthorized	The API token is invalid.
404	Not Found	Inquiry does not exist.
422	Validation error	One or more fields are invalid.