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.
How to find the Newsletter ID
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:
![Noto settings](/assets/notocat-newsletter-id.jpg)
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. |
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"
}