CRM APIs

People, contacts, and progression management

CRM APIs

Endpoints for managing people profiles, contacts, and progression tracking.

Base URL: https://ycwadelaide.adenmgb.com

Authentication: All endpoints require Authorization: Bearer <token> header.

People API

GET /api/staff/people

Retrieve all people/team members (both published and draft).

Response:

[
  {
    "id": 1,
    "name": "John Smith",
    "role": "President",
    "imageUrl": "/api/images/john-smith.jpg",
    "briefMessage": "Leading YCW Adelaide with passion and dedication",
    "displayOrder": 0,
    "published": true,
    "createdAt": "2024-01-15T10:00:00.000Z"
  }
]

Notes:

  • Results ordered by displayOrder ASC, then id ASC
  • imageUrl and briefMessage are optional
  • displayOrder controls the order they appear on the website

POST /api/staff/people

Create a new person/team member.

Request Body:

{
  "name": "Alice Williams",
  "role": "Event Coordinator",
  "imageUrl": "/api/images/alice-williams.jpg",
  "briefMessage": "Organizing events and activities",
  "displayOrder": 3,
  "published": true
}

Required Fields:

  • name - Person's name
  • role - Their role/position

PUT /api/staff/people/:id

Update an existing person.

Request Body: (All fields optional)

Notes:

  • Partial updates supported
  • displayOrder can be updated to reorder team members

DELETE /api/staff/people/:id

Delete a person/team member.

Notes:

  • This action cannot be undone
  • Consider implementing a confirmation dialog

Contacts API

GET /api/staff/contacts

Retrieve all contacts in the CRM system.

Response:

[
  {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "0412 345 678",
    "status": "Member",
    "progressionStage": "Active Member",
    "tags": ["volunteer", "youth"],
    "createdAt": "2024-01-15T10:00:00.000Z"
  }
]

Query Parameters:

  • status (optional) - Filter by status
  • progressionStage (optional) - Filter by progression stage
  • tag (optional) - Filter by tag

Notes:

  • Results ordered by createdAt DESC
  • status can be: "Contact", "Member", "Event Attendee", "Prospect", "Inactive"
  • Includes current progression stage

POST /api/staff/contacts

Create a new contact.

Request Body:

{
  "name": "New Contact",
  "email": "contact@example.com",
  "phone": "0412 345 678",
  "status": "Event Attendee",
  "tags": ["volunteer"],
  "notes": "Met at event"
}

Required Fields:

  • name - Contact name

Notes:

  • email, phone, status, tags, notes are optional
  • Default status is "Event Attendee"

GET /api/staff/contacts/:id

Get a single contact with full details including progression timeline.

Response:

{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "0412 345 678",
  "status": "Member",
  "progressionStage": "Active Member",
  "tags": ["volunteer", "youth"],
  "notes": "Active volunteer",
  "progression": [
    {
      "id": 1,
      "stage": "Initial Contact",
      "interactionType": "Email",
      "notes": "First contact via email",
      "createdAt": "2024-01-15T10:00:00.000Z"
    }
  ],
  "emailHistory": [],
  "followUps": [],
  "createdAt": "2024-01-15T10:00:00.000Z"
}

Notes:

  • Includes progression timeline
  • Includes email history
  • Includes pending follow-ups

PUT /api/staff/contacts/:id

Update an existing contact.

Request Body: (All fields optional)

DELETE /api/staff/contacts/:id

Delete a contact.

Warning: This also deletes all progression entries and history.

Progression Stages API

GET /api/staff/progression-stages

Retrieve all progression stages.

Response:

[
  {
    "id": 1,
    "name": "Initial Contact",
    "description": "First interaction",
    "order": 0
  },
  {
    "id": 2,
    "name": "Follow-up",
    "description": "Ongoing communication",
    "order": 1
  }
]

Notes:

  • Results ordered by order ASC
  • Stages define the progression workflow

POST /api/staff/progression-stages

Create a new progression stage.

Request Body:

{
  "name": "New Stage",
  "description": "Stage description",
  "order": 2
}

PUT /api/staff/progression-stages/:id

Update an existing progression stage.

DELETE /api/staff/progression-stages/:id

Delete a progression stage.

Contact Progression API

POST /api/staff/contacts/:id/progression

Add a progression entry to a contact.

Request Body:

{
  "stageId": 2,
  "interactionType": "Email",
  "notes": "Follow-up email sent"
}

Required Fields:

  • stageId - Progression stage ID

Notes:

  • Creates a timeline entry
  • Updates contact's current progression stage
  • interactionType is optional

GET /api/staff/contacts/:id/progression

Get all progression entries for a contact.

Response:

[
  {
    "id": 1,
    "stage": "Initial Contact",
    "interactionType": "Email",
    "notes": "First contact",
    "createdAt": "2024-01-15T10:00:00.000Z",
    "createdBy": {
      "id": 1,
      "username": "admin"
    }
  }
]

Follow-up Rules API

GET /api/staff/follow-up-rules

Retrieve all follow-up automation rules.

Response:

[
  {
    "id": 1,
    "name": "7-Day Follow-up",
    "triggerStageId": 1,
    "daysAfter": 7,
    "catchupType": "Email",
    "emailTemplateId": 1,
    "active": true
  }
]

Notes:

  • Rules automatically create follow-up reminders
  • Triggered when contacts reach certain stages

POST /api/staff/follow-up-rules

Create a new follow-up rule.

Request Body:

{
  "name": "7-Day Follow-up",
  "triggerStageId": 1,
  "daysAfter": 7,
  "catchupType": "Email",
  "emailTemplateId": 1,
  "active": true
}

Notes:

  • triggerStageId - Stage that triggers the follow-up
  • daysAfter - Number of days after reaching the stage
  • catchupType - Type of follow-up interaction
  • emailTemplateId - Optional email template to send

Follow-up Dashboard API

GET /api/staff/follow-up-dashboard

Get pending and overdue follow-ups.

Response:

{
  "pending": [
    {
      "id": 1,
      "contactId": 5,
      "contactName": "John Doe",
      "ruleName": "7-Day Follow-up",
      "dueDate": "2024-12-20T10:00:00.000Z",
      "catchupType": "Email"
    }
  ],
  "overdue": [],
  "completed": []
}

Notes:

  • Shows follow-ups that need attention
  • Organized by status (pending, overdue, completed)

Bulk Import API

POST /api/staff/contacts/bulk-import

Import multiple contacts from CSV.

Headers:

Authorization: Bearer <token>
Content-Type: multipart/form-data

Request Body (FormData):

file: <CSV file>

CSV Format:

name,email,phone,status
John Doe,john@example.com,0412 345 678,Member
Jane Smith,jane@example.com,0413 456 789,Contact

Success Response:

{
  "success": true,
  "imported": 10,
  "skipped": 2,
  "errors": []
}

Notes:

  • CSV should have header row
  • Required column: name
  • Optional columns: email, phone, status, tags
  • Duplicate emails are skipped

Related Guides

Edit this page
Email APIs
Newsletters, compose emails, templates, and subscribers
Media APIs
Image upload and management