Console

POSTImport Addresses into Address Set

Webhook APIhttps://web3.nodit.io/v1/webhook/address-sets/1788439512345678901/imports

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
filestring (binary)required

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.

예: 42

statusstring (enum)required

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.

예: IN_PROGRESS

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.

예: 2000000

processedCountintegerrequired

Number of address lines processed so far. Updated while loading; compare with totalCount to calculate progress.

예: 1250000

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.

예: 1240000

errorMessagestringnullrequired

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.

예: null

createdAtstring (date-time)required

Indicates when the import request was accepted. This field is returned in ISO 8601 format.

예: 2026-07-01T00:00:00.000Z

startedAtstring,null (date-time)required

Indicates when loading started. null while the status is PENDING. This field is returned in ISO 8601 format.

예: 2026-07-01T00:00:05.000Z

finishedAtstring,null (date-time)required

Indicates when the import ended as DONE or FAILED. null while in progress. This field is returned in ISO 8601 format.

예: null

X-API-KEY
Request
cURL
curl -X POST "https://web3.nodit.io/v1/webhook/address-sets/1788439512345678901/imports" \
  -H "X-API-KEY: {YOUR_API_KEY}" \
  -H "Content-Type: multipart/form-data" \
  -d '{
  "file": "addresses.csv"
}'
Response
Example · 202
{
  "importId": 42,
  "status": "PENDING",
  "totalCount": 2000000,
  "processedCount": 0,
  "addedCount": 0,
  "errorMessage": null,
  "createdAt": "2026-07-01T00:00:00.000Z",
  "startedAt": null,
  "finishedAt": null
}

Last updated