# Getting Started

## Prerequisites

Before you begin integration:

1. Contact the echo carrier team at [IntegrationCarrierAPI@echo.com](mailto:IntegrationCarrierAPI@echo.com) to obtain API credentials (`client_id` and `client_secret`)
2. Obtain an OAuth 2.0 Bearer token via the [EchoSync Authorizer API](/authorizer-api/introduction)
3. Ensure your system can make HTTPS REST API calls with JSON payloads
4. Review the OpenAPI specification for complete endpoint details


## API Endpoints

### Available Loads

Both versions accept identical request bodies and query parameters. See [V1 vs V2](#v1-vs-v2-available-loads) for response differences.

| Method | Endpoint | Purpose |
|  --- | --- | --- |
| POST | `/v2/availableloads` | Search available loads — **recommended** |
| POST | `/v1/availableloads` | Search available loads (legacy) |


**Required query parameters:** `offset` (integer, minimum 0), `limit` (integer, 10–100 in increments of 10)

### Bidding and Booking

| Method | Endpoint | Purpose |
|  --- | --- | --- |
| POST | `/v1/bid` | Place a bid on an available load |
| POST | `/v1/booking` | Book an available load |


## V1 vs V2 Available Loads

**V2 is recomended.** It returns everything V1 does, plus an `echoDriveDeepLink` for each load. New integrations should start with V2.

| Aspect | V1 | V2 |
|  --- | --- | --- |
| **Request** | Identical | Identical |
| **Response** | Not included | `echoDriveDeepLink` URL included per load |
| **Recommendation** | Legacy | **Recommended** |


## Typical Carrier Workflow

### Search and Bid

1. **Search loads** - POST to `/v2/availableloads` with your search criteria
2. **Review results** - Inspect returned loads with pricing, stops, equipment, and special services
3. **Place a bid** - POST to `/v1/bid` with `loadId`, `bidAmount`, and `bidContact`
4. **Receive confirmation** - Response includes `truckloadBidKey`


### Search and Book

1. **Search loads** - POST to `/v2/availableloads`
2. **Book a load** - POST to `/v1/booking` with `loadId`, `bookingAmount`, `bookingContact`, `emptyCity`, and `equipmentType`
3. **Receive confirmation** - Response includes `truckloadBookingKey`


## Pagination

Available loads results are paginated using query parameters:

| Parameter | Required | Description |
|  --- | --- | --- |
| `offset` | Yes | Number of results to skip (minimum 0) |
| `limit` | Yes | Page size: minimum 10, maximum 100, must be a multiple of 10 |


The response `resultSet` object contains `count`, `offset`, `limit`, and `total` for navigating pages.