DOCUMENTATION
CONSOLE
DATA MARKETPLACE API
DATA TRANSFER AND INTEGRATION
Import
The import endpoint allows you to instruct Magenta Advertising Platform to import a file containing Advertising Identifiers and associated Attributes from S3. When you are provisioned by Magenta Advertising Platform, you will be given a set of Amazon Web Services S3 credentials and a bucket/path prefix. You will then create the data files to be imported, upload each file to Amazon S3 and then post to the import API endpoint to tell Magenta Advertising Platform to queue the import job. You can also request import logs via the API to check on status of each file you queue for import.
Magenta Advertising Platform also supports ingestion from your own S3 bucket. When you call the "/v1/marketplace/import" endpoint, you can optionally supply a bucket and credentials to be used for the import. If those are not supplied, Magenta Advertising Platform will attempt to ingest from the bucket and path we allocated to you during partner setup.
An import is a complete replacement for all attributes present in the platform. An import is not an append, it is a delete followed by an insert. Each time you perform an import you must send a full list of all ids associated with each attribute. This does not mean all the data must be in a single file. It is actually better if the data is split across multiple files as it allows us to process the data more quickly. Do not make an import API call for each file, instead upload all the files to a common prefix/directory and specify the prefix as part of the import API call. We will load all files with the same prefix in parallel.
Imports are queued and will complete in the order submitted.
Endpoint
List import logs
Lists the last 100 import jobs in reverse order of creation.
cURL
curl -X GET -H "Authorization: Bearer <APIKEY>" "https://api.magentamarketing.com/v1/marketplace/import"
Response
JSON
[
{
"import_log_id":3,
"file_path":"export1.csv",
"path_type": 0,
"key_type": 0,
"status":0,
"log_type": 0,
"keys":null,
"unique_devices":"1234",
"total_rows":"1300",
"errors":null,
"created_at":"2016-09-16T15:49:01.437Z",
"updated_at":"2016-09-16T15:49:01.437Z"
},
{
"import_log_id":4,
"file_path":"export2.csv",
"path_type": 0,
"key_type": 1,
"status":0,
"log_type": 0,
"keys":null,
"unique_devices":"4321",
"total_rows":"5000",
"errors":null,
"created_at":"2016-09-1T5:49:01.437Z",
"updated_at":"2016-09-1T5:49:01.437Z"
}
]
Status | Meaning |
0 | Pending. All requests are handled in the order they are received. If your import shows this status code it is waiting behind other imports. |
1 | Importing. |
2 | Done |
3 | Error. Something happened during the import |
Get import log
Gets a single import log entry
cURL
curl -X GET -H "Authorization: Bearer <APIKEY>" "https://api.magentamarketing.com/v1/marketplace/import/3"
Response
JSON
[
{
"import_log_id":3,
"file_path":"export1.csv",
"path_type": 0,
"key_type": 1,
"status":0,
"log_type": 0,
"keys":null,
"unique_devices":"1234",
"total_rows":"1300",
"errors":null,
"created_at":"2016-09-16T15:49:01.437Z",
"updated_at":"2016-09-16T15:49:01.437Z"
}
]
Import
Queues a file for import.
Parameters
Field | Required | Type | Description |
file_path | Y | string | A relative file path. Do not include s3://import-pushspring-com or your issued path prefix. If you uploaded a file to s3://import-pushspring-com//export.csv the relative path would be "export.csv". If you specify a path_type of 1 below this should be a absolute path of the form s3:///. This can also represent a path prefix. If a path prefix is used all files under that prefix will be loaded. If you need to load multiple files per day this method is recommended over individual import calls. |
key_type | Y | integer | Indicates the types of keys in file that is imported. 0 = MAP assigned attribute_id 1 = partner_foreign_key associated with attribute Make sure the partner_foreign_key is associated with an attribute before importing the file. |
path_type | N | ||
compressed |
N | boolean | If not specified and path_type includes a single file we will look at the file extension and if it is ".gz" we will assume the file is compressed. If you are using a path prefix for the file_path you must specify this as there is no file extension to look at to determine if the file is compressed. Defaults to false. |
credentials | N | object | For a Partner-Owned S3 bucket credentials should contain: { "accessKeyId": "XXXXX", "secretAccessKey":"YYYY", "region":"ZZZZZ" } Region should be whatever AWS region your bucket is in, e.g. 'us-west-2' |
file_path can be either a file i.e. export.csv OR a path prefix like 2020/09/15/. If a path prefix we will load all the files in parallel.
Sample
cURL
curl -X POST -H "Authorization: Bearer <APIKEY>" -H "Content-Type: application/json"
-d '{
"file_path":"export.csv",
"key_type":0
}' "https://api.magentamarketing.com/v1/marketplace/import"
Response
JSON
{
"import_log_id":4
}
Delete
Occasionally you may need to delete the data associated with an attribute. NOTE: This data is permanently deleted and cannot be restored.
Field | Required | Description | |
key_type | Y | Indicates the types of keys in file that is imported. 0 = MAP assigned attribute_id 1 = partner_foreign_key associated with attribute Make sure the partner_foreign_key is associated with an attribute before importing the file. |
|
keys | Y | Either the attribute_ids or partner_foreign_keys you wish to delete. |
Sample
cURL
curl -X POST -H "Authorization: Bearer <APIKEY>" -H "Content-Type: application/json"
-d '{
"file_path":"export.csv",
"key_type":0
}' "https://api.magentamarketing.com/v1/marketplace/import"
Response
JSON
{
"import_log_id":4
}