Quick Reference Guide

Base URL & Authentication

Base URL: https://builtin-crm.azurewebsites.net/api/v1

Required Headers:

Authorization: Bearer {access_token}
tenant-code: {your_tenant_code}
Content-Type: application/json

Get Access Token:

curl -X POST "https://builtin-crm.azurewebsites.net/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

Essential Endpoints

People Management

# List people with pagination
POST /people/PeoplePagingList
{
  "pageIndex": 0,
  "pageSize": 50,
  "filter": { "isActive": true }
}

# Get person by ID
GET /people/{id}

# Create person
POST /people/CreatePersonInline/{organizationId}
{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com"
}

# Update person
PUT /people/UpdatePersonHeader/{id}
{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe.updated@example.com"
}

# Search people
POST /people/SearchPeopleList/{searchText}

Organization Management

# List organizations
POST /organization/OrganizationPagingList
{
  "pageIndex": 0,
  "pageSize": 50,
  "filter": { "isActive": true }
}

# Get organization by ID
GET /organization/{id}

# Create organization
POST /organization
{
  "name": "Acme Corp",
  "type": "Company",
  "email": "info@acme.com"
}

# Get organization members
POST /organization/{id}/GetAllPeople

Committee Management

# List committees
POST /committee/CommiteePagingList

# Get committee details
GET /committee/get/{committeeId}

# Create committee
POST /committee/createcommittee
{
  "name": "Board of Directors",
  "description": "Executive committee",
  "organizationId": "org-123"
}

# Add committee member
POST /committee/savecommitteemember
{
  "committeeId": "committee-123",
  "personId": "person-456",
  "positionId": "pos-1"
}

Advocacy & Relationships

# Get relationship types
GET /advocacy/GetRelationshipTypes

# Get people relationships
GET /advocacy/list/people-relationships/{peopleId}

# Save people relationship
POST /advocacy/save/people-relationship
{
  "personId": "person-456",
  "relatedOfficialId": "official-789",
  "relationshipTypeId": "rel-1"
}

# Get officials list
GET /advocacy/officials-list-lite/{id}

Audience & Communication

# Search across modules
POST /audience/ModuleSearchList
{
  "searchText": "john",
  "modules": ["people", "organization"]
}

# Broadcast email
POST /audience/BroacastViaEmail
{
  "subject": "Important Update",
  "body": "Message content",
  "audienceSelection": {
    "selectedPeople": ["person-123"]
  }
}

Common Request Patterns

Pagination Request

{
  "pageIndex": 0,
  "pageSize": 50,
  "sortField": "lastName",
  "sortDirection": "asc",
  "searchText": "search term",
  "filter": {
    "isActive": true,
    "dateRange": {
      "startDate": "2023-01-01T00:00:00Z",
      "endDate": "2024-01-01T00:00:00Z"
    }
  }
}

Filter Examples

{
  "filter": {
    "organizationId": "org-123",
    "tags": ["vip", "board-member"],
    "customFields": {
      "field123": "value"
    },
    "locationFilter": {
      "state": "CA",
      "city": "San Francisco"
    }
  }
}

Response Formats

Paginated List Response

{
  "data": [...],
  "totalCount": 150,
  "pageIndex": 0,
  "pageSize": 50,
  "hasNextPage": true,
  "hasPreviousPage": false
}

Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request contains validation errors",
    "details": [
      {
        "field": "email",
        "message": "Email is required",
        "code": "REQUIRED_FIELD"
      }
    ],
    "requestId": "req-123"
  }
}

Common Data Formats

Person Object

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1-555-123-4567",
  "organizationId": "org-123",
  "organizationName": "Acme Corp",
  "isActive": true,
  "createdDate": "2023-01-15T10:30:00Z"
}

Organization Object

{
  "id": "org-123",
  "name": "Acme Corporation",
  "type": "Company",
  "email": "info@acme.com",
  "phone": "+1-555-000-1234",
  "website": "https://acme.com",
  "memberCount": 150,
  "isActive": true
}

Address Object

{
  "type": "Primary",
  "street": "123 Main St",
  "city": "New York",
  "state": "NY",
  "zipCode": "10001",
  "country": "USA"
}

HTTP Status Codes

Code	Meaning	Action
200	Success	Request completed
201	Created	Resource created successfully
400	Bad Request	Check request format and validation
401	Unauthorized	Check access token
403	Forbidden	Check tenant code and permissions
404	Not Found	Check resource ID
429	Rate Limited	Wait and retry
500	Server Error	Contact support with request ID

Rate Limits

• Limit: 1,000 requests per minute per client
• Headers: Check X-RateLimit-* headers in responses
• Retry: Implement exponential backoff for 429 responses

JavaScript Quick Start

// Authentication
const getAccessToken = async () => {
  const response = await fetch('https://builtin-crm.azurewebsites.net/oauth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      'grant_type': 'client_credentials',
      'client_id': 'your-client-id',
      'client_secret': 'your-client-secret'
    })
  });
  const data = await response.json();
  return data.access_token;
};

// API Request Helper
const apiRequest = async (endpoint, options = {}) => {
  const token = await getAccessToken();
  const response = await fetch(`https://builtin-crm.azurewebsites.net/api/v1${endpoint}`, {
    ...options,
    headers: {
      'Authorization': `Bearer ${token}`,
      'tenant-code': 'your-tenant-code',
      'Content-Type': 'application/json',
      ...options.headers
    }
  });
  
  if (!response.ok) {
    const error = await response.json();
    throw new Error(`API Error: ${error.error.message}`);
  }
  
  return response.json();
};

// Get people
const people = await apiRequest('/people/PeoplePagingList', {
  method: 'POST',
  body: JSON.stringify({
    pageIndex: 0,
    pageSize: 50,
    filter: { isActive: true }
  })
});

// Create person
const newPerson = await apiRequest('/people/CreatePersonInline/org-123', {
  method: 'POST',
  body: JSON.stringify({
    firstName: 'John',
    lastName: 'Doe',
    email: 'john.doe@example.com'
  })
});

cURL Examples

# Get access token
curl -X POST "https://builtin-crm.azurewebsites.net/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

# List people
curl -X POST "https://builtin-crm.azurewebsites.net/api/v1/people/PeoplePagingList" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "tenant-code: YOUR_TENANT" \
  -H "Content-Type: application/json" \
  -d '{"pageIndex":0,"pageSize":50,"filter":{"isActive":true}}'

# Get person by ID
curl -X GET "https://builtin-crm.azurewebsites.net/api/v1/people/PERSON_ID" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "tenant-code: YOUR_TENANT"

# Create organization
curl -X POST "https://builtin-crm.azurewebsites.net/api/v1/organization" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "tenant-code: YOUR_TENANT" \
  -H "Content-Type: application/json" \
  -d '{"name":"New Company","type":"Company","email":"info@newco.com"}'

Validation Rules

Required Fields

• Person: firstName, lastName, email
• Organization: name, organizationType
• Committee: name, organizationId

Format Requirements

• Email: Valid RFC 5322 format
• Phone: International format with country code
• Dates: ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ)
• GUIDs: Standard format with hyphens

Length Limits

• Name fields: 200 characters max
• Email: 254 characters max
• Phone: 20 characters max
• Search text: 200 characters max

Troubleshooting

Common Issues

401 Unauthorized

• Missing Authorization header
• Expired access token
• Invalid token format

403 Forbidden

• Missing tenant-code header
• Invalid tenant code
• Insufficient permissions

400 Bad Request

• Invalid JSON format
• Missing required fields
• Validation errors

404 Not Found

• Invalid resource ID
• Resource deleted or inactive

429 Rate Limited

• Too many requests
• Implement retry with backoff

Debug Tips

1. Check request headers include Authorization and tenant-code
2. Verify JSON format and required fields
3. Use request ID from error responses for support
4. Monitor rate limit headers
5. Test with Swagger UI for validation

Links

• Swagger UI: https://builtin-crm.azurewebsites.net/swagger/
• Full API Reference: api-reference.md
• Getting Started: getting-started.md
• Data Models: data-models.md
• Error Handling: error-handling.md