Bulk operations on data objects. Flow: Create job -> Upload NDJSON data -> Start processing -> Poll progress -> Download results -> Cleanup.
openapi: 3.2.0
info:
version: v1
title: Spotio 2.0 Data Objects Bulk Jobs API
description: 'Bulk operations on data objects. Flow: Create job -> Upload NDJSON data -> Start processing -> Poll progress -> Download results -> Cleanup.'
contact:
name: Contact us
url: https://spotio.com/contact/
email: support@spotio.com
servers:
- url: https://api.spotio2.com
description: Production
- url: https://app-test.spotio2.com
description: Test
security:
- Bearer: []
tags:
- name: DataObjectsBulkJobs
description: 'Bulk operations on data objects. Flow: Create job -> Upload NDJSON data -> Start processing -> Poll progress -> Download results -> Cleanup.'
paths:
/api/jobs/dataObjects/bulk:
post:
tags:
- DataObjectsBulkJobs
summary: Create a bulk job
description: 'Creates a new bulk job for the specified data object type. After creation, upload NDJSON data files, then start processing. Allowed operations: ''create'', ''update'', ''patch''.'
requestBody:
content:
application/merge-patch+json:
schema:
$ref: '#/components/schemas/Spotio.Frontend.ViewModel.DataObjects.Bulk.CreateBulkJobRequest'
application/json-patch+json:
schema:
$ref: '#/components/schemas/Spotio.Frontend.ViewModel.DataObjects.Bulk.CreateBulkJobRequest'
application/json:
schema:
$ref: '#/components/schemas/Spotio.Frontend.ViewModel.DataObjects.Bulk.CreateBulkJobRequest'
text/json:
schema:
$ref: '#/components/schemas/Spotio.Frontend.ViewModel.DataObjects.Bulk.CreateBulkJobRequest'
application/*+json:
schema:
$ref: '#/components/schemas/Spotio.Frontend.ViewModel.DataObjects.Bulk.CreateBulkJobRequest'
responses:
'200':
description: Success
content:
text/plain:
schema:
$ref: '#/components/schemas/Spotio.Frontend.ViewModel.DataObjects.Bulk.BulkJob'
application/json:
schema:
$ref: '#/components/schemas/Spotio.Frontend.ViewModel.DataObjects.Bulk.BulkJob'
text/json:
schema:
$ref: '#/components/schemas/Spotio.Frontend.ViewModel.DataObjects.Bulk.BulkJob'
'400':
description: Bad Request
security:
- Bearer: []
servers:
- url: https://api.spotio2.com
description: Production
- url: https://app-test.spotio2.com
description: Test
/api/jobs/dataObjects/bulk/inprogress:
get:
tags:
- DataObjectsBulkJobs
summary: Get in-progress bulk jobs
responses:
'200':
description: Success
content:
text/plain:
schema:
type: array
items:
$ref: '#/components/schemas/Spotio.Frontend.ViewModel.DataObjects.Bulk.BulkJob'
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Spotio.Frontend.ViewModel.DataObjects.Bulk.BulkJob'
text/json:
schema:
type: array
items:
$ref: '#/components/schemas/Spotio.Frontend.ViewModel.DataObjects.Bulk.BulkJob'
security:
- Bearer: []
servers:
- url: https://api.spotio2.com
description: Production
- url: https://app-test.spotio2.com
description: Test
/api/jobs/dataObjects/bulk/{id}:
get:
tags:
- DataObjectsBulkJobs
summary: Get a bulk job
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Success
content:
text/plain:
schema:
$ref: '#/components/schemas/Spotio.Frontend.ViewModel.DataObjects.Bulk.BulkJob'
application/json:
schema:
$ref: '#/components/schemas/Spotio.Frontend.ViewModel.DataObjects.Bulk.BulkJob'
text/json:
schema:
$ref: '#/components/schemas/Spotio.Frontend.ViewModel.DataObjects.Bulk.BulkJob'
'404':
description: Not Found
security:
- Bearer: []
servers:
- url: https://api.spotio2.com
description: Production
- url: https://app-test.spotio2.com
description: Test
/api/jobs/dataObjects/bulk/{id}/data:
put:
tags:
- DataObjectsBulkJobs
summary: Upload bulk job data
description: Upload an NDJSON file (one JSON object per line) as the raw request body. Each line must be a valid JSON object matching the BulkDataObjectRequest schema (see Schemas section for field definitions). Multiple files can be uploaded to the same job. Content-Type should be application/octet-stream.
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
requestBody:
description: Upload NDJSON data. Each line must be a valid JSON object matching the schema.
required: true
content:
application/x-ndjson:
schema:
$ref: '#/components/schemas/Spotio.DataObjects.Client.Contract.Bulks.BulkDataObjectRequest'
examples:
default:
value: '{"Fields": [{"FieldId": "f-title", "Label": "Title", "Value": "Value A", "FormattedValue": "Value A"}], "TypeId": 101, "OwnerId": 1}
{"Fields": [{"FieldId": "f-title", "Label": "Title", "Value": "Value B", "FormattedValue": "Value B"}], "TypeId": 101, "OwnerId": 2}
{"Fields": [{"FieldId": "f-email", "Label": "Email", "Value": "test@example.com", "FormattedValue": "test@example.com"}], "TypeId": 101, "OwnerId": 1, "Pin": {"Id": "ChIJ...", "Lat": 40.7128, "Lng": -74.0060, "Address": "290 Broadway, New York, NY 10007, USA", "Street": "Broadway", "HouseNumber": "290", "Zip": "10007", "City": "New York", "Country": "USA", "ShortAddress": "290 Broadway"}}'
application/octet-stream:
schema:
$ref: '#/components/schemas/Spotio.DataObjects.Client.Contract.Bulks.BulkDataObjectRequest'
examples:
default:
value: '{"Fields": [{"FieldId": "f-title", "Label": "Title", "Value": "Value A", "FormattedValue": "Value A"}], "TypeId": 101, "OwnerId": 1}
{"Fields": [{"FieldId": "f-title", "Label": "Title", "Value": "Value B", "FormattedValue": "Value B"}], "TypeId": 101, "OwnerId": 2}
{"Fields": [{"FieldId": "f-email", "Label": "Email", "Value": "test@example.com", "FormattedValue": "test@example.com"}], "TypeId": 101, "OwnerId": 1, "Pin": {"Id": "ChIJ...", "Lat": 40.7128, "Lng": -74.0060, "Address": "290 Broadway, New York, NY 10007, USA", "Street": "Broadway", "HouseNumber": "290", "Zip": "10007", "City": "New York", "Country": "USA", "ShortAddress": "290 Broadway"}}'
responses:
'200':
description: File uploaded successfully
content:
text/plain:
schema:
$ref: '#/components/schemas/Spotio.Frontend.ViewModel.DataObjects.Bulk.BulkJobFile'
application/json:
schema:
$ref: '#/components/schemas/Spotio.Frontend.ViewModel.DataObjects.Bulk.BulkJobFile'
text/json:
schema:
$ref: '#/components/schemas/Spotio.Frontend.ViewModel.DataObjects.Bulk.BulkJobFile'
'400':
description: Bad Request
'404':
description: Not Found
default:
description: Error
security:
- Bearer: []
servers:
- url: https://api.spotio2.com
description: Production
- url: https://app-test.spotio2.com
description: Test
/api/jobs/dataObjects/bulk/{id}/start:
post:
tags:
- DataObjectsBulkJobs
summary: Start processing a bulk job
description: Marks the job as ready for processing. At least one data file must be uploaded before starting. The job must be in 'Open' state.
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Success
content:
text/plain:
schema:
$ref: '#/components/schemas/Spotio.Frontend.ViewModel.DataObjects.Bulk.BulkJob'
application/json:
schema:
$ref: '#/components/schemas/Spotio.Frontend.ViewModel.DataObjects.Bulk.BulkJob'
text/json:
schema:
$ref: '#/components/schemas/Spotio.Frontend.ViewModel.DataObjects.Bulk.BulkJob'
'400':
description: Bad Request
'404':
description: Not Found
security:
- Bearer: []
servers:
- url: https://api.spotio2.com
description: Production
- url: https://app-test.spotio2.com
description: Test
/api/jobs/dataObjects/bulk/{id}/progress:
get:
tags:
- DataObjectsBulkJobs
summary: Get bulk job progress
description: Returns current processing progress including per-file breakdown of processed and failed records.
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Success
content:
text/plain:
schema:
$ref: '#/components/schemas/Spotio.Frontend.ViewModel.DataObjects.Bulk.BulkJobProgress'
application/json:
schema:
$ref: '#/components/schemas/Spotio.Frontend.ViewModel.DataObjects.Bulk.BulkJobProgress'
text/json:
schema:
$ref: '#/components/schemas/Spotio.Frontend.ViewModel.DataObjects.Bulk.BulkJobProgress'
'404':
description: Not Found
security:
- Bearer: []
servers:
- url: https://api.spotio2.com
description: Production
- url: https://app-test.spotio2.com
description: Test
/api/jobs/dataObjects/bulk/{id}/results/succeeded:
get:
tags:
- DataObjectsBulkJobs
summary: Download succeeded results
description: Downloads an NDJSON file with successfully processed records. Each line contains FileId, DataObjectId, and the original Data.
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Success
'404':
description: Not Found
security:
- Bearer: []
servers:
- url: https://api.spotio2.com
description: Production
- url: https://app-test.spotio2.com
description: Test
/api/jobs/dataObjects/bulk/{id}/results/failed:
get:
tags:
- DataObjectsBulkJobs
summary: Download failed results
description: Downloads an NDJSON file with failed records. Each line contains FileId, Error message, and the original Data.
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Success
'404':
description: Not Found
security:
- Bearer: []
servers:
- url: https://api.spotio2.com
description: Production
- url: https://app-test.spotio2.com
description: Test
/api/jobs/dataObjects/bulk/{id}/cleanup:
delete:
tags:
- DataObjectsBulkJobs
summary: Cleanup a bulk job
description: 'Cleans up bulk job resources: drops the staging data table, deletes result files, and/or deletes uploaded files. The job state is set to ''Aborted''. All flags default to true.'
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/merge-patch+json:
schema:
$ref: '#/components/schemas/Spotio.Frontend.ViewModel.DataObjects.Bulk.CleanupBulkJobRequest'
application/json-patch+json:
schema:
$ref: '#/components/schemas/Spotio.Frontend.ViewModel.DataObjects.Bulk.CleanupBulkJobRequest'
application/json:
schema:
$ref: '#/components/schemas/Spotio.Frontend.ViewModel.DataObjects.Bulk.CleanupBulkJobRequest'
text/json:
schema:
$ref: '#/components/schemas/Spotio.Frontend.ViewModel.DataObjects.Bulk.CleanupBulkJobRequest'
application/*+json:
schema:
$ref: '#/components/schemas/Spotio.Frontend.ViewModel.DataObjects.Bulk.CleanupBulkJobRequest'
responses:
'200':
description: Success
'400':
description: Bad Request
'404':
description: Not Found
security:
- Bearer: []
servers:
- url: https://api.spotio2.com
description: Production
- url: https://app-test.spotio2.com
description: Test
components:
schemas:
Spotio.Frontend.ViewModel.DataObjects.Bulk.BulkJob:
type: object
additionalProperties: false
properties:
id:
type:
- string
- 'null'
operation:
type:
- string
- 'null'
dataObjectTypeId:
type: integer
format: int32
createdById:
type: integer
format: int32
createdDate:
type: string
format: date-time
updatedDate:
type: string
format: date-time
state:
type:
- string
- 'null'
Spotio.Frontend.ViewModel.DataObjects.Bulk.BulkJobFile:
type: object
additionalProperties: false
properties:
id:
type:
- string
- 'null'
bulkJobId:
type:
- string
- 'null'
partNumber:
type: integer
format: int32
size:
type: integer
format: int64
recordCount:
type: integer
format: int32
state:
type:
- string
- 'null'
createdDate:
type: string
format: date-time
Spotio.DataObjects.Client.Contract.Bulks.BulkPin:
type: object
additionalProperties: false
properties:
id:
type: integer
format: int32
lat:
type: number
format: double
lng:
type: number
format: double
placeId:
type:
- string
- 'null'
address:
type:
- string
- 'null'
street:
type:
- string
- 'null'
houseNumber:
type:
- string
- 'null'
zip:
type:
- string
- 'null'
city:
type:
- string
- 'null'
state:
type:
- string
- 'null'
country:
type:
- string
- 'null'
shortAddress:
type:
- string
- 'null'
skipGeocoding:
type: boolean
Spotio.Frontend.ViewModel.DataObjects.Bulk.BulkJobProgress:
type: object
additionalProperties: false
properties:
id:
type:
- string
- 'null'
state:
type:
- string
- 'null'
operation:
type:
- string
- 'null'
dataObjectTypeId:
type: integer
format: int32
createdById:
type: integer
format: int32
createdDate:
type: string
format: date-time
processingStartedAt:
type:
- string
- 'null'
format: date-time
totalRecordsToProcess:
type: integer
format: int32
recordsProcessed:
type: integer
format: int32
recordsFailed:
type: integer
format: int32
errorMessage:
type:
- string
- 'null'
files:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/Spotio.Frontend.ViewModel.DataObjects.Bulk.BulkJobFileProgress'
Spotio.DataObjects.Client.Contract.Bulks.BulkFieldValue:
type: object
additionalProperties: false
properties:
fieldId:
type:
- string
- 'null'
label:
type:
- string
- 'null'
value:
type:
- string
- 'null'
formattedValue:
type:
- string
- 'null'
values:
type:
- array
- 'null'
items:
type: string
Spotio.Frontend.ViewModel.DataObjects.Bulk.BulkJobFileProgress:
type: object
additionalProperties: false
properties:
id:
type:
- string
- 'null'
partNumber:
type: integer
format: int32
state:
type:
- string
- 'null'
recordCount:
type: integer
format: int32
recordsProcessed:
type: integer
format: int32
recordsFailed:
type: integer
format: int32
Spotio.Frontend.ViewModel.DataObjects.Bulk.CreateBulkJobRequest:
type: object
additionalProperties: false
properties:
operation:
type:
- string
- 'null'
dataObjectTypeId:
type: integer
format: int32
Spotio.DataObjects.Client.Contract.Bulks.BulkDataObjectRequest:
type: object
additionalProperties: false
properties:
id:
type:
- string
- 'null'
stageId:
type:
- integer
- 'null'
format: int32
ownerId:
type:
- integer
- 'null'
format: int32
pin:
$ref: '#/components/schemas/Spotio.DataObjects.Client.Contract.Bulks.BulkPin'
source:
type:
- string
- 'null'
externalDataObjectId:
type:
- string
- 'null'
fields:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/Spotio.DataObjects.Client.Contract.Bulks.BulkFieldValue'
typeId:
type: integer
format: int32
parentId:
type:
- string
- 'null'
createdAt:
type:
- string
- 'null'
format: date-time
updatedAt:
type:
- string
- 'null'
format: date-time
collaboratorIds:
type:
- array
- 'null'
items:
type: integer
format: int32
Spotio.Frontend.ViewModel.DataObjects.Bulk.CleanupBulkJobRequest:
type: object
additionalProperties: false
properties:
dropDataTable:
type: boolean
deleteResultFiles:
type: boolean
deleteUploadedFiles:
type: boolean
securitySchemes:
Bearer:
type: apiKey
description: 'Enter the Bearer Authorization string as following: `Bearer Generated-JWT-Token`'
name: Authorization
in: header