Getting Started

OverviewCopied!

The Evalumo API enables developers to integrate construction cost estimation capabilities into their applications. Whether you're building contractor management software, project management tools, or custom estimation workflows, the API provides access to Evalumo's core features including project creation, cost calculations, client management, and third-party integrations.

Key Capabilities:

• Project Management: Create and organize construction projects with client information

• Cost Estimation: Access exported project reports with detailed cost breakdowns

• Workflow Integration: Connect with tools like Zapier for automated workflows

• Real-time Data: Retrieve up-to-date project information and cost estimates

Authentication FlowCopied!

Evalumo uses a custom OAuth2-style authentication flow designed for Firebase integration. The process involves three main steps:

Step 1: Generate Custom Token

Start by calling the /apiAuth endpoint to generate a custom authentication token:

curl -X POST https://api.evalumo.com/authorize \
  -H "Content-Type: application/json" \
  -d '{
    "redirect_uri": "https://your-app.com/auth/callback",
    "state": "random-state-string"
  }'

This endpoint will redirect you to the specified redirect_uri with an authorization code.

Step 2: Exchange Code for Tokens

Use the authorization code from step 1 to get your access and refresh tokens:

curl -X POST https://api.evalumo.com/token \
  -H "Content-Type: application/json" \
  -d '{
    "code": "custom-token-from-step-1"
  }'

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "AEu4IL3T7wW9zKNdHTzQ..."
}

Step 3: Make Authenticated Requests

Include the access token in the Authorization header for all API requests:

curl -X GET https://api.evalumo.com/project \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Token Refresh

Access tokens expire after 1 hour. Use the refresh token to get a new access token:

curl -X POST https://api.evalumo.com/refreshToken \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "AEu4IL3T7wW9zKNdHTzQ..."
  }'

Making Your First API CallCopied!

Once authenticated, test your setup with the /user endpoint:

curl -X GET "https://api.evalumo.com/user" \
  -H "Authorization: Bearer your-access-token"

Expected Response:

{
  "userEmail": "contractor@example.com",
  "userDisplayName": "John Smith",
}

This confirms your authentication is working and returns your user information.

Common Integration PatternsCopied!

Creating a New Project

Start by creating a construction project with client information:

curl -X POST https://api.evalumo.com/project \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -d '{
    "project_name": "Kitchen Renovation",
    "client_name": "John Smith",
    "client_email": "john@example.com",
    "client_phone": "+1 (555) 123-4567",
    "client_address": "123 Main St, Toronto, ON"
  }'

Retrieving Project Data

List your exported projects with pagination:

curl -X GET "https://api.evalumo.com/exportedProject?page=0&limit=10&lineItemsToExpand=TasksByItem
  -H "Authorization: Bearer your-access-token"

Managing Project Workflow

Update project status using predefined categories:

curl -X PATCH https://api.evalumo.com/project/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -d '{
    "project_category": "Pending"
  }'

Error HandlingCopied!

The API uses standard HTTP status codes and returns error details in JSON format:

{
  "error": "Category not found",
}

Common Status Codes:

• 200: Success

• 201: Created successfully

• 400: Bad request (invalid parameters)

• 401: Unauthorized (invalid or expired token)

• 404: Resource not found

• 500: Internal server error

Rate Limits and Best PracticesCopied!

Authentication Best Practices:

• Store refresh tokens securely (never in client-side code)

• Implement automatic token refresh before expiration

• Use HTTPS for all API communications

• Validate SSL certificates

API Usage Guidelines:

• Implement exponential backoff for failed requests

• Cache project data when appropriate to reduce API calls

• Use pagination for large data sets

• Include error handling for network timeouts

Performance Optimization:

• Use the lineItemsToExpand parameter to control response size

• Batch related operations when possible

• Monitor API response times and adjust request frequency

Next StepsCopied!

Now that you have authentication working, explore these common integration scenarios:

1. Project Management Integration: Learn how to sync projects with your existing workflow tools

2. Webhook Integration: Set up real-time notifications using Zapier and other platforms

3. Advanced Querying: Master the flexible search and filtering capabilities

For detailed endpoint documentation, see the API Reference section. For integration examples and troubleshooting, check our comprehensive guides below.