Project Creation

Creates a new project in Sodtrack linked to a customer.

POST/api/integration/project

Request

cURL

curl -X POST "https://dev.integration.cl.sodtrack-shared.sodtrack.com/api/integration/project" \
  -H "Authorization: Bearer $SODTRACK_TOKEN" \
  -H "origin: <your-origin>"

Base URL: https://dev.integration.cl.sodtrack-shared.sodtrack.com · other environments

Headers

Name	Type	Description
`origin`	string	—

Responses

Project Creation

{
  "name": "Proyecto ejemplo",
  "reference": "PROJ-EXT-100",
  "customer": {
    "name": "María"
  }
}

Error responses for this endpoint follow the shared error reference.

Purpose

Creates a new project in Sodtrack linked to a customer.

The project is created with the provided name, reference, and optional description. The customer is resolved by reference or email: if an existing customer matches, that customer is linked to the project; otherwise a new customer is created and then linked.

Projects created through this endpoint can later be targeted when creating bookings, so that bookings are attached to a stage of that project.

Field Definitions

📁 Project

Field	Type	Required	Description
`name`	`string`	✅	Project name.
`description`	`string`	❌	Optional project description.
`reference`	`string`	✅	External system reference for the project. Must be unique across projects.
`customer`	`object`	✅	Customer to associate with the project. Used to find an existing customer or to create a new one.

🧍 Customer

Field	Type	Required	Description
`customer`	`object`	✅	Customer information.
`customer.name`	`string`	✅	Customer's first name.
`customer.lastName`	`string`	❌	Customer's last name.
`customer.identificationNumber`	`string`	❌	National ID or tax identification number.
`customer.identificationNumberCountry`	`string`	❌	ISO 3166-1 alpha-2 country code for the identification number.
`customer.phoneNumber`	`string`	❌	Contact phone number in international format.
`customer.email`	`string`	❌	Customer's email address. When creating a new customer, if missing or invalid a temporary email may be generated.
`customer.reference`	`string`	❌	External reference of the customer. Used together with email to resolve an existing customer.

If customer is new, one of email, reference or identification numbers should be provided, in order to generate a temporary email for that customer

Example Request (with full customer)

json

{
  "name": "Instalación cortinas - Av. Providencia",
  "description": "Proyecto creado desde sistema externo",
  "reference": "PROJ-EXT-100",
  "customer": {
    "name": "María",
    "lastName": "García",
    "identificationNumber": "12345678-9",
    "identificationNumberCountry": "CL",
    "phoneNumber": "+56912345678",
    "email": "maria.garcia@example.com",
    "reference": "CUST-EXT-001"
  }
}

Example Request (minimal)

json

{
  "name": "Proyecto ejemplo",
  "reference": "PROJ-EXT-101",
  "customer": {
    "name": "Juan Pérez",
    "email": "juanperez@example.com"
  }
}

Response Example

json

{
  "id": 502,
  "reference": "PROJ-EXT-100"
}

Response Fields

Field	Type	Description
`id`	`number`	Unique Sodtrack project ID.
`reference`	`string`	The project reference as stored (same as requested).

Error Responses

HTTP Status	Error	Description
`400 Bad Request`	`PROJECT_REFERENCE_ALREADY_USED: {reference}`	A project with the given `reference` already exists. The reference must be unique.
`400 Bad Request`	`MULTIPLE_CUSTOMERS_FOUND_FOR_REFERENCE`	More than one customer matches the provided reference/email; resolution is ambiguous. Use a unique reference or contact.
`400 Bad Request`	`InvalidParameters`	One or more required fields are missing or invalid.
`401 Unauthorized`	—	Authentication token missing or expired.
`403 Forbidden`	—	The API key or origin is not authorized.
`500 Internal Server Error`	—	Unexpected server error. Contact Sodtrack support.

Business Rules & Constraints

Project reference uniqueness

The reference must be unique across all projects in Sodtrack.
If a project with the same reference already exists, the request is rejected with PROJECT_REFERENCE_ALREADY_USED and no project is created.

Customer resolution

The customer object is used to either link an existing customer or create a new one:

Existing customer: Sodtrack searches by reference and email (from the request).
- If exactly one customer is found, that customer is linked to the new project.
- If more than one customer matches, the request fails with MULTIPLE_CUSTOMERS_FOUND_FOR_REFERENCE. Ensure your external references or emails uniquely identify a single customer.
New customer: If no customer is found, a new customer is created with the provided data. If email is missing or invalid, the system may generate a temporary email so the user can be created; the customer can be updated later (e.g. via the administrator or other APIs).

Data and format

All timestamps follow the ISO 8601 format (UTC) where applicable.