Bulk Export API

API endpoints for creating and managing bulk location exports.

Create Export Request

Endpoint

POST /locations/exports

Creates a new location data export request.

Request

POST /locations/exports
Content-Type: application/json
Authorization: Bearer {access_token}

Request Body

{
  "format": "json",
  "modifiedSince": "2025-06-01T00:00:00Z"
}

Request Fields

Field	Type	Required	Description
format	String	Yes	Output format: json or csv
modifiedSince	ISO 8601 DateTime	No	Only export locations modified after this time (UTC with Z suffix)

Response

Success Response (202 Accepted)

{
  "requestId": "7890abcd-ef12-3456-7890-abcdef123456",
  "status": "PENDING",
  "message": "Export request queued for processing"
}

Response Fields

Field	Type	Description
requestId	UUID	Unique identifier for this export request
status	String	Export status (always PENDING for new requests)
message	String	Human-readable status message

Status Codes

• 202 Accepted - Export request queued successfully
• 400 Bad Request - Invalid request parameters
• 401 Unauthorized - Authentication failed
• 429 Too Many Requests - Rate limit exceeded

Error Response

{
  "error": {
    "code": "INVALID_FORMAT",
    "message": "Unsupported export format. Supported formats: json, csv"
  }
}

Error Codes

• INVALID_FORMAT - Unsupported export format specified
• INVALID_DATE_RANGE - Invalid modifiedSince parameter
• EXPORT_SIZE_EXCEEDED - Requested export would exceed size limits

Get Export Status

Endpoint

GET /locations/exports/{id}

Retrieves the current status of an export request.

Request

GET /locations/exports/{id}
Authorization: Bearer {access_token}

Path Parameters

• id - UUID of the export request

Response

Success Response (200 OK)

{
  "requestId": "7890abcd-ef12-3456-7890-abcdef123456",
  "status": "COMPLETED",
  "exportUrl": "https://downloads.operator.com/exports/7890abcd.json",
  "downloadExpiresAt": "2025-06-09T00:00:00Z",
  "exportTimestamp": "2025-06-08T15:30:00Z",
  "totalCount": 45678
}

Response Fields

Field	Type	When Present	Description
requestId	UUID	Always	Original request ID
status	String	Always	Current export status
exportUrl	URL	If COMPLETED	Signed URL for download
downloadExpiresAt	ISO 8601 DateTime	If COMPLETED	When URL expires (UTC with Z suffix)
exportTimestamp	ISO 8601 DateTime	If COMPLETED	When export was generated (UTC with Z suffix)
totalCount	Number	If COMPLETED	Number of locations exported

Status Codes

• 200 OK - Export status retrieved successfully
• 401 Unauthorized - Authentication failed
• 404 Not Found - Export request not found

Download Export

Request

GET {exportUrl}

The export URL provided in the notification is typically a signed URL that:

• Expires after a set time (e.g., 24 hours)
• Requires no additional authentication
• Returns the file directly

Response Headers

Content-Type: application/json
Content-Disposition: attachment; filename="locations-export-2025-06-08.json"
Content-Length: 123456789

Export Events

Network operators send notifications to RSP-provided webhook endpoints when exports complete or fail.

Export Events Endpoint

RSPs must implement this endpoint to receive export completion notifications:

POST {rsp_webhook_url}/locations/exports/events

Headers

Header	Description	Required
Content-Type	Must be application/json	Yes

Request Body

For successful exports:

{
  "requestId": "7890abcd-ef12-3456-7890-abcdef123456",
  "status": "COMPLETED",
  "exportUrl": "https://downloads.operator.com/exports/7890abcd.json",
  "downloadExpiresAt": "2025-06-09T00:00:00Z",
  "exportTimestamp": "2025-06-08T15:30:00Z",
  "totalCount": 45678
}

For failed exports:

{
  "requestId": "7890abcd-ef12-3456-7890-abcdef123456",
  "status": "FAILED",
  "error": {
    "code": "EXPORT_GENERATION_FAILED",
    "message": "Unable to generate export due to system error"
  }
}

Response Fields

Field	Type	When Present	Description
requestId	UUID	Always	Original request ID
status	String	Always	COMPLETED or FAILED
exportUrl	URL	If COMPLETED	Signed URL for download
downloadExpiresAt	ISO 8601 DateTime	If COMPLETED	When URL expires (UTC with Z suffix)
exportTimestamp	ISO 8601 DateTime	If COMPLETED	When export was generated (UTC with Z suffix)
totalCount	Number	If COMPLETED	Number of locations exported
error	Object	If FAILED	Error details with code and message

Expected Responses

Status	Meaning	Network Operator Action
200 OK	Notification processed successfully	Mark as delivered
202 Accepted	Notification queued for processing	Mark as delivered
400 Bad Request	Invalid notification data	Do not retry
401 Unauthorized	Authentication failed	Check credentials, retry
429 Too Many Requests	Rate limit exceeded	Retry with backoff
500 Internal Server Error	RSP system error	Retry with backoff

Request Examples

Full Export

POST /locations/exports
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "format": "json"
}

Response:

{
  "requestId": "012abc34-5678-90de-f123-4567890abcde",
  "status": "PENDING",
  "message": "Export request queued for processing"
}

Incremental Export

POST /locations/exports
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "format": "csv",
  "modifiedSince": "2025-06-01T00:00:00Z"
}

Response:

{
  "requestId": "345def67-8901-23ab-cdef-4567890abcde",
  "status": "PENDING",
  "message": "Export request queued for processing"
}

Export Notification Example

POST https://rsp.example.com/webhooks/locations/exports/events
Content-Type: application/json

{
  "requestId": "012abc34-5678-90de-f123-4567890abcde",
  "status": "COMPLETED",
  "exportUrl": "https://downloads.networkoperator.com/exports/012abc34.json",
  "downloadExpiresAt": "2025-06-10T00:00:00Z",
  "exportTimestamp": "2025-06-09T15:30:00Z",
  "totalCount": 125432
}