Skip to main content

Sales Representatives API

The Sales Representatives API allows you to manage sales representatives (sales reps) in the Nilo platform. Sales reps are associated with commercial routes and can be assigned to stores for order management and customer relationship purposes.

Understanding Sales Representatives​

Sales representatives in Nilo are linked to your commercial route structure:

  • Sales Rep Structure
    • Unique internal code for identification
    • Name and contact information (phone with country code)
    • Association with a commercial route
    • Enabled/disabled status

Important Considerations​

  1. Unique Codes: Each sales rep requires a unique internal code (same as in your ERP)
  2. Commercial Routes: Sales reps can be associated with a commercial route for territory management
  3. Contact Info: Country code and phone are required for communication features
  4. Status Control: Use enabled/disabled instead of deleting sales reps

Single Operations​

Upsert Sales Representative​

PUT/sales-rep

Create or update a single sales representative. If a sales rep with the same internal code exists, it will be updated; otherwise, a new one will be created.

Request Body Parameters​

ParameterTypeRequiredDescription
internalCodestringNoUnique sales rep code (same as in ERP)
namestringYesSales representative full name
countryCodestringYesPhone country code (e.g., "+54")
phonestringYesPhone number
enabledbooleanYesWhether the sales rep is active
commertialRouteInternalCodestringNoCommercial route internal code to associate

Request Body Example​

{
  "internalCode": "SR-001",
  "name": "Juan Pérez",
  "countryCode": "+54",
  "phone": "1155443322",
  "enabled": true,
  "commertialRouteInternalCode": "ROUTE-NORTH"
}

Response Codes​

CodeDescription
200Successful operation
400Validation error
401Unauthorized
403Forbidden - Insufficient permissions

Example Usage​

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
};

const data = {
  internalCode: "SR-001",
  name: "Juan Pérez",
  countryCode: "+54",
  phone: "1155443322",
  enabled: true,
  commertialRouteInternalCode: "ROUTE-NORTH",
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/sales-rep",
  {
    method: "PUT",
    headers: headers,
    body: JSON.stringify(data),
  }
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Batch Operations​

Batch Upsert Sales Representatives​

POST/batch/sales-rep

This endpoint allows you to create or update multiple sales representatives at once. The operation is processed asynchronously.

Use this endpoint when you need to:

  • Synchronize your sales team from your ERP or CRM system
  • Onboard multiple sales representatives simultaneously
  • Bulk update sales rep assignments to commercial routes

Request Body Parameters​

ParameterTypeRequiredDescription
upsertarrayYesArray of sales representative objects
upsert[].idintegerNoSales rep ID (required for updates)
upsert[].internalCodestringNoUnique sales rep code (same as in ERP)
upsert[].namestringNoSales representative full name
upsert[].countryCodestringNoPhone country code (e.g., "+54")
upsert[].phonestringNoPhone number
upsert[].enabledbooleanNoWhether the sales rep is active
upsert[].commertialRouteInternalCodestringNoCommercial route internal code to associate

Request Body Example​

{
  "upsert": [
    {
      "internalCode": "SR-001",
      "name": "Juan Pérez",
      "countryCode": "+54",
      "phone": "1155443322",
      "enabled": true,
      "commertialRouteInternalCode": "ROUTE-NORTH"
    },
    {
      "internalCode": "SR-002",
      "name": "María López",
      "countryCode": "+54",
      "phone": "1166554433",
      "enabled": true,
      "commertialRouteInternalCode": "ROUTE-SOUTH"
    },
    {
      "internalCode": "SR-003",
      "name": "Carlos García",
      "countryCode": "+54",
      "phone": "1177665544",
      "enabled": false,
      "commertialRouteInternalCode": null
    }
  ]
}

Response Codes​

CodeDescription
202Accepted - Operation in processing
400Validation error
403Unauthorized

Response Example​

{
  "code": 202,
  "batchIds": {},
  "message": "Operation in processing"
}

Example Usage​

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
};

const data = {
  upsert: [
    {
      internalCode: "SR-001",
      name: "Juan Pérez",
      countryCode: "+54",
      phone: "1155443322",
      enabled: true,
      commertialRouteInternalCode: "ROUTE-NORTH",
    },
    {
      internalCode: "SR-002",
      name: "María López",
      countryCode: "+54",
      phone: "1166554433",
      enabled: true,
      commertialRouteInternalCode: "ROUTE-SOUTH",
    },
  ],
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/batch/sales-rep",
  {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data),
  }
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Error Codes​

When an operation fails, the API returns a structured error response:

{
  "code": 409,
  "message": "INTERNAL_CODE_ALREADY_EXISTS",
  "object": {
    "statusCode": 409,
    "code": "INTERNAL_CODE_ALREADY_EXISTS",
    "message": "Sales rep not found",
    "entity": "salesRep",
    "entityCode": "SR-001",
    "timestamp": "2026-05-18T15:16:47.000Z"
  }
}

The object field provides additional context about the error:

FieldDescription
statusCodeHTTP status code
codeError code (same as top-level message)
messageHuman-readable error description
entityEntity type that caused the error
entityCodeThe internalCode of the entity involved
timestampWhen the error occurred (ISO 8601)

400 — Bad Request​

Error CodeDescription
INVALID_COUNTRY_CODEThe provided country code is null or invalid
INVALID_USERNAMEThe username format is not valid

404 — Not Found​

Error CodeDescription
SALES_REP_NOT_FOUNDThe sales representative does not exist
SALES_REP_NOT_EXISTThe sales rep ID provided does not match any existing record
COMMERTIAL_ROUTE_NOT_EXISTThe specified commercial route does not exist

409 — Conflict​

Error CodeDescription
USERNAME_ALREADY_EXIST_IN_SFAThe phone number is already registered as another sales rep
USERNAME_ALREADY_EXIST_IN_PWAThe phone number is already registered as a store user
COMMERTIAL_ROUTE_ALREADY_ASSIGNEDThe commercial route is already assigned to another sales rep
INTERNAL_CODE_ALREADY_EXISTSA sales rep with the same internal code already exists

Security​

Authentication​

All endpoints require two types of authentication:

  • API Key in header: x-api-key
  • Authorization token in header: Authorization
  • Copyright © 2026 Nilo Labs
    Nilo
Tana

Tana

Ask me anything about Nilo's API — endpoints, authentication, integration guides, or code examples.

Best practice: validate against the official documentation for the most up-to-date details.