---
title: "Create a placement."
method: POST
path: "/api/external/placement-record/create"
tags: ["Placement APIs"]
---

# Create a placement.

`POST /api/external/placement-record/create`

**The below table describes the required input without any job engagement type**

| <h3>Params</h3>    | <h3>Data Type</h3> | <h3>Required</h3> |
| ------------------ | ------------------ | ----------------- |
| job                | object             | True              |
| prospect           | object             | True              |
| revenue            | object             | optional          |
| salary             | object             | optional          |
| revenue_split      | object             | optional          |
| contacts           | array              | optional          |
| billing_date       | date               | True              |
| bonus              | object             | optional          |
| job_start_date     | date               | optional          |
| note               | string             | optional          |
| user_id            | integer            | True              |
| custom_fields      | array              | optional          |

**Sample Payload**
```
{
    "user_id": 1 (Integer),
    "placements": [
        {
            "job": {
                "id": 6 (Integer)
            },
            "prospect": {
                "id": 30 (Integer)
            },
            "revenue": {
                "currency": "USD", (String, Currency code eg. USD, GBP)
                "number": 77688 (Integer)
            },
            "salary": {
                "currency": "USD", (String, Currency code eg. USD, GBP)
                "number": 77688 (Integer)
            },
            "revenue_split": [
                {
                    "user": {
                        "id": 1 (Integer)
                    },
                    "revenue": {
                        "number": 0, (Integer)
                        "pct": 12 (Integer)
                    }
                }
            ],
            "contacts": [
                {
                    "id": 32 (Integer)
                }
            ],
            "billing_date": "2023-03-8" (String),
            "bonus": {
                "currency": "USD", (String, Currency code eg. USD, GBP)
                "number": 77688 (Integer)
            },
            "job_start_date": "2023-02-14", (String)
            "note": "", (String)
            "custom_fields": [
                {
                    "id": 16,
                    "value": {"currency": "USD" (String, Currency code eg. USD, GBP), "number": 600000 (float)}
                },
                {
                    "id": 17,
                    "value": {"currency": "USD" (String), "number1": 600000 (Float), "number2": 800000 (Float)}
                },
                {
                    "id": 19,
                    "value": {"number1": 600000 (Float), "number2": 800000 (Float)}
                },
                {
                    "id": 20,
                    "value": ["choice1", "choice2"] (list of strings)
                },
                {
                    "id" : 33,
                    "value" : "Random" (String)
                },
                {
                    "id" : 99,
                    "value" : [{"type": "candidate", "id": 1}]
                },
                {
                    "id" : 34,
                    "value" : [{"user_id": 1}]
                }
            ]
        }
    ]
}
```

**The below table describes the required input based on job engagement type**

**1 : Job Type Contingent**

| <h3>Params</h3>    | <h3>Data Type</h3> | <h3>Required</h3> |
| ------------------ | ------------------ | ----------------- |
| job                | object             | True              |
| prospect           | object             | True              |
| revenue            | object             | optional          |
| salary             | object             | optional          |
| revenue_split      | object             | optional          |
| contacts           | array              | optional          |
| billing_date       | date               | True              |
| bonus              | object             | optional          |
| job_start_date     | date               | optional          |
| note               | string             | optional          |
| user_id            | integer            | True              |
| custom_fields      | array              | optional          |

**Sample Payload**
```
{
    "user_id": 1 (Integer),
    "placements": [
        {
            "job": {
                "id": 6 (Integer)
            },
            "prospect": {
                "id": 30 (Integer)
            },
            "revenue": {
                "currency": "USD", (String, Currency code eg. USD, GBP)
                "number": 77688 (Integer)
            },
            "salary": {
                "currency": "USD", (String, Currency code eg. USD, GBP)
                "number": 77688 (Integer)
            },
            "revenue_split": [
                {
                    "user": {
                        "id": 1 (Integer)
                    },
                    "revenue": {
                        "number": 0, (Integer)
                        "pct": 12 (Integer)
                    }
                }
            ],
            "contacts": [
                {
                    "id": 32 (Integer)
                }
            ],
            "billing_date": "2023-03-8" (String),
            "bonus": {
                "currency": "USD", (String, Currency code eg. USD, GBP)
                "number": 77688 (Integer)
            },
            "job_start_date": "2023-02-14", (String)
            "note": "", (String)
            "custom_fields": [
                {
                    "id": 16,
                    "value": {"currency": "USD" (String, Currency code eg. USD, GBP), "number": 600000 (float)}
                },
                {
                    "id": 17,
                    "value": {"currency": "USD" (String), "number1": 600000 (Float), "number2": 800000 (Float)}
                },
                {
                    "id": 19,
                    "value": {"number1": 600000 (Float), "number2": 800000 (Float)}
                },
                {
                    "id": 20,
                    "value": ["choice1", "choice2"] (list of strings)
                },
                {
                    "id" : 33,
                    "value" : "Random" (String)
                },
                {
                    "id" : 99,
                    "value" : [{"type": "candidate", "id": 1}]
                },
                {
                    "id" : 34,
                    "value" : [{"user_id": 1}]
                }
            ]
        }
    ]
}
```

**2 : Job Type Contract**

| <h3>Params</h3>    | <h3>Data Type</h3> | <h3>Required</h3> |
| ------------------ | ------------------ | ----------------- |
| job                | object             | True              |
| prospect           | object             | True              |
| revenue_split      | object             | optional          |
| contacts           | array              | optional          |
| contract_start_date| date               | optional          |
| contract_end_date  | date               | optional          |
| pay_rate           | date               | optional          |
| bill_rate          | date               | optional          |
| work_quantum       | date               | optional          |
| bonus              | object             | optional          |
| note               | string             | optional          |
| user_id            | integer            | True              |
| custom_fields      | array              | optional          |

**Sample Payload**<br>
* __Allowed bill rate frequency__
    1. hour
    2. day
    3. week
    4. month
* __Allowed pay rate frequency__
    1. hour
    2. day
    3. week
    4. month
* __Allowed work quantum frequency__
    1. day
    2. week
    3. month
* __Allowed work quantum unit__
    1. hour
    2. day
    3. week
```
{
    "user_id": 1 (Integer),
    "placements": [
        {
            "job": {
                "id": 6 (Integer)
            },
            "prospect": {
                "id": 30 (Integer)
            },
            "revenue_split": [
                {
                    "user": {
                        "id": 1 (Integer)
                    },
                    "revenue": {
                        "number": 0, (Integer)
                        "pct": 12 (Integer)
                    }
                }
            ],
            "contacts": [
                {
                    "id": 32 (Integer)
                }
            ],
            "contract_start_date": "2023-03-8" (String),
            "contract_end_date": "2023-03-8" (String),
            "pay_rate": {
                "currency": "USD", (String, Currency code eg. USD, GBP)
                "number": 77688 (Integer)
                "frequency": {
                    "name": "hour" (String)
                }
            },
            "bill_rate": {
                "currency": "USD", (String, Currency code eg. USD, GBP)
                "number": 77688 (Integer)
                "frequency": {
                    "name": "hour" (String)
                }
            },
            "work_quantum": {
                "number": 1 (Integer)
                "unit": {
                    "name": "hour" (String)
                },
                "frequency": {
                    "name": "day" (String)
                },
                "is_full_time": false (Boolean)
            },
            "bonus": {
                "currency": "USD", (String, Currency code eg. USD, GBP)
                "number": 77688 (Integer)
            },
            "note": "", (String)
            "custom_fields": [
                {
                    "id": 16,
                    "value": {"currency": "USD" (String, Currency code eg. USD, GBP), "number": 600000 (float)}
                },
                {
                    "id": 17,
                    "value": {"currency": "USD" (String), "number1": 600000 (Float), "number2": 800000 (Float)}
                },
                {
                    "id": 19,
                    "value": {"number1": 600000 (Float), "number2": 800000 (Float)}
                },
                {
                    "id": 20,
                    "value": ["choice1", "choice2"] (list of strings)
                },
                {
                    "id" : 33,
                    "value" : "Random" (String)
                },
                {
                    "id" : 99,
                    "value" : [{"type": "candidate", "id": 1}]
                },
                {
                    "id" : 34,
                    "value" : [{"user_id": 1}]
                }
            ]
        }
    ]
}
```

**3 : Job Type Retained**

| <h3>Params</h3>    | <h3>Data Type</h3> | <h3>Required</h3> |
| ------------------ | ------------------ | ----------------- |
| job                | object             | True              |
| prospect           | object             | True              |
| salary             | object             | optional          |
| revenue_split      | object             | optional          |
| contacts           | array              | optional          |
| billing_date       | date               | True              |
| bonus              | object             | optional          |
| job_start_date     | date               | optional          |
| success_fee        | object             | optional          |
| retainer           | object             | optional          |
| note               | string             | optional          |
| user_id            | integer            | True              |
| custom_fields      | array              | optional          |

**Sample Payload**<br>
* __Allowed retainer frequency__
    1. net
    2. hour
    3. day
    4. month

```
{
    "user_id": 1 (Integer),
    "placements": [
        {
            "job": {
                "id": 6 (Integer)
            },
            "prospect": {
                "id": 30 (Integer)
            },
            "salary": {
                "currency": "USD", (String, Currency code eg. USD, GBP)
                "number": 77688 (Integer)
            },
            "revenue_split": [
                {
                    "user": {
                        "id": 1 (Integer)
                    },
                    "revenue": {
                        "number": 0, (Integer)
                        "pct": 12 (Integer)
                    }
                }
            ],
            "contacts": [
                {
                    "id": 32 (Integer)
                }
            ],
            "billing_date": "2023-03-8" (String),
            "bonus": {
                "currency": "USD", (String, Currency code eg. USD, GBP)
                "number": 77688 (Integer)
            },
            "job_start_date": "2023-02-14", (String)
            "success_fee": {
                "currency": "USD", (String, Currency code eg. USD, GBP)
                "number": 77688 (Integer)
            },
            "retainer": {
                "currency": "USD", (String, Currency code eg. USD, GBP)
                "number": 77688 (Integer)
                "frequency": {
                    "name": "net" (String)
                }
            },
            "note": "", (String)
            "custom_fields": [
                {
                    "id": 16,
                    "value": {"currency": "USD" (String, Currency code eg. USD, GBP), "number": 600000 (float)}
                },
                {
                    "id": 17,
                    "value": {"currency": "USD" (String), "number1": 600000 (Float), "number2": 800000 (Float)}
                },
                {
                    "id": 19,
                    "value": {"number1": 600000 (Float), "number2": 800000 (Float)}
                },
                {
                    "id": 20,
                    "value": ["choice1", "choice2"] (list of strings)
                },
                {
                    "id" : 33,
                    "value" : "Random" (String)
                },
                {
                    "id" : 99,
                    "value" : [{"type": "candidate", "id": 1}]
                },
                {
                    "id" : 34,
                    "value" : [{"user_id": 1}]
                }
            ]
        }
    ]
}
```

**4 : Job Type Temporary**

| <h3>Params</h3>    | <h3>Data Type</h3> | <h3>Required</h3> |
| ------------------ | ------------------ | ----------------- |
| job                | object             | True              |
| prospect           | object             | True              |
| revenue_split      | object             | optional          |
| contacts           | array              | optional          |
| pay_rate           | date               | optional          |
| bill_rate          | date               | optional          |
| work_quantum       | date               | optional          |
| job_start_date     | date               | optional          |
| note               | string             | optional          |
| user_id            | integer            | True              |
| custom_fields      | array              | optional          |

**Sample Payload**
* __Allowed bill rate frequency__
    1. hour
    2. day
    3. week
    4. month
* __Allowed pay rate frequency__
    1. hour
    2. day
    3. week
    4. month
* __Allowed work quantum frequency__
    1. day
    2. week
    3. month
* __Allowed work quantum unit__
    1. hour
    2. day
    3. week
```
{
    "user_id": 1 (Integer),
    "placements": [
        {
            "job": {
                "id": 6 (Integer)
            },
            "prospect": {
                "id": 30 (Integer)
            },
            "revenue_split": [
                {
                    "user": {
                        "id": 1 (Integer)
                    },
                    "revenue": {
                        "number": 0, (Integer)
                        "pct": 12 (Integer)
                    }
                }
            ],
            "contacts": [
                {
                    "id": 32 (Integer)
                }
            ],
            "pay_rate": {
                "currency": "USD", (String, Currency code eg. USD, GBP)
                "number": 77688 (Integer)
                "frequency": {
                    "name": "hour" (String)
                }
            },
            "bill_rate": {
                "currency": "USD", (String, Currency code eg. USD, GBP)
                "number": 77688 (Integer)
                "frequency": {
                    "name": "hour" (String)
                }
            },
            "work_quantum": {
                "number": 1 (Integer)
                "unit": {
                    "name": "hour" (String)
                },
                "frequency": {
                    "name": "hour" (String)
                }
                "is_full_time": false (Boolean)
            },
            "job_start_date": "2023-02-14", (String)
            "note": "", (String)
            "custom_fields": [
                {
                    "id": 16,
                    "value": {"currency": "USD" (String, Currency code eg. USD, GBP), "number": 600000 (float)}
                },
                {
                    "id": 17,
                    "value": {"currency": "USD" (String), "number1": 600000 (Float), "number2": 800000 (Float)}
                },
                {
                    "id": 19,
                    "value": {"number1": 600000 (Float), "number2": 800000 (Float)}
                },
                {
                    "id": 20,
                    "value": ["choice1", "choice2"] (list of strings)
                },
                {
                    "id" : 33,
                    "value" : "Random" (String)
                },
                {
                    "id" : 99,
                    "value" : [{"type": "candidate", "id": 1}]
                },
                {
                    "id" : 34,
                    "value" : [{"user_id": 1}]
                }
            ]
        }
    ]
}
```

## Headers

- `RF-Api-Key` string, required
- `content-type` string

## Request body

- object
  - `placements` object[]
    - `bill_rate` object
      - `currency` string
      - `frequency` object
        - `name` string
      - `number` integer
    - `billing_date` unknown
    - `bonus` object
      - `currency` string
      - `number` integer
    - `contacts` object[]
      - `id` integer
    - `contract_end_date` unknown
    - `contract_start_date` unknown
    - `custom_fields` object[] — Please refer to doc above
      - `id` integer
      - `value` string
    - `job` object
      - `id` integer
    - `job_start_date` unknown
    - `note` integer
    - `pay_rate` object
      - `currency` string
      - `frequency` object
        - `name` string
      - `number` integer
    - `prospect` object
      - `id` integer
    - `revenue` object
      - `currency` string
      - `number` integer
    - `revenue_split` object[]
      - `revenue` object
        - `number` integer
        - `pct` integer
      - `user` object
        - `id` integer
    - `salary` object
      - `currency` string
      - `number` integer
    - `success_fee` object
      - `currency` string
      - `number` integer
    - `work_quantum` object
      - `frequency` object
        - `name` string
      - `is_full_time` boolean
      - `number` integer
      - `unit` object
        - `name` string
  - `user_id` unknown

## Response `200`

Auto generated using Swagger Inspector

- unknown

## Changes

- **2026-08-13** `febc104d89ff` — 1 breaking
  - the `header` request parameter `RF-Api-Key` became required

[Change history](https://skmtc.dev/recruiterflow/apis/recruiterflow-api-documentation/changes/api/external/placement-record/create/post.md)

---

[API](https://skmtc.dev/recruiterflow/apis/recruiterflow-api-documentation.md) · [All operations](https://skmtc.dev/recruiterflow/apis/recruiterflow-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/recruiterflow/recruiterflow-api-documentation/revisions/febc104d89ff/schema)