Contacts endpoint

The /contacts endpoint allows you to manage your Notocat contacts. You can create, update, delete and list your contacts.

TIP

Before you proceed, make sure you have read the API Authentication documentation to learn how to get your API key.

You can get the newsletter ID from the URL of your newsletter page in Notocat. Open your newsletter from your dashboard and check the URL in your browser. The newsletter ID starts with wks_ and has 25 characters like in the picture below:

List contacts

Example request

curl "https://api.notocat.com/v1/contacts?newsletter_id=<newsletter_id>" \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <token>"

Request headers

Name	Type	Description
Accept	`string`	`application/json`
Authorization	`string`	`Bearer <token>` required

Query parameters

Name	Type	Description
newsletter_id	`string`	The newsletter ID required
limit	`number`	How many contacts per page to return. Default is 100.
page	`number`	The current page. Default is 1.
email	`string`	Used to search by email. The search is case-insensitive.
subscribed	`boolean`	Used to filter by subscription status.

Response

Click to view a response sample

Successful response - 200 OK

{
	"data": [
		{
			"id": "con_D6zCfeVDaAAT-b9dl9SIE",
			"workspace_id": "wks_Tj4fTx-GWT0kCkKc375tG",
			"name": "Noto",
			"first_name": "Noto",
			"last_name": "Cat",
			"email": "[email protected]",
			"subscribed": true,
			"unsub_token": "DwVf3KDpCeLqQTWADxulW",
			"createdAt": "2023-04-25T14:34:03.000Z",
			"updatedAt": "2023-04-25T15:30:28.000Z"
		},
		{
			"id": "con_VZJPm7NePiZ_rMNablrvJ",
			"workspace_id": "wks_Tj4fTx-GWT0kCkKc375tG",
			"name": "Raz",
			"first_name": "",
			"last_name": "",
			"email": "[email protected]",
			"subscribed": true,
			"unsub_token": "mYjH5tzwr2FKexOuhZruK",
			"createdAt": "2023-04-25T14:34:03.000Z",
			"updatedAt": "2023-04-25T14:34:19.000Z"
		}
	],
	"total": 2,
	"page": 1,
	"offset": 0
}

No contacts found - 404 Not Found

{
  "message": "No contacts found"
}

Invalid newsletter ID - 400 Bad request

{
  "message": "Invalid newsletter ID"
}

Create or update contacts in bulk

The endpoint can be used to create a full list of contacts with Notocat. If a contact already exists, the data will be merged. The contacts can be updated in bulk when provided with IDs or emails that already exist in the database. If the contact does not exist, it will be created with the email provided.

The endpoint accepts a minimum of 1 contact and a maximum of 1000 contacts.

Example request

curl "https://api.notocat.com/v1/contacts" \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
	"newsletter_id": "wks_40LizbZv26Cu2jKbnoibN",
	"contacts": [
		{
			"id": "con_D6zCfeVDaAAT-b9dl9SIE",
			"name": "Noto",
			"email": "[email protected]",
			"first_name": "Noto",
			"last_name": "Cat",
			"subscribed_from": "update"
		}
	]
}'

Request headers

Name	Type	Description
Accept	`string`	`application/json` required
Content-Type	`string`	`application/json` required
Authorization	`string`	`Bearer <token>` required

Request body

Name	Type	Description
newsletter_id	`string`	The newsletter ID required
contacts	`array`	An array of 1-1000 contacts required
contacts[].id	`string`	The contact ID if the contact already exists in the database. Useful for bulk updates.
contacts[].email	`string`	The contact email required
contacts[].name	`string`	The contact name
contacts[].first_name	`string`	The contact's first name
contacts[].last_name	`string`	The contact's last name
contacts[].subscribed_from	`string`	Informational field to help categorizing contacts later on.
contacts[].subscribed	`boolean`	If the contact is subscribed or not. Defaults to `true`.

Response

Click to view a response sample

Successful response - 200 OK

{
  "synced": 1000
}

No contacts found - 404 Not Found

{
  "message": "No contacts found"
}

Invalid workspace ID - 400 Bad request

{
  "message": "Invalid workspace ID"
}

Update a contact

This endpoint can be used to update a single contact at a time by providing the contact ID. con_D6zCfeVDaAAT-b9dl9SIE is the contact ID in the example below.

Example request

curl "https://api.notocat.com/v1/contacts/con_D6zCfeVDaAAT-b9dl9SIE" \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
	"newsletter_id": "wks_40LizbZv26Cu2jKbnoibN",
	"name": "Noto",
	"email": "[email protected]",
	"first_name": "Noto",
	"last_name": "Cat",
	"subscribed": true,
	"subscribed_from": "update"
}'

Request headers

Name	Type	Description
Accept	`string`	`application/json` required
Content-Type	`string`	`application/json` required
Authorization	`string`	`Bearer <token>` required

Request body

Name	Type	Description
newsletter_id	`string`	The newsletter ID required
contacts	`array`	An array of 1-1000 contacts required
contacts[].email	`string`	The contact email
contacts[].name	`string`	The contact name
contacts[].first_name	`string`	The contact's first name
contacts[].last_name	`string`	The contact's last name
contacts[].subscribed_from	`string`	Informational field to help categorizing contacts later on.
contacts[].subscribed	`boolean`	If the contact is subscribed or not. Defaults to `true`.

Response

Click to view a response sample

Successful response - 200 OK

{
	"id": "con_D6zCfeVDaAAT-b9dl9SIE",
	"workspace_id": "wks_Tj4fTx-GWT0kCkKc375tG",
	"name": "Noto",
	"first_name": "Noto",
	"last_name": "Cat",
	"email": "[email protected]",
	"subscribed": true,
	"unsub_token": "DwVf3KDpCeLqQTWADxulW",
	"createdAt": "2023-04-25T14:34:03.000Z",
	"updatedAt": "2023-04-25T15:30:28.000Z"
},

No contacts found - 404 Not Found

{
	"error": "Contact not found"
}

400 Bad request

{
	"error": "You do not have access to this resource."
}

Delete contacts

This endpoint can be used to delete contacts from a workspace in bulk. This action is irreversible.

TIP

By default, the endpoint will only delete contacts that are not subscribed. If you want to delete all contacts, you can pass the subscribed query parameter with the value true.

Example request

curl "https://api.notocat.com/v1/contacts?newsletter_id=<newsletter_id>" \
	-X DELETE \
	-H "Accept: application/json" \
	-H "Authorization : Bearer <token>" \

Request headers

Name	Type	Description
Accept	`string`	`application/json` required
Authorization	`string`	`Bearer <token>` required

Query parameters

Name	Type	Description
newsletter_id	`string`	The newsletter ID required
subscribed	`boolean`	Used to filter by subscription status.

Response

Click to view a response sample

Successful response - 200 OK

{
	"contacts_removed": 1000
}

No contacts found - 404 Not Found

{
	"message": "No contacts found"
}

Invalid newsletter ID - 400 Bad request

{
	"message": "Invalid newsletter ID"
}

# Contacts endpoint

# How to find the Newsletter ID

# List contacts

# Example request

# Request headers

# Query parameters

# Response

# Create or update contacts in bulk

# Example request

# Request headers

# Request body

# Response

# Update a contact

# Example request

# Request headers

# Request body

# Response

# Delete contacts

# Example request

# Request headers

# Query parameters

# Response

Contacts endpoint

How to find the Newsletter ID

List contacts

Example request

Request headers

Query parameters

Response

Create or update contacts in bulk

Example request

Request headers

Request body

Response

Update a contact

Example request

Request headers

Request body

Response

Delete contacts

Example request

Request headers

Query parameters

Response