Contacts¶

Manage your contact list programmatically — list, create, and update contacts.

List contacts¶

GET /api/v1/contacts

Query parameters¶

Parameter	Type	Default	Description
`page`	integer	`1`	Page number
`per_page`	integer	`20`	Results per page (max: `100`)
`search`	string	—	Filter by name, email, or phone
`group_id`	integer	—	Filter by group ID
`subscribed`	integer	—	`1` = SMS-subscribed only, `0` = unsubscribed only

Example¶

cURLPython

curl "https://admin.notifybulk.com/api/v1/contacts?page=1&per_page=20&search=john" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

import requests

r = requests.get(
    'https://admin.notifybulk.com/api/v1/contacts',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
    params={'page': 1, 'per_page': 20, 'search': 'john'}
)
data = r.json()

Response¶

{
  "success": true,
  "data": [
    {
      "id": 142,
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "phone": "+12125551234",
      "company": "Acme Corp",
      "groups": [
        { "id": 3, "name": "VIP Customers" }
      ],
      "sms_subscribed": true,
      "email_subscribed": true,
      "created_at": "2025-03-15 14:22:10"
    }
  ],
  "pagination": {
    "total": 843,
    "page": 1,
    "per_page": 20,
    "pages": 43
  }
}

Create a contact¶

POST /api/v1/contacts/create

Request body¶

Field	Type	Required	Description
`email`	string	Yes*	Email address (*required if no `phone`)
`phone`	string	Yes*	Phone in E.164 format (*required if no `email`)
`first_name`	string	No	First name
`last_name`	string	No	Last name
`company`	string	No	Company name
`group_id`	integer	No	Assign to an existing group
`sms_subscribed`	boolean	No	Default: `true`
`email_subscribed`	boolean	No	Default: `true`

Example¶

cURLNode.js

curl -X POST https://admin.notifybulk.com/api/v1/contacts/create \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "phone": "+12125559876",
    "first_name": "Jane",
    "last_name": "Smith",
    "group_id": 3,
    "sms_subscribed": true
  }'

await fetch('https://admin.notifybulk.com/api/v1/contacts/create', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: '[email protected]',
    phone: '+12125559876',
    first_name: 'Jane',
    last_name: 'Smith',
    group_id: 3,
  }),
});

Response¶

{
  "success": true,
  "contact": {
    "id": 201,
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "[email protected]",
    "phone": "+12125559876",
    "company": "",
    "group_id": 3,
    "sms_subscribed": true,
    "email_subscribed": true
  }
}

HTTP status: 201 Created

Error responses¶

HTTP	Error	Cause
`400`	`Provide at least "email" or "phone"`	Both missing
`400`	`"phone" must be a valid number in E.164 format`	Invalid phone
`404`	`Group not found`	Invalid `group_id`
`409`	`A contact with this email already exists`	Duplicate email

Update a contact¶

PUT /api/v1/contacts/update

Only the fields you include are updated. Fields not present in the request are left unchanged.

Request body¶

Field	Type	Required	Description
`id`	integer	Yes	Contact ID to update
`first_name`	string	No	New first name
`last_name`	string	No	New last name
`email`	string	No	New email address
`phone`	string	No	New phone in E.164 format
`company`	string	No	New company name
`group_ids`	integer[]	No	Replaces all group memberships. Pass `[]` to remove from all groups.
`sms_subscribed`	boolean	No	Update SMS opt-in status
`email_subscribed`	boolean	No	Update email opt-in status

group_ids replaces all memberships

Passing group_ids replaces the contact's entire group membership. To add a contact to a new group without removing existing ones, fetch their current groups first and include all IDs in the update.

Example¶

cURL

curl -X PUT https://admin.notifybulk.com/api/v1/contacts/update \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 201,
    "first_name": "Jane",
    "company": "New Corp",
    "group_ids": [3, 7]
  }'

Response¶

{
  "success": true,
  "contact": {
    "id": 201,
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "[email protected]",
    "phone": "+12125559876",
    "company": "New Corp",
    "sms_subscribed": true,
    "email_subscribed": true,
    "groups": [
      { "id": 3, "name": "VIP Customers" },
      { "id": 7, "name": "Newsletter" }
    ]
  }
}

Error responses¶

HTTP	Error	Cause
`400`	`"id" is required`	Missing contact ID
`404`	`Contact not found`	ID doesn't exist or belongs to another store
`409`	`A contact with this email already exists`	Duplicate email on update