> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.tryenvoy.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.tryenvoy.ai/_mcp/server.

# Prefixed IDs

## Format

All resource IDs in the Envoy AI API follow a consistent format: a short prefix indicating the resource type, followed by an underscore and a UUID.

```
{prefix}_{uuid}
```

For example: `load_550e8400-e29b-41d4-a716-446655440000`

## Prefix table

| Resource     | Prefix  | Example                                     |
| ------------ | ------- | ------------------------------------------- |
| Load         | `load_` | `load_a1b2c3d4-e5f6-7890-abcd-ef1234567890` |
| Offer        | `ofr_`  | `ofr_a1b2c3d4-e5f6-7890-abcd-ef1234567890`  |
| Carrier      | `car_`  | `car_a1b2c3d4-e5f6-7890-abcd-ef1234567890`  |
| Organization | `org_`  | `org_a1b2c3d4-e5f6-7890-abcd-ef1234567890`  |
| User         | `usr_`  | `usr_a1b2c3d4-e5f6-7890-abcd-ef1234567890`  |
| API Key      | `key_`  | `key_a1b2c3d4-e5f6-7890-abcd-ef1234567890`  |
| Outreach     | `otr_`  | `otr_a1b2c3d4-e5f6-7890-abcd-ef1234567890`  |
| Contact      | `con_`  | `con_a1b2c3d4-e5f6-7890-abcd-ef1234567890`  |

## How they work

Prefixed IDs are returned in all API responses. When you receive an ID from any endpoint, it already includes the prefix:

```json
{
  "id": "load_550e8400-e29b-41d4-a716-446655440000",
  "load_number": "LD-2024-001",
  "status": "pending"
}
```

Use the full prefixed ID when making subsequent API calls:

```bash
curl https://tryenvoy.ai/api/v1/loads/load_550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: <your-api-key>"
```

## Why prefixed IDs

**Self-describing.** You can identify the resource type from the ID alone. When you see `ofr_...` in a log file, you immediately know it refers to an offer.

**Prevent resource mixing.** The API validates that the prefix matches the expected resource type. Passing a `car_` ID to a loads endpoint returns a clear `invalid_id_format` error instead of a confusing "not found."

**Easier debugging.** When IDs appear in logs, error messages, or database records, the prefix tells you what kind of resource is involved without additional context.

## Extracting the raw UUID

If you need the underlying UUID (e.g., for database joins or external system references), strip the prefix:

```python
def strip_prefix(prefixed_id: str) -> str:
    """Remove the resource prefix to get the raw UUID."""
    return prefixed_id.split("_", 1)[1]

strip_prefix("load_550e8400-e29b-41d4-a716-446655440000")
# => "550e8400-e29b-41d4-a716-446655440000"
```

```typescript
function stripPrefix(prefixedId: string): string {
  return prefixedId.split("_").slice(1).join("_");
}

stripPrefix("load_550e8400-e29b-41d4-a716-446655440000");
// => "550e8400-e29b-41d4-a716-446655440000"
```

## Validation

If you pass an ID with the wrong prefix, the API returns a `400` error:

```json
{
  "error": {
    "code": "invalid_id_format",
    "message": "Expected a load ID (load_), got carrier ID (car_).",
    "param": "id"
  }
}
```

Validate prefixes in your code before making requests to catch mismatches early:

```python
def is_valid_load_id(id: str) -> bool:
    return id.startswith("load_")
```