Skip to main content

Creating API Requests

MagicalAPI provides two methods for handling API requests and receiving results. Choose the approach that best fits your workflow.

Two Ways to Get Results​

1. Request ID (Polling)​

The traditional approach where you poll for results:

  1. Initial Request: Send your data to get a request_id
  2. Status Check: Use the request_id to poll for results
  3. Final Response: Receive the processed data

Best for: Simple integrations, one-off requests, or when you need immediate control over when to check results.

2. Webhook (Push Notifications)​

Receive results automatically without polling:

  1. Initial Request: Send your data with a webhook_url
  2. Automatic Delivery: Receive results at your endpoint when ready

Best for: Production applications, high-volume processing, or when you want to eliminate polling overhead.

tip

For detailed webhook setup and usage, see the Webhook Integration Guide.

Choosing the Right Method​

FeatureRequest IDWebhook
Setup ComplexitySimpleRequires endpoint setup
API CallsMultiple (polling)Single request
Real-time ResultsManual polling neededAutomatic delivery
Best Use CaseTesting, simple scriptsProduction, automation

Request Flow (Request ID Method)​

Step 1: Initial Request​

Send your request to the appropriate service endpoint. You'll receive a 201 response with a request_id:

{
  "data": {
    "request_id": "abc123xyz"
  },
  "usage": {
    "credits": 10
  }
}

Request Parameters​

Each service has specific parameters. For example:

  • Profile Data: Requires profile_name
  • Resume Parser: Needs url to the resume file
  • Company Data: Takes company_name

See individual service documentation for parameter details.

Step 2: Retrieve Results​

Use the request_id to check the status and get results by sending a request to the same service endpoint you initially used:

{
  "request_id": "abc123xyz"
}

Polling Best Practices​

  1. Poll Interval: Check every 2-3 seconds
  2. Timeout: Set a maximum wait time
  3. Error Handling: Implement retry logic

Example polling implementation:

import time
import requests

def get_results(service_endpoint, request_id, max_attempts=10):
    headers = {
        'Content-Type': 'application/json',
        'api-key': 'YOUR-API-KEY'
    }
    
    for attempt in range(max_attempts):
        response = requests.post(
            service_endpoint,  # Use the same endpoint as the initial request
            headers=headers,
            json={'request_id': request_id}
        )
        
        if response.status_code == 200:
            return response.json()
            
        time.sleep(2)  # Wait 2 seconds between attempts
    
    raise TimeoutError("Result not available after maximum attempts")

Credit Usage​

The usage field in responses shows credit consumption:

{
  "usage": {
    "credits": 10
  }
}

Monitor your credit balance:

Example Workflows​

Using Request ID​

  1. Send Initial Request
curl -X POST "https://gw.magicalapi.com/profile-data" \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR-API-KEY" \
  -d '{"profile_name": "williamhgates"}'
  1. Check Status (using the same endpoint)
curl -X POST "https://gw.magicalapi.com/profile-data" \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR-API-KEY" \
  -d '{"request_id": "abc123xyz"}'

Using Webhook​

Send a single request with your webhook URL:

curl -X POST "https://gw.magicalapi.com/profile-data" \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR-API-KEY" \
  -d '{
    "profile_name": "williamhgates",
    "webhook_url": "https://yourdomain.com/api/webhook"
  }'

Results will be automatically sent to your webhook endpoint when ready. Learn more about setting up webhooks.

tip

Use the Python SDK or Postman Collection to simplify request handling.

Error Handling​

Common issues to handle:

  • Invalid parameters
  • Insufficient credits
  • Timeout errors

See Status Codes for error handling guidance.