Import contacts from CSV
Import up to 1,000 contacts from CSV text (at most 1,000,000 bytes) into a contact book.
https://app.usenotix.dev/api/v1/contactBooks/{contactBookId}/contacts/importNeeds a full access key. Sending access keys cannot call this. Key permissions lists the extra rules some calls have.
Import up to 1,000 contacts from CSV text (at most 1,000,000 bytes) into a contact book. The first row names the columns: email is required; firstName, lastName and subscribed are optional; any other column becomes a property.
Every row is checked before anything is written. A row is refused, with its reason, when the address is not valid (invalid-email), repeats an earlier row (duplicate), a name or property would run as a spreadsheet formula (formula: it starts with =, +, -, @ or | and is not a plain number), or a field is too long (too-long).
An address on the suppression list is written unsubscribed, whatever the file says. A temporary SOFT_BOUNCE_REPEATED entry is the exception: it is not an opt-out, so it leaves the row as the file says. A contact book with double opt-in creates each new contact pending and sends it the confirmation email; confirmationEmails says how many. An existing contact is updated and never re-subscribed. Accepted rows are queued and appear within seconds.
Dry run
Send the header Notix-Dry-Run: true to get the same summary without writing anything or sending any confirmation email.
Idempotency
Pass an Idempotency-Key header to make a retry safe for 24 hours. The same key and body answers the first summary with Idempotent-Replayed: true and queues nothing again.
Path parameters
Body parameters
The file's text. A header row naming an email column, optional firstName, lastName and subscribed columns, and any other column as a property. At most 1000 rows and 1,000,000 bytes.
At most 1,000,000 characters.
Headers
Bearer followed by your API key.
Makes the request safe to retry for 24 hours. Same key and same body answers the original result without running again, with the response header Idempotent-Replayed: true. Same key and a different body answers 409 NOT_UNIQUE; same key while the first request is still running answers 409 too, so retry shortly. Keys are scoped to the API key.
Set to true to preview the request instead of running it. The answer is 200 with dryRun: true: who it would reach, what they would see, what it would cost, whether policy allows it and the limits it counts against. Nothing is sent, charged, reserved or written. A write route that cannot preview answers 400.
Errors
The file is too large, has too many rows, or the body is not valid.
The key's approval policy does not allow the journey enrolments or confirmation emails this import sets off.
No contact book with this id for the calling team.
The key's daily journey enrolment limit or email cap is reached.
Every error has the same shape. See all error codes.
curl -X POST "https://app.usenotix.dev/api/v1/contactBooks/<contactBookId>/contacts/import" \
-H "Authorization: Bearer $NOTIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"csv": "email,firstName,plan\nada@example.com,Ada,Pro"
}'
{
"contactBookId": "cm1x8f3k20001qz7v5b9d2e4a",
"totalRows": 1,
"accepted": 1,
"newContacts": 1,
"existingContacts": 1,
"suppressed": 1,
"confirmationEmails": 1,
"rejected": 1,
"rejections": [
{
"value": "string",
"reason": "invalid-email"
}
],
"rejectionsTruncated": true,
"journeyEnrolments": 1,
"refusal": "string",
"dryRun": true
}