Skip to main content
Version: v5.3

Import and async tasks

Use the import API to create individuals of many classes in one request and to join them by their source-system keys. A real import is queued and returns a task ID. You poll the task to get the outcome. Large relationship loads work the same way. For more information, see Importing individuals.

This section contains the following API calls:

Before you start​

Every call needs an Authorization: Bearer <token> header and the nsfilter query parameter.

  • Individuals land in the ontology's live version. Until you promote the first version, a queued import, an undo, and a bulk relationship load return 409.
  • Every class you import into needs a live collection mapping with a collection. For more information, see Individuals.
  • On the /ontologies/{ontologyId}/import routes, nsfilter must name only namespaces the ontology belongs to. Otherwise the call returns 404.
  • You can't cancel or delete an async task.

One ID links the calls on this page. The _taskId that an import returns is the ID you poll with Get an async task and the ID you pass to Undo an import. The service also stamps it on every individual the import creates, at properties._provenance.asyncTaskId.

For the full permission model, see Permissions.

Import individuals​

Creates or updates individuals across several classes, and sets relationships between them. The body is a flat JSON array of individuals. Options are query parameters.

By default the import is queued and returns 202 with a task ID. A 202 means the service stored the request and will run it, not that the data conforms. To check the result, poll Get an async task and read _response._body._conforms.

To validate without writing, set dryRun=true. A dry run answers inline with 200 if the data conforms or 422 if it doesn't. Only a dry run returns the per-element plan, which shows what each element would do and why a conflict occurred.

You need INDIVIDUALS_CREATE on every _classId, and INDIVIDUALS_EDIT on every class whose elements carry import-form relationships.

Endpoints​

POST /aosvc/api/v1/ontologies/{ontologyId}/import

Parameters​

Path​

ParameterTypeDescriptionRequired
ontologyIdStringThe ID of the application ontology.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace filter. Must name only namespaces the ontology belongs to.Required
dryRunBooleanSet to true to validate and answer inline without writing or queuing anything.Optional, default is false
modeStringUPSERT matches existing individuals on their external key and updates them. CREATE_ONLY always creates.Optional, default is UPSERT
rollbackBooleanSet to false to keep what a failed import created. When true, a failed import deletes the individuals it created.Optional, default is true
facetsStringENFORCE rejects value-facet failures, such as datatype and range checks. REPORT turns them into warnings. Count checks stay enforced.Optional, default is ENFORCE
modelRevisionIntegerThe ontology revision to validate against.Optional, default is the current revision

Body​

A non-empty JSON array of individuals, up to 10 MB. Order doesn't matter. The service groups elements by class.

ParameterTypeDescriptionRequired
_classIdStringThe ID of the individual's class.Required
_externalKeyFieldsArrayThe fields that form the external key, as a non-empty array of field names. Must be the same for every element of a class. Omit it, or send null, to use the key declared on the class. Under UPSERT, a class with no key fields, sent or declared, fails.Optional
_nameStringThe display name. Must be a non-blank string or null. Any other value fails validation for the element's class.Optional
_relationshipsArrayAn array of relationship objects from this individual, in import form or native form. See the following table.Optional

Any other field is stored on the item, as in Create individuals.

External keys have the form field=value, with several pairs joined by |, for example "_sourceKey=r-1". The service doesn't store this combined key. Under UPSERT, and for _parentExternalKey and _childExternalKeys, it matches existing individuals on the _externalKeyFields themselves, at the path you sent them. A number matches its text form. A real import also asks the Item Service to index those fields on each class's collection. To find an imported individual, search on its key field. A blank key, a key that appears twice in the payload, or a key that matches more than one existing individual makes that element a conflict. A conflicting element isn't written, and the import doesn't conform.

Each _relationships entry uses one of two forms:

FormFieldsTargets
Import form_propertyName; _parentIndividualId or _parentExternalKey; _childIndividualIds, _childExternalKeys, or both. _childExternalKeys needs _targetClassId.Can be individuals created by the same request.
Native form_userType, _relatedToIds, and optional _customAttributes, as in Create individuals.Must already exist. On an existing individual, the entries replace its stored relationships of each _userType you send.

Note: Import-form relationships replace. After all classes are written, the import sets each parent and property to exactly the targets you name, so naming one target for an existing individual removes its other relationships of that type. Send the complete set of targets. An empty _childExternalKeys removes all of them. A rollback doesn't restore removed relationships, and a dry run skips this step.

An import-form relationship with at least one target counts toward a required relationship of its source. So you can import an individual and its required relationship in the same request.

Example:

[
{
"_classId": "5e7f9a1b-3c2d-4e6f-8a0b-1c3d5e7f9a20",
"_externalKeyFields": ["_sourceKey"],
"_sourceKey": "r-1",
"_name": "Room 1"
},
{
"_classId": "3f6c1a52-8d0e-4b7a-9c4f-2e1d5b8a7c90",
"_externalKeyFields": ["_sourceKey"],
"_sourceKey": "p-1",
"_name": "Pump A",
"properties": { "flowRate": 42.5 },
"_relationships": [
{
"_propertyName": "locatedAt",
"_parentExternalKey": "_sourceKey=p-1",
"_childExternalKeys": ["_sourceKey=r-1"],
"_targetClassId": "5e7f9a1b-3c2d-4e6f-8a0b-1c3d5e7f9a20"
}
]
}
]

Response​

A queued import returns 202 with a Location header that points at /aosvc/api/v1/async-tasks/{taskId}.

{
"_taskId": "9a1e5f7c-4b2d-4e8a-b6c3-0d7f1e9a2b54",
"_status": "QUEUED",
"_classesQueued": 2,
"_individualsQueued": 2
}

A dry run returns the full result document. In each _classes entry, _plan lists one decision per element. _action is CREATE, UPDATE, SKIP, or CONFLICT. _validation appears when a class fails validation.

{
"_dryRun": true,
"_conforms": true,
"_modelRevision": 7,
"_classesProcessed": 2,
"_totalIndividualsCreated": 0,
"_totalIndividualsUpdated": 0,
"_totalIndividualsSkipped": 0,
"_totalConflicts": 0,
"_totalIssues": 0,
"_classes": [
{
"_classId": "3f6c1a52-8d0e-4b7a-9c4f-2e1d5b8a7c90",
"_requested": 1,
"_created": 0,
"_updated": 0,
"_skipped": 0,
"_conflicts": 0,
"_externalKeyFields": ["_sourceKey"],
"_plan": [
{
"_externalKey": "_sourceKey=p-1",
"_action": "CREATE",
"_individualId": "6702a9f3c1e4b2001f9a1c21"
}
],
"_createdIds": ["6702a9f3c1e4b2001f9a1c21"],
"_conforms": true
}
]
}

Codes​

CodeDescription
200Success. Dry run only: the data conforms.
202Accepted. The import is queued.
400Bad Request. The body isn't a non-empty JSON array or isn't valid JSON, an element has no _classId, _externalKeyFields isn't a non-empty array of field names or differs within a class, _relationships isn't an array of objects, an import-form relationship has a blank _propertyName, no parent, or _childExternalKeys without _targetClassId, dryRun or rollback isn't a Boolean, or nsfilter is missing. On a dry run, also a bad mode or facets value.
401Unauthorized
403Forbidden. A class is missing an INDIVIDUALS_CREATE or INDIVIDUALS_EDIT grant.
404Not Found. Queued import: a _classId isn't in the live version or has no collection mapping, or a _targetClassId isn't in the ontology. Any import: nsfilter names a namespace outside the ontology.
409Conflict. Queued import: the ontology has no live version, or a class's mapping has no collection.
413Payload Too Large. The body is over 10 MB.
422Unprocessable Entity. Dry run only: the data doesn't conform. The body is the result document.
503Service Unavailable. The service couldn't store the request. Nothing was queued; retry.

Get an async task​

Gets the status of a queued job, such as an import, by its task ID. You can read any task in the namespaces that nsfilter names. Fields with no value are omitted.

_status is the task's state, not its verdict. A job that rejects its data still ends COMPLETED. Read the verdict in _response._body.

_statusMeaning
CREATED, QUEUED, IN_PROGRESS, RESETWaiting or running. RESET means the job was interrupted and queued again. Keep polling.
COMPLETEDThe job finished. Read the verdict in _response._body.
FAILEDThe job itself failed. Read the reason in _detailedStatus.

_response._body._handler names the kind of job:

_handlerRaised byVerdict
ONTOLOGY_IMPORTImport individuals_conforms
RELATIONSHIP_BULK_ADDAdd relationships in bulk_accepted. Poll Get a bulk relationship task instead, which also reports the Item Service write.
INDIVIDUAL_PERMISSION_RECONCILEClass, mapping, and permission changes that return an X-AOSVC-Reconciliation-Task-Id headerNone. The job either ran or is FAILED.
NoneConfirming a promotion requestThe body is the promotion outcome. Read the verdict on the promotion request.

Endpoints​

GET /aosvc/api/v1/async-tasks/{taskId}

Parameters​

Path​

ParameterTypeDescriptionRequired
taskIdStringThe task ID.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace filter. The task must belong to one of these namespaces.Required

Response​

_batchCompleted counts the class groups an import has finished. _timeTakenInMilliSecs has whole-second precision. _response appears only once the task is COMPLETED or FAILED. _response._status is the job's HTTP status: 200 for any job that ran to the end, 400 for input the job refused, and 500 otherwise.

{
"_id": "9a1e5f7c-4b2d-4e8a-b6c3-0d7f1e9a2b54",
"_status": "COMPLETED",
"_batchCompleted": 2,
"_reqBodySize": 412,
"_timeTakenInMilliSecs": 1000,
"_namespaces": ["myapp_Xw6AQru7"],
"_metadata": {
"_createdAt": "2026-10-20T10:00:00Z",
"_createdById": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedAt": "2026-10-20T10:00:01Z"
},
"_response": {
"_status": 200,
"_statusMsg": "SUCCESS",
"_body": {
"_handler": "ONTOLOGY_IMPORT",
"_asyncTaskId": "9a1e5f7c-4b2d-4e8a-b6c3-0d7f1e9a2b54",
"_conforms": true,
"_modelRevision": 7,
"_classesProcessed": 2,
"_totalIndividualsCreated": 2,
"_totalIndividualsUpdated": 0,
"_totalIndividualsSkipped": 0,
"_totalConflicts": 0,
"_totalIssues": 0,
"_classes": [
{
"_classId": "3f6c1a52-8d0e-4b7a-9c4f-2e1d5b8a7c90",
"_requested": 1,
"_created": 1,
"_updated": 0,
"_skipped": 0,
"_conflicts": 0,
"_conforms": true
},
{
"_classId": "5e7f9a1b-3c2d-4e6f-8a0b-1c3d5e7f9a20",
"_requested": 1,
"_created": 1,
"_updated": 0,
"_skipped": 0,
"_conflicts": 0,
"_conforms": true
}
],
"_relationships": {
"_requestedEdges": 1,
"_parentsUpdated": 1,
"_edgesSet": 1
}
}
}
}

The import report has counts only. For conflict reasons and validation violations, run the import as a dry run. When an import rolled back, the report includes _rollback. When the task is FAILED, _response._body holds only _error, the reason.

Codes​

CodeDescription
200Success
400Bad Request. The task ID is malformed, or nsfilter is missing.
401Unauthorized
404Not Found. No task with this ID exists in your namespaces.

Undo an import​

Deletes the individuals that an import created. Use it after an import that ran with rollback=false, or to remove an import's data later. Deleting an individual also deletes its relationships.

The service searches the classes that the import wrote to, and finds individuals by the import's task ID stamp. If the service no longer has the import's task, it searches every class of the ontology. An individual that the import only updated isn't selected. An individual the import created is still found after a later update. The call doesn't restore _externalKeyFields.

The deletes run asynchronously in the Item Service. The response says what the service sent, not that the deletes finished. A task ID that matches nothing deletes nothing and returns 200 with an empty _dispatched.

You need INDIVIDUALS_DELETE on every class that the service searches. If any class denies it, the call returns 403 and deletes nothing.

Endpoints​

DELETE /aosvc/api/v1/ontologies/{ontologyId}/import/{asyncTaskId}

Parameters​

Path​

ParameterTypeDescriptionRequired
ontologyIdStringThe ID of the application ontology.Required
asyncTaskIdStringThe _taskId that the import returned.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace filter. Must name only namespaces the ontology belongs to.Required

Response​

FieldDescription
_classesSearchedThe number of classes searched.
_dispatchedOne entry per class the service sent a delete for, with the class ID, collection ID, and Item Service task ID.
_classesWithoutMappingClasses skipped because they have no collection mapping or no collection.
_classesWithoutMatchesMapped classes where no individual carries the stamp. No delete was sent.
_errorsPer-class failures, as "<classId>: <reason>". The other classes still ran.
{
"_asyncTaskId": "9a1e5f7c-4b2d-4e8a-b6c3-0d7f1e9a2b54",
"_ontologyId": "1c3e5a7b-9d2f-4b6a-8c0e-2f4a6b8d0c13",
"_classesSearched": 3,
"_dispatched": [
{
"_classId": "3f6c1a52-8d0e-4b7a-9c4f-2e1d5b8a7c90",
"_collectionId": "6702a8e1c1e4b2001f9a1b10",
"_itemsvcTaskId": "3c8e1f5a-7b2d-4e9a-8f6c-0a4d2b6e8c13"
},
{
"_classId": "5e7f9a1b-3c2d-4e6f-8a0b-1c3d5e7f9a20",
"_collectionId": "6702a8e1c1e4b2001f9a1b22",
"_itemsvcTaskId": "5d0a2c7e-9f4b-4a1c-b8e3-2c6f4d8a0e25"
}
],
"_classesWithoutMapping": [],
"_classesWithoutMatches": ["9b2d4e6f-8a1c-4b3d-9e5f-7a6b8c0d1e23"],
"_errors": []
}

Codes​

CodeDescription
200Success
400Bad Request. The task ID is blank, or nsfilter is missing.
401Unauthorized
403Forbidden. A class that the service searches is missing an INDIVIDUALS_DELETE grant.
404Not Found. nsfilter names a namespace outside the ontology.
409Conflict. The ontology has no live version.

Add relationships in bulk​

Adds many relationships from individuals of a class in one asynchronous request. Unlike Replace relationships for many individuals, this call adds to the stored relationships and doesn't replace them.

The call returns 202 once the service stores the batch. Validation and the write happen later, so a data fault never comes back as an HTTP status here. To get the outcome, poll Get a bulk relationship task. If validation finds any fault, nothing is written.

You need INDIVIDUALS_EDIT on the class or an ancestor.

Endpoints​

POST /aosvc/api/v1/classes/{classId}/individuals/relationships/bulk

Parameters​

Path​

ParameterTypeDescriptionRequired
classIdStringThe ID of the source individuals' class.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace filter. Must name only namespaces the class's ontology belongs to.Required

Body​

A non-empty JSON array of entries. Each source must be an individual of this class or its subclasses. Entries with the same source and _userType are combined into one relationship, unless their _customAttributes differ.

ParameterTypeDescriptionRequired
_userTypeStringThe name of the relationship.Required
_relatedFromIdStringThe ID of the source individual.Required
_relatedToIdsArrayThe IDs of the target individuals.Required
_customAttributesObjectA flat map of key-value pairs on the relationship.Optional

Example:

[
{
"_userType": "locatedAt",
"_relatedFromId": "6702a9f3c1e4b2001f9a1c21",
"_relatedToIds": ["6702a9f3c1e4b2001f9a1d40"]
},
{
"_userType": "feeds",
"_relatedFromId": "6702a9f3c1e4b2001f9a1c21",
"_relatedToIds": ["6702a9f3c1e4b2001f9a1c35", "6702a9f3c1e4b2001f9a1c36"],
"_customAttributes": { "installedYear": 2020 }
}
]

Response​

The Location header points at this batch's poll route, /aosvc/api/v1/classes/{classId}/individuals/relationships/bulk/{taskId}.

{
"_taskId": "c47d2e10-8f3a-4b6c-9d1e-5a7b9c0d2e43",
"_status": "QUEUED",
"_entriesAccepted": 2
}

Codes​

CodeDescription
202Accepted
400Bad Request. The body isn't a non-empty JSON array or isn't valid JSON, or nsfilter is missing.
401Unauthorized
403Forbidden. No INDIVIDUALS_EDIT grant, or the class is a lifecycle class.
404Not Found. The class isn't in the live version, has no collection mapping, or nsfilter names a namespace outside the ontology.
409Conflict. The ontology has no live version, or the live mapping has no collection.
413Payload Too Large. The body is over 10 MB, or the batch is too large for one Item Service request (8 MB by default, counting about 160 bytes of overhead per entry). Split it into smaller batches.
503Service Unavailable. The service couldn't store the batch. Nothing was queued; retry.

Get a bulk relationship task​

Gets the status and verdict of a bulk relationship batch. Poll this route rather than Get an async task, which reports COMPLETED as soon as the batch passes to the Item Service. Fields with no value are omitted.

_status_acceptedMeaning
CREATED, QUEUED, IN_PROGRESS, RESETAbsentWaiting or validating. Nothing is written yet.
COMPLETEDfalseThe batch was refused. Read _error, _errorStatus, and _issues. Nothing was written.
The Item Service task status: IN_PROGRESS, then COMPLETED or FAILEDtrueThe batch passed validation and went to the Item Service. Only COMPLETED means the relationships are written.
COMPLETEDtrueThe batch passed validation, but every relationship was already stored, so nothing was sent. _itemsvcTaskId is absent.
FAILEDAbsentAn unexpected error or a dependency failure. The reason is in _error. An unknown amount may be written; a retry may succeed.

Each entry in _issues has _entryIndex (zero-based), _check, _status, _message, and where relevant the _userType, _relatedFromId, or _relatedToId at fault. _check is one of ENTRY_SHAPE, ENTRY_MISSING_SOURCE, RELATIONSHIP_NOT_DECLARED, TARGET_CLASS_UNBOUND, SOURCE_NOT_FOUND, SOURCE_WRONG_CLASS, TARGET_NOT_FOUND, or FUNCTIONAL_EXCEEDED. The list holds up to 100 issues. At that limit validation stops, _issuesTruncated is true, and _issueCount is a lower bound.

On an accepted batch, _recordsSubmitted counts the relationship records sent, _edgesSubmitted counts new relationships, and _edgesAlreadyStored counts relationships the sources already had.

Endpoints​

GET /aosvc/api/v1/classes/{classId}/individuals/relationships/bulk/{taskId}

Parameters​

Path​

ParameterTypeDescriptionRequired
classIdStringThe ID of the source individuals' class.Required
taskIdStringThe _taskId that Add relationships in bulk returned. An Item Service task ID from _itemsvcTaskId also works.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace filter. The task must belong to one of these namespaces.Required

Response​

A refused batch:

{
"_taskId": "c47d2e10-8f3a-4b6c-9d1e-5a7b9c0d2e43",
"_entriesAccepted": 4,
"_status": "COMPLETED",
"_error": "3 issues found while validating 4 entries — nothing was written. See _issues.",
"_errorStatus": 400,
"_issueCount": 3,
"_issues": [
{
"_entryIndex": 1,
"_check": "RELATIONSHIP_NOT_DECLARED",
"_status": 400,
"_message": "No relationship 'ownedBy' is declared from class 'Pump'",
"_userType": "ownedBy"
}
],
"_accepted": false
}

An accepted batch. _itemsvcTask is the Item Service task as the Item Service returns it, shortened here.

{
"_taskId": "c47d2e10-8f3a-4b6c-9d1e-5a7b9c0d2e43",
"_entriesAccepted": 2,
"_accepted": true,
"_recordsSubmitted": 2,
"_edgesSubmitted": 3,
"_edgesAlreadyStored": 0,
"_itemsvcTaskId": "b7e3c9a1-4d2f-4a8e-9c6b-1f0d3e5a7c92",
"_status": "COMPLETED",
"_itemsvcTask": {
"_id": "b7e3c9a1-4d2f-4a8e-9c6b-1f0d3e5a7c92",
"_status": "COMPLETED"
}
}

Codes​

CodeDescription
200Success
400Bad Request. The task ID isn't a UUID, or nsfilter is missing.
401Unauthorized
403Forbidden. No INDIVIDUALS_READ grant on the class or an ancestor.
404Not Found. No bulk task with this ID exists in your namespaces, or nsfilter names a namespace outside the ontology.