Svit.One Docs
Reference

Create a Person

Creates a persisted Person in the Project established by the server token. Plain creation needs no Integration or mapper and is not idempotent. Optional externalAssociation claims an exact Integration/externalId key atomically with the Person. It requires this token's ID in the Integration's properties.personRegistration.projectAccessTokenIds allowlist. An occupied key returns 409 without updating the existing Person; use the separate by-external-id lookup to recover its current Person ID. No source payload is captured.

POST/v1/external/people

Creates a persisted Person in the Project established by the server token. Plain creation needs no Integration or mapper and is not idempotent. Optional externalAssociation claims an exact Integration/externalId key atomically with the Person. It requires this token's ID in the Integration's properties.personRegistration.projectAccessTokenIds allowlist. An occupied key returns 409 without updating the existing Person; use the separate by-external-id lookup to recover its current Person ID. No source payload is captured.

Authorization

projectAccessToken
AuthorizationBearer <token>

Server-to-server Project Access Token. Requests operate in the token's Project.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://api-external.svit.one/api/v1/external/people" \  -H "Content-Type: application/json" \  -d '{    "name": "string"  }'
{
  "id": "string",
  "name": "string",
  "description": "string",
  "emails": [
    "string"
  ],
  "organizationId": "string",
  "ownerUserId": 0,
  "phones": [
    "string"
  ],
  "position": "string",
  "tags": [
    "string"
  ],
  "createdAt": "string",
  "updatedAt": "string"
}
Empty
{
  "type": "https://api-errors.svit.one/access/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Association permission denied",
  "code": "FORBIDDEN",
  "timestamp": "2026-10-27T09:18:23.000Z"
}
Empty
{
  "type": "https://api-errors.svit.one/conflict/resource",
  "title": "Conflict",
  "status": 409,
  "detail": "External key is occupied, unavailable, or its Integration configuration is invalid",
  "code": "CONFLICT",
  "timestamp": "2026-10-27T09:18:23.000Z"
}
Empty
{
  "type": "https://api-errors.svit.one/internal/service-unavailable",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "Concurrent change; retry with the same key",
  "code": "SERVICE_UNAVAILABLE",
  "timestamp": "2026-10-27T09:18:23.000Z"
}

Associate an existing Person with an exact external identity POST

Requires the separate properties.personAssociation.projectAccessTokenIds grant. Without an onboardingPolicy this is explicit linking only. With svit-user enabled, a new claim requires onboarding.email (nullable) and must still resolve to this Person. Same key and Person repeats successfully, including after email changes. Other owners, retired keys and inactive/foreign targets are rejected. Never creates or edits a Person. Creation/lookup permissions and existing associations are unchanged.

Create a task POST

Creates a task in the project associated with the bearer project access token. The operation uses the token creator's current task permissions and attributes the task to that user. Assignable priorities are numeric 0–3; the default remains 3. Creating a Task is not idempotent; do not blindly retry an ambiguous transport failure.