API Reference

Base Information
People Management
Organization Management
Committee Management
Advocacy & Political Relations
Audience & Communication
Common Patterns

Base Information

Base URL

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

Common Headers

All requests require these headers:

http

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

Response Format

All responses follow a consistent format:

json

{
  "data": [...],           // Response data
  "totalCount": 150,       // Total record count (for paginated responses)
  "pageIndex": 0,          // Current page index
  "pageSize": 50,          // Records per page
  "hasNextPage": true      // Whether more pages exist
}

People Management

Get Person Details

Retrieve detailed information about a specific person.

Endpoint: GET /people/{id}

Parameters:

id (path, required): GUID - Unique identifier of the person

Authentication: Required

Example Request:

bash

curl -X GET "https://builtin-crm.azurewebsites.net/api/v1/people/123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer your-access-token" \
  -H "tenant-code: your-tenant-code"

Example Response:

json

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1-555-123-4567",
  "organizationId": "org-456",
  "organizationName": "Acme Corporation",
  "positions": [
    {
      "id": "pos-789",
      "title": "Senior Manager",
      "department": "Engineering",
      "startDate": "2023-01-15T00:00:00Z",
      "isActive": true
    }
  ],
  "addresses": [
    {
      "type": "Primary",
      "street": "123 Main St",
      "city": "New York",
      "state": "NY",
      "zipCode": "10001",
      "country": "USA"
    }
  ],
  "createdDate": "2023-01-15T10:30:00Z",
  "modifiedDate": "2024-01-20T15:45:00Z",
  "isActive": true
}

List People with Pagination

Retrieve a paginated list of people with advanced filtering capabilities.

Endpoint: POST /people/PeoplePagingList

Authentication: Required

Request Body:

json

{
  "pageIndex": 0,
  "pageSize": 50,
  "sortField": "lastName",
  "sortDirection": "asc",
  "filter": {
    "searchText": "john",
    "organizationId": "org-456",
    "isActive": true,
    "personaTypeId": "type-123",
    "dateRange": {
      "startDate": "2023-01-01T00:00:00Z",
      "endDate": "2024-01-01T00:00:00Z"
    },
    "tags": ["vip", "board-member"],
    "customFields": {
      "field123": "value",
      "field456": "another-value"
    }
  }
}

Example Response:

json

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "phone": "+1-555-123-4567",
      "organizationName": "Acme Corporation",
      "primaryPosition": "Senior Manager",
      "isActive": true,
      "tags": ["vip", "board-member"],
      "lastModified": "2024-01-20T15:45:00Z"
    }
  ],
  "totalCount": 1,
  "pageIndex": 0,
  "pageSize": 50,
  "hasNextPage": false
}

Search People

Search for people using text-based queries.

Endpoint: POST /people/SearchPeopleList/{searchText}

Parameters:

searchText (path, required): Search query string

Authentication: Required

Request Body: ListViewRequest<PeopleListViewBodyFilter>

Example:

bash

curl -X POST "https://builtin-crm.azurewebsites.net/api/v1/people/SearchPeopleList/john%20doe" \
  -H "Authorization: Bearer your-access-token" \
  -H "tenant-code: your-tenant-code" \
  -H "Content-Type: application/json" \
  -d '{
    "pageIndex": 0,
    "pageSize": 20,
    "filter": {
      "isActive": true
    }
  }'

Create Person

Create a new person record.

Endpoint: POST /people/CreatePersonInline/{organizationId}

Parameters:

organizationId (path, required): GUID - Organization to associate the person with

Authentication: Required

Request Body:

json

{
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "jane.smith@example.com",
  "phone": "+1-555-987-6543",
  "title": "Marketing Director",
  "department": "Marketing",
  "addresses": [
    {
      "type": "Primary",
      "street": "456 Oak Avenue",
      "city": "Los Angeles",
      "state": "CA",
      "zipCode": "90210",
      "country": "USA"
    }
  ],
  "customFields": {
    "birthDate": "1985-03-15",
    "notes": "Key stakeholder in marketing initiatives"
  }
}

Example Response:

json

{
  "id": "456e7890-e89b-12d3-a456-426614174001",
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "jane.smith@example.com",
  "organizationId": "org-456",
  "createdDate": "2024-01-25T10:00:00Z",
  "isActive": true
}

Update Person

Update an existing person's information.

Endpoint: PUT /people/UpdatePersonHeader/{id}

Parameters:

id (path, required): GUID - Person identifier

Authentication: Required

Request Body:

json

{
  "firstName": "Jane",
  "lastName": "Smith-Johnson",
  "email": "jane.smith-johnson@example.com",
  "phone": "+1-555-987-6543",
  "title": "Senior Marketing Director"
}

Manage Person Tags

Add tags to multiple people for categorization and filtering.

Endpoint: POST /people/AddPeoplesTags

Authentication: Required

Request Body:

json

{
  "peopleIds": [
    "123e4567-e89b-12d3-a456-426614174000",
    "456e7890-e89b-12d3-a456-426614174001"
  ],
  "tagIds": [
    "tag-123",
    "tag-456"
  ],
  "action": "add"  // or "remove"
}

Organization Management

Get Organization Details

Retrieve detailed information about a specific organization.

Endpoint: GET /organization/{id}

Parameters:

id (path, required): GUID - Organization identifier

Authentication: Required

Example Response:

json

{
  "id": "org-123",
  "name": "Acme Corporation",
  "type": "Company",
  "parentOrganizationId": null,
  "description": "Leading provider of innovative solutions",
  "website": "https://acme.com",
  "phone": "+1-555-000-1234",
  "email": "info@acme.com",
  "addresses": [
    {
      "type": "Headquarters",
      "street": "100 Corporate Blvd",
      "city": "San Francisco",
      "state": "CA",
      "zipCode": "94105",
      "country": "USA"
    }
  ],
  "childOrganizations": [
    {
      "id": "org-124",
      "name": "Engineering Department",
      "type": "Department"
    }
  ],
  "memberCount": 150,
  "isActive": true,
  "createdDate": "2023-01-01T00:00:00Z"
}

List Organizations with Pagination

Endpoint: POST /organization/OrganizationPagingList

Authentication: Required

Request Body:

json

{
  "pageIndex": 0,
  "pageSize": 50,
  "sortField": "name",
  "sortDirection": "asc",
  "filter": {
    "searchText": "corp",
    "organizationType": "Company",
    "isActive": true,
    "hasMembers": true,
    "parentOrganizationId": null,
    "tags": ["fortune-500"]
  }
}

Create Organization

Endpoint: POST /organization

Authentication: Required

Request Body:

json

{
  "name": "New Company Inc.",
  "type": "Company",
  "parentOrganizationId": "parent-org-id",
  "description": "A new innovative company",
  "website": "https://newcompany.com",
  "phone": "+1-555-999-8888",
  "email": "contact@newcompany.com",
  "addresses": [
    {
      "type": "Headquarters",
      "street": "200 Innovation Drive",
      "city": "Austin",
      "state": "TX",
      "zipCode": "78701",
      "country": "USA"
    }
  ],
  "customFields": {
    "industry": "Technology",
    "employeeCount": "50-100"
  }
}

Get Organization Members

Retrieve all people associated with an organization.

Endpoint: POST /organization/{id}/GetAllPeople

Parameters:

id (path, required): GUID - Organization identifier

Request Body:

json

{
  "pageIndex": 0,
  "pageSize": 50,
  "filter": {
    "isActive": true,
    "position": "Manager",
    "department": "Engineering"
  }
}

Get Child Organizations

Endpoint: POST /organization/{id}/ChildOrganizationsById

Parameters:

id (path, required): GUID - Parent organization identifier

Authentication: Required

Committee Management

Get Committee Details

Endpoint: GET /committee/get/{committeeId}

Parameters:

committeeId (path, required): Committee identifier

Authentication: Required

Example Response:

json

{
  "id": "committee-123",
  "name": "Board of Directors",
  "description": "Executive oversight committee",
  "committeeType": "Board",
  "organizationId": "org-123",
  "isActive": true,
  "memberCount": 8,
  "positions": [
    {
      "id": "pos-1",
      "title": "Chairman",
      "description": "Committee chair and primary decision maker",
      "sequence": 1
    },
    {
      "id": "pos-2", 
      "title": "Vice Chairman",
      "description": "Secondary leadership role",
      "sequence": 2
    }
  ],
  "createdDate": "2023-01-01T00:00:00Z"
}

List Committees with Pagination

Endpoint: POST /committee/CommiteePagingList

Authentication: Required

Request Body:

json

{
  "pageIndex": 0,
  "pageSize": 25,
  "sortField": "name",
  "sortDirection": "asc",
  "filter": {
    "searchText": "board",
    "committeeTypeId": "type-123",
    "organizationId": "org-456",
    "isActive": true,
    "hasMembers": true
  }
}

Create Committee

Endpoint: POST /committee/createcommittee

Authentication: Required

Request Body:

json

{
  "name": "Marketing Committee",
  "description": "Committee focused on marketing strategy and initiatives",
  "committeeTypeId": "type-marketing",
  "organizationId": "org-123",
  "isActive": true,
  "startDate": "2024-01-01T00:00:00Z",
  "positions": [
    {
      "title": "Committee Chair",
      "description": "Primary leadership role",
      "sequence": 1
    },
    {
      "title": "Secretary",
      "description": "Record keeping and administrative duties",
      "sequence": 2
    }
  ]
}

Add Committee Member

Endpoint: POST /committee/savecommitteemember

Authentication: Required

Request Body:

json

{
  "committeeId": "committee-123",
  "personId": "person-456",
  "positionId": "pos-1",
  "startDate": "2024-01-01T00:00:00Z",
  "endDate": null,
  "isActive": true,
  "notes": "Appointed as committee chair for 2024 term"
}

Get Committee Members by Position

Endpoint: POST /committee/committeememberbyposition

Authentication: Required

Request Body:

json

{
  "committeeId": "committee-123",
  "positionId": "pos-1",
  "isActive": true,
  "includeHistory": false
}

Advocacy & Political Relations

Get Relationship Types

Endpoint: GET /advocacy/GetRelationshipTypes

Authentication: Required

Example Response:

json

[
  {
    "id": "rel-1",
    "name": "Constituent",
    "description": "Person is a constituent of the official",
    "category": "Political"
  },
  {
    "id": "rel-2", 
    "name": "Donor",
    "description": "Financial contributor to campaigns",
    "category": "Financial"
  }
]

Get People Relationships

Endpoint: GET /advocacy/list/people-relationships/{peopleId}

Parameters:

peopleId (path, required): GUID - Person identifier

Authentication: Required

Example Response:

json

[
  {
    "id": "relationship-123",
    "personId": "person-456",
    "relatedOfficialId": "official-789",
    "relatedOfficialName": "Senator Jane Smith",
    "relationshipType": "Constituent",
    "relationshipTypeId": "rel-1",
    "startDate": "2023-01-01T00:00:00Z",
    "endDate": null,
    "isActive": true,
    "notes": "Active constituent relationship"
  }
]

Save People Relationship

Endpoint: POST /advocacy/save/people-relationship

Authentication: Required

Request Body:

json

{
  "personId": "person-456",
  "relatedOfficialId": "official-789",
  "relationshipTypeId": "rel-1",
  "startDate": "2024-01-01T00:00:00Z",
  "notes": "New constituent relationship established",
  "isActive": true
}

Get Officials List

Get list of political officials associated with a person.

Endpoint: GET /advocacy/officials-list-lite/{id}

Parameters:

id (path, required): GUID - Person identifier

Authentication: Anonymous allowed

Example Response:

json

[
  {
    "id": "official-789",
    "firstName": "Jane",
    "lastName": "Smith",
    "title": "Senator",
    "office": "U.S. Senate",
    "district": "California",
    "party": "Democratic",
    "email": "jane.smith@senate.gov",
    "phone": "+1-202-555-0123",
    "isActive": true
  }
]

Get Constituent People List

Endpoint: POST /advocacy/get-constituent-people-list

Authentication: Required

Request Body:

json

{
  "officialId": "official-789",
  "pageIndex": 0,
  "pageSize": 50,
  "filter": {
    "relationshipType": "Constituent",
    "isActive": true,
    "location": {
      "state": "CA",
      "district": "12"
    }
  }
}

Start GeoCode Job

Begin geocoding process for address validation and geographic data enrichment.

Endpoint: POST /advocacy/startGeoCodeJob

Authentication: Required

Request Body:

json

{
  "entityType": "Person",
  "entityIds": [
    "person-123",
    "person-456"
  ],
  "forceReGeocode": false
}

Audience & Communication

Get Audience Search Settings

Endpoint: GET /audience/AudienceSearchSettings/{category}

Parameters:

category (path, required): Search category (e.g., "people", "organization", "committee")

Authentication: Required

Example Response:

json

{
  "category": "people",
  "availableFilters": [
    {
      "fieldName": "organizationType",
      "displayName": "Organization Type",
      "fieldType": "select",
      "options": [
        {"value": "company", "label": "Company"},
        {"value": "nonprofit", "label": "Non-Profit"}
      ]
    },
    {
      "fieldName": "location", 
      "displayName": "Location",
      "fieldType": "location",
      "supportedLevels": ["state", "city", "zipCode"]
    }
  ],
  "defaultPageSize": 50,
  "maxPageSize": 500
}

Search Across Modules

Endpoint: POST /audience/ModuleSearchList

Authentication: Required

Request Body:

json

{
  "searchText": "john",
  "modules": ["people", "organization", "committee"],
  "pageIndex": 0,
  "pageSize": 50,
  "filters": {
    "isActive": true,
    "dateRange": {
      "startDate": "2023-01-01T00:00:00Z",
      "endDate": "2024-01-01T00:00:00Z"
    }
  }
}

Broadcast via Email

Send email communications to selected audience.

Endpoint: POST /audience/BroacastViaEmail

Authentication: Required

Request Body:

json

{
  "subject": "Important Update from Acme Corporation",
  "body": "<html><body><h1>Important Update</h1><p>This is an important message...</p></body></html>",
  "isHtml": true,
  "fromEmail": "noreply@acme.com",
  "fromName": "Acme Communications",
  "audienceSelection": {
    "selectedPeople": ["person-123", "person-456"],
    "selectedOrganizations": ["org-789"],
    "selectedCommittees": ["committee-101"],
    "filters": {
      "tags": ["newsletter-subscriber"],
      "organizationType": "Company"
    }
  },
  "scheduledSendTime": null, // null for immediate send
  "trackOpens": true,
  "trackClicks": true
}

Common Patterns

Pagination Request Format

Most list endpoints use this request format:

json

{
  "pageIndex": 0,        // Zero-based page number
  "pageSize": 50,        // Records per page (max 500)
  "sortField": "name",   // Field to sort by
  "sortDirection": "asc", // "asc" or "desc"
  "filter": {           // Endpoint-specific filters
    // Filter properties vary by endpoint
  }
}

Pagination Response Format

json

{
  "data": [...],         // Array of result objects
  "totalCount": 1250,    // Total records matching filter
  "pageIndex": 0,        // Current page number
  "pageSize": 50,        // Records per page
  "hasNextPage": true,   // Whether more pages exist
  "hasPreviousPage": false // Whether previous pages exist
}

Date Format

All dates use ISO 8601 format with UTC timezone:

2024-01-25T10:30:00Z

GUID Format

All identifiers use standard GUID format with hyphens:

123e4567-e89b-12d3-a456-426614174000

Error Response Format

json

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request contains invalid parameters",
    "details": [
      {
        "field": "email",
        "message": "Email address is required"
      }
    ],
    "timestamp": "2024-01-25T10:30:00Z",
    "requestId": "req-123456"
  }
}

Rate Limiting Headers

All responses include rate limiting information:

http

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Custom Fields

Many entities support custom fields through a flexible schema:

json

{
  "customFields": {
    "customField123": "string value",
    "customField456": 42,
    "customField789": true,
    "customField101": "2024-01-25T10:30:00Z"
  }
}

For complete endpoint details and interactive testing, visit the Swagger Documentation.

API Reference ​

Table of Contents ​

Base Information ​

Base URL ​

Common Headers ​

Response Format ​

People Management ​

Get Person Details ​

List People with Pagination ​

Search People ​

Create Person ​

Update Person ​

Manage Person Tags ​

Organization Management ​

Get Organization Details ​

List Organizations with Pagination ​

Create Organization ​

Get Organization Members ​

Get Child Organizations ​

Committee Management ​

Get Committee Details ​

List Committees with Pagination ​

Create Committee ​

Add Committee Member ​

Get Committee Members by Position ​

Advocacy & Political Relations ​

Get Relationship Types ​

Get People Relationships ​

Save People Relationship ​

Get Officials List ​

Get Constituent People List ​

Start GeoCode Job ​

Audience & Communication ​

Get Audience Search Settings ​

Search Across Modules ​

Broadcast via Email ​

Common Patterns ​

Pagination Request Format ​

Pagination Response Format ​

Date Format ​

GUID Format ​

Error Response Format ​

Rate Limiting Headers ​

Custom Fields ​

API Reference

Table of Contents

Base Information

Base URL

Common Headers

Response Format

People Management

Get Person Details

List People with Pagination

Search People

Create Person

Update Person

Manage Person Tags

Organization Management

Get Organization Details

List Organizations with Pagination

Create Organization

Get Organization Members

Get Child Organizations

Committee Management

Get Committee Details

List Committees with Pagination

Create Committee

Add Committee Member

Get Committee Members by Position

Advocacy & Political Relations

Get Relationship Types

Get People Relationships

Save People Relationship

Get Officials List

Get Constituent People List

Start GeoCode Job

Audience & Communication

Get Audience Search Settings

Search Across Modules

Broadcast via Email

Common Patterns

Pagination Request Format

Pagination Response Format

Date Format

GUID Format

Error Response Format

Rate Limiting Headers

Custom Fields