Skip to main content

​
How to use Salú Public API

This guide explains:
  1. What the Public API is
  2. The difference between environments (dev and prd)
  3. How to obtain and use your API Key (x-api-key)
  4. How to navigate the documentation (tabs, endpoints, examples)
  5. How to test an endpoint using the API Playground and curl
  6. How to interpret common responses and errors

​
1. What is the Public API?

The Public API is a set of HTTP routes that allow external systems to integrate with Salú.
  • You make an HTTP request (for example, GET /v0/sector)
  • The API responds with data in JSON (lists, objects, etc.)
  • Access is protected with authentication (x-api-key header)

​
2. Environments: dev vs prd

There are two main environments:
  • dev → development / staging environment
  • prd → production environment (real data)
Base URLs: 
https://public-api.salu.com.vc/dev/routes
https://public-api.salu.com.vc/prd/routes
We will refer to this as BASE_URL. Endpoints follow the pattern:
BASE_URL + path
For example, to list sectors: 
GET {BASE_URL}/v0/sector

​
3. Authentication and API Key

Most Public API routes require a header called x-api-key.

​
3.1. Important headers

  • x-api-key → required: identifies the client calling the API
Example headers: 
x-api-key: YOUR_API_KEY_HERE
If you do not send x-api-key, or if it is invalid/expired, the API will return an authentication error.

​
3.2. How to obtain your API Key

API Keys are managed through your organization’s Salú portal. Typical flow:
  1. A user with the appropriate permissions logs into the Salú Portal.
  2. Navigate to the Integrations / Public API section (label may vary).
  3. Click Create new API Key.
  4. Provide a descriptive name for the key (e.g. erp-payroll-integration) and, if applicable, select environment/scope.
  5. The portal generates the key and shows the full value once.
  6. Copy the key and configure it in the system that will call the API (backend, Postman, Insomnia, etc.).
Notes:
  • Store the key securely (ideally in a vault or environment variable).
  • If a key is exposed or compromised, revoke and generate a new one in the portal.
  • You can have multiple active keys (for different systems or environments).
If you do not have access to the portal, ask a teammate with admin privileges to generate the key.

​
3.3. Example curl request

Assuming you are using the dev environment: 
curl --request GET "https://public-api.salu.com.vc/dev/routes/v0/sector" \
  --header "Accept: application/json" \
  --header "x-api-key: YOUR_API_KEY_HERE"

​
4. How to navigate the documentation

On the top of the site you will find several tabs. The most relevant here are:
  • API reference → generic examples
  • Public API → Salú’s public API documentation
Under Public API: In API documentation you will find:
  • The Public API overview page
  • Optional links to additional guides or overview pages
In Endpoint examples you will find groups like:
  • Branches
  • Positions
  • Sectors
  • Employees
  • Organizations

​
4.1. What each endpoint page shows

On an endpoint page (for example Public List Sectors) you will typically see:
  • Endpoint title
  • Method + path (e.g. GET /v0/sector)
  • A description of what the route does
  • Authentication info (e.g. x-api-key header)
  • Parameters:
    • Path parameters (e.g. :sector_id)
    • Query parameters (e.g. is_active, order_by)
    • Headers
  • Example request (usually curl)
  • Example response (JSON)
  • The API Playground, where you can test the route directly in the docs

​
5. How to test an endpoint in practice

You have two main options:
  1. Use the API Playground in the documentation
  2. Use tools such as Postman, Insomnia or curl in your terminal

​
5.1. Testing via the API Playground

  1. Open the Public API section.
  2. Choose an endpoint (for example Public List Sectors).
  3. In the Playground header:
    • Confirm the server/environment (dev or prd).
  4. In Headers, set:
    • x-api-key → your key
  5. Fill in any parameters you want (query, path, etc.).
  6. Click Send.
  7. Inspect the JSON response in the response panel (status 200, 4xx, 5xx, etc.).
If an error occurs, check the response body — it usually contains JSON explaining the issue.

​
5.2. Testing with curl

Pattern: 
curl --request <METHOD> "<BASE_URL><PATH>" \
  --header "Accept: application/json" \
  --header "x-api-key: YOUR_API_KEY_HERE" \
  [--data '{"json": "if POST/PUT"}']
To list sectors in production: 
curl --request GET "https://public-api.salu.com.vc/prd/routes/v0/sector" \
  --header "Accept: application/json" \
  --header "x-api-key: YOUR_API_KEY_HERE"

​
6. Understanding common responses and errors

​
6.1. Success responses

  • 200 OK → request succeeded (e.g. list, fetch)
  • 201 Created → resource created successfully (on POST)
Typical response body example: 
{
  "data": [
    {
      "id": "sector-uuid",
      "name": "Nursing",
      "is_active": true
    }
  ]
}

​
6.2. Authentication errors

Common examples: Missing or invalid API Key
  • Status: 401 or 403
  • Possible messages:
{
  "detail": "Not authenticated"
}
or 
{
  "detail": "Invalid API key"
}
Check:
  • That the x-api-key header is being sent
  • No extra spaces or stray characters were copied
  • You are using the correct key for the selected environment (dev vs prd)

​
6.3. Validation errors (422)

When a parameter is missing or invalid, you might see: 
{
  "detail": [
    {
      "loc": ["query", "order_by"],
      "msg": "value is not a valid enumeration member",
      "type": "type_error.enum"
    }
  ]
}
This indicates a field was sent with an invalid value. Check the Parameters section in the docs for valid values and retry.

​
6.4. Server errors (5xx)

If you receive a 500 or similar error:
  1. Retry after a few seconds.
  2. If the issue persists, collect:
    • The endpoint called
    • Environment (dev or prd)
    • Approximate time
    • The error response body
  3. Send these details to Salú support.

​
7. Quick checklist

Before reporting a problem, verify:
  • Are you using the correct base URL (dev vs prd)?
  • Are you sending the x-api-key header?
  • Is the API Key for Salú Public API?
  • Did you fill mandatory parameters?
  • Did you read the error JSON (field detail)?
If you still need help, share these details with the Salú team — it speeds up troubleshooting.