Definition
The API enables vendors, plugins, and enterprise clients to manage Imports externally by API. It adds the option to automate data flow by service instead of a manual user process. Utilizing the API can significantly shorten the time to import, which is useful for external plugins.
You may make use of Management API for Imports by:
- Copying import definitions from one project to another.
- Deploying the same import to multiple projects by a script.
Management API for Imports exposes API methods to list, read, create, and delete import definitions. Create operation creates a new import definition and supports:
- Import from URL and File storage identified by integration_id.
- Function 'run once' or 'run on a schedule'.
- Running import every 30 minutes as the scheduler allows up to 48 scheduled daily repeats.
- Creating up to 25 active import definitions in a project.
- Importing Customers, Events, and Catalogs.
Note
Imports created via the API can only be edited using the same API and not via the UI.
Authorization
In this API call you must use the following authorization access and permissions:
| Available access type | Permissions needed |
|---|---|
| Private access | Imports > Allow to Create new Imports |
Admin must first create Private access keys and grant permissions. Then the service can call the API and perform the operation.
Read more about:
Request
Path parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| projectToken | string | The ID of your project. | Required |
Body parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| import_id | string | The ID of your import. Part of the success response. | Optional |
| import_definition | object | The definition of your import. | Optional |
Import_definition object description
| Parameter | Type | Description | Required |
|---|---|---|---|
| name | string | The name of your import. | Required |
| trigger | one of: object | The trigger for import either now, or repeated based on frequency or new files. | Required |
| active | boolean | Default: true | Optional |
| source | one of: object | The source of imported data. | Required |
| destination | one of: object | The destination where data is imported. | Required |
| mapping | object | Data mapping pattern of your import. | Required |
Trigger object description
Trigger can be defined by one of the two object descriptions:
(1) First trigger object description option:
| Parameter | Type | Description | Required |
|---|---|---|---|
| trigger_type | string | Type of the trigger. Allowed values: now, on_new_file | Required |
(2) Second trigger object description option:
| Parameter | Type | Description | Required |
|---|---|---|---|
| trigger_type | string | Type of the trigger. | Required |
| frequency | string | The frequency in which imports are triggered. Allowed values: hourly, daily, weekly, monthly | Required |
| times | array[object] | <= 48 items | Required |
| days | array (oneOf) [Day_of_week] or array (oneOf) [Day_of_month] | The days on which imports are triggered. | Optional |
| minutes | array[integer] | Required | |
| timezone | string | Timezone in which time of trigger is set. | Required |
| from_date | number | From which date imports are triggered. | Optional |
| to_date | number | To which date imports are triggered. | Optional |
Times object description
| Parameter | Type | Description | Required |
|---|---|---|---|
| hour | integer | >= 0, <= 23 | Required |
| minute | integer | >= 0, <= 59 | Required |
Source object description
Source can be defined by one of the two object descriptions:
(1) First source object description option:
| Parameter | Type | Description | Required |
|---|---|---|---|
| source_type | string | Allowed value: url | Required |
| import_url | string | Required | |
| use_socks_proxy | boolean | Default: false | Optional |
| auth | object | Optional |
(2) Second source object description option:
| Parameter | Type | Description | Required |
|---|---|---|---|
| source_type | string | Allowed value: filestorage | Required |
| integration_id | string | The ID of your integration.>= 24 characters | Required |
| parent_path | string | Optional | |
| path | string | >= 1 characters | Required |
| file_selection | string | Allowed values: all, last_mod, last_alpha, not_imported | Required |
Auth object description
Auth object description is only applicable in case of URL import.
| Parameter | Type | Description | Required |
|---|---|---|---|
| username | string | Required | |
| password | string | Required |
Destination object description
Destination can be defined by one of the three object descriptions:
(1) First destination object description option:
| Parameter | Type | Description | Required |
|---|---|---|---|
| event_destination | object | A specific event type into which you import data. | Required |
(2) Second destination object description option:
| Parameter | Type | Description | Required |
|---|---|---|---|
| customer_destination | object | The customer table where you import data. | Required |
(3) Third destination object parameter option:
| Parameter | Type | Description | Required |
|---|---|---|---|
| catalog_destination | object | The catalog into which you import data. | Required |
Event_destination object description
| Parameter | Type | Description | Required |
|---|---|---|---|
| event_type | string | >= 1 characters | Optional |
| event_triggers | boolean | Default: false | Optional |
Catalog_destination object description
| Parameter | Type | Description | Required |
|---|---|---|---|
| catalog_name | string | Name of the catalog into which you import data. | Required |
| catalog_attributes | one of: object | Optional |
Catalog_attributes object description
Catalog_attributes can be defined by one of the two object descriptions:
(1) First catalog_attributes object description option:
| Parameter | Type | Description | Required |
|---|---|---|---|
| catalog_type | string | Allowed values: generic, product, variants | Required |
(2) Second catalog_attributes object description option:
| Parameter | Type | Description | Required |
|---|---|---|---|
| catalog_type | string | Allowed values: generic, product, variants | Required |
| associated_product_catalog_id | string | The ID of your product catalog. | Optional |
Mapping object description
| Parameter | Type | Description | Required |
|---|---|---|---|
| tz_info | string | The timezone to use for time/datetime/timestamp columns. Default: UTC | Optional |
| column_mapping | object | Required |
Column_mapping object description
| Parameter | Type | Description | Required |
|---|---|---|---|
| id_mappings | array[object] | The ID of your mappings. | Required |
| property_mappings | array[object] | Required | |
| timestamp_column | string | Optional |
Id_mappings object description
| Parameter | Type | Description | Required |
|---|---|---|---|
| from_column | string | Required | |
| to_id | string | Required |
Property_mappings object description
| Parameter | Type | Description | Required |
|---|---|---|---|
| from_column | string | Optional | |
| to_column | string | Required | |
| target_type | string | Default: string | Optional |
| searchable | boolean | Optional | |
| indexed | string | Indicates whether a property should be indexed for faster retrieval. | Optional |
Response description
| Parameter | Type | Description | Required |
|---|---|---|---|
| import_id | integer | The ID of your import. | Optional |
Limitations
- Update API method is not implemented.
- You cannot create an import for Vouchers.
- You cannot create import of other types (e.g. from Input/Uploaded file, from Database by query, from the application).
- Managing import definitions created by Users is done in the app (not via API).
API rate limits:
- The joint number of requests for operations 'List', 'Read', and 'Delete' cannot exceed 100 requests per minute.
- Up to 10 requests for the 'Create' operation are allowed per minute, with a maximum of 48 allowed requests per day. The limit for active import definitions is 25.