Build customer integrations fast

Customer Integration APIs

Customer Integration APIs – Locate2u

What are Customer Integration APIs?

Customer Integration APIs provide a secure, programmatic way to interact with the Locate2u platform. These APIs enable your systems to create stops, manage webhooks, and retrieve user information directly from your own applications. Instead of manually entering data into the Locate2u portal, you can automate your workflows and keep your systems synchronized in real-time.

How Customer Integration APIs Help Your Business

Customer Integration APIs in Locate2u are designed for building customer-specific integrations within your own Locate2u account. Unlike the core api.locate2u.com, which is primarily used for platform-wide and operational workflows, the Customer Integration API allows you to create integrations that are scoped to an individual customer. This makes it ideal when you need to import data, trigger automations, or receive webhook events only for a specific customer’s stops, jobs, or orders. Using these APIs, you can automate customer imports, create and manage customer-specific stops, and subscribe to webhook events that fire exclusively for that customer’s data. This ensures clean separation between customers, reduces unnecessary data processing, and enables safer, more targeted integrations.

When to Use Customer Integration APIs

These APIs are designed for developers and integration partners who need to build integrations for a specific customer within their Locate2u account.

• Automatically create and manage stops for a specific customer from an e-commerce platform, CRM, or order management system
• Bulk import customer-specific stops or jobs from external data sources
• Subscribe to customer-scoped webhook events to receive real-time notifications for that customer’s activity only
• Build isolated integrations that connect Locate2u with your existing business systems while keeping customer data separated

Generate Customer-Specific API Keys

Creating API Credentials in the Locate2u App Portal

To access the Customer Integration APIs, you need to generate API credentials (Client ID and Client Secret) from the Locate2u App Portal. Follow these steps:

1. Log in to the App Portal:
   • Navigate to https://app.locate2u.com and sign in with your Locate2u account.
2. Navigate to API Settings:
   • Go to your account settings and locate the API or Apps section.
   • Select the option to create a new application.
3. Create a New Application:
   • Provide a name for your application (e.g., “My Integration App”).
   • Select the customer account you want to associate with this API access.
   • Click Create to generate your credentials.
4. Save Your Credentials:
   • Your Client ID and Client Secret will be displayed.
   • Important: The Client Secret is shown only once. Copy and store it securely immediately.
   • If you lose your Client Secret, you will need to regenerate new credentials.

Security Best Practices

• Never share your Client Secret in public repositories, client-side code, or unsecured locations.
• Store credentials in environment variables or a secure secrets manager.
• If you suspect your credentials have been compromised, regenerate them immediately from the App Portal.
• Use HTTPS for all API communications.

Authentication (OAuth 2.0 — Client Credentials Flow)

Overview

The Customer Integration API uses the OAuth 2.0 Client Credentials Flow for authentication — the same flow used by the main Locate2u Public API. Your application exchanges its Client ID and Client Secret directly for an access token. There is no authorization code exchange and no redirect URI required.

All API requests must include a valid access token in the Authorization header.

Base URL: https://integration.locate2u.com

Identity Server (Production): https://id.locate2u.com

Identity Server (Sandbox/Testing): https://id-test.locate2u.com

How It Works

1. Send your application credentials (Client ID and Client Secret) to the Locate2u Identity Server.
2. The Identity Server validates your credentials.
3. The Identity Server responds with an access token.
4. Use the access token in the Authorization header to call the Customer Integration API.

OAuth 2.0 Token Endpoint

Environment	URL
Production	https://id.locate2u.com/connect/token
Sandbox	https://id-test.locate2u.com/connect/token

Required Parameters

Parameter	Description
grant_type	Must be set to client_credentials.
client_id	Your application’s Client ID (provided by Locate2u or generated from the App Portal).
client_secret	Your application’s Client Secret (provided by Locate2u or generated from the App Portal).
scope	Use integrations-api to access the Customer Integration API.

Step 1: Request an Access Token

Send a POST request to the token endpoint with your client credentials:

curl -X POST https://id.locate2u.com/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=integrations-api"

Example Token Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 1800,
  "token_type": "Bearer",
  "scope": "integrations-api"
}

Note: Access tokens expire after 30 minutes (expires_in is in seconds). Request a new token before the current one expires.

Step 2: Call the API with Your Token

Include the access token in the Authorization header for all API requests:

curl -X GET https://integration.locate2u.com/v1/Discovery/User \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Example API Response

{
  "userId": 12345,
  "email": "[email protected]",
  "teamId": 67890,
  "teamName": "My Company"
}

Available APIs

The Customer Integration API provides the following endpoint groups. Click on each API group to view detailed documentation for all available endpoints.

API Group	Description
Discovery API	Retrieve information about the authenticated user and their team.
Stops API	Create individual stops, bulk import stops, create batch deliveries, and retrieve stop details.
Webhooks API	Subscribe to webhook events, manage subscriptions, and list available event types.

Discovery API Endpoints

Method	Endpoint	Description
GET	/v1/Discovery/User	Retrieve information about the currently authenticated user.

Stops API Endpoints

Method	Endpoint	Description
GET	/v1/Stops/{id}	Retrieve details of a specific stop by its ID.
POST	/v1/Stops	Create a new stop with the provided details.
POST	/v1/Stops/import	Bulk import multiple stops in a single request.
POST	/v1/Logistics/batch-delivery	Create a delivery batch with items, pickup stops, and drop-off stops in a single call.
GET	/v1/Stops/import/{batchId}/status	Check the current status of a batch import operation.

Webhooks API Endpoints

Method	Endpoint	Description
GET	/v1/Webhooks/event-types	List all available webhook event types.
GET	/v1/Webhooks	List all your subscribed webhooks.
POST	/v1/Webhooks	Subscribe to a webhook event.
GET	/v1/Webhooks/{id}	Retrieve details of a specific webhook subscription.
PUT	/v1/Webhooks/{id}	Update an existing webhook subscription.
DELETE	/v1/Webhooks/{id}	Unsubscribe from a webhook event.

Batch Delivery API

POST /v1/Logistics/batch-delivery

Create delivery batches containing items, pickup stops, and drop-off stops in a single API call. Ideal for scenarios where multiple items need to be picked up from one or more locations and delivered to multiple destinations.

Authorization: Requires a Bearer Token in the Authorization header.

Request Body Structure

{
  "batchSourceReference": "string",
  "batchDescription": "string",
  "teamSourceReference": "string",
  "customerSourceReference": "string",
  "serviceDate": "2024-01-15",
  "items": [...],
  "pickups": [...],
  "dropoffs": [...]
}

Root Level Fields

Field	Type	Required	Max Length	Description
batchSourceReference	string	Yes	100	Unique identifier for this batch from your system.
batchDescription	string	No	256	Human-readable description of the batch.
teamSourceReference	string	Yes	100	Team identifier from your upstream system.
customerSourceReference	string	No	100	Optional customer identifier for reference.
serviceDate	date	Yes	—	Date for delivery service (YYYY-MM-DD). All stop trip dates must match.
items	array	Yes	—	Array of items being transported. Min 1 item.
pickups	array	Yes	—	Array of pickup stop locations. Min 1 pickup.
dropoffs	array	Yes	—	Array of drop-off stop locations. Min 1 drop-off.

Items Array

Each item represents a physical item or shipment being transported.

Field	Type	Required	Max Length / Range	Description
itemSourceReference	string	Yes	100	Unique identifier for this item within the batch.
barcode	string	No	100	Barcode associated with the item.
description	string	No	256	Human-readable description.
quantity	decimal	No	0.01–1,000,000	Quantity. Defaults to 1. Must be > 0.
productReference	string	No	100	Product reference code.
productVariantId	integer	No	—	Product variant identifier.
serviceId	integer	No	—	Service identifier.
status	string	No	100	Current status of the item.
contents	object	No	—	Shipment contents classification.
load	object	No	—	Load/dimensional information.
customFields	object	No	—	Key-value pairs for custom data.

Example Item:

{
  "itemSourceReference": "ITEM-001",
  "barcode": "9876543210123",
  "description": "Electronics Package",
  "quantity": 1,
  "productReference": "ELEC-TV-55",
  "status": "Ready",
  "contents": { "isFragile": true },
  "load": { "weight": 15.5, "length": 140, "width": 90, "height": 20 },
  "customFields": { "orderNumber": "ORD-12345" }
}

Pickup Stops Array

Each pickup stop defines a location where items will be collected.

Field	Type	Required	Max Length	Description
stopSourceReference	string	Yes	100	Unique identifier. Must be unique across all stops.
name	string	Yes	250	Name of the pickup location.
address	string	Yes	500	Full street address.
contact	object	No	—	Contact person details.
location	object	No	—	Geographic coordinates (lat/lng).
tripDate	datetime	Yes	—	Date/time for pickup. Date must match serviceDate. ISO 8601.
appointmentTime	string	No	—	Appointment time (HH:mm).
timeWindowStart	datetime	No	—	Start of acceptable time window.
timeWindowEnd	datetime	No	—	End of acceptable time window. Must be ≥ timeWindowStart.
durationMinutes	integer	No	—	Estimated duration at stop (minutes).
notes	string	No	—	Special instructions for the driver.
customFields	object	No	—	Key-value pairs for custom data.
load	object	No	—	Load info for capacity planning.
skills	array	No	—	Required driver skills (e.g., ["forklift"]).
driverInstructions	object	No	—	Driver-specific instructions.
source	string	No	—	Source system identifier.
sourceReference	string	No	—	Source system reference.
itemSourceReferences	array	Yes	—	Item references being picked up. Min 1.
warehouseSourceReference	string	No	100	Warehouse identifier.
requireAllItemsBeforeRelease	boolean	No	—	All items must be collected before dispatch. Default: true.

Example Pickup Stop:

{
  "stopSourceReference": "PICKUP-001",
  "name": "Main Warehouse",
  "address": "123 Industrial Ave, Sydney NSW 2000",
  "contact": { "name": "John Smith", "phone": "+61412345678", "email": "[email protected]" },
  "location": { "latitude": -33.8688, "longitude": 151.2093 },
  "tripDate": "2024-01-15T09:00:00",
  "timeWindowStart": "2024-01-15T08:00:00",
  "timeWindowEnd": "2024-01-15T12:00:00",
  "durationMinutes": 30,
  "notes": "Use loading dock B",
  "itemSourceReferences": ["ITEM-001", "ITEM-002"],
  "warehouseSourceReference": "WH-MAIN",
  "requireAllItemsBeforeRelease": true
}

Drop-off Stops Array

Each drop-off stop defines a delivery destination.

Field	Type	Required	Max Length	Description
stopSourceReference	string	Yes	100	Unique identifier. Must be unique across all stops.
name	string	Yes	250	Name of delivery location or recipient.
address	string	Yes	500	Full street address.
contact	object	No	—	Contact person details.
location	object	No	—	Geographic coordinates.
tripDate	datetime	Yes	—	Date/time for delivery. Date must match serviceDate.
appointmentTime	string	No	—	Appointment time (HH:mm).
timeWindowStart	datetime	No	—	Start of acceptable time window.
timeWindowEnd	datetime	No	—	End of time window. Must be ≥ timeWindowStart.
durationMinutes	integer	No	—	Estimated duration (minutes).
notes	string	No	—	Special instructions for the driver.
customFields	object	No	—	Key-value pairs for custom data.
load	object	No	—	Load info for capacity planning.
skills	array	No	—	Required driver skills.
driverInstructions	object	No	—	Driver-specific instructions.
source	string	No	—	Source system identifier.
sourceReference	string	No	—	Source system reference.
itemSourceReferences	array	Yes	—	Item references being delivered. Min 1.
sequence	integer	No	—	Preferred delivery sequence number.
requireProofOfDelivery	boolean	No	—	Proof of delivery required. Default: true.

Example Drop-off Stop:

{
  "stopSourceReference": "DROPOFF-001",
  "name": "Customer ABC",
  "address": "456 Customer St, Melbourne VIC 3000",
  "contact": { "name": "Jane Doe", "phone": "+61498765432", "email": "[email protected]" },
  "location": { "latitude": -37.8136, "longitude": 144.9631 },
  "tripDate": "2024-01-15T14:00:00",
  "timeWindowStart": "2024-01-15T13:00:00",
  "timeWindowEnd": "2024-01-15T17:00:00",
  "durationMinutes": 15,
  "notes": "Ring doorbell twice",
  "itemSourceReferences": ["ITEM-001"],
  "sequence": 1,
  "requireProofOfDelivery": true
}

Nested Object Definitions

Contact

Field	Type	Required	Description
name	string	No	Contact person’s full name.
phone	string	No	Contact phone number.
email	string	No	Contact email address.

Coordinates

Field	Type	Required	Description
latitude	decimal	No	Latitude coordinate.
longitude	decimal	No	Longitude coordinate.

Load

Field	Type	Required	Description
weight	decimal	No	Weight in kilograms.
length	decimal	No	Length in centimeters.
width	decimal	No	Width in centimeters.
height	decimal	No	Height in centimeters.
volume	decimal	No	Volume in cubic centimeters.
quantity	integer	No	Number of units.

Shipment Contents (all fields are optional booleans):

Field	Description
isAlcohol	Contains alcohol
isTobacco	Contains tobacco products
isPrescriptionMedication	Contains prescription medication
isDangerousGoods	Contains dangerous goods
isMeat	Contains meat products
isPork	Contains pork
isBeef	Contains beef
isFragile	Contents are fragile
isFlowers	Contains flowers
isCake	Contains cake
isFood	Contains food items
isLiquid	Contains liquids
isNotRotatable	Cannot be rotated during transport
isGlass	Contains glass items
isBaked	Contains baked goods
mustBeUpright	Must be kept upright during transport

Driver Instructions

Field	Type	Required	Description
notes	string	No	General notes for the driver.
accessInstructions	string	No	Instructions for accessing the location.
parkingInstructions	string	No	Parking instructions.

Validation Rules

1. Unique References: All itemSourceReference values must be unique within the batch. All stopSourceReference values must be unique across all pickups and dropoffs.
2. Date Consistency: All tripDate values must have the same date portion as serviceDate.
3. Item Coverage: Every item must be referenced in at least one pickup and one dropoff. Stops can only reference items that exist in the items array.
4. Time Windows: If both timeWindowStart and timeWindowEnd are provided, end must be ≥ start.
5. Minimum Requirements: At least 1 item, 1 pickup, and 1 dropoff. Each stop must have at least 1 item reference.

Complete Example Request

{
  "batchSourceReference": "BATCH-2024-001",
  "batchDescription": "Morning deliveries - North Region",
  "teamSourceReference": "TEAM-NORTH",
  "customerSourceReference": "CUST-123",
  "serviceDate": "2024-01-15",
  "items": [
    {
      "itemSourceReference": "ITEM-001",
      "barcode": "1234567890123",
      "description": "Large Package",
      "quantity": 1,
      "contents": { "isFragile": true },
      "load": { "weight": 10.5, "length": 50, "width": 40, "height": 30 }
    },
    {
      "itemSourceReference": "ITEM-002",
      "barcode": "1234567890124",
      "description": "Small Package",
      "quantity": 2
    }
  ],
  "pickups": [
    {
      "stopSourceReference": "PICKUP-001",
      "name": "Central Warehouse",
      "address": "100 Warehouse Road, Sydney NSW 2000",
      "contact": { "name": "Warehouse Manager", "phone": "+61400000001" },
      "tripDate": "2024-01-15T08:00:00",
      "timeWindowStart": "2024-01-15T07:00:00",
      "timeWindowEnd": "2024-01-15T10:00:00",
      "durationMinutes": 20,
      "itemSourceReferences": ["ITEM-001", "ITEM-002"],
      "warehouseSourceReference": "WH-CENTRAL"
    }
  ],
  "dropoffs": [
    {
      "stopSourceReference": "DROPOFF-001",
      "name": "Customer A",
      "address": "50 Main Street, Parramatta NSW 2150",
      "contact": { "name": "Alice Johnson", "phone": "+61400000002", "email": "[email protected]" },
      "tripDate": "2024-01-15T11:00:00",
      "timeWindowStart": "2024-01-15T10:00:00",
      "timeWindowEnd": "2024-01-15T12:00:00",
      "durationMinutes": 10,
      "notes": "Leave at front door if not home",
      "itemSourceReferences": ["ITEM-001"],
      "sequence": 1,
      "requireProofOfDelivery": true
    },
    {
      "stopSourceReference": "DROPOFF-002",
      "name": "Customer B",
      "address": "75 Side Street, Chatswood NSW 2067",
      "contact": { "name": "Bob Smith", "phone": "+61400000003" },
      "tripDate": "2024-01-15T13:00:00",
      "timeWindowStart": "2024-01-15T12:00:00",
      "timeWindowEnd": "2024-01-15T14:00:00",
      "durationMinutes": 10,
      "itemSourceReferences": ["ITEM-002"],
      "sequence": 2,
      "requireProofOfDelivery": true
    }
  ]
}

Success Response (200 OK)

{
  "success": true,
  "data": {
    "batchId": "string",
    "stopsCreated": 3,
    "itemsProcessed": 2
  }
}

Error Response (400 Bad Request)

{
  "success": false,
  "errors": [
    {
      "field": "items[0].itemSourceReference",
      "message": "Item source reference is required."
    }
  ]
}

HTTP Status Codes

Code	Description
200	Success — Batch created successfully.
400	Bad Request — Validation errors in request body.
401	Unauthorized — Missing or invalid authentication token.
403	Forbidden — Insufficient permissions.
500	Internal Server Error.

Quick Reference — Required Fields

• Always Required: batchSourceReference, teamSourceReference, serviceDate, items[], pickups[], dropoffs[]
• Per Item: itemSourceReference
• Per Stop (Pickup or Dropoff): stopSourceReference, name, address, tripDate, itemSourceReferences[]

Import Status API

GET /v1/Stops/import/{batchId}/status

Query the current status of a batch import operation. Use the batchId returned from a batch delivery request to track progress.

Authorization: Requires a Bearer Token in the Authorization header.

Path Parameters

Parameter	Type	Required	Description
batchId	string (GUID)	Yes	The unique batch import ID returned from the import operation.

Example Request:

GET https://integration.locate2u.com/v1/Stops/import/a1b2c3d4-e5f6-7890-abcd-ef1234567890/status

Response Fields

Field	Type	Description
batchImportId	string	Unique identifier for the batch import.
status	string	Current status. See Status Values below.
totalCount	integer	Total number of stops submitted.
successCount	integer	Stops successfully imported.
failedCount	integer	Stops that failed to import.
processedCount	integer	Stops processed so far.
progressPercentage	decimal	Progress (0–100).
batchSourceReference	string	External reference for correlation.
createdDate	datetime	When the import was submitted.
startedDate	datetime	When processing started. null if not started.
completedDate	datetime	When processing completed. null if not done.
errors	array	List of errors during import.
successfulStops	array	List of successfully imported stops.

Status Values

Status	Description
Queued	Import received, waiting to be processed.
Importing	Currently being processed.
Completed	All stops successfully imported.
PartiallyCompleted	Some stops succeeded, some failed.
Failed	Import failed completely. Check errors array.

Error Object

Field	Type	Description
rowNumber	integer	Row/index of the failed stop.
sourceReference	string	Source reference of the failed stop.
stage	string	PreProcessing, Validation, or Save.
messages	array	Error messages describing what went wrong.

Success Object

Field	Type	Description
stopId	integer	ID of the successfully created stop in Locate2u.
sourceReference	string	Source reference provided during import.

Example — In Progress

{
  "data": {
    "batchImportId": "a1b2c3d4-e5f6-...",
    "status": "Importing",
    "totalCount": 100,
    "successCount": 45,
    "failedCount": 5,
    "processedCount": 50,
    "progressPercentage": 50.00,
    "batchSourceReference": "BATCH-2024-001",
    "createdDate": "2024-01-15T08:00:00Z",
    "startedDate": "2024-01-15T08:00:05Z",
    "completedDate": null,
    "errors": [
      {
        "rowNumber": 12,
        "sourceReference": "STOP-012",
        "stage": "Validation",
        "messages": ["Address is required"]
      }
    ],
    "successfulStops": null
  }
}

Example — Completed Successfully

{
  "data": {
    "batchImportId": "a1b2c3d4-e5f6-...",
    "status": "Completed",
    "totalCount": 50,
    "successCount": 50,
    "failedCount": 0,
    "processedCount": 50,
    "progressPercentage": 100.00,
    "createdDate": "2024-01-15T08:00:00Z",
    "startedDate": "2024-01-15T08:00:05Z",
    "completedDate": "2024-01-15T08:02:30Z",
    "errors": [],
    "successfulStops": [
      { "stopId": 12345, "sourceReference": "STOP-001" },
      { "stopId": 12346, "sourceReference": "STOP-002" }
    ]
  }
}

Example — Partially Completed

{
  "data": {
    "batchImportId": "a1b2c3d4-e5f6-...",
    "status": "PartiallyCompleted",
    "totalCount": 10,
    "successCount": 8,
    "failedCount": 2,
    "processedCount": 10,
    "progressPercentage": 100.00,
    "errors": [
      { "rowNumber": 3, "sourceReference": "STOP-003", "stage": "Validation",
        "messages": ["Invalid date format for tripDate"] },
      { "rowNumber": 7, "sourceReference": "STOP-007", "stage": "Save",
        "messages": ["Duplicate sourceReference already exists"] }
    ],
    "successfulStops": [
      { "stopId": 12350, "sourceReference": "STOP-001" },
      { "stopId": 12351, "sourceReference": "STOP-002" }
    ]
  }
}

HTTP Status Codes

Code	Description
200	Success — Status retrieved successfully.
400	Bad Request — Invalid batch ID format (expected GUID).
401	Unauthorized — Missing or invalid authentication token.
403	Forbidden — Insufficient permissions.
404	Not Found — Batch import not found.
500	Internal Server Error.

Polling Recommendations

1. Initial Wait: After submitting a batch, wait 2–5 seconds before the first status check.
2. Polling Interval: Poll every 5–10 seconds while status is Queued or Importing.
3. Completion: Stop polling once status is Completed, PartiallyCompleted, or Failed.
4. Timeout: Implement a maximum polling duration based on your batch size.

Interactive API Documentation

For detailed request/response schemas and the ability to test API calls directly, visit the interactive Swagger documentation:

https://integration.locate2u.com/swagger/index.html

Get Started Today

Ready to integrate with Locate2u? Follow these steps to get started:

1. Generate API Keys: Log in to the Locate2u App Portal and create your application credentials.
2. Authenticate: Use the OAuth 2.0 Client Credentials flow to obtain an access token.
3. Explore the APIs: Use the Swagger documentation to explore available endpoints.
4. Build Your Integration: Start making API calls to automate your workflows.

If you have questions or need assistance, contact us at [email protected]