API Documentation

Appearance

Getting Started with Engagifii CRM API ​

Table of Contents ​

Prerequisites ​

Before you begin integrating with the Engagifii CRM API, ensure you have:

Required Access ​

  • API Access Credentials: Client ID and Client Secret from your system administrator
  • Tenant Code: Your organization's unique identifier
  • Base URL: The correct API endpoint for your environment
  • Network Access: Ability to make HTTPS requests to the API endpoints

Development Tools ​

  • HTTP Client: curl, Postman, or your preferred HTTP testing tool
  • Development Environment: Support for your chosen programming language
  • JSON Parser: Ability to parse and generate JSON data
  • HTTPS Support: Your application must support secure HTTPS connections
  • REST API Concepts: Understanding of HTTP methods, status codes, and JSON
  • OAuth2 Flow: Basic knowledge of client credentials grant flow
  • Multi-tenancy: Understanding of tenant-based data isolation

Authentication Setup ​

The Engagifii CRM API uses OAuth2 Client Credentials flow for authentication. Follow these steps to set up authentication:

Step 1: Obtain Access Credentials ​

Contact your system administrator to receive:

Client ID: your-client-id
Client Secret: your-client-secret
Tenant Code: your-organization-code

Step 2: Request an Access Token ​

Make a POST request to the token endpoint:

cURL Example:

bash
curl -X POST "https://builtin-crm.azurewebsites.net/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=your-client-id" \
  -d "client_secret=your-client-secret"

JavaScript Example:

javascript
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 tokenData = await response.json();
  return tokenData.access_token;
};

C# Example:

csharp
using System.Net.Http;
using System.Collections.Generic;

public async Task<string> GetAccessTokenAsync()
{
    var client = new HttpClient();
    var tokenRequest = new FormUrlEncodedContent(new[]
    {
        new KeyValuePair<string, string>("grant_type", "client_credentials"),
        new KeyValuePair<string, string>("client_id", "your-client-id"),
        new KeyValuePair<string, string>("client_secret", "your-client-secret")
    });

    var response = await client.PostAsync("https://builtin-crm.azurewebsites.net/oauth/token", tokenRequest);
    var responseContent = await response.Content.ReadAsStringAsync();
    var tokenData = JsonSerializer.Deserialize<TokenResponse>(responseContent);
    
    return tokenData.AccessToken;
}

Python Example:

python
import requests

def get_access_token():
    token_url = "https://builtin-crm.azurewebsites.net/oauth/token"
    
    payload = {
        'grant_type': 'client_credentials',
        'client_id': 'your-client-id',
        'client_secret': 'your-client-secret'
    }
    
    response = requests.post(token_url, data=payload)
    token_data = response.json()
    
    return token_data['access_token']

Step 3: Handle Token Response ​

A successful token request returns:

json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "api:read api:write"
}

Important Token Management:

  • Store the access token securely
  • Tokens expire after 1 hour (3600 seconds)
  • Request a new token before the current one expires
  • Never expose tokens in client-side code or logs

Your First API Call ​

Now that you have an access token, let's make your first API call to retrieve people from your organization.

Step 1: Set Up Request Headers ​

All API requests require these headers:

  • Authorization: Bearer {access_token}
  • tenant-code: {your-tenant-code}
  • Content-Type: application/json (for POST/PUT requests)

Step 2: Make a GET Request ​

cURL Example:

bash
curl -X GET "https://builtin-crm.azurewebsites.net/api/v1/people" \
  -H "Authorization: Bearer your-access-token" \
  -H "tenant-code: your-tenant-code" \
  -H "Accept: application/json"

JavaScript Example:

javascript
const getPeople = async (accessToken, tenantCode) => {
  const response = await fetch('https://builtin-crm.azurewebsites.net/api/v1/people', {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'tenant-code': tenantCode,
      'Accept': 'application/json'
    }
  });
  
  if (response.ok) {
    const people = await response.json();
    console.log('People:', people);
    return people;
  } else {
    throw new Error(`API Error: ${response.status} ${response.statusText}`);
  }
};

C# Example:

csharp
public async Task<List<Person>> GetPeopleAsync(string accessToken, string tenantCode)
{
    var client = new HttpClient();
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
    client.DefaultRequestHeaders.Add("tenant-code", tenantCode);
    
    var response = await client.GetAsync("https://builtin-crm.azurewebsites.net/api/v1/people");
    
    if (response.IsSuccessStatusCode)
    {
        var jsonContent = await response.Content.ReadAsStringAsync();
        return JsonSerializer.Deserialize<List<Person>>(jsonContent);
    }
    else
    {
        throw new HttpRequestException($"API Error: {response.StatusCode}");
    }
}

Python Example:

python
import requests

def get_people(access_token, tenant_code):
    headers = {
        'Authorization': f'Bearer {access_token}',
        'tenant-code': tenant_code,
        'Accept': 'application/json'
    }
    
    response = requests.get(
        'https://builtin-crm.azurewebsites.net/api/v1/people',
        headers=headers
    )
    
    if response.status_code == 200:
        return response.json()
    else:
        response.raise_for_status()

Step 3: Handle the Response ​

A successful response returns a list of people:

json
{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "phone": "+1-555-123-4567",
      "organizationId": "org-123",
      "createdDate": "2024-01-15T10:30:00Z",
      "isActive": true
    }
  ],
  "totalCount": 1,
  "pageIndex": 0,
  "pageSize": 50
}

Testing Your Integration ​

Using Postman ​

  1. Import Collection: Download our Postman Collection
  2. Set Variables: Configure environment variables for your credentials
  3. Test Authentication: Run the "Get Access Token" request
  4. Test API Calls: Execute sample requests to verify connectivity

Using Swagger UI ​

  1. Open Swagger: Navigate to https://builtin-crm.azurewebsites.net/swagger/
  2. Authenticate: Click "Authorize" and enter your access token
  3. Test Endpoints: Try different API endpoints interactively
  4. View Responses: Examine request/response formats

Test Checklist ​

  • [ ] Successfully obtain access token
  • [ ] Make authenticated GET request to /api/v1/people
  • [ ] Handle pagination in list responses
  • [ ] Test error scenarios (invalid token, missing headers)
  • [ ] Verify tenant isolation (data belongs to your organization)

Common Integration Patterns ​

1. People Management Workflow ​

Scenario: Synchronize contacts between your system and Engagifii CRM

javascript
// 1. Get existing people
const existingPeople = await getPeople(token, tenantCode);

// 2. Create new person
const newPerson = await createPerson(token, tenantCode, {
  firstName: 'Jane',
  lastName: 'Smith',
  email: 'jane.smith@example.com',
  phone: '+1-555-987-6543'
});

// 3. Update person information
const updatedPerson = await updatePerson(token, tenantCode, newPerson.id, {
  email: 'jane.smith.updated@example.com'
});

// 4. Add person to organization
await addPersonToOrganization(token, tenantCode, newPerson.id, organizationId);

2. Organization Hierarchy Management ​

Scenario: Build and maintain organizational structures

javascript
// 1. Get organization tree
const organizations = await getOrganizations(token, tenantCode);

// 2. Create parent organization
const parentOrg = await createOrganization(token, tenantCode, {
  name: 'Acme Corporation',
  type: 'Company',
  parentId: null
});

// 3. Create child organization
const childOrg = await createOrganization(token, tenantCode, {
  name: 'Engineering Department',
  type: 'Department',
  parentId: parentOrg.id
});

3. Committee and Member Management ​

Scenario: Manage committee structures and membership

javascript
// 1. Create committee
const committee = await createCommittee(token, tenantCode, {
  name: 'Board of Directors',
  description: 'Executive oversight committee',
  isActive: true
});

// 2. Add members to committee
await addCommitteeMember(token, tenantCode, committee.id, {
  personId: personId,
  position: 'Chairman',
  startDate: '2024-01-01'
});

4. Bulk Data Operations ​

Scenario: Efficiently process large datasets

javascript
// Use pagination for large datasets
const getAllPeople = async (token, tenantCode) => {
  let allPeople = [];
  let pageIndex = 0;
  const pageSize = 100;
  
  while (true) {
    const response = await getPeople(token, tenantCode, {
      pageIndex,
      pageSize
    });
    
    allPeople = allPeople.concat(response.data);
    
    if (response.data.length < pageSize) {
      break; // Last page reached
    }
    
    pageIndex++;
  }
  
  return allPeople;
};

Troubleshooting ​

Common Issues and Solutions ​

1. Authentication Failures ​

Problem: 401 Unauthorized responses Solutions:

  • Verify your Client ID and Client Secret are correct
  • Check that your access token hasn't expired
  • Ensure you're including the Bearer prefix in the Authorization header
  • Confirm your tenant code is valid and correctly formatted

2. Missing Tenant Context ​

Problem: 400 Bad Request or empty results Solutions:

  • Always include the tenant-code header in every request
  • Verify your tenant code matches your organization
  • Check that your user account has access to the specified tenant

3. Rate Limiting ​

Problem: 429 Too Many Requests responses Solutions:

  • Implement exponential backoff retry logic
  • Reduce request frequency to stay under 1,000 requests/minute
  • Use bulk operations instead of individual requests where possible
  • Cache data locally to reduce API calls

4. Network and SSL Issues ​

Problem: Connection timeouts or SSL errors Solutions:

  • Verify your network allows HTTPS connections to our endpoints
  • Check firewall settings for outbound connections on port 443
  • Ensure your HTTP client supports modern SSL/TLS protocols
  • Test connectivity using curl from your server environment

5. Data Format Issues ​

Problem: 400 Bad Request with validation errors Solutions:

  • Validate JSON formatting before sending requests
  • Check required fields are included and properly formatted
  • Verify date formats use ISO 8601 standard (YYYY-MM-DDTHH:mm:ssZ)
  • Ensure GUIDs are properly formatted (with hyphens)

Getting Additional Help ​

If you continue to experience issues:

  1. Check Error Messages: API responses include detailed error information
  2. Review Documentation: Consult the API Reference for endpoint details
  3. Test with Swagger: Use the interactive documentation to validate requests
  4. Contact Support: Reach out to your system administrator with specific error details

Debugging Tips ​

  • Enable Logging: Log all API requests and responses during development
  • Use Unique Request IDs: Include correlation IDs to trace requests
  • Test in Stages: Verify authentication before testing business logic
  • Validate Environments: Ensure you're connecting to the correct API endpoint
  • Monitor Rate Limits: Track your request frequency to avoid limits

Next Steps: Once you've successfully made your first API calls, explore the API Reference for detailed documentation on all available endpoints and their capabilities.

Copyright © 2025 Engagifii