Soul Machines Interactions API - Postman Documentation

This guide provides comprehensive instructions for setting up and using Postman (or similar) to interact with the Soul Machines Interactions API.

Table of Contents

• Prerequisites
• Initial Setup
• Environment Configuration
• Authentication
• Common API Endpoints
  
• Troubleshooting

Prerequisites

1. Postman Installation: Download and install Postman or similar API client
2. Soul Machines Account: Active account with API access
3. API Key: Generated from Digital Workforce

Initial Setup

1. Generate API Key

1. Log in to your Soul Machines Digital Workforce account at workforce.soulmachines.com
2. Navigate to Connect (Left Sidebar) → Interactions API → Manage & Learn
3. Click Create API Key
4. Copy the API key

Important: Keep your API key secure and never share it publicly or commit it to version control.

Environment Configuration

Create Environment Variables

1. In Postman, click Environments → Create Environment
2. Name it "Soul Machines API"
3. Add the following variables:

Authentication

Collection-Level Authorization

1. Select your Soul Machines collection
2. Go to Authorization tab
3. Set Type to "API Key"
4. Configure:
   • Key: x-api-key
   • Value: {{apiKey}}
   • Add to: Header

Request-Level Authorization (Alternative)

For individual requests, add the header:

x-api-key: {{apiKey}}

Common API Endpoints

1. Health Check

GET {{baseUrl}}/api/v1/health

Purpose: Verify API connectivity

Headers: None required

Response Example:

{
  "status": "HEALTHY"
}

2. Create Generator Interaction

POST {{baseUrl}}/api/v1/generator

Purpose: Generate a new Soul Machines interaction with a Digital Person

Headers:

Content-Type: application/json
x-api-key: {{apiKey}}

Body (raw JSON):

{
  "role": "Customer Service Agent",
  "purpose": "Help customers with product inquiries and provide support",
  "results": {
    "customer_issue": "The main issue the customer needs help with",
    "resolution_provided": "The solution or next steps provided to the customer",
    "customer_satisfaction": "Customer's satisfaction level (1-5 scale)"
  },
  "name": "Riley",
  "tone": "friendly",
  "objectives": [
    "Understand the customer's issue",
    "Provide appropriate solution or escalation",
    "Ensure customer satisfaction"
  ],
  "context": {
    "company_name": "Test Company",
    "support_hours": "9 AM - 5 PM EST"
  },
  "avatar": "dwf_riley",
  "response_length": "moderate",
  "auto_end_session": true
}

Response Example:

{
  "interaction_url": "https://workforce.soulmachines.com/assistant?a=eyJhdXRoU2VydmVyIjogImh0dHBzOi8vaW50ZXJhY3Rpb25zLWFwaS5zb3VsbWFjaGluZXMuY2xvdWQvYXBpL3YxL2ludGVyYWN0aW9ucy9hcHAvand0IiwgImludGVyYWN0aW9uX2lkIjogImVmZjRlZDAyLWExMWItNDY2ZC05NTZhLTg5YzA0OWFhOWY2MyJ9",
  "state": "preparing",
  "failure_reason": null,
  "welcome_message": "Generating experience...",
  "waiting_message": null,
  "warning_messages": null,
  "topics_to_avoid": null,
  "prompt": "",
  "organization_id": "7d6a2a4a-7365-40bb-8c90-d912ae8a219b",
  "interaction_id": "eff4ed02-a11b-466d-956a-89c049aa9f63",
  "created_at": "2025-09-09T02:31:10.780910+00:00",
  "name": "Riley",
  "avatar": "dwf_riley",
  "style_id": null,
  "voice_id": null,
  "expires_at": "2025-10-07T02:31:10+00:00",
  "created_by_key_id": "5d7d11bd02366714a891a13b624a2388",
  "response_length": "moderate",
  "group_name": null,
  "template_id": null,
  "deleted_at": null,
  "is_deleted": false
}

Post-Response Script (to save interaction details):

if (pm.response.code === 200 || pm.response.code === 201) {
  const response = pm.response.json();
  pm.environment.set('interactionId', response.interaction_id);
  pm.environment.set('interactionUrl', response.interaction_url);
}

Important Notes:

• State: Initially "preparing" while the AI generates the interaction, then becomes "ready"
• Interaction URL: Can be opened immediately - it will show "Generating experience..." until ready
• Expiration: Interactions expire after ~28 days (expires_at field)
• Welcome Message: Shows "Generating experience..." during preparation, then updates to AI-generated greeting

3. Get Available Digital Persons

GET {{baseUrl}}/api/v1/people

Purpose: Retrieve available Digital Person avatars

Headers: None required

Response Example:

[
  {
    "id": "dwf_riley",
    "name": "Riley",
    "image": "https://assets.cdn.soulmachines.cloud/AvatarCoverImages/2025stock/workforce/dwf_riley_e1.png",
    "transparent_image": "https://assets.cdn.soulmachines.cloud/AvatarCoverImages/2025stock/summary_page/DWF_Riley-summary-page.png",
    "avatar_image": "https://assets.cdn.soulmachines.cloud/AvatarCoverImages/2025stock/workforce/dwf_riley_e1.jpg",
    "image_jpg": "https://assets.cdn.soulmachines.cloud/AvatarCoverImages/2025stock/workforce/dwf_riley_e1.jpg",
    "styles": [
      {
        "id": "formal",
        "image": "https://assets.cdn.soulmachines.cloud/AvatarCoverImages/2025stock/workforce/dwf_riley_e1.jpg"
      },
      {
        "id": "smart_casual",
        "image": "https://assets.cdn.soulmachines.cloud/AvatarCoverImages/2025stock/workforce/dwf_riley_e2.jpg"
      },
      {
        "id": "scrubs",
        "image": "https://assets.cdn.soulmachines.cloud/AvatarCoverImages/2025stock/workforce/dwf_riley_e3.jpg"
      }
    ],
    "voices": [{ "id": "en" }, { "id": "multi-lingual" }],
    "default_style_id": "formal",
    "default_voice_id": "en"
  },
  {
    "id": "dwf_mira",
    "name": "Mira",
    "image": "https://assets.cdn.soulmachines.cloud/AvatarCoverImages/2025stock/workforce/dwf_mira_e1.png",
    "transparent_image": "https://assets.cdn.soulmachines.cloud/AvatarCoverImages/2025stock/summary_page/DWF_Mira-summary-page.png",
    "avatar_image": "https://assets.cdn.soulmachines.cloud/AvatarCoverImages/2025stock/workforce/dwf_mira_e1.jpg",
    "image_jpg": "https://assets.cdn.soulmachines.cloud/AvatarCoverImages/2025stock/workforce/dwf_mira_e1.jpg",
    "styles": [
      {
        "id": "formal",
        "image": "https://assets.cdn.soulmachines.cloud/AvatarCoverImages/2025stock/workforce/dwf_mira_e1.jpg"
      },
      {
        "id": "smart_casual",
        "image": "https://assets.cdn.soulmachines.cloud/AvatarCoverImages/2025stock/workforce/dwf_mira_e2.jpg"
      },
      {
        "id": "scrubs",
        "image": "https://assets.cdn.soulmachines.cloud/AvatarCoverImages/2025stock/workforce/dwf_mira_e3.jpg"
      }
    ],
    "voices": [{ "id": "en" }, { "id": "multi-lingual" }],
    "default_style_id": "formal",
    "default_voice_id": "en"
  }
]

Available Digital Persons: Riley, Mira, Hana, Emma, Ren, Leo (each with multiple styles and voice options)

Key Features:

• Each digital person has multiple styles: formal, smart_casual, scrubs
• Voice options: en (English), multi-lingual
• Style images show different clothing/appearance options
• Use the id field (e.g., dwf_riley) when creating interactions

4. Get Available Tones

GET {{baseUrl}}/api/v1/tones

Purpose: Retrieve available conversation tones

Headers: None required

Response Example:

[
  "friendly",
  "sweet",
  "conscientious",
  "bubbly",
  "free-spirited",
  "shy",
  "troubled",
  "frosty",
  "elated"
]

5. Get Response Lengths

GET {{baseUrl}}/api/v1/response_lengths

Purpose: Retrieve available response length options

Headers: None required

Response Example:

["concise", "moderate", "detailed"]

6. List Templates

GET {{baseUrl}}/api/v1/templates

Purpose: List all templates for your organization

Headers:

x-api-key: {{apiKey}}

Query Parameters (optional):

• tags: Array of tags to filter templates
• include_deleted: Boolean to include deleted templates (default: false)

7. Get Organization Info

GET {{baseUrl}}/api/v1/org

Purpose: Get organization information

Headers:

x-api-key: {{apiKey}}

Response Example:

{
  "organization_id": "7d6a2a4a-7365-40bb-8c90-d912ae8a219b"
}

8. Subscribe to Trigger

POST {{baseUrl}}/api/v1/triggers/subscribe

Purpose: Subscribe to a webhook trigger for interaction events

Headers:

Content-Type: application/json
x-api-key: {{apiKey}}

Body (raw JSON):

{
  "trigger_id": "interaction_complete",
  "webhook": {
    "url": "https://your-webhook-endpoint.com/interaction-complete",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer your-webhook-token"
    }
  }
}

Troubleshooting

Common Issues and Solutions

1. Authentication Errors (401 Unauthorized)

Symptoms: 401 Unauthorized responses

Solutions:

• Verify API key is correct and not expired
• Check that the API key has proper scope for your project
• Ensure Authorization header format: Bearer your-api-key
• Verify your IP address is whitelisted (if developing locally)

2. CORS Issues

Symptoms: CORS-related errors in browser-based testing

Solutions:

• Use Postman desktop app instead of web version
• Verify Custom UI Domain settings in Soul Machines Studio
• Check that your domain is properly configured in API key settings

3. Interaction Generation Errors

Symptoms: Interaction creation fails or returns error states

Solutions:

• Verify all required fields are provided (role, purpose, results)
• Check that the results object contains valid key-value pairs
• Ensure objectives array contains actionable items
• Verify avatar ID matches available digital persons
• Check tone matches available options

4. Rate Limiting

Symptoms: 429 Too Many Requests responses

Solutions:

• Implement delays between requests in Collection Runner
• Check your API key's rate limits
• Use Postman's built-in delays in test scripts:

// Add 1-second delay between requests
setTimeout(function () {}, 1000);

Debug Headers

Add these headers to requests for debugging:

X-Request-ID: {{$guid}}

Interaction URL Testing

After creating an interaction, you can:

1. Copy the interaction_url from the response
2. Open it in a browser to test the Digital Person
3. Share it with stakeholders for review

Logging Responses

Add to Tests tab for detailed logging:

console.log('Request URL:', pm.request.url.toString());
console.log('Response Status:', pm.response.code);
console.log('Response Body:', pm.response.text());
console.log('Response Headers:', pm.response.headers.toJSON());

Best Practices

1. Environment Management: Use separate environments for development, staging, and production
2. API Key Security: Never commit API keys to version control; use environment variables
3. Error Handling: Always check response status codes and implement proper error handling
4. Interaction Design:
   • Write clear, specific purposes and objectives
   • Define meaningful results to capture
   • Choose appropriate tones for your use case
   • Test interactions thoroughly before production use
5. Rate Limiting: Respect API rate limits and implement appropriate delays
6. Monitoring: Use Postman monitors for continuous API health checking
7. Template Usage: Create reusable templates for common interaction patterns
8. Webhook Integration: Set up webhooks to capture interaction results programmatically

Additional Resources

• Soul Machines Interactions API Documentation
• Soul Machines Digital Workforce
• Soul Machines Support Portal
• Postman Learning Center

Note: Replace placeholder values (API keys, project IDs, etc.) with your actual values. Keep your API credentials secure and never share them publicly.