--- updatedAt: 2025-11-27T10:33:00.000Z --- # List drivers and pickers Get a paginated list of drivers and pickers (employees) with filtering, searching, and ordering capabilities. Supports filtering by role, department, license status, and active status. # OpenAPI definition ````json { "openapi": "3.0.3", "info": { "title": "MapFlow API", "version": "1.0.0", "x-logo": { "url": "https://api.mapflow.co/static/admin/img/logo-MapFlow.png", "altText": "MapFlow Logo" }, "description": "Complete API for route management and logistics optimization\n\n## Authentication\n\nThe MapFlow API uses API key authentication to secure access to endpoints. All requests must include a valid API key in the headers.\n\n### Getting an API Key\n\nAPI keys are generated and managed by your MapFlow administrator. Contact your administrator to obtain an API key.\n\n### Authentication Methods\n\n#### Method 1: X-API-Key Header (Recommended)\n\nThe recommended method is to send your API key in the `X-API-Key` header:\n\n```bash\ncurl -H \"X-API-Key: mk_your_api_key_here\" \\\n https://api.mapflow.co/api/v1/catalog/delivery-items/\n```\n\n#### Method 2: Authorization Bearer Token\n\nYou can also use the `Authorization` header with the `Bearer` prefix:\n\n```bash\ncurl -H \"Authorization: Bearer mk_your_api_key_here\" \\\n https://api.mapflow.co/api/v1/catalog/delivery-items/\n```\n\n**Note**: MapFlow API keys start with the `mk_` prefix.\n\n### Request Examples\n\n#### With cURL\n\n```bash\n# GET request\ncurl -X GET \\\n -H \"X-API-Key: mk_your_api_key_here\" \\\n -H \"Content-Type: application/json\" \\\n https://api.mapflow.co/api/v1/catalog/delivery-items/\n\n# POST request\ncurl -X POST \\\n -H \"X-API-Key: mk_your_api_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\": \"Test Product\", \"type\": \"product\"}' \\\n https://api.mapflow.co/api/v1/catalog/delivery-items/\n```\n\n#### With Python (requests)\n\n```python\nimport requests\n\nheaders = {\n \"X-API-Key\": \"mk_your_api_key_here\",\n \"Content-Type\": \"application/json\"\n}\n\n# GET request\nresponse = requests.get(\n \"https://api.mapflow.co/api/v1/catalog/delivery-items/\",\n headers=headers\n)\n\n# POST request\ndata = {\"name\": \"Test Product\", \"type\": \"product\"}\nresponse = requests.post(\n \"https://api.mapflow.co/api/v1/catalog/delivery-items/\",\n headers=headers,\n json=data\n)\n```\n\n#### With JavaScript (fetch)\n\n```javascript\nconst apiKey = \"mk_your_api_key_here\";\n\n// GET request\nfetch(\"https://api.mapflow.co/api/v1/catalog/delivery-items/\", {\n method: \"GET\",\n headers: {\n \"X-API-Key\": apiKey,\n \"Content-Type\": \"application/json\"\n }\n})\n .then(response => response.json())\n .then(data => console.log(data));\n\n// POST request\nfetch(\"https://api.mapflow.co/api/v1/catalog/delivery-items/\", {\n method: \"POST\",\n headers: {\n \"X-API-Key\": apiKey,\n \"Content-Type\": \"application/json\"\n },\n body: JSON.stringify({\n name: \"Test Product\",\n type: \"product\"\n })\n})\n .then(response => response.json())\n .then(data => console.log(data));\n```\n\n### Authentication Error Handling\n\nIf your API key is invalid or missing, you will receive a `401 Unauthorized` error:\n\n```json\n{\n \"detail\": \"Invalid API key\"\n}\n```\n\nOther possible errors:\n- `API key expired`: Your API key has expired\n- `API key disabled`: Your API key has been disabled\n- `Access denied for IP `: Your IP address is not authorized\n- `Rate limit per hour exceeded`: You have exceeded your hourly quota\n- `Rate limit per day exceeded`: You have exceeded your daily quota\n\n### Restrictions and Limits\n\nAPI keys can have configured restrictions:\n\n- **IP Restrictions**: Only certain IP addresses can use the key\n- **Domain Restrictions**: Only certain domains can use the key\n- **Rate Limits**: Per-hour and per-day limits to prevent abuse\n- **Scopes**: Access levels (read, write, read_write, admin)\n\n### Security\n\n⚠️ **Important**: Never share your API key publicly. Keep it secret and never commit it to your source code. Use environment variables to store your API keys.\n\n### Support\n\nFor any questions regarding authentication or to obtain an API key, contact your MapFlow administrator or technical support." }, "paths": { "/drivers-pickers/people/": { "get": { "operationId": "drivers_pickers_people_list", "description": "Get a paginated list of drivers and pickers (employees) with filtering, searching, and ordering capabilities. Supports filtering by role, department, license status, and active status.", "summary": "List drivers and pickers", "parameters": [ { "in": "query", "name": "department", "schema": { "type": "string" }, "description": "Filter by department" }, { "in": "query", "name": "has_valid_license", "schema": { "type": "boolean" }, "description": "Filter by valid driving license status" }, { "in": "query", "name": "is_active", "schema": { "type": "boolean" }, "description": "Filter by active status" }, { "name": "ordering", "required": false, "in": "query", "description": "Which field to use when ordering the results.", "schema": { "type": "string" } }, { "name": "page", "required": false, "in": "query", "description": "A page number within the paginated result set.", "schema": { "type": "integer" } }, { "in": "query", "name": "role", "schema": { "type": "string" }, "description": "Filter by role (driver, order_picker)" }, { "in": "query", "name": "search", "schema": { "type": "string" }, "description": "Global search in name, email, phone, employee ID, license number, notes, and tags" } ], "tags": [ "Drivers & Pickers - People" ], "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedDriversPickersListList" } } }, "description": "" } } } } }, "components": { "schemas": { "BlankEnum": { "enum": [ "" ] }, "DepartmentEnum": { "enum": [ "logistics", "delivery", "warehouse", "customer_service", "management", "maintenance", "planning" ], "type": "string", "description": "* `logistics` - Logistique\n* `delivery` - Livraison\n* `warehouse` - Entrepôt\n* `customer_service` - Service client\n* `management` - Direction\n* `maintenance` - Maintenance\n* `planning` - Planification" }, "DriversPickersList": { "type": "object", "description": "Serializer pour la liste des conducteurs/préparateurs (format compact)", "properties": { "id": { "type": "integer", "readOnly": true }, "email": { "type": "string", "format": "email", "title": "Adresse e-mail", "description": "Adresse email utilisée pour la connexion", "maxLength": 254 }, "full_name": { "type": "string", "readOnly": true }, "first_name": { "type": "string", "title": "Prénom", "description": "Prénom de l'utilisateur", "maxLength": 150 }, "last_name": { "type": "string", "title": "Nom", "description": "Nom de famille de l'utilisateur", "maxLength": 150 }, "phone": { "type": "string", "title": "Téléphone", "description": "Numéro de téléphone de l'utilisateur", "pattern": "^\\+?1?\\d{9,15}$", "maxLength": 17 }, "role": { "allOf": [ { "$ref": "#/components/schemas/RoleEnum" } ], "title": "Rôle", "description": "Rôle principal de l'utilisateur dans l'organisation\n\n* `admin` - Administrateur\n* `manager` - Manager\n* `dispatcher` - Dispatcheur\n* `driver` - Livreur/Chauffeur\n* `order_picker` - Préparateur de commande\n* `customer_service` - Service client\n* `analyst` - Analyste\n* `viewer` - Observateur" }, "role_display": { "type": "string", "readOnly": true }, "department": { "title": "Département", "description": "Département de l'utilisateur\n\n* `logistics` - Logistique\n* `delivery` - Livraison\n* `warehouse` - Entrepôt\n* `customer_service` - Service client\n* `management` - Direction\n* `maintenance` - Maintenance\n* `planning` - Planification", "oneOf": [ { "$ref": "#/components/schemas/DepartmentEnum" }, { "$ref": "#/components/schemas/BlankEnum" } ] }, "employee_id": { "type": "string", "title": "ID Employé", "description": "Identifiant employé de l'organisation", "maxLength": 50 }, "organisation_name": { "type": "string", "readOnly": true }, "has_valid_driving_license": { "type": "boolean", "title": "Permis de conduire valide", "description": "Indique si l'employé a un permis de conduire valide" }, "vehicle_types": { "type": "array", "items": { "$ref": "#/components/schemas/VehicleTypesEnum" }, "title": "Types de véhicules autorisés", "description": "Liste des types de véhicules que l'utilisateur peut conduire" }, "vehicle_types_display": { "type": "string", "readOnly": true }, "has_active_contract": { "type": "string", "readOnly": true }, "contract_type": { "type": "string", "readOnly": true }, "is_active": { "type": "boolean", "title": "Actif", "description": "Précise si l’utilisateur doit être considéré comme actif. Décochez ceci plutôt que de supprimer le compte." }, "tags": { "type": "string", "readOnly": true }, "date_joined": { "type": "string", "format": "date-time", "readOnly": true, "title": "Date d'inscription" }, "last_login": { "type": "string", "format": "date-time", "readOnly": true, "nullable": true, "title": "Dernière connexion" } }, "required": [ "email", "first_name", "last_name" ] }, "PaginatedDriversPickersListList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=4" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?page=2" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/DriversPickersList" } } } }, "RoleEnum": { "enum": [ "admin", "manager", "dispatcher", "driver", "order_picker", "customer_service", "analyst", "viewer" ], "type": "string", "description": "* `admin` - Administrateur\n* `manager` - Manager\n* `dispatcher` - Dispatcheur\n* `driver` - Livreur/Chauffeur\n* `order_picker` - Préparateur de commande\n* `customer_service` - Service client\n* `analyst` - Analyste\n* `viewer` - Observateur" }, "VehicleTypesEnum": { "enum": [ "bicycle", "cargo_bike", "electric_scooter", "scooter_50", "scooter_125", "motorcycle", "car", "van_small", "van_medium", "van_large", "van_xl", "truck_small", "truck_medium", "truck_large", "truck_xl", "truck_trailer", "semi_trailer", "refrigerated", "tanker", "flatbed", "other" ], "type": "string", "description": "* `bicycle` - Vélo\n* `cargo_bike` - Vélo cargo\n* `electric_scooter` - Trottinette électrique\n* `scooter_50` - Scooter 50cc\n* `scooter_125` - Scooter 125cc\n* `motorcycle` - Moto\n* `car` - Voiture\n* `van_small` - Fourgonnette <2m³ (PTAC ≤3.5T)\n* `van_medium` - Fourgonnette 2-6m³ (PTAC ≤3.5T)\n* `van_large` - Fourgonnette 6-12m³ (PTAC ≤3.5T)\n* `van_xl` - Fourgonnette >12m³ (PTAC 3.5-7.5T)\n* `truck_small` - Camion 7.5T (12-20m³)\n* `truck_medium` - Camion 19T (20-40m³)\n* `truck_large` - Camion 26T (40-60m³)\n* `truck_xl` - Camion 40T (60-90m³)\n* `truck_trailer` - Camion + Remorque (>90m³)\n* `semi_trailer` - Semi-remorque\n* `refrigerated` - Frigorifique\n* `tanker` - Citerne\n* `flatbed` - Plateau\n* `other` - Autre" } }, "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key authentication for accessing the MapFlow API. Include your API key in the X-API-Key header with every request. Format: \"mk_xxxxx\" (MapFlow API keys always start with \"mk_\"). Contact your administrator to obtain an API key." } } }, "tags": [ { "name": "Drivers & Pickers - People", "description": "Driver/picker management - Manage drivers and pickers (employees) with roles, departments, and licenses" } ], "servers": [ { "url": "https://api.mapflow.co/api/v1/" } ], "x-readme": {} } ````