API Tutorial

Welcome! This guide will walk you through everything you need to start integrating with e-manage | ONE. Whether you're building a custom integration or connecting to a third-party tool, you'll be up and running in just a few steps.

What You'll Learn

By the end of this guide, you'll know how to:

✅ Get your API key
✅ Set up your development environment
✅ Make your first API call
✅ Generate a client library (optional, but recommended)

Before You Begin

What You'll Need:

Basic familiarity with APIs (or a willingness to learn!)
A development environment (any programming language works)

Time Required: 15-30 minutes

Step 1: Get Your API Key

Your API key is your password for accessing the e-manage | ONE API. You'll need one before you can make any API calls.

How to Request Your API Key

Submit a technical support request here:
👉 Create Technical Support Request

Important Information to Include:

Key Type Needed

Developer Key: For custom integrations you're building yourself
Zapier Key: Required if you're connecting via Zapier (has special configuration)

Important: Zapier requires a specially configured key and will not work with a standard Developer key. Make sure to specify if you need Zapier support!

What Happens Next

Our support team will review your request
You'll receive a one-time link to your API key
Use the one-time link to view your API key. The link is one-time use only and expires in 24 hours
Remember to store your API key securely, as you will not be able to see it again

Keep Your API Key Safe

DO:

✅ Store your key in environment variables or a secure vault

DON'T:

❌ Commit your key to Git/GitHub
❌ Share your key in public forums or Slack
❌ Include your key in client-side JavaScript (web browser code)
❌ Email your key or include it in screenshots

Step 2: Explore the API Documentation

Before writing any code, familiarize yourself with what's available.

Interactive Documentation

Visit our comprehensive API documentation at:
👉 api.emanageone.com

What You'll Find:

Complete list of all available endpoints
Request and response examples
Field descriptions and data types
Interactive API explorer (test calls right in your browser!)
Authentication guides
Code examples in multiple languages

Recommended Reading:

Authentication guide (how to use your API key)
Browse endpoints for the data you need (Projects, Customers, Invoices, etc.)
Review common error codes
Check out code examples for your programming language

Step 3: Make Your First API Call

Let's test your API key and make your first successful API call!

Base URL

All API requests go to:

<https://emanageone.azure-api.net/emws>

Authentication

Include your API key in every request header:

x-api-key: your-api-key-here

Example 1: Using cURL (Command Line)

This works on Mac, Linux, or Windows (with Git Bash or WSL):

curl -X GET "<https://emanageone.azure-api.net/emws/projects>" \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json"

What to expect:

A JSON response with a list of projects
HTTP status code 200 (success)

If you get an error:

401 Unauthorized: Check your API key is correct
403 Forbidden: Your account may not have API access enabled
404 Not Found: Check the URL is correct

Example 2: Using Postman

Postman is a popular tool for testing APIs with a visual interface.

Steps:

Download Postman from postman.com
Create a new request
Set method to GET
Enter URL: <https://emanageone.azure-api.net/emws/projects>
Go to Headers tab
Add header: x-api-key with your API key as the value
Add header: Content-Type with value application/json
Click Send

You should see a JSON response with your project data!

Example 3: Using Python

import os
import requests

# Store your API key in an environment variable
api_key = os.getenv('EMANAGE_API_KEY')

# API endpoint
url = '<https://emanageone.azure-api.net/emws/projects>'

# Request headers
headers = {
    'x-api-key': api_key,
    'Content-Type': 'application/json'
}

# Make the request
response = requests.get(url, headers=headers)

# Check if successful
if response.status_code == 200:
    projects = response.json()
    print(f"Found {len(projects)} projects")
    print(projects)
else:
    print(f"Error: {response.status_code}")
    print(response.text)

To run:

# Set your API key (do this once per terminal session)
export EMANAGE_API_KEY="your-api-key-here"

# Run the script
python test_api.py

Example 4: Using JavaScript (Node.js)

const fetch = require('node-fetch');

// Store your API key in an environment variable
const apiKey = process.env.EMANAGE_API_KEY;

// API endpoint
const url = '<https://emanageone.azure-api.net/emws/projects>';

// Make the request
fetch(url, {
  method: 'GET',
  headers: {
    'x-api-key': apiKey,
    'Content-Type': 'application/json'
  }
})
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    return response.json();
  })
  .then(data => {
    console.log(`Found ${data.length} projects`);
    console.log(data);
  })
  .catch(error => {
    console.error('Error:', error);
  });

To run:

# Install dependencies
npm install node-fetch

# Set your API key
export EMANAGE_API_KEY="your-api-key-here"

# Run the script
node test_api.js

Example 5: Using C#

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        // Store your API key in an environment variable
        var apiKey = Environment.GetEnvironmentVariable("EMANAGE_API_KEY");

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("x-api-key", apiKey);
        client.DefaultRequestHeaders.Accept.Add(
            new MediaTypeWithQualityHeaderValue("application/json"));

        var url = "<https://emanageone.azure-api.net/emws/projects>";

        try
        {
            var response = await client.GetAsync(url);
            response.EnsureSuccessStatusCode();

            var content = await response.Content.ReadAsStringAsync();
            Console.WriteLine("Projects:");
            Console.WriteLine(content);
        }
        catch (HttpRequestException e)
        {
            Console.WriteLine($"Error: {e.Message}");
        }
    }
}

Step 4: Generate a Client Library (Optional)

For production applications, we recommend generating a client library. This gives you:

Type-safe method calls (no manual URL construction)
Built-in error handling
Automatic serialization/deserialization
IDE autocomplete support

What is OpenAPI?

OpenAPI is a standard way to describe APIs. We provide an OpenAPI specification that describes every endpoint, parameter, and response in the e-manage | ONE API.

Your development tools can read this specification and automatically generate code that matches our API perfectly.

OpenAPI Specification URL

<https://api.emanageone.com/openapi/combined.json>

Method 1: Using Docker (Recommended)

Why Docker?

No need to install OpenAPI Generator tools
Works the same on Windows, Mac, and Linux
Keeps your system clean

Prerequisites:

Install Docker Desktop

Generate a Client Library:

For Python:

docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \
  -i <https://api.emanageone.com/openapi/combined.json> \
  -g python \
  -o /local/emanage-client-python \
  --additional-properties=packageName=emanage_api

For C#:

docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \
  -i <https://api.emanageone.com/openapi/combined.json> \
  -g csharp \
  -o /local/emanage-client-csharp \
  --additional-properties=packageName=EmanageApi

For JavaScript/TypeScript:

docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \
  -i <https://api.emanageone.com/openapi/combined.json> \
  -g typescript-fetch \
  -o /local/emanage-client-typescript

For Java:

docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \
  -i <https://api.emanageone.com/openapi/combined.json> \
  -g java \
  -o /local/emanage-client-java \
  --additional-properties=groupId=com.yourcompany,artifactId=emanage-api

For Go:

docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \
  -i <https://api.emanageone.com/openapi/combined.json> \
  -g go \
  -o /local/emanage-client-go \
  --additional-properties=packageName=emanageapi

Other Supported Languages:
Ruby, Rust, Swift, Kotlin, Scala, Perl, R, and many more!

See the full list of generators.

Method 2: Using NPM (for JavaScript/TypeScript)

# Install the OpenAPI Generator CLI globally
npm install -g @openapitools/openapi-generator-cli

# Generate TypeScript client
openapi-generator-cli generate \
  -i <https://api.emanageone.com/openapi/combined.json> \
  -g typescript-fetch \
  -o ./emanage-client

Method 3: Online Generator

Don't want to install anything? Use the online generator:

Go to editor.swagger.io
Click File → Import URL
Enter: <https://api.emanageone.com/openapi/combined.json>
Click Generate Client and select your language
Download the generated ZIP file

Step 5: Use Your Generated Client Library

Once generated, you can install and use the client library in your project.

Example: Using Generated Python Client

import os
from emanage_api import ApiClient, Configuration
from emanage_api.api.projects_api import ProjectsApi

# Configure API authentication
configuration = Configuration()
configuration.api_key['ApiKeyAuth'] = os.getenv("EMANAGE_API_KEY")
configuration.host = "<https://emanageone.azure-api.net/emws>"

# Create an API client
api_client = ApiClient(configuration)

# Create a Projects API instance
projects_api = ProjectsApi(api_client)

try:
    # Get all projects
    projects = projects_api.get_projects()
    print(f"Found {len(projects)} projects:")

    for project in projects:
        print(f"- {project.project_name} (ID: {project.project_id})")

except Exception as e:
    print(f"Error calling API: {e}")

Example: Using Generated C# Client

using System;
using EmanageApi.Api;
using EmanageApi.Client;

class Program
{
    static void Main()
    {
        // Configure API authentication
        var config = new Configuration();
        config.ApiKey["ApiKeyAuth"] = Environment.GetEnvironmentVariable("EMANAGE_API_KEY");
        config.BasePath = "<https://emanageone.azure-api.net/emws>";

        // Create Projects API instance
        var projectsApi = new ProjectsApi(config);

        try
        {
            // Get all projects
            var projects = projectsApi.GetProjects();
            Console.WriteLine($"Found {projects.Count} projects:");

            foreach (var project in projects)
            {
                Console.WriteLine($"- {project.ProjectName} (ID: {project.ProjectId})");
            }
        }
        catch (Exception e)
        {
            Console.WriteLine($"Error: {e.Message}");
        }
    }
}

Benefits of Using the Generated Client

Type Safety:

# The IDE knows what fields are available
project.project_name  # ✅ Autocomplete works
project.porject_name  # ❌ IDE catches the typo

Automatic Serialization:

# No manual JSON parsing needed
projects = projects_api.get_projects()
# Returns typed objects, not raw JSON

Built-in Error Handling:

try:
    projects = projects_api.get_projects()
except ApiException as e:
    # Structured error information
    print(f"Error code: {e.status}")
    print(f"Error message: {e.reason}")

Common Issues & Solutions

Issue: "401 Unauthorized"

Possible Causes:

API key is missing
API key is incorrect
API key has expired

Solution:

Verify you're sending the x-api-key header
Check for typos in your API key
Confirm the key is active (contact support if needed)

Issue: "403 Forbidden"

Possible Causes:

Your account doesn't have API access enabled
You're trying to access a resource you don't have permission for

Solution:

Contact your e-manage support

Issue: "404 Not Found"

Possible Causes:

Wrong endpoint URL
Resource ID doesn't exist

Solution:

Double-check the endpoint URL against api.emanageone.com
Verify the resource ID is correct
Check for typos in the URL

Issue: "429 Too Many Requests"

Possible Cause:

You've exceeded the rate limit (100 requests per minute)

Solution:

Add delays between requests
Implement exponential backoff

Issue: Generated Client Won't Compile

Possible Causes:

Missing dependencies
Language version mismatch

Solution:

Check the README.md in the generated client folder
Install all required dependencies
Verify your language version matches requirements
Try regenerating with different options

Best Practices

1. Use Environment Variables for Secrets

Never hardcode API keys in your source code.

Good:

api_key = os.getenv('EMANAGE_API_KEY')

Bad:

api_key = "sk_live_abc123..." # ❌ Don't do this!

2. Implement Error Handling

Always handle potential errors gracefully:

try:
    projects = api.get_projects()
except ApiException as e:
    if e.status == 429:
        # Rate limited - wait and retry
        time.sleep(60)
        projects = api.get_projects()
    elif e.status == 401:
        # Authentication failed
        logging.error("Invalid API key")
    else:
        # Other error
        logging.error(f"API error: {e}")

3. Use Pagination for Large Datasets

Don't try to fetch thousands of records at once:

# Good - fetch in batches
page = 1
page_size = 100

while True:
    projects = api.get_projects(page=page, limit=page_size)
    if not projects:
        break

    process_projects(projects)
    page += 1

4. Cache Responses When Appropriate

If data doesn't change frequently, cache it:

import time

cache = {}
cache_ttl = 300  # 5 minutes

def get_projects_cached():
    now = time.time()

    if 'projects' in cache and cache['projects']['expires'] > now:
        return cache['projects']['data']

    # Fetch fresh data
    projects = api.get_projects()

    cache['projects'] = {
        'data': projects,
        'expires': now + cache_ttl
    }

    return projects

5. Log API Calls for Debugging

Keep a record of API interactions:

import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

try:
    logger.info("Fetching projects from API")
    projects = api.get_projects()
    logger.info(f"Successfully fetched {len(projects)} projects")
except Exception as e:
    logger.error(f"Failed to fetch projects: {e}")

Next Steps

Now that you've made your first API call, here's what to explore next:

1. Browse the Full Documentation

Visit api.emanageone.com to explore all available endpoints.

2. Learn About Webhooks

Instead of polling for changes, have e-manage push updates to you in real-time.
See our Webhook Guide for details.

3. Build Your Integration

Start building your actual integration:

Identify which endpoints you need
Design your data flow
Implement error handling and retries
Test thoroughly in a development environment

4. Go to Production

When ready to deploy:

Set up monitoring and logging
Implement proper error handling
Document your integration for your team

Additional Resources

Documentation

API Reference: api.emanageone.com
OpenAPI Spec: api.emanageone.com/openapi/combined.json
Webhook Guide: See separate webhook documentation

Tools

Postman: postman.com - API testing tool
OpenAPI Generator: openapi-generator.tech - Client library generator
Swagger Editor: editor.swagger.io - Online API explorer

Support

Technical Support: Submit a support request
Documentation Issues: Report problems with the documentation
Feature Requests: Suggest new API endpoints or improvements

Frequently Asked Questions

Q: Do I need to generate a client library, or can I just use HTTP requests?

A: Both work! Client libraries provide type safety and better developer experience, but simple HTTP requests (with fetch, requests, etc.) work perfectly fine, especially for quick scripts or testing.

Q: Can I have multiple API keys?

A: Yes! We recommend having separate keys for:

Development/testing
Production
Different applications or integrations

Q: How often should I rotate my API key?

A: We recommend rotating every 6-12 months as a security best practice. Rotate immediately if you suspect a key has been compromised.

Q: What's the difference between a Developer key and a Zapier key?

A: Zapier keys have special configuration to work with Zapier's authentication flow. Standard Developer keys won't work with Zapier. Specify which you need when requesting your key.

Q: Can I test the API without writing code?

A: Yes! Visit api.emanageone.com to use our interactive API explorer. You can test API calls right in your browser.

Q: What data can I access via the API?

A: You can access all data in your e-manage account that you have permission to view, including Projects, Customers, Invoices, and more. See the full documentation for the complete list.

Ready to Build?

You now have everything you need to start integrating with the e-manage | ONE API!

Quick Recap:

✅ Request your API key from support
✅ Explore the documentation at api.emanageone.com
✅ Make your first API call
✅ (Optional) Generate a client library
✅ Start building your integration

Need Help?

Happy coding! 🚀