Create matching job
Request accessPurpose
Submit a new matching job to process your uploaded data and align it with GERS identifiers.
Request data
HTTP method: POST
- Constants and parameters enclosed in curly brackets
{}must be replaced with their values. - See the following Request parameters section with the required and optional parameters tables for these values.
URL format
post
URL format
https://api.tomtom.com/maps/orbis/platform/gem/jobsURL example
post
URL example
https://api.tomtom.com/maps/orbis/platform/gem/jobscurl command example
post
curl command example
curl -X POST "https://api.tomtom.com/maps/orbis/platform/gem/jobs" \ -H "tomtom-api-key: YOUR_API_KEY" \ -H "Authorization: Bearer YOUR_AUTH_TOKEN" \ -H "Content-Type: application/json" \ -H "X-Version: 1" \ -d '{ "storageId": "storage-001", "inputFileName": "your_data.parquet", "matchingType": "road" }'Request headers
| Header | Required | Description |
|---|---|---|
tomtom-api-key | Yes | Your TomTom API key |
Authorization | Yes | Bearer token from Azure CLI |
Content-Type | Yes | Must be application/json |
X-Version | Yes | API version (use 1) |
Request body
{ "storageId": "storage-001", "inputFileName": "your_data.parquet", "matchingType": "road"}Request body parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
storageId | string | Yes | ID of the storage containing your data |
inputFileName | string | Yes | Name of the uploaded Parquet file (including .parquet extension) |
matchingType | string | Yes | Type of matching to perform (currently only road) |
overtureRelease | string | No | Overture Maps release version (defaults to latest) |
Response data
Response example
{ "jobRunId": "job-abc123-def456", "storageId": "storage-001", "inputFileName": "your_data.parquet", "matchingType": "road", "overtureRelease": "<latest-overture-release>", "status": "queued", "createdAt": "2026-01-26T10:30:00Z"}Response fields
| Field | Type | Description |
|---|---|---|
jobRunId | string | Unique identifier for the job |
storageId | string | Storage where input/output files are located |
inputFileName | string | Name of the input file |
matchingType | string | Type of matching performed |
overtureRelease | string | Overture Maps release version used |
status | string | Current job status (queued) |
createdAt | string | ISO 8601 timestamp of job creation |
Error responses
| HTTP Status | Error | Cause | Solution |
|---|---|---|---|
| 400 | Bad Request | Invalid request body | Check JSON format and required fields |
| 401 | Unauthorized | Invalid credentials | Refresh API key or token |
| 404 | Not Found | Storage not found | Verify storage ID |
| 422 | Unprocessable Entity | Invalid parameters | Check input file name and matching type |