Import your contacts with consent

Upload a CSV, map the columns, record the consent you hold, check the preview and commit.

Embed
Preview of the card
<a href="https://hermeticor.com/guides/import-contacts"><img src="https://hermeticor.com/guides/_api/public/orgs/5fcd8b3c-a27c-4688-972f-de710125592f/spaces/9a3da731-ded5-4536-b84f-8c9a61420ff4/pages/0fdedf0f-87d4-4163-a6a8-5e08017af8a2/social-card.svg?v=3e7ae33eec8b" alt="Import your contacts with consent" width="600" height="315"></a>

An import creates or updates people. It records consent only when you say how you got it.

What you need first

  • A CSV (or Excel, or a ZIP with one CSV), up to 50 MB, with column headings in the first row.

  • Each row needs an email, phone or external id.

  • For marketing: a true statement of how these people agreed to hear from you.

  • A key with profiles:write and consent:write.

curl -s -X POST "$BASE/v1/imports" \
  -H "Authorization: Bearer $HERMETICA_API_KEY" -H "Idempotency-Key: import-webinar-1" \
  -F 'file=@webinar.csv;type=text/csv' \
  -F 'mapping={"Email":"email","First name":"firstName","Last name":"lastName","Company":"attributes.company","Unsubscribed":"unsubscribed"}' \
  -F 'tags=webinar-oct-2026' \
  -F 'consentAssertion={"channel":"email","purpose":"marketing","sourceText":"Webinar registration: Email me product updates.","attestedBy":"Acme team"}'

The answer is 201 with status: uploaded and an import id. Add -F listId=<listId> to put everyone on a list.

The sourceText is kept on every consent record it creates. Write what the person actually saw.

2. Preview

curl -s "$BASE/v1/imports/<importId>/preview" -H "Authorization: Bearer $HERMETICA_API_KEY"

You see the parsed rows and any syntax errors.

3. Commit and read the result

curl -s -X POST "$BASE/v1/imports/<importId>/commit" \
  -H "Authorization: Bearer $HERMETICA_API_KEY" -H "Content-Type: application/json" -d '{}'
curl -s "$BASE/v1/imports/<importId>" -H "Authorization: Bearer $HERMETICA_API_KEY"
curl -s "$BASE/v1/imports/<importId>/errors" -H "Authorization: Bearer $HERMETICA_API_KEY"

The stats show created, errors and consentGranted. Errors list the row, the reason and the original data.

  • No consentAssertion: people are imported with no consent on record. Marketing is held back for them.

  • An unsubscribed column revokes consent for any truthy cell. It never grants.

  • Anyone who unsubscribed before, or is suppressed, is never re-granted by an import.

  • Double opt-in lists refuse a consentAssertion. Import without one and send opt-in requests with POST /v1/lists/<listId>/opt-in.

Undo

POST /v1/imports/<importId>/rollback removes the profiles that import created.

Without a file

curl -s -X POST "$BASE/v1/imports/json" \
  -H "Authorization: Bearer $HERMETICA_API_KEY" -H "Content-Type: application/json" \
  -d '{"profiles":[{"email":"ada@example.com","firstName":"Ada"}],"tags":["api-import"]}'

To record consent for people one at a time, see Consent and suppression.

Next: Track events from your app.

Updated