Import API Classifications by uploading files

This guide includes instructions for importing JSON classification datasets that are larger than 50 MB, or that include a .tsv or .tab file. With this method, a dataset is uploaded as a file with the POST request. Alternatively, your dataset can be imported as a JSON body of the POST request if it is smaller than 50MB. For more information on this alternative, see the Analytics classification APIs guide.

Additionally, using these endpoints requires your global company ID in each request. If you receive the response error message "Cannot find proper global company ID," add the following header to your requests: x-proxy-global-company-id:{GLOBAL_COMPANY_ID}. You can find your global company ID by using the Discovery API.

Adobe may add optional request and response members (name/value pairs) to existing API objects at any time and without notice or changes in versioning. Adobe recommends that you refer to the API documentation of any third-party tool you integrate with our APIs so that such additions are ignored in processing if not understood. If implemented properly, such additions are non-breaking changes for your implementation. Adobe will not remove parameters or add required parameters without first providing standard notification through release notes.

To import an API classification by uploading a file, you follow a three-step process:

Create an import job with the POST create job endpoint.
Upload a file using the PUT upload file endpoint.
Commit your upload using the POST commit job endpoint.

The endpoints described in this guide are routed through analytics.adobe.io. To use them, you will need to first create a client with access to the Adobe Developer Console. For more information, refer to Getting started with the Analytics API.

POST create job

Use this endpoint to create an import job for a classification dataset. Creating an import job is required to produce a job ID that can be associated with an uploaded dataset file. For more information on classification jobs, see Classification set jobs manager.

POST https://analytics.adobe.io/api/{GLOBALCOMPANYID}/classifications/job/import/createApiJob/{DATASET_ID}

Request and Response Examples

Click the Request tab in the following example to see a cURL request for this endpoint. Click the Response tab to see a successful JSON response for the request.

Request

Response

curl -X POST "https://analytics.adobe.io/api/{GLOBALCOMPANYID}/classifications/job/import/createApiJob/6449b63563c1e069c6159415" \
     -H "x-api-key: {CLIENT_ID}" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -d '{
          "dataFormat": "tsv",
          "encoding": "UTF8",
          "jobName": "testsuite evar1 classifications",
          "notifications": [
            {
              "method": "email",
              "state": "completed",
              "recipients": [
                "john@example.com"
              ]
            }
          ],
          "listDelimiter": ",",
          "source": "Direct API Upload",
          "keyOptions": {
            "byte_length": 0,
            "type": "string"
          }
        }'
Copied to your clipboard
curl -X POST "https://analytics.adobe.io/api/{GLOBALCOMPANYID}/classifications/job/import/createApiJob/6449b63563c1e069c6159415" \
     -H "x-api-key: {CLIENT_ID}" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -d '{
          "dataFormat": "tsv",
          "encoding": "UTF8",
          "jobName": "testsuite evar1 classifications",
          "notifications": [
            {
              "method": "email",
              "state": "completed",
              "recipients": [
                "john@example.com"
              ]
            }
          ],
          "listDelimiter": ",",
          "source": "Direct API Upload",
          "keyOptions": {
            "byte_length": 0,
            "type": "string"
          }
        }'

{
  "api_job_id": "a6fc824c-4d6f-45f9-8f55-456f918e0b41",
  "dataset_id": "6449b63563c1e069c6159415",
  "ims_org_id": "0DFE76D95967D5B50A494010@AdobeOrg",
  "api_job_status": "CREATED",
  "job_options": {
    "dataFormat": "tsv",
    "encoding": "utf8",
    "jobName": "testsuite evar1 classifications",
    "notifications": [
      {
        "method": "email",
        "state": "completed",
        "recipients": [
          "john@example.com"
        ]
      }
    ],
    "listDelimiter": ",",
    "source": "Direct API Upload",
    "keyOptions": {
      "byte_length": 255,
      "type": "string"
    },
    "notification_extras": [
      {
        "key": "Report Suite",
        "value": "testsuite"
      }
    ]
  }
}
Copied to your clipboard
{
  "api_job_id": "a6fc824c-4d6f-45f9-8f55-456f918e0b41",
  "dataset_id": "6449b63563c1e069c6159415",
  "ims_org_id": "0DFE76D95967D5B50A494010@AdobeOrg",
  "api_job_status": "CREATED",
  "job_options": {
    "dataFormat": "tsv",
    "encoding": "utf8",
    "jobName": "testsuite evar1 classifications",
    "notifications": [
      {
        "method": "email",
        "state": "completed",
        "recipients": [
          "john@example.com"
        ]
      }
    ],
    "listDelimiter": ",",
    "source": "Direct API Upload",
    "keyOptions": {
      "byte_length": 255,
      "type": "string"
    },
    "notification_extras": [
      {
        "key": "Report Suite",
        "value": "testsuite"
      }
    ]
  }
}

Request example details

The example request above creates an import job with the following specifications:

The dataFormat for the classification as tsv.
The jobName to be testsuite evar1 classifications.
The notification will be delivered by email to john@example.com when the state is completed.
The data source is Direct API Upload.

Response example details

The example response above shows the following job creation information:

The api_job_id is a6fc824c-4d6f-45f9-8f55-456f918e0b41. This ID is necessary to both upload and commit the dataset with the other endpoints in this guide.
The notification details, including its completed state.

Request Parameters

The following table describes the POST create job request parameters:

Name	Required	Type	Description
`dataFormat`	required	string	The data format options. Includes `tsv`, `tab`, or `json`.
`encoding`	optional	string	The encoding for data. The default value is `UTF-8`.
`jobName`	optional	string	The name of the job
`notifications`	optional	container	Contains the notification information. Includes the `method`, `state`, and `recipients` parameters.
`method`	optional	string	The method by which the notification is sent. This includes the enums `email` and `rabbit`.
`state`	optional	string	The state of the notification. Includes the following enums: `created`, `queued`, `validated`, `failed_validation`, `processing`, `done_processing`, `failed_processing`, and `completed`.
`recipients`	optional	string	The recipients of the notification
`listDelimiter`	optional	string	Specifies the data delimiter for the list. Default delimiter is `,` (comma)
`source`	optional	string	The data source. Default value is `Direct API Upload`.
`keyOptions`	optional	container	Contains the `byte_length`, `type`, and `overwrite` parameters
`byte_length`	optional	integer	The byte length of the job
`type`	optional	string	The type of the job
`overwrite`	optional	boolean	Whether or not the import will overwrite.
`notification_extras`	optional	container	Extra options for notifications. Contains the `key`, and `value` parameters.
`key`	optional	string	The field or column name associated with key value
`value`	optional	string	The actual value of the key (as in a field or column name)

Response Parameters

The following table describes the POST create job response parameters:

Name	Type	Description
`api_job_status`	string	The staus of the API job
`dataset_id`	string	Classification dataset ID
`api_job_id`	string	The API Job ID for uploading the file
`ims_org_id`	string	The ID associated with the analytics company of the user
`taxonomist_job_id`	string	Job ID for taxonomist
`job_options`	container	Contains the options for jobs. Includes the `dataFormat`, `encoding`, `jobName`, and `notifications` parameters as shown in the following five rows.
`dataFormat`	string	The data format options. Includes `tsv`, `tab`, or `json`.
`encoding`	string	The encoding for data. The default value is `UTF-8`.
`jobName`	string	The name of the job
`notifications`	container	Contains the notification information. Includes the `method`, `state`, and `recipients` parameters.
`method`	string	The method by which the notification is sent. This includes the enums `email` and `rabbit`.
`state`	string	The state of the notification. Includes the following enums: `created`, `queued`, `validated`, `failed_validation`, `processing`, `done_processing`, `failed_processing`, and `completed`.
`recipients`	string	The recipients of the notification
`listDelimiter`	string	Specifies the data delimiter for the list. Default delimiter is `,` (comma)
`source`	string	The data source. Default value is `"Direct API Upload"`.
`keyOptions`	container	Contains the `byte_length` `type` and `overwrite` parameters
`byte_length`	integer	The byte length of the job
`type`	string	The type of the job
`overwrite`	boolean	Whether or not the import will overwrite.
`notification_extras`	container	Extra options for notifications. Contains the `key`, and `value` parameters.
`key`	string	The field or column name associated with key value
`value`	string	The actual value of the key (as in a field or column name)

PUT upload file

Use this endpoint to upload a file that will be associated with the job ID created with the POST create job endpoint. This file can be tsv, tab, or JSON. For more information on how to structure your classification files, see Classification data files

PUT https://analytics.adobe.io.api/{GLOBAL_COMPANY_ID}/classifications/job/import/uploadFile/{API_JOB_ID}

Request and Response Examples

Click the Request tab in the following example to see a cURL request for this endpoint. Click the Response tab to see a successful JSON response for the request.

Request

Response

curl -X PUT "https://analytics.adobe.io.api/{GLOBAL_COMPANY_ID}/classifications/job/import/uploadFile/a6fc824c-4d6f-45f9-8f55-456f918e0b41"
     -H "x-api-key: {CLIENT_ID}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Content-Type: multipart/form-data" \
     -d '{
          "Key": "example_file.tsv",
          "Value": "/files/examples/example_file.tsv"
         }' 
Copied to your clipboard
curl -X PUT "https://analytics.adobe.io.api/{GLOBAL_COMPANY_ID}/classifications/job/import/uploadFile/a6fc824c-4d6f-45f9-8f55-456f918e0b41"
     -H "x-api-key: {CLIENT_ID}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Content-Type: multipart/form-data" \
     -d '{
          "Key": "example_file.tsv",
          "Value": "/files/examples/example_file.tsv"
         }'

{
  "api_job_id": "a6fc824c-4d6f-45f9-8f55-456f918e0b41",
  "status": "success"
}
Copied to your clipboard
{
  "api_job_id": "a6fc824c-4d6f-45f9-8f55-456f918e0b41",
  "status": "success"
}

Request example details

The example above shows a cURL request with the following:

The Key parameter specified as the file name example_file.tsv.
The Value parameter specified as the file path /files/examples/example_file.tsv.

Response example details

The example response above shows a successful status for the upload.

Request Parameters

The following table describes the PUT upload file request parameters:

Name	Required	Type	Description
`api_job_id`	required	string	The API job ID for uploading the file. This ID was provided with the response of the POST create job endpoint.
`Key`	required	string	The name of the uploaded file
`Value`	required	string	The location of the uploaded file

Response Parameters

The following table describes the PUT upload file response parameters:

Name	Type	Description
`api_job_id`	string	The API job ID for uploading the file. This ID is provided with the response of the POST create job endpoint.
`status`	string	The status of the API job

POST commit job

Use this endpoint to commit the changes of a specified job ID. This endpoint finalizes the file uploading process. For more information on classification jobs, see Classification set jobs manager.

POST https://analytics.adobe.io.api/{GLOBAL_COMPANY_ID}/classifications/job/import/commitApiJob/{API_JOB_ID}

Request and Response Examples

Click the Request tab in the following example to see a cURL request for this endpoint. Click the Response tab to see a successful JSON response for the request.

Request

Response

curl -X POST "https://analytics.adobe.io.api/{GLOBAL_COMPANY_ID}/classifications/job/import/commitApiJob/a6fc824c-4d6f-45f9-8f55-456f918e0b41" \
     -H "x-api-key: {CLIENT_ID}" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer {ACCESS_TOKEN}"
Copied to your clipboard
curl -X POST "https://analytics.adobe.io.api/{GLOBAL_COMPANY_ID}/classifications/job/import/commitApiJob/a6fc824c-4d6f-45f9-8f55-456f918e0b41" \
     -H "x-api-key: {CLIENT_ID}" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer {ACCESS_TOKEN}"

{
  "import_job_id": "e11671f1-d352-4b34-bb95-3a26775ef334",
  "api_job_id": "a6fc824c-4d6f-45f9-8f55-456f918e0b41"
}
Copied to your clipboard
{
  "import_job_id": "e11671f1-d352-4b34-bb95-3a26775ef334",
  "api_job_id": "a6fc824c-4d6f-45f9-8f55-456f918e0b41"
}

Request example details

The example above shows a cURL request to commit the job associated with the api_job_id of a6fc824c-4d6f-45f9-8f55-456f918e0b41.

Response example details

The example above shows the successful response for committing the job, including the values for import_job_id and api_job_id.

Request Parameters

The following table describes the POST commit job request parameters:

Name	Required	Type	Description
`api_job_id`	required	string	The API job ID for uploading the file. This ID was provided with the response of the POST create job endpoint.

Response Parameters

The following table describes the POST commit job response parameters:

Name	Type	Description
`import_job_id`	string	The ID of the import job
`api_job_id`	string	The API job ID for uploading the file. This ID was provided with the response of the POST create job endpoint.

After importing your classification datasets you can export them to other applications. See the Analytics classification APIs guide for more information.

Classifications

Troubleshooting