First Import Walkthrough

This walkthrough covers a complete import: sending data, receiving a job, polling it, and reading the outcome. We’ll import an asset, but every import resource follows the same pattern.

The asynchronous import model

The Praedico Integration Platform never processes your data inline:

1. You POST a JSON payload to a resource endpoint.
2. The API validates the request shape and immediately returns 202 Accepted with a job document. Your data is now queued, not yet applied.
3. A background worker processes the job.
4. You poll GET /v2/status/{id} until the job reaches a terminal state.

Why asynchronous?

Imports can be sizeable and take significant processing. The job model lets you submit data quickly and check the outcome on your own schedule, without holding a long-lived connection open.

Walkthrough

1. Set your variables (from Getting Started):

   export BASE_URL="https://<api-host>/<your-tenant-prefix>"
   export API_KEY="<your-api-key>"   # form: <key>_<id>

2. Submit the import. Asset endpoints accept a JSON array, so you can send one or many:

   curl -i -X POST "$BASE_URL/v2/assets" \
     -H "Api-Key: $API_KEY" \
     -H "Content-Type: application/json" \
     -d '[
       {
         "id": "External-Id",
         "subAreaId": "004",
         "name": "Asset Name",
         "description": "Asset Description",
         "status": "A",
         "assetCategoryId": "TRACK-RAIL",
         "assetTypeId": "OBJ007",
         "shapeType": "LineString",
         "startPoint": 1.0,
         "endPoint": 2.0,
         "geolocation": {
           "linearReferenceStart": "303-79A",
           "linearReferenceEnd": "303-79A",
           "locationStart": 1.0,
           "locationEnd": 2.0,
           "locationUnit": "m"
         }
       }
     ]'

3. Read the 202 Accepted response. You get a job:

   {
     "id": 1234,
     "importJobType": "Asset",
     "importJobStatus": "Pending",
     "statusUrl": "/v2/status/1234",
     "output": null
   }

   Keep the id (or statusUrl) to track this import.

4. Poll the job until it finishes:

   curl "$BASE_URL/v2/status/1234" \
     -H "Api-Key: $API_KEY"

   A successful run returns:

   {
     "id": 1234,
     "importJobType": "Asset",
     "importJobStatus": "Succeeded",
     "statusUrl": "/v2/status/1234",
     "output": { "message": "..." }
   }

Understanding the response

Job status values

importJobStatus	Meaning	What to do
Pending	Accepted and queued, not started	Keep polling
Processing	The worker is applying your data	Keep polling
Succeeded	All records applied	Done
PartiallySucceeded	Some records applied, some rejected	Read output.message; fix and re-submit the failed records
Failed	The job did not apply	Read output.message; fix and re-submit

The output field

While a job is Pending/Processing, output is usually null. Once the job reaches a terminal state, output.message carries details. For PartiallySucceeded/Failed jobs, this includes which records failed and why.

Polling guidance

Poll at a sensible interval (for example every few seconds, backing off for large jobs) rather than in a tight loop. Stop as soon as the status is Succeeded, PartiallySucceeded, or Failed.

What’s next

• The payload above is a minimal asset. See the Data & Payload Guide for every field, validation rule, and per-resource examples.
• Hitting errors? Common Errors lists causes and fixes.
• Need full endpoint and schema detail? Use the interactive API Reference.