API reference

Contacts.

Add, update, upsert and remove contacts, one at a time or up to 1,000 at once. Every request needs an API key in the Authorization header; the reference overview covers keys, errors and rate limits.

List contacts

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

List the contacts in a contact book, paged by the query parameters.

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

Query parameters
Field	Type	About
`emails`	`string`
`ids`	`string`
`page`	`integer`	1-based page number, at most 10000. Default `1`.
`limit`	`integer`	Contacts per page, at most 200. Defaults to 50. Default `50`.

terminal

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

notix-sdk

from notix import Notix

notix = Notix()  # reads NOTIX_API_KEY

contacts, _ = notix.contacts.list("cb_123", page=1, limit=50)

Responses

200Retrieve multiple contacts

200 response fields
Field	Type	About
`id`required	`string`
`firstName`	`string`	Can be null.
`lastName`	`string`	Can be null.
`email`required	`string`
`subscribed`	`boolean`	Default `true`.
`properties`required	`map of string`
`contactBookId`required	`string`
`createdAt`required	`string`
`updatedAt`required	`string`

Add a contact

POST/v1/contactBooks/{contactBookId}/contactsFull access key

Add one contact to a contact book.

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

Request body (JSON)
Field	Type	About
`email`required	`string`	The contact's email address. Stored trimmed and lower-cased.
`firstName`	`string`
`lastName`	`string`
`properties`	`map of string`
`subscribed`	`boolean`

terminal

curl -X POST "https://app.usenotix.dev/api/v1/contactBooks/<contactBookId>/contacts" \
  -H "Authorization: Bearer $NOTIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "ada@example.com"
}'

notix-js

import { Notix } from "notix-js";

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

const { data, error } = await notix.contacts.create("cb_123", {
  email: "ada@example.com",
  firstName: "Ada",
  properties: { company: "Acme" },
});

notix-sdk

from notix import Notix

notix = Notix()  # reads NOTIX_API_KEY

contact, _ = notix.contacts.create("cb_123", {
    "email": "ada@example.com",
    "firstName": "Ada",
    "properties": {"company": "Acme"},
})

usenotix/notix-php

use Notix\Notix;

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

$contact = $notix->contacts->create('cb_123', [
    'email' => 'ada@example.com',
    'firstName' => 'Ada',
    'properties' => ['company' => 'Acme'],
]);

Responses

200The contact was added.

200 response fields
Field	Type	About
`contactId`	`string`

Get a contact

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

Retrieve one contact.

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

terminal

curl -X GET "https://app.usenotix.dev/api/v1/contactBooks/<contactBookId>/contacts/<contactId>" \
  -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.contacts.get("cb_123", "cnt_456");

notix-sdk

from notix import Notix

notix = Notix()  # reads NOTIX_API_KEY

contact, _ = notix.contacts.get("cb_123", "cnt_456")

usenotix/notix-php

use Notix\Notix;

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

$contact = $notix->contacts->get('cb_123', 'cnt_456');

Responses

200Retrieve the contact

200 response fields
Field	Type	About
`id`required	`string`
`firstName`	`string`	Can be null.
`lastName`	`string`	Can be null.
`email`required	`string`
`subscribed`	`boolean`	Default `true`.
`properties`required	`map of string`
`contactBookId`required	`string`
`createdAt`required	`string`
`updatedAt`required	`string`

Update a contact

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

Change the fields you send on an existing contact.

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

Request body (JSON)
Field	Type	About
`firstName`	`string`
`lastName`	`string`
`properties`	`map of string`
`subscribed`	`boolean`

terminal

curl -X PATCH "https://app.usenotix.dev/api/v1/contactBooks/<contactBookId>/contacts/<contactId>" \
  -H "Authorization: Bearer $NOTIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "firstName": "Acme",
  "lastName": "Acme",
  "properties": {},
  "subscribed": true
}'

notix-js

import { Notix } from "notix-js";

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

const { data, error } = await notix.contacts.update("cb_123", "cnt_456", { lastName: "Lovelace" });

notix-sdk

from notix import Notix

notix = Notix()  # reads NOTIX_API_KEY

contact, _ = notix.contacts.update("cb_123", "cnt_456", {"lastName": "Lovelace"})

usenotix/notix-php

use Notix\Notix;

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

$contact = $notix->contacts->update('cb_123', 'cnt_456', ['lastName' => 'Lovelace']);

Responses

200The contact was updated.

200 response fields
Field	Type	About
`contactId`	`string`

Upsert a contact

PUT/v1/contactBooks/{contactBookId}/contacts/{contactId}Full access key

Create the contact if it does not exist, or update it if it does.

Path parameters
Field	Type	About
`contactBookId`required	`string`
`contactId`required	`string`	The contact this request is about. With an email in the body it must be the id of the contact that email already belongs to, or the email must be new to the book. Without an email in the body the contact must already exist.

Request body (JSON)
Field	Type	About
`email`	`string`	The contact's email address, stored trimmed and lower-cased. Optional: leave it out to update the contact the path id names, by id alone.
`firstName`	`string`
`lastName`	`string`
`properties`	`map of string`
`subscribed`	`boolean`

terminal

curl -X PUT "https://app.usenotix.dev/api/v1/contactBooks/<contactBookId>/contacts/<contactId>" \
  -H "Authorization: Bearer $NOTIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "customer@example.com",
  "firstName": "Acme",
  "lastName": "Acme",
  "properties": {},
  "subscribed": true
}'

notix-js

import { Notix } from "notix-js";

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

const { data, error } = await notix.contacts.upsert("cb_123", "cnt_456", {
  email: "ada@example.com",
  firstName: "Ada",
});

notix-sdk

from notix import Notix

notix = Notix()  # reads NOTIX_API_KEY

contact, _ = notix.contacts.upsert("cb_123", "cnt_456", {"email": "ada@example.com", "firstName": "Ada"})

usenotix/notix-php

use Notix\Notix;

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

$contact = $notix->contacts->upsert('cb_123', 'cnt_456', ['email' => 'ada@example.com', 'firstName' => 'Ada']);

Responses

200Contact upserted successfully

200 response fields
Field	Type	About
`contactId`required	`string`

Delete a contact

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

Remove one contact from a contact book.

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

terminal

curl -X DELETE "https://app.usenotix.dev/api/v1/contactBooks/<contactBookId>/contacts/<contactId>" \
  -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.contacts.delete("cb_123", "cnt_456");

notix-sdk

from notix import Notix

notix = Notix()  # reads NOTIX_API_KEY

result, _ = notix.contacts.delete(book_id="cb_123", contact_id="cnt_456")

usenotix/notix-php

use Notix\Notix;

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

$result = $notix->contacts->delete('cb_123', 'cnt_456');

Responses

200Contact deleted successfully

200 response fields
Field	Type	About
`success`required	`boolean`

Add contacts in bulk

POST/v1/contactBooks/{contactBookId}/contacts/bulkFull access key

Add up to 1,000 contacts to a contact book in one request.

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

Request body (JSON)
Field	Type	About
`email`required	`string`
`firstName`	`string`
`lastName`	`string`
`properties`	`map of string`
`subscribed`	`boolean`

terminal

curl -X POST "https://app.usenotix.dev/api/v1/contactBooks/<contactBookId>/contacts/bulk" \
  -H "Authorization: Bearer $NOTIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
  {
    "email": "customer@example.com"
  }
]'

notix-js

import { Notix } from "notix-js";

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

const { data, error } = await notix.contacts.bulkCreate("cb_123", [
  { email: "ada@example.com", firstName: "Ada" },
  { email: "tunde@example.com", firstName: "Tunde" },
]);

notix-sdk

from notix import Notix

notix = Notix()  # reads NOTIX_API_KEY

result, _ = notix.contacts.bulk_create("cb_123", [
    {"email": "ada@example.com", "firstName": "Ada"},
    {"email": "tunde@example.com", "firstName": "Tunde"},
])

usenotix/notix-php

use Notix\Notix;

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

$result = $notix->contacts->bulkCreate('cb_123', [
    ['email' => 'ada@example.com', 'firstName' => 'Ada'],
    ['email' => 'tunde@example.com', 'firstName' => 'Tunde'],
]);

Responses

200Bulk add contacts to a contact book

200 response fields
Field	Type	About
`message`required	`string`
`count`required	`number`

Delete contacts in bulk

DELETE/v1/contactBooks/{contactBookId}/contacts/bulkFull access key

Remove up to 1,000 contacts from a contact book in one request.

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

Request body (JSON)
Field	Type	About
`contactIds`required	`string[]`

terminal

curl -X DELETE "https://app.usenotix.dev/api/v1/contactBooks/<contactBookId>/contacts/bulk" \
  -H "Authorization: Bearer $NOTIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "contactIds": [
    "string"
  ]
}'

notix-js

import { Notix } from "notix-js";

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

const { data, error } = await notix.contacts.bulkDelete("cb_123", { contactIds: ["cnt_1", "cnt_2"] });

notix-sdk

from notix import Notix

notix = Notix()  # reads NOTIX_API_KEY

result, _ = notix.contacts.bulk_delete("cb_123", {"contactIds": ["cnt_1", "cnt_2"]})

usenotix/notix-php

use Notix\Notix;

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

$result = $notix->contacts->bulkDelete('cb_123', ['contactIds' => ['cnt_1', 'cnt_2']]);

Responses

200Bulk delete contacts from a contact book

200 response fields
Field	Type	About
`success`required	`boolean`
`count`required	`number`