Agency API

Manage your agency programmatically with our comprehensive API. Create subteams, manage users, and configure access controls.

API Key Required

You need an agency API key to use this endpoint. Agency owners can generate API keys from their settings.

Overview

The Agency API allows you to programmatically manage your agency's operations. Currently, we provide endpoints for creating and managing subteams. More endpoints for user management, billing, and analytics are coming soon.

Subteams API

Create and manage subteams for your agency with full control over access permissions and credit limits.

1. Endpoint

POST Request

POST /api/v1/agency/subteams

2. Authentication

Include your agency API key in the X-AGENCY-KEY header:

Header

X-AGENCY-KEY: your-api-key

3. Example Request

cURL Example

curl -X POST https://echo.win/api/v1/agency/subteams \
  -H "Content-Type: application/json" \
  -H "X-AGENCY-KEY: your-api-key" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "teamName": "John's Team",
    "email": "john@example.com",
    "totalMonthlyCredits": 1000,
    "accessConfig": {
      "users": true,
      "instructions": false,
      "instructionsWrite": false,
      "testing": true,
      "knowledgeBase": true,
      "agentConfiguration": false,
      "agentCreation": false
    }
  }'

Reading a Subteam's Data

Use a single agency API key to read data for any subteam you provisioned — no separate key per subteam. Append a teamId query parameter (the subteam's teamId, returned when the subteam is created) to any read endpoint:

Examples

GET /api/v1/calls?teamId=<subteam-team-id>
GET /api/v1/chats?teamId=<subteam-team-id>&channel=voice
GET /api/v1/contacts?teamId=<subteam-team-id>

How teamId scoping works

Without teamId, the key returns its own team's data (unchanged behavior).
teamId must be a subteam under the agency that owns the key. Any other team returns 403.
Non-agency keys — including a subteam's own key — cannot use teamId to read a sibling team.
Rate limits count against the agency key's own team, so iterating many subteams draws from one shared quota.

400Invalid teamId

teamId is not a valid UUID.

403Not Your Subteam

teamId is not a subteam of the agency that owns the key.

Request Schema

Field	Type	Required	Description
firstName	string	✓	User's first name (1-50 characters)
lastName	string	✓	User's last name (1-50 characters)
teamName	string	✓	Name for the new subteam (1-50 characters)
email	string	✓	Valid email address for the team admin
totalMonthlyCredits	number	-	Monthly credit limit (default: 1000)
accessConfig	object	-	Access permissions configuration

Access Configuration

The accessConfig object controls what features the subteam can access:

users - User management capabilities
instructions - Read access to instructions
instructionsWrite - Write access to instructions
testing - Testing capabilities
knowledgeBase - Knowledge base access
agentConfiguration - Agent configuration access
agentCreation - Agent creation capabilities

Response Format

Success Response (201)

JSON Response

{
  "message": "Subteam created successfully",
  "subteam": {
    "agencyTeam": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "John's Team",
      "teamId": "987fcdeb-51a2-43d7-8fed-123456789abc",
      "totalMonthlyCredits": 1000,
      "accessConfig": {
        "users": true,
        "instructions": false,
        "instructionsWrite": false,
        "testing": true,
        "knowledgeBase": true,
        "agentConfiguration": false,
        "agentCreation": false
      }
    },
    "user": {
      "id": "user-uuid",
      "email": "john@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "verificationSent": false
    }
  }
}

Error Codes

401Missing API Key

The X-AGENCY-KEY header is missing from your request. Make sure to include your API key in the header.

403Invalid API Key

The provided API key is invalid or doesn't exist. Verify your API key is correct.

403Agency Not Found

The API key doesn't belong to an agency owner team. Only agency owners can create subteams.

400Validation Error

The request data is invalid. Check the error message for specific validation failures.

405Method Not Allowed

Only POST requests are allowed for this endpoint.

500Internal Server Error

An unexpected error occurred on the server. Please try again or contact support if the problem persists.

API Reference