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.

data-variant=info

data-slots=text

To import an API classification by uploading a file, use the following enpoints:

• POST import job by dataset ID
• POST import upload file
• POST import commit job ID

Each endpoint is used in the following process:

1. Create an import job entity with the POST import job by dataset ID endpoint.
2. Upload a file using the POST import upload file endpoint.
3. Commit your upload using the POST import 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 import job by dataset ID

Use this endpoint to create an import job entity for a classification dataset. Creating an import job entity returns a job ID that can be associated with an uploaded dataset file. The dataset file is uploaded after this API call. 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.

data-slots=heading, code

data-repeat=2

data-languages=CURL,JSON

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"
      }
    ]
  }
}

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:

Response Parameters

The following table describes the POST create job response parameters:

POST import 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

POST 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.

data-slots=heading, code

data-repeat=2

data-languages=CURL,JSON

curl -X POST "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"
}

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:

Response Parameters

The following table describes the PUT upload file response parameters:

POST import commit job ID

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.

data-slots=heading, code

data-repeat=2

data-languages=CURL,JSON

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"
}

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:

Response Parameters

The following table describes the POST commit job response parameters:

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