Contacts

Contacts are the core object in PushButtonCRM. Each contact belongs to a single tenant and can be assigned to a pipeline stage, tagged, and linked to a company.

Schema notes: The auth identifier field is login, not email. Soft-deleted contacts have deleted = true. Pipeline stage is stored in stage.

GET/api/v1/contacts

Return a paginated list of contacts for your tenant. Soft-deleted contacts are excluded by default.

Query parameters

Name	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Results per page — max 100 (default: 25)
`stage`	string	Filter by pipeline stage slug
`tag`	string	Filter by tag name
`search`	string	Full-text search on first_name, last_name, email
`include_deleted`	boolean	Include soft-deleted contacts (default: false)

Example response

{
  "contacts": [
    {
      "id": 1042,
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@acme.com",
      "login": "jane@acme.com",
      "cellphone": "+15551234567",
      "stage": "prospect",
      "pipeline_type": "sales",
      "deleted": false,
      "addedtime": 1710000000
    }
  ],
  "total": 142,
  "page": 1,
  "limit": 25
}

GET/api/v1/contacts/:id

Fetch a single contact by ID.

Example response

{
  "id": 1042,
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@acme.com",
  "login": "jane@acme.com",
  "cellphone": "+15551234567",
  "stage": "prospect",
  "pipeline_type": "sales",
  "deleted": false,
  "addedtime": 1710000000
}

POST/api/v1/contacts

Create a new contact. Returns the created contact with its assigned ID.

Request body

Field	Type	Description
`first_name`required	string	Contact's first name
`last_name`	string	Contact's last name
`email`	string	Email address (display)
`login`	string	Auth identifier — defaults to email if omitted
`cellphone`	string	Phone number in E.164 format
`stage`	string	Pipeline stage slug
`pipeline_type`required	string	Pipeline type (e.g. 'sales')

Example request

curl -X POST https://app.pushbuttoncrm.com/api/v1/contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@acme.com",
    "pipeline_type": "sales"
  }'

Example response

{
  "id": 1043,
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@acme.com",
  "login": "jane@acme.com",
  "pipeline_type": "sales",
  "deleted": false,
  "addedtime": 1710100000
}

PUT/api/v1/contacts/:id

Replace all fields on a contact. Fields not included are set to null.

Request body

Field	Type	Description
`first_name`required	string	Contact's first name
`last_name`	string	Contact's last name
`email`	string	Email address
`cellphone`	string	Phone number in E.164 format
`stage`	string	Pipeline stage slug
`pipeline_type`required	string	Pipeline type

Example response

{ "id": 1042, "first_name": "Jane", ... }

DELETE/api/v1/contacts/:id

Soft-delete a contact. Sets deleted = true. The contact is hidden from list endpoints but not removed from the database.

Example response

{ "id": 1042, "deleted": true }