Client Management

Overview

The Client Management API (sgivu-client) manages client information for both individual persons and companies. It provides CRUD operations, multi-criteria search, and status management for clients involved in vehicle purchase and sales transactions.

Base URL

https://your-domain.com/v1

Persons

Create Person

POST /v1/persons

Registers a new individual person as a client. Authentication: Required Authorization: person:create permission

Request Body

firstName

string

required

First name

lastName

string

required

Last name

nationalId

integer

required

National identification number

string

required

Email address

phoneNumber

integer

required

Phone number

address

object

Address information

address.street

string

Street address

address.city

string

City

address.state

string

State/province

address.postalCode

string

Postal code

enabled

boolean

default:"true"

Whether the client is enabled

{
  "firstName": "María",
  "lastName": "García López",
  "nationalId": 1234567890,
  "email": "maria.garcia@example.com",
  "phoneNumber": 3001234567,
  "address": {
    "street": "Calle 123 #45-67",
    "city": "Bogotá",
    "state": "Cundinamarca",
    "postalCode": "110111"
  },
  "enabled": true
}

Response

{
  "id": 25,
  "clientId": 50,
  "firstName": "María",
  "lastName": "García López",
  "nationalId": 1234567890,
  "email": "maria.garcia@example.com",
  "phoneNumber": 3001234567,
  "address": {
    "id": 30,
    "street": "Calle 123 #45-67",
    "city": "Bogotá",
    "state": "Cundinamarca",
    "postalCode": "110111"
  },
  "enabled": true,
  "createdAt": "2026-03-06T10:30:00",
  "updatedAt": "2026-03-06T10:30:00"
}

Status Codes

201 Created - Person created successfully
400 Bad Request - Invalid input data
401 Unauthorized - Not authenticated
403 Forbidden - Missing person:create permission

Example

curl -X POST https://your-domain.com/v1/persons \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "María",
    "lastName": "García López",
    "nationalId": 1234567890,
    "email": "maria.garcia@example.com",
    "phoneNumber": 3001234567,
    "address": {
      "street": "Calle 123 #45-67",
      "city": "Bogotá"
    }
  }'

Get Person by ID

GET /v1/persons/{id}

Retrieves detailed information about a specific person. Authentication: Required Authorization: person:read permission

Path Parameters

integer

required

Person ID

Response

{
  "id": 25,
  "clientId": 50,
  "firstName": "María",
  "lastName": "García López",
  "nationalId": 1234567890,
  "email": "maria.garcia@example.com",
  "phoneNumber": 3001234567,
  "address": {
    "street": "Calle 123 #45-67",
    "city": "Bogotá"
  },
  "enabled": true,
  "createdAt": "2026-03-06T10:30:00"
}

Example

curl -X GET https://your-domain.com/v1/persons/25 \
  -H "Authorization: Bearer YOUR_TOKEN"

List Persons (Paginated)

GET /v1/persons/page/{page}

Retrieves a paginated list of persons. Authentication: Required Authorization: person:read permission

Path Parameters

page

integer

required

Page number (0-based)

Response

{
  "content": [
    {
      "id": 25,
      "firstName": "María",
      "lastName": "García López",
      "nationalId": 1234567890,
      "email": "maria.garcia@example.com",
      "phoneNumber": 3001234567,
      "enabled": true
    }
  ],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 10
  },
  "totalElements": 150,
  "totalPages": 15
}

Example

curl -X GET https://your-domain.com/v1/persons/page/0 \
  -H "Authorization: Bearer YOUR_TOKEN"

Update Person

PUT /v1/persons/{id}

Updates an existing person record. Authentication: Required Authorization: person:update permission

Path Parameters

integer

required

Person ID to update

Request Body

Same structure as Create Person.

{
  "firstName": "María",
  "lastName": "García López",
  "nationalId": 1234567890,
  "email": "maria.garcia.updated@example.com",
  "phoneNumber": 3009876543
}

Status Codes

200 OK - Person updated successfully
400 Bad Request - Invalid input
401 Unauthorized - Not authenticated
403 Forbidden - Missing person:update permission
404 Not Found - Person does not exist

Example

curl -X PUT https://your-domain.com/v1/persons/25 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "maria.garcia.updated@example.com",
    "phoneNumber": 3009876543
  }'

Delete Person

DELETE /v1/persons/{id}

Permanently deletes a person from the system. Authentication: Required Authorization: person:delete permission

Path Parameters

integer

required

Person ID to delete

Status Codes

204 No Content - Person deleted successfully
401 Unauthorized - Not authenticated
403 Forbidden - Missing person:delete permission
404 Not Found - Person does not exist

Example

curl -X DELETE https://your-domain.com/v1/persons/25 \
  -H "Authorization: Bearer YOUR_TOKEN"

Change Person Status

PATCH /v1/persons/{id}/status

Enables or disables a person client. Authentication: Required Authorization: person:update permission

Path Parameters

integer

required

Person ID

Request Body

enabled

boolean

required

New status (true=enabled, false=disabled)

true

Response

{
  "enabled": true
}

Example

curl -X PATCH https://your-domain.com/v1/persons/25/status \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d 'true'

Get Person Counts

GET /v1/persons/count

Retrieves statistics: total persons, active, and inactive. Authentication: Required Authorization: person:read permission

Response

{
  "total": 150,
  "active": 145,
  "inactive": 5
}

Example

curl -X GET https://your-domain.com/v1/persons/count \
  -H "Authorization: Bearer YOUR_TOKEN"

Search Persons

GET /v1/persons/search

Multi-criteria search for persons. Authentication: Required Authorization: person:read permission

Query Parameters

name

string

Filter by first or last name (partial match)

string

Filter by email

nationalId

integer

Filter by national ID

phoneNumber

integer

Filter by phone number

enabled

boolean

Filter by enabled status

city

string

Filter by city

Response

[
  {
    "id": 25,
    "firstName": "María",
    "lastName": "García López",
    "nationalId": 1234567890,
    "email": "maria.garcia@example.com",
    "enabled": true
  }
]

Example

curl -X GET "https://your-domain.com/v1/persons/search?city=Bogot%C3%A1&enabled=true" \
  -H "Authorization: Bearer YOUR_TOKEN"

Search Persons (Paginated)

GET /v1/persons/search/page/{page}

Paginated variant of person search. Authentication: Required Authorization: person:read permission

Path Parameters

page

integer

required

Page number (0-based)

Query Parameters

size

integer

default:"10"

Page size

All search parameters from the non-paginated endpoint are available.

Example

curl -X GET "https://your-domain.com/v1/persons/search/page/0?size=20&city=Bogot%C3%A1" \
  -H "Authorization: Bearer YOUR_TOKEN"

Companies

Company endpoints follow the same pattern as person endpoints but use /v1/companies as the base path.

Company-Specific Fields

companyName

string

required

Legal company name

taxId

string

required

Tax identification number (NIT)

legalRepresentative

string

Name of legal representative

industry

string

Industry sector

Example: Create Company

curl -X POST https://your-domain.com/v1/companies \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "companyName": "AutoFleet Colombia S.A.S.",
    "taxId": "900123456-7",
    "legalRepresentative": "Carlos Mendoza",
    "email": "contacto@autofleet.com",
    "phoneNumber": 6012345678,
    "industry": "Transportation",
    "address": {
      "street": "Av. Eldorado #99-50",
      "city": "Bogotá"
    }
  }'

All company endpoints (GET, PUT, DELETE, PATCH, search) work identically to person endpoints but operate on the /v1/companies path.

Client Model

Both persons and companies are considered “clients” in SGIVU. Each person or company record has an associated clientId which is used in purchase/sale contracts.

Client Hierarchy

Client (base)
├── Person
└── Company

Error Responses

400 Bad Request

{
  "error": "validation_error",
  "message": "Invalid input data",
  "details": [
    {
      "field": "email",
      "message": "Email address is invalid"
    }
  ]
}

404 Not Found

{
  "error": "not_found",
  "message": "Person with ID 999 not found"
}

Authentication

User Management

Vehicle Management

Client Management

Purchase & Sales

Machine Learning

​Overview

​Base URL

​Persons

​Create Person

​Request Body

​Response

​Status Codes

​Example

​Get Person by ID

​Path Parameters

​Response

​Example

​List Persons (Paginated)

​Path Parameters

​Response

​Example

​Update Person

​Path Parameters

​Request Body

​Status Codes

​Example

​Delete Person

​Path Parameters

​Status Codes

​Example

​Change Person Status

​Path Parameters

​Request Body

​Response

​Example

​Get Person Counts

​Response

​Example

​Search Persons

​Query Parameters

​Response

​Example

​Search Persons (Paginated)

​Path Parameters

​Query Parameters

​Example

​Companies

​Company-Specific Fields

​Example: Create Company

​Client Model

​Client Hierarchy

​Error Responses

​400 Bad Request

​404 Not Found

Overview

Base URL

Persons

Create Person

Request Body

Response

Status Codes

Example

Get Person by ID

Path Parameters

Response

Example

List Persons (Paginated)

Path Parameters

Response

Example

Update Person

Path Parameters

Request Body

Status Codes

Example

Delete Person

Path Parameters

Status Codes

Example

Change Person Status

Path Parameters

Request Body

Response

Example

Get Person Counts

Response

Example

Search Persons

Query Parameters

Response

Example

Search Persons (Paginated)

Path Parameters

Query Parameters

Example

Companies

Company-Specific Fields

Example: Create Company

Client Model

Client Hierarchy

Error Responses

400 Bad Request

404 Not Found