> For the complete documentation index, see [llms.txt](https://docs.coherent.global/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coherent.global/spark-apis/impex-apis/import.md).

# Import

The import API receives the ZIP file from the [Export](/spark-apis/impex-apis/export.md)API and includes many options to add, replace, or update services in the destination environment. The API is designed not to proceed if a successful import cannot be completed.

## Prerequisites to import Spark services <a href="#api-request" id="api-request"></a>

* Only `1` job can be executed at once per tenant.
* Any destination folders need to already exist and be accessible with the provided authorization.
* The uploaded package size does not exceed the configured limit (default to `200 MB`).

## Import actions for Spark services

The `services_modify` and `services_existing` parameters can be used to control the destination and overwrite behaviors.

* The `services_modify` `service_uri_source` and `service_uri_destination` parameters can be used to map each source service to a destination. This is useful if the folder and service names in production are different than in a lower environment.
* The `services_existing` parameter controls the behavior if the destination already exists.
* Where possible, the existing `version_id` of a service version will be migrated to the new environment (see [Execute API (v3)](/spark-apis/execute-api/execute-api-v3.md) for more information about the `version_id`).

<table><thead><tr><th width="249.33333333333331">Destination</th><th>services_existing parameter</th><th>Import action</th></tr></thead><tbody><tr><td>Service does not currently exist</td><td>does not impact import action</td><td>A new service will be added with all of the service versions included in the source.</td></tr><tr><td>Service currently exists</td><td>not defined</td><td>The upload activity will fail.</td></tr><tr><td>Service currently exists</td><td><code>abort</code></td><td>The upload activity will fail.</td></tr><tr><td>Service currently exists</td><td><code>replace</code></td><td>The destination service and service versions will be replaced by the service in the source. <mark style="color:red;"><strong>Note that the previous</strong></mark> <a data-mention href="/pages/-Mbp1TWI7E1KNb9JlN0_">/pages/-Mbp1TWI7E1KNb9JlN0_</a> <mark style="color:red;"><strong>for the service will no longer be accessible.</strong></mark></td></tr><tr><td>Service currently exists</td><td><code>add_version</code></td><td>The destination service will be updated with the service versions included from the source. The semantic versioning will follow the parameter provided in <code>update_version_type</code>.</td></tr></tbody></table>

## Authorization

* `Bearer {token}` accessible from [Authorization - Bearer token](/spark-apis/authorization-bearer-token.md) or systematically via [Client credentials](/identity-and-access-management/client-credentials.md).
  * The request headers should include a key for `Authorization` with the value `Bearer {token}`.
* API key created from [Authorization - API keys](/spark-apis/authorization-api-keys.md). It must contain [Manage users](/tenant-administration/manage-users.md#user-groups) that are also assigned to [Permissions - Features permissions](/spark-apis/authorization-api-keys/permissions-features-permissions.md) `Spark.Imports.json` or `Spark.AllEncompassingProxy.json`.
  * The request headers should include the keys `x-synthetic-key` and `x-tenant-name` with the values of the API key and tenant name respectively.

## `POST` import job <a href="#api-request" id="api-request"></a>

Returns: Response from [#get-import-status](#get-import-status "mention").

```shellscript
POST /{tenant}/api/v4/import
```

### Path parameters

<table><thead><tr><th width="374">Key</th><th>Value</th></tr></thead><tbody><tr><td><code>tenant</code> *</td><td>Tenant is part of your <a data-mention href="/pages/-MboyUpg0GSvjBVkVMcw#log-in-to-spark">/pages/-MboyUpg0GSvjBVkVMcw#log-in-to-spark</a> URL and also available in the <a data-mention href="/pages/ylWjjoVBLOcB7JZks4Cp#user-menu">/pages/ylWjjoVBLOcB7JZks4Cp#user-menu</a>.</td></tr></tbody></table>

### Request body <a href="#request-body" id="request-body"></a>

`Content-Type: multipart/form-data`

| Key                   | Value                                                                                                                                  |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `file` \*             | File to import from the previous step.                                                                                                 |
| `importRequestEntity` | Stringified JSON content of the `importRequestEntity` parameters. If not provided, sensible defaults will be attempted for the import. |

#### `importRequestEntity` parameters

| Key                      | Value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `inputs.services_modify` | <p>Array of services modify objects. If not provided, it is assumed that the destination is taken from the source <code>folder</code> and <code>service</code> name.</p><p>The primary use of this parameter is to modify the destination of the exported service. Settings will apply only to the noted services.</p><p>JSON Array of the imported service settings:</p><ul><li><code>service\_uri\_source</code> in <code>C.SPARK\_XCALL()</code> <code>{folder}/{service}</code> reference the service provided in the source.</li><li><code>service\_uri\_destination</code> in <code>C.SPARK\_XCALL()</code> <code>{folder}/{service}</code> format to change destination <code>folder</code> and <code>service</code>. If omitted assume the same as <code>service\_uri\_source</code>.</li><li><code>update\_version\_type</code> <code>major</code>, <code>minor</code>, or <code>patch</code>, if not provided assume <code>minor</code> as default. This only applies when <code>services\_existing</code> is <code>add\_version</code>. Alternatively if <code>copy</code> is provided, then Spark will try to use the exact same semantic versions as the source.</li></ul><p>See the sample request for an example.</p> |
| `services_existing`      | <p>Optional parameter that defines how to process the service if there is an existing service in the destination folder with the same service name exists and is accessible.</p><ul><li>The default value is <code>abort</code> which means the import will fail if there is already an existing service with in the specified destination folder and service.</li><li><p><code>replace</code> means the entire service will be removed and replaced with the service versions in the imported file. <mark style="color:red;"><strong>Note that the previous API Call History for the service will no longer be accessible.</strong></mark></p><ul><li>If there are existing overlapping semantic versions between the destination and source, this will maintain the existing <code>version\_id</code>.</li></ul></li><li><code>add\_version</code> means that any existing services will be updated with the service versions included in the file.</li></ul>                                                                                                                                                                                                                                                                      |
| `source_system`          | <p>Tag API call.</p><p>Example: <code>mycicd</code></p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `correlation_id`         | <p>Tag API call.</p><p>Example: <code>456</code></p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

### Sample request

* The exported ZIP contains a service taken from the folder `myproduct` service `myservice`.
* The destination for this service is the folder `newproduct` and service `newservice`.
* The service version semantic versions will be incremented with a `major` revision number, e.g. from `1.3.1` to `2.0.0`.

```sh
curl --location 'https://excel.myenvironment.coherent.global/mytenant/api/v4/import' \
--header 'Authorization: Bearer {token}' \
--form 'file=@"/C:/myfolder/myfile.zip"'
--form 'importRequestEntity="{
	\"inputs\": {
		\"services_modify\": [{
			\"service_uri_source\": \"myproduct/myservice\",
			\"service_uri_destination\": \"newproduct/newservice\",
			\"update_version_type\": \"major\",
		}]
	},
	\"services_existing\": \"add_version\",
	\"source_system\": \"mycicd\",
	\"correlation_id\": \"456\"
}"'
```

`importRequestEntity`

```json
{
	"inputs": {
		"services_modify": [{
			"service_uri_source": "myproduct/myservice",
			"service_uri_destination": "newproduct/newservice",
			"update_version_type": "major"
		}]
	},
	"services_existing": "add_version",
	"source_system": "mycicd",
	"correlation_id": "456"
}
```

### Response <a href="#request_data" id="request_data"></a>

`HTTP 200 OK` `Content-Type: application/json`

Returns the response from [#get-import-status](#get-import-status "mention").

## `GET` import status

Returns: `status` response.

{% code overflow="wrap" %}

```shellscript
GET /{tenant}/api/v4/import/{jobId}/status
```

{% endcode %}

### Path parameters

<table><thead><tr><th width="374">Key</th><th>Value</th></tr></thead><tbody><tr><td><code>tenant</code> *</td><td>Tenant is part of your <a data-mention href="/pages/-MboyUpg0GSvjBVkVMcw#log-in-to-spark">/pages/-MboyUpg0GSvjBVkVMcw#log-in-to-spark</a> URL and also available in the <a data-mention href="/pages/ylWjjoVBLOcB7JZks4Cp#user-menu">/pages/ylWjjoVBLOcB7JZks4Cp#user-menu</a>.</td></tr><tr><td><code>jobId</code> *</td><td><code>id</code> from <a data-mention href="#api-request-1">#api-request-1</a>.</td></tr></tbody></table>

### Response <a href="#request-body" id="request-body"></a>

Similar to the [Export](/spark-apis/impex-apis/export.md) API [Export](/spark-apis/impex-apis/export.md#request-body), with the following differences:

| Key                        | Value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `outputs.services`         | <p>Array of the imported services sorted by <code>folder\_source</code>, <code>service\_source</code>:</p><ul><li><code>service\_uri\_source</code> in <code>C.SPARK\_XCALL()</code> format of <code>{folder}/{service}</code></li><li><code>folder\_source</code></li><li><code>service\_source</code></li><li><code>service\_id\_source</code></li><li><code>service\_uri\_destination</code> in <code>C.SPARK\_XCALL()</code> format of <code>{folder}/{service}</code></li><li><code>folder\_destination</code></li><li><code>service\_destination</code></li><li><code>service\_id\_destination</code></li><li><p><code>status</code>:</p><ul><li><code>added</code> service did not exist and it was added.</li><li><code>replaced</code> service exists and was replaced.</li><li><code>updated</code> service exists and new service versions were added.</li></ul></li></ul>                                                                                                                                                                                       |
| `outputs.service_versions` | <p>Array of the imported service versions sorted by <code>folder\_source</code>, <code>service\_source</code>, <code>version\_source</code>:</p><ul><li><code>service\_uri\_source</code> in <code>C.SPARK\_XCALL()</code> format of <code>{folder}/{service}\[{version}]</code></li><li><code>folder\_source</code></li><li><code>service\_source</code></li><li><code>version\_source</code> (semantic version)</li><li>service\_id\_source (not possible to get this value)</li><li><code>version\_id\_source</code></li><li><code>service\_uri\_destination</code> in <code>C.SPARK\_XCALL()</code> format of <code>{folder}/{service}\[{version}]</code></li><li><code>folder\_destination</code></li><li><code>service\_destination</code></li><li><code>version\_destination</code></li><li><code>service\_id\_destination</code></li><li><code>version\_id\_destination</code></li><li><p><code>status</code>:</p><ul><li><code>added</code> service version was added.</li><li><code>replaced</code> service version existed and was replaced.</li></ul></li></ul> |

### Sample response

`HTTP 200 OK` `Content-Type: application/json`

```json
{
    "object": "import",
    "id": "df0e9343-5657-4fd2-959d-89dc4eadf12d",
    "response_timestamp": "2023-11-01T03:21:34.573Z",
    "status": "completed",
    "status_url": "https://excel.myenvironment.coherent.global/mytenant/v4/import/df0e9343-5657-4fd2-959d-89dc4eadf12d/status",
    "process_time": 3453,
    "outputs": {
        "services": [
            {
                "service_uri_source": "myproduct/myservice",
                "folder_source": "myproduct",
                "service_source": "myservice",
                "service_id_source": "ad04acec-6836-4e0c-9540-c54596509979",
                "service_uri_destination": "newproduct/newservice",
                "folder_destination": "newproduct",
                "service_destination": "newservice",
                "service_id_destination": "5d14d6a4-392c-4c51-be4b-6d2b98e162fe",
                "status": "replaced"
            }
        ],
        "service_versions": [
            {
                "service_uri_source": "myproduct/myservice[1.0.0]",
                "folder_source": "myproduct",
                "service_source": "myservice",
                "version_source": "1.0.0",
                "service_id_source": "ad04acec-6836-4e0c-9540-c54596509979",
                "version_id_source": "4b05a3ea-92fa-4168-8bcd-5f732a5adc5d",
                "folder_destination": "newproduct",
                "service_destination": "newservice",
                "version_destination": "1.0.0",
                "service_uri_destination": "/newproduct/newservice[1.0.0]",
                "service_id_destination": "6bd0337c-186b-4813-a4ac-49d565d86fdb",
                "version_id_destination": "6c73f2e4-b354-4695-a991-c52817a5f25f",
                "status": "replaced"
            },
            {
                "service_uri_source": "myproduct/myservice[1.1.0]",
                "folder_source": "myproduct",
                "service_source": "myservice",
                "version_source": "1.1.0",
                "service_id_source": "ad04acec-6836-4e0c-9540-c54596509979",
                "version_id_source": "e0901e15-b305-4d43-b037-3d39cf017260",
                "folder_destination": "newproduct",
                "service_destination": "newservice",
                "version_destination": "1.1.0",
                "service_uri_destination": "/newproduct/newservice[1.1.0]",
                "service_id_destination": "6bd0337c-186b-4813-a4ac-49d565d86fdb",
                "version_id_destination": "280341de-04d4-482c-ad4c-b8c03fffa517",
                "status": "added"
            }
        ]
    },
    "source_system": "mycicd",
    "correlation_id": "456"
}
```

## `PATCH` import

Change `import` job status. This can cancel an errant job.

Returns: Response from [#get-import-status](#get-import-status "mention").

{% code overflow="wrap" %}

```shellscript
PATCH /{tenant}/api/v4/import/{jobId}
```

{% endcode %}

### Path parameters

<table><thead><tr><th width="374">Key</th><th>Value</th></tr></thead><tbody><tr><td><code>environment</code> *</td><td>Environment is part of your <a data-mention href="/pages/-MboyUpg0GSvjBVkVMcw#log-in-to-spark">/pages/-MboyUpg0GSvjBVkVMcw#log-in-to-spark</a> URL.</td></tr><tr><td><code>tenant</code> *</td><td>Tenant is part of your <a data-mention href="/pages/-MboyUpg0GSvjBVkVMcw#log-in-to-spark">/pages/-MboyUpg0GSvjBVkVMcw#log-in-to-spark</a> URL and also available in the <a data-mention href="/pages/ylWjjoVBLOcB7JZks4Cp#user-menu">/pages/ylWjjoVBLOcB7JZks4Cp#user-menu</a>.</td></tr><tr><td><code>jobId</code> *</td><td><code>id</code> from <a data-mention href="#api-request-1">#api-request-1</a>.</td></tr></tbody></table>

### Request

`Content-Type: application/json`

```json
{"import_status":"cancelled"}
```

### Response

`HTTP 200 OK` `Content-Type: application/json`

Returns the response from [#get-import-status](#get-import-status "mention").

## `GET` import status across the tenant

Get information about import jobs that are `in_progress_imports` or `recent_imports` within the past `1 h`.

Returns: Import jobs.

* If you are a `supervisor:pf` user, you will be able to see all imports run by users within your tenant.
* Otherwise, you will only see information about the batches that were initiated by yourself.

```shellscript
GET /{tenant}/api/v4/import/status
```

### Path parameters

<table><thead><tr><th width="374">Key</th><th>Value</th></tr></thead><tbody><tr><td><code>tenant</code> *</td><td>Tenant is part of your <a data-mention href="/pages/-MboyUpg0GSvjBVkVMcw#log-in-to-spark">/pages/-MboyUpg0GSvjBVkVMcw#log-in-to-spark</a> URL and also available in the <a data-mention href="/pages/ylWjjoVBLOcB7JZks4Cp#user-menu">/pages/ylWjjoVBLOcB7JZks4Cp#user-menu</a>.</td></tr></tbody></table>

### Sample response

`HTTP 200 OK` `Content-Type: application/json`

```json
{
    "in_progress_imports": [
        {
            "object": "import",
            "id": "8ecadd1b-371f-4c23-b8cb-e7eba2f26acf",
            "data": {
                "import_status": "in_progress",
                "response_timestamp": "2025-08-14T10:16:39.717Z",
                "created_by": "myuser@mydomain.com",
                "created_timestamp": "2025-08-14T10:16:33.082Z",
                "updated_timestamp": "2025-08-14T10:16:33.305Z",
                "process_time": 0
            }
        }
    ],
    "recent_imports": [],
    "tenant": {
        "configuration": {
            "import_api_job_limit": 1
        },
        "status": {
            "import_api_jobs_in_progress": 1
        }
    }
}
```