Skip to main content

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:

  1. Authentication guide (how to use your API key)
  2. Browse endpoints for the data you need (Projects, Customers, Invoices, etc.)
  3. Review common error codes
  4. 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:

  1. Download Postman from postman.com
  2. Create a new request
  3. Set method to GET
  4. Enter URL: https://emanageone.azure-api.net/emws/projects
  5. Go to Headers tab
  6. Add header: x-api-key with your API key as the value
  7. Add header: Content-Type with value application/json
  8. 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

Why Docker?

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

Prerequisites:

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:

  1. Go to editor.swagger.io
  2. Click File → Import URL
  3. Enter: https://api.emanageone.com/openapi/combined.json
  4. Click Generate Client and select your language
  5. 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:

  1. Verify you're sending the x-api-key header
  2. Check for typos in your API key
  3. 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:

  1. Contact your e-manage support

Issue: "404 Not Found"​

Possible Causes:

  • Wrong endpoint URL
  • Resource ID doesn't exist

Solution:

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

Issue: "429 Too Many Requests"​

Possible Cause:

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

Solution:

  1. Add delays between requests
  2. Implement exponential backoff

Issue: Generated Client Won't Compile​

Possible Causes:

  • Missing dependencies
  • Language version mismatch

Solution:

  1. Check the README.md in the generated client folder
  2. Install all required dependencies
  3. Verify your language version matches requirements
  4. 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​

Collection queries use the zero-based start offset and a positive limit. Keep filters and sorting unchanged between requests. For example, using an HTTP client with your existing authentication headers:

start = 0
page_size = 100

while True:
    response = requests.get(
        "https://emanageone.azure-api.net/emws/projects",
        headers=headers,
        params={"start": start, "limit": page_size, "sort_by": "asc(projectId)"},
    )
    response.raise_for_status()
    projects = response.json()
    if not projects:
        break

    process_projects(projects)
    start += page_size

See filtering, sorting, and pagination for creation-date ranges, ordering, and page-size considerations.

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​

Tools​

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:

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

Need Help?

Happy coding! 🚀