Skip to main content

Creating API Requests

MagicalAPI uses a two-step request process to handle long-running operations efficiently. This guide explains how to create requests and retrieve results.

Request Flow​

  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

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 username
  • 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:

{
  "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(request_id, max_attempts=10):
    headers = {
        'Content-Type': 'application/json',
        'api-key': 'YOUR-API-KEY'
    }
    
    for attempt in range(max_attempts):
        response = requests.post(
            'https://gw.magicalapi.com/get-result',
            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 Workflow​

  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 '{"username": "williamhgates"}'
  1. Check Status
curl -X POST "https://gw.magicalapi.com/get-result" \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR-API-KEY" \
  -d '{"request_id": "abc123xyz"}'
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.