POST reference-data/{dataset}/records/import

Overview

This method supports the importing of thousands of records into a data set (table) with a single call. Whenever your requirements call for batching up records to add or update, this is the prefered method. This request supports a request payload size of up to 2 MB.

This is an asynchronous call and the response is a ticket with the status of the request. Once the request has been completed the response location will contain the resource for the invidiual record results. This is provided by the Async Results API.

The Async Results response payload contains the following summary information about the results of the call:

  • Counts - Requested, completed, failed, ignored and total.
  • Completed - Index value and timestamp
  • Failed - Index, timestamp and error message
  • Ignored - Index

Resource URI

 https://api.yesmail.com/v2/reference-data/{dataset}/records/import

Call Description

In addition to the standard response headers, this API call will also provide a header Content-Location: https://api.yesmail.com/v2/tickets/{id}, which provides the location of the ticket resource where status information is updated. See Tickets API documenation for more details.

URI Parameters

Parameter Required Description
responseUri 

 Optional

A customer-specified URI where Yesmail’s service can post the final status of the request.  See Tickets API documentation for more details.

responseRef 

 Optional

A customer-specified value that the customer may wish to use to track the ticket internally.  See Tickets API documentation for more details.

 

Parameters

Parameter

Required

Description

errorThreshold

Optional

Optional property specifying when to stop the import process due to failures. Default is 0 or no check.

  • integer – An integer value specifying an exact error count to trigger the stop. Set to 0 (zero) to attempt import of the entire source file.
  • percent – A percentage value between > 0% and < 100% indicating when to stop processing. Percentage values must be quoted. 

importType

Required

Required property indicating how existing records are treated during the import. New records are always added.

  • ignore – Skip source records if the destination  table already has the same key, inserts the source record if no match is found. Think of this as a PUT with a "If-None-Match" header.
  • update – Will update existing records with the data available, or insert new records if no match is found. Think of this as a PUT when there is no match and as a POST (partial) for a match.
  • replace – Will replace existing records and insert new records with no match. Think of this as a straight PUT request.

 

HTTP Return Codes

 

Code

Description

202 Accepted

The request has been accepted.

400 Bad Request

The request could not be understood by the server due to malformed syntax at the request level.  Verify all emails are in lower case. If there are errors at the level of the individual member, but the syntax for one or more members can be understood, they will be processed correctly with a 200 OK return code, with the errors provided in the response payload as described above.

401 Unauthorized

The request requires user authentication.  Invalid Api-User and/or Api-Key header value.

404 Not Found

The target list "listname" does not exist or has been archived.

409 Conflict

This occurs when the If-Match condition is used, and the specified ETag does not match the current ETag for the resource.

413 Request Entity Too Large

The size of the request payload exceeded the maximum number of members.

Request

This request uses the ignore import type. This will ignore any existing records in the request and only add new records.

{
  "errorThreshold": 100,
  "importType": "ignore",
  "records": [
    {
      "clientScore": "A",
      "salesRep": "Johnny King",
      "lastCall": "2014-04-11T12:13:14-07:00"
    },
    {
      "clientScore": "C",
      "salesRep": "Tommy Tombola",
      "lastCall": "2014-04-10T10:11:15-07:00"
    },
    {
      "clientScore": "B",
      "salesRep": "Frank Roman",
      "lastCall": "2014-04-10T08:55:10-04:00"
    }
  ]
}

Response

Initial ticket response with URI parameters.

{
  "id": "654321",
  "state": "accepted",
  "message": "Import request of reference data accepted.",
  "lastUpdate": "2014-03-03T17:33:12Z",
  "events": [
    {
      "state": "accepted",
      "message": "Import request of reference data accepted.",
      "time": "2014-03-03T17:33:12Z"
    }
  ],
  "request" : {
    "id": "1234-4321-567890-098765",
    "user": "db-username",
    "time": "2014-03-03T17:33:01Z",
    "uri": "https://api.yesmail.com/v2/reference-data/my-table/records/import"
  },
  "response": {
    "uri": "http://callers.domain.com/path",
    "ref": "callers-ref-value"
  }
}

Asynchronous results where ?completed=true&ignored=true

{
  "id": "987654",
  "lastUpdate": "2014-03-03T17:33:52Z",
  "counts": {
    "completed": 3,
    "failed": 0,
    "ignored": 1,
    "total": 2,
    "requested": 3
  },
  "completed ": [
    {
      "index": 0,
      "time": "2014-03-03T17:33:22Z"
    },
    {
      "index": 2,
      "time": "2014-03-03T17:33:42Z"
    }
  ],
  "ignored": [
    {
      "index": 1,
      "time": "2014-03-03T17:33:32Z"
      }
    }
  ]
}