Bulk Upload API

Abstract

Upload bulk files by making standard POST and GET calls in the API.

Upload Endpoint

https://api.gemini.yahoo.com/v3/rest/bulk/upload

Submit a Job

To upload a bulk file, make a POST call to the bulk upload endpoint, passing in the advertiser id in the URL.

An example of a request to upload a bulk file for an advertiser id 123:

https://api.gemini.yahoo.com/v3/rest/bulk/upload/?advertiserId=123

The CSV file you’re uploading should be embedded as form-data within the file field. Compressed files are accepted. When uploading a compressed file, the results file will be automatically compressed.

Query Parameters Fields

Name Description Required
advertiserId The account the upload is for. Yes
skipExcelSpecificCharFixes Indicates whether the uploaded file should skip special Microsoft Excel fixes for inserting a leading space in front of Excel-specific characters (+,-,=) and inserting a leading single quote ‘ in front of a integer with 11 or more characters. Defaults to FALSE if not specified. optional
compressedFile Defaults to FALSE. Recommended to set to TRUE. This generates a compressed (gzip) of the CSV file result for a smaller, over-network footprint. optional

Response

The following is a sample response when submitting a job:

{
  "errors": null,
  "response": {
      "jobId": 7015,
      "status": "submitted",
      "jobResponse": null
  }
}

The response includes the following fields:

Name Description
jobId The ID of the submitted job. Use this id in order to poll the status of the job.
status The initial status of a job that was successfully submitted will be “submitted”.
jobResponse When the job is completed, this field will have details on the results of the job.

Once the job has been submitted, you can poll the job’s status until its completion. You should poll the status at reasonable intervals given the estimated size of your requested data.

Get Job Status

To query the status of your request, make a GET call to

/bulk/status/?jobId={jobId}&advertiserId={advertiserId}

For example, in order to check the status of jobId 4196 that requested data for advertiser 30944, make the following GET call:

https://api.gemini.yahoo.com/v3/rest/bulk/status/?jobId=4196&advertiserId=30944

The meaning of the possible statuses are detailed below:

Name Description
submitted The job is in the queue but work on it has yet to commence.
running The job is running.
failed The job ran but unexpectedly failed.
killed The job was killed, typically due to failure to complete in a timely manner.
completed The job completed successfully.

Upload Completion

Upon successful completion, the response includes the token you’ll need to securely download your file with the requested data. This file is available to be downloaded within 30 days of the job’s completion.

Upload Details

When an upload job completes, the jobResponse will include details on the number of added, updated, deleted and failed objects for each object type. The resultFile field will include a token that should be used to download the result file.

The result file is a spreadsheet that has one row for every object that was passed and includes error messages for failed objects.

Example Response

A sample response of an upload job upon completion:

{
"errors": null,
"timestamp": "2016-06-13 16:57:41",
"response": {
  "jobId": 26597,
  "status": "completed",
  "jobResponse": {
    "Invalid_Row": {
      "totalCount": 0
    },
    "Ad": {
      "totalCount": 0,
      "addedCount": 0,
      "updatedCount": 0,
      "deletedCount": 0,
      "failedCount": 0
    },
    "Age_Target": {
      "totalCount": 0,
      "addedCount": 0,
      "updatedCount": 0,
      "deletedCount": 0,
      "failedCount": 0
    },
    "Site_Exclusion": {
      "totalCount": 0,
      "addedCount": 0,
      "updatedCount": 0,
      "deletedCount": 0,
      "failedCount": 0
    },
    "Sitelink_Extension": {
      "totalCount": 0,
      "addedCount": 0,
      "updatedCount": 0,
      "deletedCount": 0,
      "failedCount": 0
    },
    "Call_Extension": {
      "totalCount": 0,
      "addedCount": 0,
      "updatedCount": 0,
      "deletedCount": 0,
      "failedCount": 0
    },
    "Location_Target": {
      "totalCount": 0,
      "addedCount": 0,
      "updatedCount": 0,
      "deletedCount": 0,
      "failedCount": 0
    },
    "Device_Target": {
      "totalCount": 0,
      "addedCount": 0,
      "updatedCount": 0,
      "deletedCount": 0,
      "failedCount": 0
    },
    "Ad_Schedule": {
      "totalCount": 0,
      "addedCount": 0,
      "updatedCount": 0,
      "deletedCount": 0,
      "failedCount": 0
    },
    "OS_Version_Target": {
      "totalCount": 0,
      "addedCount": 0,
      "updatedCount": 0,
      "deletedCount": 0,
      "failedCount": 0
    },
    "Radius_Target": {
      "totalCount": 0,
      "addedCount": 0,
      "updatedCount": 0,
      "deletedCount": 0,
      "failedCount": 0
    },
    "Product_Group": {
      "totalCount": 0,
      "addedCount": 0,
      "updatedCount": 0,
      "deletedCount": 0,
      "failedCount": 0
    },
    "Keyword": {
      "totalCount": 0,
      "addedCount": 0,
      "updatedCount": 0,
      "deletedCount": 0,
      "failedCount": 0
    },
    "Shared_Sitelink": {
      "totalCount": 0,
      "addedCount": 0,
      "updatedCount": 0,
      "deletedCount": 0,
      "failedCount": 0
    },
    "Custom_Audience": {
      "totalCount": 0,
      "addedCount": 0,
      "updatedCount": 0,
      "deletedCount": 0,
      "failedCount": 0
    },
    "Shared_Negative_Keyword": {
      "totalCount": 0,
      "addedCount": 0,
      "updatedCount": 0,
      "deletedCount": 0,
      "failedCount": 0
    },
    "Campaign_Shared_Set": {
      "totalCount": 0,
      "addedCount": 0,
      "updatedCount": 0,
      "deletedCount": 0,
      "failedCount": 0
    },
    "Campaign": {
      "totalCount": 0,
      "addedCount": 0,
      "updatedCount": 0,
      "deletedCount": 0,
      "failedCount": 0
    },
    "Gender_Target": {
      "totalCount": 0,
      "addedCount": 0,
      "updatedCount": 0,
      "deletedCount": 0,
      "failedCount": 0
    },
    "Shared_Set": {
      "totalCount": 0,
      "addedCount": 0,
      "updatedCount": 0,
      "deletedCount": 0,
      "failedCount": 0
    },
    "Ad_Group": {
      "totalCount": 0,
      "addedCount": 0,
      "updatedCount": 0,
      "deletedCount": 0,
      "failedCount": 0
    },
    "Product_Filter": {
      "totalCount": 0,
      "addedCount": 0,
      "updatedCount": 0,
      "deletedCount": 0,
      "failedCount": 0
    },
    "Interest_Target": {
      "totalCount": 0,
      "addedCount": 0,
      "updatedCount": 0,
      "deletedCount": 0,
      "failedCount": 0
    },
    "Shared_Sitelink_Setting": {
      "totalCount": 0,
      "addedCount": 0,
      "updatedCount": 0,
      "deletedCount": 0,
      "failedCount": 0
    },
    "Connection_Target": {
      "totalCount": 0,
      "addedCount": 0,
      "updatedCount": 0,
      "deletedCount": 0,
      "failedCount": 0
    },
    "resultFile": "Q_Fy4sBGlxvzkrj.O_6nfabIu2lwu1AapjNQXhyVZX3wkag3Qdl_xo0ubHHRGG8plok_7rzZCSjVO5jjH647ozkKWbWwXOhDunEedtAMIb_24MpQChnQkOge1PaCLA5.6Ho-~A"
    }
  }
}

Download Job Results

Once the job has completed, you will need to either download your requested data (on a download job) or get your results file (on an upload job). You can do this by making a GET call to the

https://api.gemini.yahoo.com/v3/rest/bulk/read/

endpoint and passing in the token you received in either the resultFile or the jobResponse using the resource parameter.

Example

https://api.gemini.yahoo.com/v3/rest/bulk/read/?resource=iY.mAQcBTiZcZfotBOtNMDnYDUsothZsIbVpfg0bP5R8oKXbAA6VJlCwuuV2oNsNhGQ7tVcEfVM2pNVsIsUoo8EYOj135iBehdHZAF9mPlTBmq9JfWbGLM9OUpD2JWSwlROI9Kj1Pjo.4PQ65zGMowH5D0zTzqlxWumt8mHWP.E8n8NtcD2F

Important

Bulk Download does not work if you want to Download-only Product Group object types. A workaround is available. If you change the objectType to Campaign and download the entire campaign, it will work.