imports

Embed

<a href="https://hermeticor.com/docs/ref-imports"><img src="https://hermeticor.com/docs/_api/public/orgs/5fcd8b3c-a27c-4688-972f-de710125592f/spaces/caf5dc05-15f7-4e0c-bdb8-ab29ede6211e/pages/2733675a-1b97-4143-b0af-37608a251ed5/social-card.svg?v=3e7ae33eec8b" alt="imports" width="600" height="315"></a>

POSThttps://hermeticor.com/v1/events/backfill

Upload a CSV of historic events (event, occurred_at, email|phone|external_id, value?, currency?, properties?); progress via GET /v1/profiles/bulk/:id

Code samples

cURL

curl -X POST "https://hermeticor.com/v1/events/backfill" \
  -H "Authorization: Bearer $HERMETICOR_API_KEY"

TypeScript

Python

PHP

Ruby

Java

Responses

202 Default Response

Example

{
  "id": "string",
  "kind": "bulk",
  "op": "string",
  "status": "queued",
  "progress": {
    "total": 0,
    "processed": 0,
    "failed": 0
  },
  "error": "string",
  "downloadUrl": "string",
  "failures": [
    {
      "profileId": "string",
      "message": "string"
    }
  ],
  "createdAt": "2024-01-01T00:00:00Z",
  "finishedAt": "2024-01-01T00:00:00Z"
}

Schema

idstringrequired

kindstringrequired

bulk | export

opstringrequired

statusstringrequired

queued | running | completed | failed

progressobjectrequired

Show child parameters

totalintegerrequired

processedintegerrequired

failedintegerrequired

errorstringrequired

downloadUrlstring

failuresFailuresItem[]

Show child parameters

profileIdstringrequired

messagestringrequired

createdAtstringrequired

finishedAtstringrequired

4XX Default Response

Example

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

detailsobject

5XX Default Response

Same as 4XX · POST /v1/events/backfill

GEThttps://hermeticor.com/v1/imports

Parameters

limitintegerquery

= 50

cursorstringquery

Code samples

cURL

curl -X GET "https://hermeticor.com/v1/imports" \
  -H "Authorization: Bearer $HERMETICOR_API_KEY"

TypeScript

Python

PHP

Ruby

Java

Responses

200 Default Response

Example

{
  "items": [
    {
      "id": "string",
      "filename": "string",
      "status": "uploaded",
      "mapping": {},
      "listId": "string",
      "tags": [
        "string"
      ],
      "consentAssertion": {
        "channel": "email",
        "purpose": "marketing",
        "sourceText": "string",
        "attestedBy": "string"
      },
      "verifyEmail": true,
      "listIds": [],
      "updateExisting": true,
      "topicId": null,
      "stats": {
        "total": 0,
        "created": 0,
        "updated": 0,
        "errors": 0,
        "suppressed": 0,
        "consentSkipped": 0,
        "consentGranted": 0,
        "skipped": 0,
        "blocked": 0,
        "topicSubscribed": 0,
        "topicUnsubscribed": 0
      },
      "progress": {
        "rowsRead": 0,
        "processed": 0,
        "errors": 0
      },
      "error": "string",
      "errorsUrl": "string",
      "createdAt": "2024-01-01T00:00:00Z",
      "finishedAt": "2024-01-01T00:00:00Z"
    }
  ],
  "nextCursor": "string"
}

Schema

itemsPostV1ImportsResponse[]required

Show child parameters

idstringrequired

filenamestringrequired

statusstringrequired

mappingobjectrequired

listIdstringrequired

tagsstring[]required

consentAssertionobjectrequired

Show child parameters

channelstringrequired

email | sms | whatsapp | push | postcard

purposestringrequired

marketing | prospecting | transactional | operational

sourceTextstringrequired

attestedBystringrequired

verifyEmailbooleanrequired

listIdsstring[]required

= []

updateExistingbooleanrequired

= true

topicIdstringrequired

= null

statsobjectrequired

Show child parameters

totalintegerrequired

createdintegerrequired

updatedintegerrequired

errorsintegerrequired

suppressedintegerrequired

consentSkippedintegerrequired

consentGrantedintegerrequired

skippedintegerrequired

= 0

blockedintegerrequired

= 0

topicSubscribedintegerrequired

= 0

topicUnsubscribedintegerrequired

= 0

progressobjectrequired

Show child parameters

rowsReadintegerrequired

processedintegerrequired

errorsintegerrequired

errorstringrequired

errorsUrlstring

createdAtstringrequired

finishedAtstringrequired

nextCursorstringrequired

4XX Default Response

Same as 4XX · POST /v1/events/backfill

5XX Default Response

Same as 4XX · POST /v1/events/backfill

POSThttps://hermeticor.com/v1/imports

Upload a CSV, an Excel .xlsx (first sheet) or a ZIP containing a CSV (multipart: file + mapping, delimiter?, listId?, tags?, consentAssertion?, verifyEmail?, defaultCountry?)

Code samples

cURL

curl -X POST "https://hermeticor.com/v1/imports" \
  -H "Authorization: Bearer $HERMETICOR_API_KEY"

TypeScript

Python

PHP

Ruby

Java

Responses

201 Default Response

Example

{
  "id": "string",
  "filename": "string",
  "status": "uploaded",
  "mapping": {},
  "listId": "string",
  "tags": [
    "string"
  ],
  "consentAssertion": {
    "channel": "email",
    "purpose": "marketing",
    "sourceText": "string",
    "attestedBy": "string"
  },
  "verifyEmail": true,
  "listIds": [],
  "updateExisting": true,
  "topicId": null,
  "stats": {
    "total": 0,
    "created": 0,
    "updated": 0,
    "errors": 0,
    "suppressed": 0,
    "consentSkipped": 0,
    "consentGranted": 0,
    "skipped": 0,
    "blocked": 0,
    "topicSubscribed": 0,
    "topicUnsubscribed": 0
  },
  "progress": {
    "rowsRead": 0,
    "processed": 0,
    "errors": 0
  },
  "error": "string",
  "errorsUrl": "string",
  "createdAt": "2024-01-01T00:00:00Z",
  "finishedAt": "2024-01-01T00:00:00Z"
}

Schema

idstringrequired

filenamestringrequired

statusstringrequired

mappingobjectrequired

listIdstringrequired

tagsstring[]required

consentAssertionobjectrequired

Show child parameters

channelstringrequired

email | sms | whatsapp | push | postcard

purposestringrequired

marketing | prospecting | transactional | operational

sourceTextstringrequired

attestedBystringrequired

verifyEmailbooleanrequired

listIdsstring[]required

= []

updateExistingbooleanrequired

= true

topicIdstringrequired

= null

statsobjectrequired

Show child parameters

totalintegerrequired

createdintegerrequired

updatedintegerrequired

errorsintegerrequired

suppressedintegerrequired

consentSkippedintegerrequired

consentGrantedintegerrequired

skippedintegerrequired

= 0

blockedintegerrequired

= 0

topicSubscribedintegerrequired

= 0

topicUnsubscribedintegerrequired

= 0

progressobjectrequired

Show child parameters

rowsReadintegerrequired

processedintegerrequired

errorsintegerrequired

errorstringrequired

errorsUrlstring

createdAtstringrequired

finishedAtstringrequired

4XX Default Response

Same as 4XX · POST /v1/events/backfill

5XX Default Response

Same as 4XX · POST /v1/events/backfill

GEThttps://hermeticor.com/v1/imports/{id}

Parameters

idstringpathrequired

Code samples

cURL

curl -X GET "https://hermeticor.com/v1/imports/{id}" \
  -H "Authorization: Bearer $HERMETICOR_API_KEY"

TypeScript

Python

PHP

Ruby

Java

Responses

200 Default Response

Same as 201 · POST /v1/imports

4XX Default Response

Same as 4XX · POST /v1/events/backfill

5XX Default Response

Same as 4XX · POST /v1/events/backfill

GEThttps://hermeticor.com/v1/imports/{id}/preview

First 20 rows as they would be imported, with per-row errors

Parameters

idstringpathrequired

Code samples

cURL

curl -X GET "https://hermeticor.com/v1/imports/{id}/preview" \
  -H "Authorization: Bearer $HERMETICOR_API_KEY"

TypeScript

Python

PHP

Ruby

Java

Responses

200 Default Response

Example

{
  "headers": [
    "string"
  ],
  "rows": [
    {
      "row": 0,
      "identifiers": {},
      "standard": {},
      "attributes": {},
      "errors": [
        "string"
      ],
      "warnings": [
        "string"
      ]
    }
  ]
}

Schema

headersstring[]required

rowsobject[]required

Show child parameters

rowintegerrequired

identifiersobjectrequired

standardobjectrequired

attributesobjectrequired

errorsstring[]required

warningsstring[]required

4XX Default Response

Same as 4XX · POST /v1/events/backfill

5XX Default Response

Same as 4XX · POST /v1/events/backfill

POSThttps://hermeticor.com/v1/imports/{id}/append

Add more CSV rows (no header line) to an upload that has not been committed yet; send big files in several calls, then commit

Parameters

idstringpathrequired

Request body

application/json

csvstringrequired

{
  "csv": "string"
}

Code samples

cURL

curl -X POST "https://hermeticor.com/v1/imports/{id}/append" \
  -H "Authorization: Bearer $HERMETICOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"csv":"string"}'

TypeScript

Python

PHP

Ruby

Java

Responses

200 Default Response

Same as 201 · POST /v1/imports

4XX Default Response

Same as 4XX · POST /v1/events/backfill

5XX Default Response

Same as 4XX · POST /v1/events/backfill

POSThttps://hermeticor.com/v1/imports/{id}/commit

Parameters

idstringpathrequired

Code samples

cURL

curl -X POST "https://hermeticor.com/v1/imports/{id}/commit" \
  -H "Authorization: Bearer $HERMETICOR_API_KEY"

TypeScript

Python

PHP

Ruby

Java

Responses

202 Default Response

Same as 201 · POST /v1/imports

4XX Default Response

Same as 4XX · POST /v1/events/backfill

5XX Default Response

Same as 4XX · POST /v1/events/backfill

Next part

Updated Nov 8, 2026

Was this page helpful?