Users and Role Types

This guide explains how to work with users and role types in the Sure Send CRM Partner API.

Overview

The Sure Send CRM has a flexible user and role management system with two key concepts:

Users: Team members who have access to the CRM
Roles: System-level permissions (owner, admin, member) that control access to features
Role Types: Team-defined categories that describe what kind of team member someone is (e.g., Agent, Broker, Manager, ISA)

Understanding Roles vs Role Types

Roles (System Permissions)

Roles are built-in permission levels that cannot be customized:

Role	Description	Permissions
`owner`	Team owner with full control	All permissions, can manage billing
`admin`	Team administrator	Can manage team members, settings, and most features
`member`	Regular team member	Can access contacts, tasks, and basic features

Role Types (Custom Categories)

Role types are team-defined categories that you can customize to match your organization's structure. Examples:

Agent: Front-line sales agents
Broker: Licensed brokers
Manager: Team managers
ISA: Inside sales agents
Transaction Coordinator: Handles paperwork and closing
Marketing Specialist: Manages marketing campaigns

Key Difference: Roles control what users can do (permissions), while role types describe what kind of team member they are (category/title).

Fetching Users

List All Users

Retrieve all users in your team:

GET /api/partner/users

Query Parameters:

offset (integer, optional): Number of records to skip (default: 0)
limit (integer, optional): Number of records to return (default: 25, max: 100)

Example Request:

curl -X GET "https://api.suresendcrm.com/api/partner/users?limit=10&offset=0" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response:

{
  "users": [
    {
      "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "phone": "+1234567890",
      "role": "admin",
      "roleTypeId": "f1e2d3c4-5678-90ab-cdef-1234567890ab",
      "roleType": {
        "id": "f1e2d3c4-5678-90ab-cdef-1234567890ab",
        "name": "Agent"
      },
      "timezone": "America/New_York",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-10-20T15:45:00Z"
    }
  ],
  "hasMore": false,
  "nextOffset": null
}

Get a Specific User

Retrieve details for a single user:

GET /api/partner/users/{id}

Example Request:

curl -X GET "https://api.suresendcrm.com/api/partner/users/a1b2c3d4-5678-90ab-cdef-1234567890ab" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response:

{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "firstName": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "phone": "+1234567890",
  "role": "admin",
  "roleTypeId": "f1e2d3c4-5678-90ab-cdef-1234567890ab",
  "roleType": {
    "id": "f1e2d3c4-5678-90ab-cdef-1234567890ab",
    "name": "Agent"
  },
  "timezone": "America/New_York",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-10-20T15:45:00Z"
}

Fetching Role Types

List All Role Types

Retrieve all active role types configured for your team:

GET /api/partner/role-types

Example Request:

curl -X GET "https://api.suresendcrm.com/api/partner/role-types" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response:

{
  "roleTypes": [
    {
      "id": "f1e2d3c4-5678-90ab-cdef-1234567890ab",
      "name": "Agent"
    },
    {
      "id": "a2b3c4d5-6789-01bc-def2-3456789012cd",
      "name": "Broker"
    },
    {
      "id": "b3c4d5e6-7890-12cd-ef34-567890123def",
      "name": "Manager"
    }
  ]
}

Get a Specific Role Type

Retrieve details for a single role type:

GET /api/partner/role-types/{id}

Example Request:

curl -X GET "https://api.suresendcrm.com/api/partner/role-types/f1e2d3c4-5678-90ab-cdef-1234567890ab" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response:

{
  "id": "f1e2d3c4-5678-90ab-cdef-1234567890ab",
  "name": "Agent"
}

Updating User Role Types

You can update a user's role type via the user update endpoint:

PUT /api/partner/users/{id}

Request Body:

{
  "roleTypeId": "a2b3c4d5-6789-01bc-def2-3456789012cd"
}

Example Request:

curl -X PUT "https://api.suresendcrm.com/api/partner/users/a1b2c3d4-5678-90ab-cdef-1234567890ab" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "roleTypeId": "a2b3c4d5-6789-01bc-def2-3456789012cd"
  }'

Success Response:

{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "firstName": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "role": "admin",
  "roleTypeId": "a2b3c4d5-6789-01bc-def2-3456789012cd",
  "roleType": {
    "id": "a2b3c4d5-6789-01bc-def2-3456789012cd",
    "name": "Broker"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-10-20T16:00:00Z"
}

Common Use Cases

1. Syncing Team Structure

Keep your external system in sync with the CRM's team structure:

// Fetch all users with their role types
const response = await fetch('https://api.suresendcrm.com/api/partner/users?limit=100', {
  headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }
});

const { users } = await response.json();

// Sync to your system
for (const user of users) {
  await yourSystem.upsertUser({
    externalId: user.id,
    name: `${user.firstName} ${user.lastName}`,
    email: user.email,
    role: user.role,
    roleType: user.roleType?.name
  });
}

2. Filtering by Role Type

Fetch role types and filter users by a specific role type:

// Get all role types
const roleTypesResponse = await fetch('https://api.suresendcrm.com/api/partner/role-types', {
  headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }
});
const { roleTypes } = await roleTypesResponse.json();

// Find the "Agent" role type
const agentRoleType = roleTypes.find(rt => rt.name === 'Agent');

// Get all users
const usersResponse = await fetch('https://api.suresendcrm.com/api/partner/users?limit=100', {
  headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }
});
const { users } = await usersResponse.json();

// Filter to just agents
const agents = users.filter(u => u.roleTypeId === agentRoleType.id);
console.log(`Found ${agents.length} agents`);

3. Assigning Role Types to New Team Members

When a new team member joins, assign them the appropriate role type:

// First, fetch available role types
const roleTypesResponse = await fetch('https://api.suresendcrm.com/api/partner/role-types', {
  headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }
});
const { roleTypes } = await roleTypesResponse.json();

// Find the role type you want to assign
const isaRoleType = roleTypes.find(rt => rt.name === 'ISA');

// Get the user you want to update
const userId = 'a1b2c3d4-5678-90ab-cdef-1234567890ab';

// Update the user with the role type
await fetch(`https://api.suresendcrm.com/api/partner/users/${userId}`, {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    roleTypeId: isaRoleType.id
  })
});

4. Building Team Reports

Generate reports based on role types:

// Fetch all users
const response = await fetch('https://api.suresendcrm.com/api/partner/users?limit=100', {
  headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }
});
const { users } = await response.json();

// Group by role type
const usersByRoleType = users.reduce((acc, user) => {
  const roleTypeName = user.roleType?.name || 'Unassigned';
  if (!acc[roleTypeName]) acc[roleTypeName] = [];
  acc[roleTypeName].push(user);
  return acc;
}, {});

// Print team composition
console.log('Team Composition:');
Object.entries(usersByRoleType).forEach(([roleType, users]) => {
  console.log(`  ${roleType}: ${users.length} users`);
});

Best Practices

1. Cache Role Types

Role types don't change frequently, so cache them to reduce API calls:

let roleTypesCache = null;
let cacheExpiry = null;

async function getRoleTypes() {
  const now = Date.now();

  // Return cached data if still valid (cache for 1 hour)
  if (roleTypesCache && cacheExpiry && now < cacheExpiry) {
    return roleTypesCache;
  }

  // Fetch fresh data
  const response = await fetch('https://api.suresendcrm.com/api/partner/role-types', {
    headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }
  });

  roleTypesCache = await response.json();
  cacheExpiry = now + (60 * 60 * 1000); // 1 hour

  return roleTypesCache;
}

2. Validate Role Types Before Assignment

Always verify that a role type exists and belongs to the team before assigning it:

async function assignRoleType(userId, roleTypeName) {
  // Fetch available role types
  const { roleTypes } = await getRoleTypes();

  // Find the role type
  const roleType = roleTypes.find(rt => rt.name === roleTypeName);

  if (!roleType) {
    throw new Error(`Role type "${roleTypeName}" not found`);
  }

  // Update the user
  await fetch(`https://api.suresendcrm.com/api/partner/users/${userId}`, {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ roleTypeId: roleType.id })
  });
}

3. Handle Pagination for Large Teams

For teams with many users, use pagination:

async function getAllUsers() {
  const allUsers = [];
  let offset = 0;
  const limit = 100;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `https://api.suresendcrm.com/api/partner/users?offset=${offset}&limit=${limit}`,
      { headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' } }
    );

    const data = await response.json();
    allUsers.push(...data.users);

    hasMore = data.hasMore;
    offset = data.nextOffset;
  }

  return allUsers;
}

Error Handling

Invalid Role Type

When assigning a role type that doesn't exist or doesn't belong to the team:

{
  "error": "Invalid role type for this team"
}

HTTP Status: 422 Unprocessable Entity

User Not Found

When trying to update a user that doesn't exist:

{
  "error": "User not found"
}

HTTP Status: 404 Not Found

Related Resources

Authentication Guide - Learn how to authenticate API requests
Getting Started - API quickstart guide
People API Guide - Working with contacts
Webhooks Guide - Real-time event notifications

Support

Need help? Contact our support team:

Email: [email protected]
Documentation: https://docs.suresendcrm.com