Skip to main content

API Integration

Connect Gdocify to any REST API endpoint for maximum flexibility. Perfect for custom applications, existing API infrastructure, or when you need full control over your data.

Overview​

API integration lets you:

  • Connect to any REST API endpoint
  • Use custom authentication methods
  • Send and receive data in JSON format
  • Integrate with your existing systems

Setting Up API Authentication​

Most APIs require authentication. Gdocify supports:

API Key Authentication​

  1. Enter your API Key in the authentication section
  2. Choose where to send it:
    • Header: X-API-Key: your-key-here
    • Query Parameter: ?api_key=your-key-here

Bearer Token Authentication​

  1. Enter your Bearer Token
  2. It will be sent as: Authorization: Bearer your-token-here

Basic Authentication​

  1. Enter your Username and Password
  2. They will be sent as: Authorization: Basic base64(username:password)

Custom Headers​

You can add custom headers for authentication:

  • X-Custom-Header: value
  • Authorization: Custom your-token

Configuring Your API Endpoint​

  1. Click "Datasource Config" in your automation
  2. Select "API" as the data source type
  3. Enter your API Endpoint URL
  4. Choose the HTTP Method (usually GET or POST)
  5. Configure authentication (see above)

Understanding API Responses​

Gdocify expects your API to return data in one of these formats:

Array of Objects​

[
  {
    "id": "1",
    "name": "John Smith",
    "email": "john@example.com"
  },
  {
    "id": "2",
    "name": "Sarah Johnson",
    "email": "sarah@example.com"
  }
]

Object with Array​

{
  "data": [
    {
      "id": "1",
      "name": "John Smith",
      "email": "john@example.com"
    }
  ]
}

If your API returns data in a nested structure, specify the path to the array (e.g., data.records).

Field Mapping from JSON​

After connecting, Gdocify will:

  • Parse the JSON response
  • Detect available fields
  • Make them available for mapping

Field names come from your JSON keys. For nested objects, use dot notation:

  • user.name - Access name from user object
  • address.city - Access city from address object

Testing Your API Connection​

Before using your API:

  1. Click "Test Connection"
  2. Gdocify will send a request to your endpoint
  3. Check the response:
    • Success: Data is loaded and fields are detected
    • Error: Review the error message and fix the issue

Common issues:

  • 401 Unauthorized: Check your authentication credentials
  • 404 Not Found: Verify your endpoint URL is correct
  • 500 Server Error: Your API might be having issues
  • Invalid JSON: Make sure your API returns valid JSON

Request Configuration​

HTTP Methods​

  • GET: Retrieve data (most common)
  • POST: Send data in request body
  • PUT: Update data

Request Body (for POST/PUT)​

If your API requires a request body:

{
  "filter": "active",
  "limit": 100
}

You can use placeholders in the request body:

{
  "recordId": "{{recordId}}"
}

Query Parameters​

Add query parameters to your URL:

  • ?status=active&limit=100
  • Or configure them in the API settings

Selecting a Key Field​

Choose a field that uniquely identifies each record:

  • ID fields
  • Email addresses
  • Unique codes

This is used for:

  • Tracking processed records
  • Generating unique filenames
  • Identifying specific records

Refreshing Your Data​

To reload data from your API:

  1. Click "Refresh" in the datasource config
  2. Gdocify will make a new API request
  3. Updated data will be loaded
  4. New fields will appear if the structure changed

Rate Limits and Performance​

Be aware of:

  • API rate limits: Don't exceed your API's rate limits
  • Response time: Slow APIs will slow down document generation
  • Data size: Large responses take longer to process

Security Best Practices​

  • Never share API keys: Keep them secure
  • Use HTTPS: Always use encrypted connections
  • Rotate credentials: Change keys regularly
  • Limit permissions: Only grant necessary API permissions
  • Monitor usage: Watch for unusual API activity

Troubleshooting​

"Connection failed"​

  • Check your endpoint URL is correct
  • Verify your API is accessible
  • Test the endpoint in a browser or tool like Postman

"Authentication failed"​

  • Verify your API key or token is correct
  • Check the authentication method matches your API
  • Ensure credentials haven't expired

"Invalid response format"​

  • Make sure your API returns JSON
  • Check the response structure matches expected format
  • Verify the data path if using nested structures

"No data found"​

  • Verify your API returns data
  • Check if filters are excluding all records
  • Ensure the endpoint is returning the expected format

Example API Configurations​

Simple GET Request​

Endpoint: https://api.example.com/users
Method: GET
Auth: Bearer Token

POST with Body​

Endpoint: https://api.example.com/records
Method: POST
Auth: API Key (Header)
Body: {"status": "active"}

Next Steps​

Once your API is connected:

  1. Add placeholders to your template
  2. Map placeholders to your API fields
  3. Configure result settings
  4. Set up API triggers for automation
  5. Generate documents