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

# Entity Creation

The essential first step of any flow with the Skill Engine API is creating the
Entities within the system. This is done by sending over the entity information
to the respective endpoint (`POST` to `/employees` to create an Employee,
to `/vacancies` to create a Vacancy). The sequence diagram below shows the flow
for a single Employee. Its structure would be identical for other Entity types,
and adding multiple Employees is just a matter of repeating the flow.

```mermaid theme={null}
sequenceDiagram
    participant Your System
    participant Skill Engine API
    Your System->>Skill Engine API: POST /employees
    activate Your System
    alt Creation Successful
        rect rgba(0, 255, 0, .15)
            Skill Engine API->>Skill Engine API: Skill Extraction
            Skill Engine API-->>Your System: ✅ HTTP 204 No Content
        end
    else Creation Failed
        rect rgba(255, 0, 0, .15)
            Skill Engine API->>Skill Engine API: Skill Extraction Failed
            Skill Engine API-->>Your System: ❌ HTTP 422 Unprocessable
        end
    else Entity Already Exists
        rect rgba(255, 0, 0, .15)
            Skill Engine API-->>Your System: ❌ HTTP 409 Conflict
        end
    end
```

After the initial creation, the Entity can be updated through its
Entity-specific endpoint, e.g. `/employees/101` for an Employee with ID 101.

```mermaid theme={null}
sequenceDiagram
    participant Your System
    participant Skill Engine API
    opt Updating an existing Employee
        Your System->>Skill Engine API: PATCH /employees/ID
        alt Update Successful
            rect rgba(0, 255, 0, .15)
                Skill Engine API->>Skill Engine API: Skill Extraction
                Skill Engine API-->>Your System: ✅ HTTP 204 No Content
            end
        else Update Rejected
            rect rgba(255, 0, 0, .15)
                Skill Engine API->>Skill Engine API: Skill Extraction Failed
                Skill Engine API-->>Your System: ❌ HTTP 422 Unprocessable
            end
        else Employee Doesn't Exist
            rect rgba(255, 0, 0, .15)
                Skill Engine API-->>Your System: ❌ HTTP 404 Not Found
            end
        end
    end
```

<div class="warning">
  The lifecycle of each Entity is managed explicitly, meaning that you cannot
  overwrite an existing Entity with a POST message. To update an Entity, you can
  execute a PATCH call at its specific endpoint.
</div>

## Providing Profile Feedback

After the creation of a skill profile for an Employee or Vacancy, you or your
user might still have something to add (or remove). Taking this feedback into
account makes for a win-win situation; improving the user experience, the
quality of your data and the accuracy of any matches generated. This can be
done by sending a `PUT` request to respectively
the `/employees/{external_id}/skill_profile`
and `/vacancies/{external_id}/skill_profile` endpoint.