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

# Create job source

> Add a tracked source URL to a job. Idempotent on (job_id, source_name).

Create a new source link for a job. Each source produces a unique URL that can be shared on a specific platform (LinkedIn post, internal referral page, Indeed listing, etc.) — visits to that URL are tracked separately, so you can attribute applicants back to the source they came from.

The endpoint is **idempotent on `(job_id, source_name)`**: posting twice with the same job and source name returns the existing source link instead of erroring or creating a duplicate.

## Authentication

<ResponseField name="Authorization" type="string" required>
  Bearer authentication header of the form `Bearer <token>`.
</ResponseField>

## Request Body

<ParamField body="job_id" type="string" required>
  The job UUID to attach the source to. The job must belong to your workspace.
</ParamField>

<ParamField body="source_name" type="string" required>
  Human-readable label for the source. Free-form — common values: `LinkedIn`, `Indeed`, `Referral`, `Careers Page`, `Twitter`. Trimmed to remove leading/trailing whitespace.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --location --request POST 'https://api.hirempire.com/v1/create-source' \
  --header 'Authorization: Bearer sk-••••••••••••' \
  --header 'Content-Type: application/json' \
  --data '{
    "job_id": "8fc4ea3c-ecc4-4a92-96fd-a14436a79a1b",
    "source_name": "LinkedIn"
  }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.hirempire.com/v1/create-source', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk-••••••••••••',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      job_id: '8fc4ea3c-ecc4-4a92-96fd-a14436a79a1b',
      source_name: 'LinkedIn'
    })
  });
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests
  response = requests.post(
    'https://api.hirempire.com/v1/create-source',
    headers={
      'Authorization': 'Bearer sk-••••••••••••',
      'Content-Type': 'application/json'
    },
    json={'job_id': '...', 'source_name': 'LinkedIn'}
  )
  print(response.json())
  ```
</RequestExample>

## Response

<ResponseField name="success" type="boolean" />

<ResponseField name="source" type="object">
  The created (or existing, if idempotent hit) source link.

  <Expandable title="Source object properties">
    <ResponseField name="id" type="string" />

    <ResponseField name="job_id" type="string" />

    <ResponseField name="source_name" type="string" />

    <ResponseField name="source_url" type="string">Publicly shareable URL. Visits increment the `visits` counter.</ResponseField>
    <ResponseField name="code" type="string">Internal opaque code.</ResponseField>

    <ResponseField name="visits" type="integer" />

    <ResponseField name="created_at" type="string">ISO 8601 timestamp.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "source": {
      "id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
      "job_id": "8fc4ea3c-ecc4-4a92-96fd-a14436a79a1b",
      "source_name": "LinkedIn",
      "source_url": "https://jobs.hirempire.com/acme/1a2b3c4d-5e6f-7890-abcd-ef1234567890",
      "code": "a3f9",
      "visits": 0,
      "created_at": "2026-06-27T10:00:00.000Z"
    }
  }
  ```
</ResponseExample>

## Error Responses

### 400 Bad Request

```json theme={null}
{ "success": false, "error": "job_id is required and must be a UUID" }
```

```json theme={null}
{ "success": false, "error": "source_name is required and must be a non-empty string" }
```

### 401 Unauthorized

```json theme={null}
{ "success": false, "error": "Invalid token" }
```

### 404 Not Found

```json theme={null}
{ "success": false, "error": "Job not found" }
```