Skip to main content

Import Addresses into Address Set

POST
API for replacing (overwriting) the entire address list of an Address Set by uploading a CSV file. Send the request as multipart/form-data with the file field named file. Once accepted, a 202 response with an importId is returned and the import proceeds asynchronously. Check the progress with the Get Address Set Import API.

Caution: an import overwrites, it does not append. The uploaded file becomes the set's entire address list, and all previously stored addresses are deleted. To keep existing addresses, include them in the file. To add or remove only some addresses, use the Update Addresses in Address Set API.

Processing rules
  • If the number of addresses in the file exceeds the plan limit, the upload is rejected at upload time (400 ADDRESS_LIMIT_EXCEEDED) and the set is left unchanged.
  • If the import ends as FAILED, the set is left empty.
  • A set with an import in progress (IMPORTING) cannot accept another upload, and its addresses cannot be changed or attached to a Webhook.
  • CSV import is not available for a set that has ever been attached to a Webhook.
  • totalCount in the response is the number of address lines in the file, and its final value is already present in the 202 response. addedCount is the number of distinct addresses stored in the set; it is smaller than totalCount when the file contains duplicates.
CSV format
  • The first column is the address; any following columns are ignored. If the first line is address, it is treated as a header.
  • UTF-8 BOM, CRLF line endings, blank lines, and quoted values are accepted.
  • Each line must be at most 1,024 characters, and the file at most 256MB.
  • Every line must be an address matching the set's addressFormat. At the first line that is not, the import ends as FAILED on the spot with the cause in errorMessage, and the set is left empty. This is not rejected at upload time, so check the result with the Get Address Set Import API.

This API requires a file upload, so Try it is not supported in the documentation. Refer to the code snippet and call it directly.

Path Parameters
addressSetIdstringrequired
Parameter that specifies the addressSetId assigned to the Address Set. Use the addressSetId returned when the Address Set was created. It is a 19-digit number but is returned as a string in JSON. Parsing it as a number in JavaScript or similar environments loses precision, so always handle it as a string.
Request Body
filestringrequired
CSV file to upload. The first column is the address, and a first line of address is treated as a header. Each line must be at most 1,024 characters and the file at most 256MB. The address list in this file replaces the set's entire list.
Responses
importIdintegerrequired
Field indicating the importId assigned to the import job. An integer that increments sequentially from 1; used to check the import progress.
statusstringrequired
Field indicating the status of the import job. PENDING means accepted and waiting to load, IN_PROGRESS means loading, DONE means completed, and FAILED means failed. When an import ends as FAILED, the set is left empty.
totalCountintegerrequired
Number of address lines in the uploaded CSV file. The final value is already present in the 202 response and does not change while loading.
processedCountintegerrequired
Number of address lines processed so far. Updated while loading; compare with totalCount to calculate progress.
addedCountintegerrequired
Number of distinct addresses stored in the set. Updated while loading; smaller than totalCount when the file contains the same address more than once.
errorMessagestring or nullrequired
Indicates the failure reason when the import status is FAILED. When the import failed on a line that is not an address of the set's addressFormat, it contains information about that line. Otherwise null.
createdAtstringrequired
Indicates when the import request was accepted. This field is returned in ISO 8601 format.
startedAtstring or nullrequired
Indicates when loading started. null while the status is PENDING. This field is returned in ISO 8601 format.
finishedAtstring or nullrequired
Indicates when the import ended as DONE or FAILED. null while in progress. This field is returned in ISO 8601 format.
codestringrequired
Code identifying the cause of the failed request.
messagestringrequired
Detailed message including the name and value of the invalid parameter.
{
  "code": "MISSING_REQUIRED_PARAMETER",
  "message": "Missing required parameter: file"
}
cURL
curl -X POST 'https://web3.nodit.io/v1/webhook/address-sets/1788439512345678901/imports' \
  -H 'X-API-KEY: nodit-demo' \
  -F '[email protected]'