API reference

Contact books.

Create and manage the lists contacts live in. Every request needs an API key in the Authorization header; the reference overview covers keys, errors and rate limits.

List contact books

GET/v1/contactBooksFull access key

List the contact books the API key can reach.

terminal

curl -X GET "https://app.usenotix.dev/api/v1/contactBooks" \
  -H "Authorization: Bearer $NOTIX_API_KEY"

notix-js

import { Notix } from "notix-js";

const notix = new Notix(process.env.NOTIX_API_KEY);

const { data, error } = await notix.contactBooks.list();

notix-sdk

from notix import Notix

notix = Notix()  # reads NOTIX_API_KEY

books, _ = notix.contact_books.list()

usenotix/notix-php

use Notix\Notix;

$notix = new Notix(getenv('NOTIX_API_KEY'));

$books = $notix->contactBooks->list();

Responses

200Retrieve contact books accessible by the API key

200 response fields
Field	Type	About
`id`required	`string`	The ID of the contact book
`name`required	`string`	The name of the contact book
`teamId`required	`number`	The ID of the team
`properties`required	`map of string`	Custom properties for the contact book
`variables`required	`string[]`	Allowed personalization variables for contacts in this book
`emoji`required	`string`	The emoji associated with the contact book
`doubleOptInEnabled`	`boolean`	Whether double opt-in is enabled for new contacts
`doubleOptInFrom`	`string`	From address used for double opt-in emails (must use a verified domain) Can be null.
`doubleOptInSubject`	`string`	Subject line used for double opt-in confirmation email Can be null.
`doubleOptInContent`	`string`	Email editor JSON content used for double opt-in confirmation Can be null.
`createdAt`required	`string`	The creation timestamp
`updatedAt`required	`string`	The last update timestamp
`_count`	`object`
`_count.contacts`required	`number`	The number of contacts in the contact book

Create a contact book

POST/v1/contactBooksFull access key

Create a new contact book.

Request body (JSON)
Field	Type	About
`name`required	`string`
`emoji`	`string`
`properties`	`map of string`
`doubleOptInEnabled`	`boolean`
`doubleOptInFrom`	`string`	Can be null.
`doubleOptInSubject`	`string`
`doubleOptInContent`	`string`
`variables`	`string[]`

terminal

curl -X POST "https://app.usenotix.dev/api/v1/contactBooks" \
  -H "Authorization: Bearer $NOTIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme"
}'

notix-js

import { Notix } from "notix-js";

const notix = new Notix(process.env.NOTIX_API_KEY);

const { data, error } = await notix.contactBooks.create({
  name: "Newsletter",
  variables: ["company", "plan"],
});

notix-sdk

from notix import Notix

notix = Notix()  # reads NOTIX_API_KEY

book, _ = notix.contact_books.create({"name": "Newsletter", "variables": ["company", "plan"]})

usenotix/notix-php

use Notix\Notix;

$notix = new Notix(getenv('NOTIX_API_KEY'));

$book = $notix->contactBooks->create(['name' => 'Newsletter', 'variables' => ['company', 'plan']]);

Responses

200Create a new contact book

200 response fields
Field	Type	About
`id`required	`string`	The ID of the contact book
`name`required	`string`	The name of the contact book
`teamId`required	`number`	The ID of the team
`properties`required	`map of string`	Custom properties for the contact book
`variables`required	`string[]`	Allowed personalization variables for contacts in this book
`emoji`required	`string`	The emoji associated with the contact book
`doubleOptInEnabled`	`boolean`	Whether double opt-in is enabled for new contacts
`doubleOptInFrom`	`string`	From address used for double opt-in emails (must use a verified domain) Can be null.
`doubleOptInSubject`	`string`	Subject line used for double opt-in confirmation email Can be null.
`doubleOptInContent`	`string`	Email editor JSON content used for double opt-in confirmation Can be null.
`createdAt`required	`string`	The creation timestamp
`updatedAt`required	`string`	The last update timestamp
`_count`	`object`
`_count.contacts`required	`number`	The number of contacts in the contact book

Get a contact book

GET/v1/contactBooks/{contactBookId}Full access key

Retrieve one contact book.

Path parameters
Field	Type	About
`contactBookId`required	`string`

terminal

curl -X GET "https://app.usenotix.dev/api/v1/contactBooks/<contactBookId>" \
  -H "Authorization: Bearer $NOTIX_API_KEY"

notix-js

import { Notix } from "notix-js";

const notix = new Notix(process.env.NOTIX_API_KEY);

const { data, error } = await notix.contactBooks.get("cb_123");

notix-sdk

from notix import Notix

notix = Notix()  # reads NOTIX_API_KEY

book, _ = notix.contact_books.get("cb_123")

usenotix/notix-php

use Notix\Notix;

$notix = new Notix(getenv('NOTIX_API_KEY'));

$book = $notix->contactBooks->get('cb_123');

Responses

200Retrieve the contact book

200 response fields
Field	Type	About
`id`required	`string`	The ID of the contact book
`name`required	`string`	The name of the contact book
`teamId`required	`number`	The ID of the team
`properties`required	`map of string`	Custom properties for the contact book
`variables`required	`string[]`	Allowed personalization variables for contacts in this book
`emoji`required	`string`	The emoji associated with the contact book
`doubleOptInEnabled`	`boolean`	Whether double opt-in is enabled for new contacts
`doubleOptInFrom`	`string`	From address used for double opt-in emails (must use a verified domain) Can be null.
`doubleOptInSubject`	`string`	Subject line used for double opt-in confirmation email Can be null.
`doubleOptInContent`	`string`	Email editor JSON content used for double opt-in confirmation Can be null.
`createdAt`required	`string`	The creation timestamp
`updatedAt`required	`string`	The last update timestamp
`_count`	`object`
`_count.contacts`required	`number`	The number of contacts in the contact book

403Forbidden - API key doesn't have access to this contact book

403 response fields
Field	Type	About
`error`required	`string`

404Contact book not found

404 response fields
Field	Type	About
`error`required	`string`

Update a contact book

PATCH/v1/contactBooks/{contactBookId}Full access key

Change a contact book's details.

Path parameters
Field	Type	About
`contactBookId`required	`string`

Request body (JSON)
Field	Type	About
`name`	`string`
`emoji`	`string`
`properties`	`map of string`
`doubleOptInEnabled`	`boolean`
`doubleOptInFrom`	`string`	Can be null.
`doubleOptInSubject`	`string`
`doubleOptInContent`	`string`
`variables`	`string[]`

terminal

curl -X PATCH "https://app.usenotix.dev/api/v1/contactBooks/<contactBookId>" \
  -H "Authorization: Bearer $NOTIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme",
  "emoji": "string",
  "properties": {},
  "doubleOptInEnabled": true,
  "doubleOptInFrom": "string",
  "doubleOptInSubject": "Your receipt for order 4471",
  "doubleOptInContent": "string",
  "variables": [
    "string"
  ]
}'

notix-js

import { Notix } from "notix-js";

const notix = new Notix(process.env.NOTIX_API_KEY);

const { data, error } = await notix.contactBooks.update("cb_123", { doubleOptInEnabled: true });

notix-sdk

from notix import Notix

notix = Notix()  # reads NOTIX_API_KEY

book, _ = notix.contact_books.update("cb_123", {"doubleOptInEnabled": True})

usenotix/notix-php

use Notix\Notix;

$notix = new Notix(getenv('NOTIX_API_KEY'));

$book = $notix->contactBooks->update('cb_123', ['doubleOptInEnabled' => true]);

Responses

200Update the contact book

200 response fields
Field	Type	About
`id`required	`string`	The ID of the contact book
`name`required	`string`	The name of the contact book
`teamId`required	`number`	The ID of the team
`properties`required	`map of string`	Custom properties for the contact book
`variables`required	`string[]`	Allowed personalization variables for contacts in this book
`emoji`required	`string`	The emoji associated with the contact book
`doubleOptInEnabled`	`boolean`	Whether double opt-in is enabled for new contacts
`doubleOptInFrom`	`string`	From address used for double opt-in emails (must use a verified domain) Can be null.
`doubleOptInSubject`	`string`	Subject line used for double opt-in confirmation email Can be null.
`doubleOptInContent`	`string`	Email editor JSON content used for double opt-in confirmation Can be null.
`createdAt`required	`string`	The creation timestamp
`updatedAt`required	`string`	The last update timestamp
`_count`	`object`
`_count.contacts`required	`number`	The number of contacts in the contact book

403Forbidden - API key doesn't have access to this contact book

403 response fields
Field	Type	About
`error`required	`string`

404Contact book not found

404 response fields
Field	Type	About
`error`required	`string`

Delete a contact book

DELETE/v1/contactBooks/{contactBookId}Full access key

Delete a contact book and every contact in it. Refused with 400 while a scheduled or running campaign or an active journey uses the book.

Path parameters
Field	Type	About
`contactBookId`required	`string`

terminal

curl -X DELETE "https://app.usenotix.dev/api/v1/contactBooks/<contactBookId>" \
  -H "Authorization: Bearer $NOTIX_API_KEY"

notix-js

import { Notix } from "notix-js";

const notix = new Notix(process.env.NOTIX_API_KEY);

const { data, error } = await notix.contactBooks.delete("cb_123");

notix-sdk

from notix import Notix

notix = Notix()  # reads NOTIX_API_KEY

result, _ = notix.contact_books.delete("cb_123")

usenotix/notix-php

use Notix\Notix;

$notix = new Notix(getenv('NOTIX_API_KEY'));

$result = $notix->contactBooks->delete('cb_123');

Responses

200Contact book deleted successfully

200 response fields
Field	Type	About
`id`required	`string`
`success`required	`boolean`
`message`required	`string`

403Forbidden - API key doesn't have access

403 response fields
Field	Type	About
`error`required	`string`

404Contact book not found

404 response fields
Field	Type	About
`error`required	`string`