The Waste Pickup APIs provide access to AI-generated waste pickup events and their supporting evidence. They enable customers to discover pickup events within a requested time window, review the details of an individual event, and retrieve media evidence for service verification, overage detection, and contamination detection workflows.

🚧

NOTE

The following endpoints use OAuth 2.0 Client Credentials authentication through Motive CIAM. Read the Authentication section for more info.

List waste pickup events

• Endpoint: GET /api/aivision/v1/pickups
• Purpose: Returns a searchable, paginated list of published waste pickup events. You can use filters such as time range, pickup type, loader type, confidence, and pagination parameters to find relevant events.
• Usecase: Use this endpoint as the discovery step in an integration. Retrieve the pickup events for a time period, then use the event identifier to request details or evidence for a specific pickup.

Retrieve a single waste pickup event

• Endpoint: GET /api/aivision/v1/pickups/{id}
• Purpose: Returns the complete details for a specific published waste pickup event, including event timing, vehicle information, location, detection results, confidence, and available media coverage.
• Usecase: Use this endpoint when a user or downstream system needs to investigate an individual pickup, review the detected event, or display detailed pickup information.

Retrieve waste pickup evidence

• Endpoint: GET /api/aivision/v1/pickups/{id}/evidence
• Purpose: Returns time-limited, presigned URLs for the media evidence associated with a waste pickup event. Evidence may include images, videos, and JSON overlays from connected cameras.
• Usecase: Use this endpoint to display visual proof of service, investigate overage or contamination detections, and support missed-pickup or customer-complaint workflows.

Authentication

The Waste Pickup APIs use OAuth 2.0 Client Credentials authentication through Motive CIAM. This flow is intended for server-to-server integrations and does not require an end-user authorization or redirect URI.

📘

Important

Do not use the legacy X-API-Key header with these endpoints. Use the Bearer token described below.

Generate an access token

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

Request

curl --request POST '<https://ciam.gomotive.com/oauth/token'>  
  --header 'Content-Type: application/x-www-form-urlencoded'  
  --data-urlencode 'grant_type=client_credentials'  
  --data-urlencode 'client_id=\<YOUR_CLIENT_ID>'  
  --data-urlencode 'client_secret=\<YOUR_CLIENT_SECRET>'

Request parameters

Response

{  
  "access_token": "\<ACCESS_TOKEN>",  
  "token_type": "Bearer",  
  "expires_in": 7200,
  "created_at": <timestamp>
}

The expires_in value specifies the token lifetime in seconds. Request a new access token after the current token expires.

Authenticate API requests

Include the access token in the Authorization header of every Waste Pickup API request.

curl --request GET  
  '<https://api.gomotive.com/api/aivision/v1/pickups'>  
  --header 'Authorization: Bearer \<ACCESS_TOKEN>'

Replace <ACCESS_TOKEN> with the value returned by the token endpoint.