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

How they work

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

1
{
2
  "id": "load_550e8400-e29b-41d4-a716-446655440000",
3
  "load_number": "LD-2024-001",
4
  "status": "pending"
5
}

Use the full prefixed ID when making subsequent API calls:

$
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:

1
def strip_prefix(prefixed_id: str) -> str:
2
    """Remove the resource prefix to get the raw UUID."""
3
    return prefixed_id.split("_", 1)[1]
4
5
strip_prefix("load_550e8400-e29b-41d4-a716-446655440000")
6
# => "550e8400-e29b-41d4-a716-446655440000"

1
function stripPrefix(prefixedId: string): string {
2
  return prefixedId.split("_").slice(1).join("_");
3
}
4
5
stripPrefix("load_550e8400-e29b-41d4-a716-446655440000");
6
// => "550e8400-e29b-41d4-a716-446655440000"

Validation

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

1
{
2
  "error": {
3
    "code": "invalid_id_format",
4
    "message": "Expected a load ID (load_), got carrier ID (car_).",
5
    "param": "id"
6
  }
7
}

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

1
def is_valid_load_id(id: str) -> bool:
2
    return id.startswith("load_")