# Batch Create/Update People

POST https://api.trebellar.app/api/v2/people/batch/upsert
Content-Type: application/json

Create new people or update existing employee records in a single batch operation. Use this for HR system integrations, bulk imports, or synchronized employee data updates. Each person record can include employment details, contact information, and initial group assignments. Existing people are matched by ID and updated; new records without IDs are created.

Reference: https://docs.trebellar.app/api-reference/api-resources/people/upsert-people-batch

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Batch Create/Update People
  version: endpoint_people.upsertPeopleBatch
paths:
  /api/v2/people/batch/upsert:
    post:
      operationId: upsert-people-batch
      summary: Batch Create/Update People
      description: >-
        Create new people or update existing employee records in a single batch
        operation. Use this for HR system integrations, bulk imports, or
        synchronized employee data updates. Each person record can include
        employment details, contact information, and initial group assignments.
        Existing people are matched by ID and updated; new records without IDs
        are created.
      tags:
        - - subpackage_people
      parameters:
        - name: X-Trebellar-Api-Key
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: >-
            All people records processed successfully - existing employees
            updated and new employees created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpsertPeopleBatchResponse'
        '400':
          description: Bad Request Error
          content: {}
        '500':
          description: Internal Server Error
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertPeopleBatchRequest'
components:
  schemas:
    AssetId:
      type: string
    PeopleInputEmploymentStatus:
      type: string
      enum:
        - value: active
        - value: inactive
    PeopleAddress:
      type: object
      properties:
        raw:
          type: string
        postalCode:
          type: string
        streetName:
          type: string
        city:
          type: string
        state:
          type: string
        countryIso:
          type: string
    PeopleInput:
      type: object
      properties:
        id:
          type: string
        externalId:
          type: string
        assetId:
          $ref: '#/components/schemas/AssetId'
        name:
          type: string
        hireDate:
          type: number
          format: double
        employmentStatus:
          $ref: '#/components/schemas/PeopleInputEmploymentStatus'
        terminationDate:
          type: number
          format: double
        address:
          $ref: '#/components/schemas/PeopleAddress'
    UpsertPeopleBatchRequest:
      type: object
      properties:
        people:
          type: array
          items:
            $ref: '#/components/schemas/PeopleInput'
      required:
        - people
    PeopleEmploymentStatus:
      type: string
      enum:
        - value: active
        - value: inactive
    PeopleGroupPropertiesOutput:
      type: object
      properties:
        color:
          type: string
    PeopleGroup:
      type: object
      properties:
        id:
          type: string
        path:
          type: string
        parentId:
          type: string
        avatarUrl:
          type: string
        name:
          type: string
        description:
          type: string
        properties:
          $ref: '#/components/schemas/PeopleGroupPropertiesOutput'
        externalId:
          type: string
      required:
        - id
        - name
    PeopleCreatedAt:
      oneOf:
        - type: string
        - type: number
          format: double
    PeopleUpdatedAt:
      oneOf:
        - type: string
        - type: number
          format: double
    People:
      type: object
      properties:
        id:
          type: string
        externalId:
          type: string
        assetId:
          $ref: '#/components/schemas/AssetId'
        name:
          type: string
        hireDate:
          type: number
          format: double
        employmentStatus:
          $ref: '#/components/schemas/PeopleEmploymentStatus'
        terminationDate:
          type: number
          format: double
        address:
          $ref: '#/components/schemas/PeopleAddress'
        groups:
          type: array
          items:
            $ref: '#/components/schemas/PeopleGroup'
        createdAt:
          $ref: '#/components/schemas/PeopleCreatedAt'
        updatedAt:
          $ref: '#/components/schemas/PeopleUpdatedAt'
      required:
        - id
        - groups
    UpsertPeopleBatchResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/People'
      required:
        - data

```

## SDK Code Examples

```typescript
import { TrebellarApiClient } from "@trebellar/api-sdk";

async function main() {
    const client = new TrebellarApiClient({
        environment: "https://api.trebellar.app",
    });
    await client.people.upsertPeopleBatch({
        people: [
            {
                externalId: "EMP001",
                name: "Jane Smith",
                employmentStatus: "active",
            },
            {
                id: "emp_existing_123",
                name: "John Updated",
                employmentStatus: "active",
            },
        ],
    });
}
main();

```

```python
from trebellar import TrebellarApi

client = TrebellarApi(
    base_url="https://api.trebellar.app",
    api_key=
)

client.people.upsert_people_batch(
    people=[
        {
            "external_id": "EMP001",
            "name": "Jane Smith",
            "employment_status": "active"
        },
        {
            "id": "emp_existing_123",
            "name": "John Updated",
            "employment_status": "active"
        }
    ]
)

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.trebellar.app/api/v2/people/batch/upsert"

	payload := strings.NewReader("{\n  \"people\": [\n    {\n      \"externalId\": \"EMP001\",\n      \"name\": \"Jane Smith\",\n      \"employmentStatus\": \"active\"\n    },\n    {\n      \"id\": \"emp_existing_123\",\n      \"name\": \"John Updated\",\n      \"employmentStatus\": \"active\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Trebellar-Api-Key", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.trebellar.app/api/v2/people/batch/upsert")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Trebellar-Api-Key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"people\": [\n    {\n      \"externalId\": \"EMP001\",\n      \"name\": \"Jane Smith\",\n      \"employmentStatus\": \"active\"\n    },\n    {\n      \"id\": \"emp_existing_123\",\n      \"name\": \"John Updated\",\n      \"employmentStatus\": \"active\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.trebellar.app/api/v2/people/batch/upsert")
  .header("X-Trebellar-Api-Key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"people\": [\n    {\n      \"externalId\": \"EMP001\",\n      \"name\": \"Jane Smith\",\n      \"employmentStatus\": \"active\"\n    },\n    {\n      \"id\": \"emp_existing_123\",\n      \"name\": \"John Updated\",\n      \"employmentStatus\": \"active\"\n    }\n  ]\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.trebellar.app/api/v2/people/batch/upsert', [
  'body' => '{
  "people": [
    {
      "externalId": "EMP001",
      "name": "Jane Smith",
      "employmentStatus": "active"
    },
    {
      "id": "emp_existing_123",
      "name": "John Updated",
      "employmentStatus": "active"
    }
  ]
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'X-Trebellar-Api-Key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.trebellar.app/api/v2/people/batch/upsert");
var request = new RestRequest(Method.POST);
request.AddHeader("X-Trebellar-Api-Key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"people\": [\n    {\n      \"externalId\": \"EMP001\",\n      \"name\": \"Jane Smith\",\n      \"employmentStatus\": \"active\"\n    },\n    {\n      \"id\": \"emp_existing_123\",\n      \"name\": \"John Updated\",\n      \"employmentStatus\": \"active\"\n    }\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "X-Trebellar-Api-Key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = ["people": [
    [
      "externalId": "EMP001",
      "name": "Jane Smith",
      "employmentStatus": "active"
    ],
    [
      "id": "emp_existing_123",
      "name": "John Updated",
      "employmentStatus": "active"
    ]
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.trebellar.app/api/v2/people/batch/upsert")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```